Invoke Amazon Bedrock AgentCore harness with Step Functions

You can integrate Step Functions with Amazon Bedrock AgentCore to invoke a harness from your state machine. A harness is a managed runtime that orchestrates model inference, tool use, and multi-turn conversations. In Workflow Studio, search for AgentCore InvokeHarness to find this state and drag it into your workflow.

From the configuration panel, you can create a new harness and execution role using Quick Create Harness, or select an existing harness ARN. When you use an existing harness, you can override configurations on a per-invocation basis – values in your Task state definition override the harness defaults. For available parameters, see InvokeHarness in the Amazon Bedrock AgentCore API Reference. For more information about harness execution roles, see Runtime permissions in the Amazon Bedrock AgentCore Developer Guide.

To learn about integrating with AWS services in Step Functions, see Integrating services and Passing parameters to a service API in Step Functions.

Optimized Amazon Bedrock AgentCore harness APIs

The following API is supported:

InvokeHarness

Invokes a harness to run an AI agent that can use tools, access memory, and execute multi-turn conversations.

Supported pattern: Request Response only.

For the full request syntax, see InvokeHarness in the Amazon Bedrock AgentCore API Reference.

Response fields

Response syntax

{
  "Output": {
    "Message": {
      "Role": "string",
      "Content": [
        {
          "Text": "string"
        }
      ]
    }
  },
  "StopReason": "string",
  "Usage": {
    "InputTokens": long,
    "OutputTokens": long,
    "TotalTokens": long
  },
  "Metrics": {
    "LatencyMs": long
  }
}

Task state definition for Amazon Bedrock AgentCore integration

The following examples show how to define a Task state that invokes an Amazon Bedrock AgentCore harness.

The RuntimeSessionId field identifies the conversation session. Use the same session ID across invocations to continue a conversation.

{
  "Type": "Task",
  "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
  "Arguments": {
    "HarnessArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:harness/my-agent-harness",
    "RuntimeSessionId": "{% $uuid() %}",
    "Messages": [
      {
        "Content": [{ "Text": "{% $states.input.userMessage %}" }],
        "Role": "user"
      }
    ],
    "SystemPrompt": [{ "Text": "You are a helpful customer service agent." }],
    "Model": {
      "BedrockModelConfig": {
        "Temperature": 0.7,
        "ModelId": "global.anthropic.claude-sonnet-4-6"
      }
    },
    "MaxIterations": 75,
    "TimeoutSeconds": 600
  },
  "End": true
}

{
  "Type": "Task",
  "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
  "Arguments": {
    "HarnessArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:harness/order-agent",
    "RuntimeSessionId": "{% $uuid() %}",
    "Messages": [
      {
        "Content": [{ "Text": "What is the status of order #12345?" }],
        "Role": "user"
      }
    ],
    "Tools": [
      {
        "Type": "agentcore_browser",
        "Name": "aws_browser_v1",
        "Config": {
          "AgentCoreBrowser": {
            "BrowserArn": "arn:aws:bedrock-agentcore:us-east-1:aws:browser/aws.browser.v1"
          }
        }
      }
    ],
    "MaxIterations": 10,
    "TimeoutSeconds": 300
  },
  "End": true
}

Error handling

The InvokeHarness API can fail with a variety of errors, including throttling, validation, and access denied errors. For a complete list, see InvokeHarness errors in the Amazon Bedrock AgentCore API Reference.

The following example shows a Task state with Retry and Catch fields for error handling:

{
  "Type": "Task",
  "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness",
  "Arguments": {
    "HarnessArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:harness/my-harness",
    "Messages": [
      {
        "Content": [{ "Text": "{% $states.input.userMessage %}" }],
        "Role": "user"
      }
    ]
  },
  "Retry": [
    {
      "ErrorEquals": ["BedrockAgentCore.ThrottlingException"],
      "IntervalSeconds": 2,
      "MaxAttempts": 3,
      "BackoffRate": 2.0
    }
  ],
  "Catch": [
    {
      "ErrorEquals": ["BedrockAgentCore.ResourceNotFoundException"],
      "Next": "HandleNotFound"
    },
    {
      "ErrorEquals": ["States.ALL"],
      "Next": "HandleError"
    }
  ],
  "End": true
}

IAM policies for calling Amazon Bedrock AgentCore

The following example templates show how AWS Step Functions generates IAM policies based on the resources in your state machine definition. For more information, see How Step Functions generates IAM policies for integrated services and Discover service integration patterns in Step Functions.

IAM policy examples for Amazon Bedrock AgentCore integration

The following examples show how you can create IAM policies for your Step Functions execution role to interact with Amazon Bedrock AgentCore resources.

In the following policy examples, replace the placeholder values with your own values.

IAM policy to invoke a specific harness

The following example policy allows invoking a specific Amazon Bedrock AgentCore harness by ARN.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeSpecificHarness",
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:InvokeHarness",
                "bedrock-agentcore:InvokeAgentRuntime"
            ],
            "Resource": "arn:aws:bedrock-agentcore:region:accountId:harness/harnessName"
        }
    ]
}

IAM policy to invoke all harnesses in an account

The following example policy allows invoking any Amazon Bedrock AgentCore harness in your account. We recommend scoping down to a specific harness ARN when possible.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "InvokeAllHarnesses",
            "Effect": "Allow",
            "Action": [
                "bedrock-agentcore:InvokeHarness",
                "bedrock-agentcore:InvokeAgentRuntime"
            ],
            "Resource": "arn:aws:bedrock-agentcore:region:accountId:harness/*"
        }
    ]
}