Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Step Functions as Connector Target

Amazon Step Functions is a workflow service that coordinates Amazon services, your own code, and HTTP APIs as a series of steps called a state machine. Step Functions provides built-in retries and error handling, and it passes data between steps. For Standard workflows, it also records every step in an execution history. To learn more, see What is Step Functions? in the Amazon Step Functions Developer Guide.

Amazon Bedrock AgentCore Gateway includes a built-in Step Functions connector. You create a gateway target that uses the connector and choose which Step Functions operations to expose as tools. Your agents discover and call these tools through the Model Context Protocol (MCP). The gateway creates the tool schemas and authenticates to Step Functions with the gateway service role. You don’t write a Lambda function or an MCP server, and you don’t define the tools yourself. If you already use Step Functions, you can expose your existing Standard and Express state machines without changing them.

Use a Step Functions target when a task must run the same steps in the same order every time. The agent decides when to run the workflow and what input to pass. The state machine decides which steps run and in what order, so the agent can’t skip or reorder them. This helps when a process must follow an approved sequence, or when you need a record of each step for audit. Standard workflows keep that record in the execution history, and they can run for up to one year, so work can continue after the agent’s session ends.

The connector exposes ten operations. Four of them act on a state machine that you pin to the operation when you create the target: StartExecution, StartSyncExecution, ListExecutions, and DescribeStateMachine. The agent doesn’t see the pinned state machine and can’t change it. The gateway rejects any call that tries. Each operation takes one pin in a target, so to expose several state machines for the same operation, create a target for each one.

The other six operations act on an execution Amazon Resource Name (ARN) or a task token that the agent provides: DescribeExecution, StopExecution, GetExecutionHistory, SendTaskSuccess, SendTaskFailure, and SendTaskHeartbeat. They aren’t limited to the pinned state machine. The gateway service role’s IAM (Identity and Access Management) policy controls what they can reach. You can limit DescribeExecution, StopExecution, and GetExecutionHistory by scoping that policy to the execution ARNs of the state machines you expose. Because IAM can’t limit SendTaskSuccess, SendTaskFailure, and SendTaskHeartbeat to specific executions, any agent with a valid task token can complete that task. Treat task tokens as secrets and send them only to the agent that should act on them.

Agents and workflows can work together in two ways. In the first, the agent starts a workflow, checks its progress, and stops it if needed. In the second, a workflow pauses and waits for the agent to complete a task. The workflow uses a task with the callback pattern (.waitForTaskToken), and Step Functions creates a task token. Your workflow must deliver the token and the task details to the agent’s application, for example through an Amazon SQS queue or an Activity that the application polls. The agent does the work, then calls SendTaskSuccess with the result or SendTaskFailure if it can’t finish. For long tasks, the agent calls SendTaskHeartbeat to show it’s still working. This pattern works only with Standard workflows, because Express workflows don’t support the callback pattern.

The following sections walk through how the connector works, common use cases, how to set up a target, the differences between Standard and Express workflows, and the tool schemas.

How it works

The Step Functions connector is a built-in connector. The Gateway handles schema management, parameter governance, endpoint resolution, and service authentication. A typical flow works as follows:

Use cases

Set up a Step Functions target

For setup examples that use Boto3, the Amazon CLI, and the AgentCore CLI, see Set up a Step Functions target.

Pin state machines to operations

Only the four operations that take a stateMachineArn can be pinned. The other six identify their target by an execution ARN or a task token, which belong to a specific execution rather than a state machine, so the agent supplies them.

You set pins for each operation, so one target can point StartExecution at a Standard state machine and StartSyncExecution at an Express one. The Gateway removes a pinned parameter from the tool schema and enforces it on every call. If an agent passes stateMachineArn anyway, the Gateway rejects the call with Invalid request parameters: cannot set parameter(s): [/stateMachineArn].

Always set parameterValues.stateMachineArn on each pinnable operation that you include. If you leave it out, the Gateway can still create the target, but the tool fails on every call because no state machine is supplied.

Because only the Gateway service role bounds the six unpinned operations, scope that role’s IAM policy as tightly as the operations allow. You can limit DescribeExecution, StopExecution, and GetExecutionHistory to the execution ARNs of the state machines you expose instead of granting states:*.

SendTaskSuccess, SendTaskFailure, and SendTaskHeartbeat have no resource-level permissions in IAM, so you must grant them on "*". The task token is the only control, so treat task tokens as secrets. Pinning and IAM are complementary controls, not alternatives. See Configure the Gateway Service Role.

Standard and Express workflows

Step Functions has two workflow types, and some operations only work with one of them. Step Functions returns these errors. They aren’t connector failures.

If you need both types behind one target, pin StartSyncExecution to an Express state machine and the other pinnable operations to a Standard one. The tool descriptions returned by tools/list state these constraints so the agent can choose the right tool.

Configure the Gateway Service Role

The Gateway needs a service role that allows the AgentCore service to call Step Functions on your behalf. For the required IAM permissions and policy configuration, see Configure the Gateway Service Role in the target configuration guide.

Invoke the tools

After you create the target, your agent discovers the tools with tools/list and calls them with tools/call. Each tool name is prefixed with the target name, in the form <target-name>_<operation>_StartExecution).

The following JSON-RPC request starts a workflow on the pinned state machine. The agent passes only the input:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "orders___StartExecution",
    "arguments": {
      "input": "{\"orderId\": \"12345\"}"
    }
  }
}

The result contains the executionArn. To check on the execution, the agent passes that ARN to DescribeExecution. By default, the response contains metadata only. The following JSON-RPC request sets includedData to ALL_DATA to include the execution’s input and output:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "orders___DescribeExecution",
    "arguments": {
      "executionArn": "arn:aws:states:us-east-1:123456789012:execution:OrderWorkflow:3c1a...",
      "includedData": "ALL_DATA"
    }
  }
}

The following JSON-RPC request resumes a workflow that’s waiting on a task token. The agent passes the token it received and the task output:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "orders___SendTaskSuccess",
    "arguments": {
      "taskToken": "AQCEAAAAKgAAAAMAAAAA...",
      "output": "{\"approved\": true}"
    }
  }
}

Input schemas

The schema returned by tools/list for each tool is the set of fields the agent can set. Pinned parameters are omitted. By default, each tool shows only the fields in the Default fields column. To let the agent set a field from the Fields you can expose column, add it to parameterOverrides on that operation’s configuration entry with visible set to true. The parameterOverrides format is the same as for other connectors. For details, see Control which parameters the agent can set. The following table applies to connector version 1.0.0.

You can’t expose stateMachineArn with parameterOverrides. You set it only by pinning.

For the shape of each field and of the responses, see the corresponding operation in the Amazon Step Functions API Reference.

Response format

Each tool returns an MCP tools/call result wrapped in a JSON-RPC envelope. The text field contains the serialized Step Functions API response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"executionArn\":\"arn:aws:states:us-east-1:123456789012:execution:OrderWorkflow:3c1a...\",\"startDate\":1.7596E9}"
      }
    ]
  }
}

When Step Functions returns an error, the result has isError set to true and the text field names the Step Functions error, for example ExecutionDoesNotExist or StateMachineTypeNotSupported.

Availability

The Step Functions connector is available in all Amazon Regions where Amazon Bedrock AgentCore Gateway is available. The Gateway calls the Step Functions endpoint in the same Region as the Gateway.