Prerequisites Step 1: Create a state machine Step 2: Create a service role for the gateway Step 3: Create a gateway and add the Step Functions connector target Step 4: Start an execution through the gateway Step 5: Confirm the result Step 6: Clean up Related resources

Use your Step Functions workflows as tools for AI agents

You can let AI agents run your Step Functions workflows by exposing a state machine as Model Context Protocol (MCP) tools through Amazon Bedrock AgentCore Gateway. An agent connected to the gateway can start executions, check their status and output, read the event history, and stop executions. You don't need to write a Lambda function or define the tools yourself. The gateway creates the tool schemas and calls Step Functions for the agent.

This pattern is useful 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, so the agent can't skip or reorder them, and the execution history records each step of the workflow.

You control what the agent can do in two ways. Tools that start or list executions are pinned to the state machine you choose, and the agent can't change it. Tools that act on a specific execution take an execution Amazon Resource Name (ARN) from the agent. The AWS Identity and Access Management policy on your gateway service role limits which executions those tools can access. This tutorial scopes that policy to a single state machine.

In this tutorial, you create a simple Standard state machine and a gateway with a Step Functions connector target that points to it. You then make the same MCP calls an agent makes, using awscurl, so you can see each request and response. If you already have a Standard state machine, you can skip to Step 2: Create a service role for the gateway and use its ARN in place of AgentHelloWorld. This tutorial uses a Standard workflow because ListExecutions, DescribeExecution, and GetExecutionHistory don't work with Express executions. The resources that you create can incur charges until you delete them in Step 6: Clean up.

Important

The resources in this tutorial can incur charges for Step Functions state transitions and Amazon Bedrock AgentCore Gateway tool calls. For rates, see Step Functions pricing and Amazon Bedrock AgentCore pricing. To avoid ongoing charges, delete the resources when you finish, as described in Step 6: Clean up.

Note

The Step Functions connector exposes ten operations. This tutorial configures six of them: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, and StopExecution. For the full list, including the task-token operations and the differences between Standard and Express workflows, see AWS Step Functions as Connector Target in the Amazon Bedrock AgentCore Developer Guide.

Prerequisites

Before you begin, make sure that you have the following:

The AWS CLI version 2, configured with credentials for your account. Steps 3 through 6 use the AWS CLI.
A client that can send Signature Version 4-signed HTTP requests to the gateway. This tutorial uses awscurl, which you can install with pip install awscurl. Any MCP client that supports Signature Version 4 works the same way.
Permission to create IAM roles, Step Functions state machines, and AgentCore gateways in your account, and the bedrock-agentcore:InvokeGateway permission on the gateway that you create in Step 3 for the identity that calls it in Steps 4 and 5.

Create every resource in this tutorial in the same AWS Region. The gateway calls Step Functions in its own Region, so a state machine in a different Region is not reachable through the connector.

Step 1: Create a state machine

Create a Standard state machine for the agent to run. The following definition has a single Pass state that returns a fixed result. Make sure that the console is set to the Region where you will create the gateway in Step 3.

To create the state machine (console)

Open the AWS Step Functions console and choose Create state machine.
Choose Blank, and then choose Select.

Choose Code and replace the definition with the following.


{
  "Comment": "A workflow that an AI agent starts through AgentCore Gateway",
  "StartAt": "Hello",
  "States": {
    "Hello": {
      "Type": "Pass",
      "Result": "Hello from Step Functions",
      "End": true
    }
  }
}

Choose Config. For State machine name, enter AgentHelloWorld. Keep Type as Standard.
Choose Create to create the state machine.
Allow Step Functions to create an execution role when prompted. If you use the AWS CLI instead, create the role yourself, as shown in the following procedure.
On the state machine details page, note the ARN, as shown in the following example.
```
arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld
```

To create the same state machine with the AWS CLI instead, use the following procedure. Unlike the console, the AWS CLI does not create an execution role for you, so create one first. This Pass-only workflow calls no other services, so the role needs no permissions policy.

To create the state machine (AWS CLI)

Create an execution role that Step Functions can assume. Replace the Region and account ID with your own.


aws iam create-role \
  --role-name AgentHelloWorldExecutionRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": { "Service": "states.amazonaws.com" },
        "Action": "sts:AssumeRole",
        "Condition": {
          "ArnLike": {
            "aws:SourceArn": "arn:aws:states:region:123456789012:stateMachine:*"
          },
          "StringEquals": {
            "aws:SourceAccount": "123456789012"
          }
        }
      }
    ]
  }'

Save the definition shown in the console procedure to a file named definition.json, and then create the state machine.


aws stepfunctions create-state-machine \
  --name AgentHelloWorld \
  --type STANDARD \
  --definition file://definition.json \
  --role-arn "arn:aws:iam::123456789012:role/AgentHelloWorldExecutionRole" \
  --region region

The response contains the stateMachineArn. Note it for Steps 2 and 3.

Step 2: Create a service role for the gateway

The gateway calls Step Functions with a service role. Scope the role to the state machine you created so the agent cannot act on other workflows in your account.

To create the gateway service role

Open the IAM console and choose Roles, Create role.

For Trusted entity type, choose Custom trust policy, and enter the following. Replace the Region and account ID with your own.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "bedrock-agentcore.amazonaws.com" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:region:123456789012:gateway/step-functions-gateway-*"
        }
      }
    }
  ]
}

Choose Next, and then Next again without attaching a managed policy.
For Role name, enter AgentCoreGatewayToStepFunctions, and then choose Create role.

Open the role, choose Add permissions, Create inline policy, choose JSON, and enter the following policy. Replace the Region and account ID with your own.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "StateMachineOperations",
      "Effect": "Allow",
      "Action": [
        "states:StartExecution",
        "states:ListExecutions",
        "states:DescribeStateMachine"
      ],
      "Resource": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld"
    },
    {
      "Sid": "ExecutionOperations",
      "Effect": "Allow",
      "Action": [
        "states:DescribeExecution",
        "states:GetExecutionHistory",
        "states:StopExecution"
      ],
      "Resource": "arn:aws:states:region:123456789012:execution:AgentHelloWorld:*"
    }
  ]
}

Name the policy StepFunctionsConnectorAccess, and then choose Create policy.

Note the role ARN, as shown in the following example.


arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions

Note

Execution ARNs are a different resource type from state machine ARNs, which is why the policy has two statements.

If you later expose the task-token operations (SendTaskSuccess, SendTaskFailure, and SendTaskHeartbeat), you must grant them on "*", because IAM doesn't support resource-level permissions for these actions. The task token is then the only control on which tasks the agent can complete, so treat task tokens as secrets and send each one only to the agent that should act on it.

All targets on a gateway share its service role. If different workflows need different IAM boundaries, use a separate gateway for each.

Step 3: Create a gateway and add the Step Functions connector target

Create a gateway that accepts requests signed with AWS credentials, and then add a target that uses the states connector and pins it to your state machine.

To create the gateway and target

Create the gateway with the AWS CLI. Replace the role ARN with the one from Step 2.


aws bedrock-agentcore-control create-gateway \
  --name "step-functions-gateway" \
  --protocol-type MCP \
  --authorizer-type AWS_IAM \
  --role-arn "arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions" \
  --region region

The response includes the gatewayId and gatewayUrl. Note both.

Wait until the gateway status is READY. This can take a few minutes. Replace GATEWAY_ID with the gatewayId from the previous step.


aws bedrock-agentcore-control get-gateway \
  --gateway-identifier "GATEWAY_ID" \
  --query status --output text --region region

Add the connector target. The configurations list chooses which operations become tools. StartExecution, ListExecutions, and DescribeStateMachine are pinned to your state machine. DescribeExecution, GetExecutionHistory, and StopExecution take an execution ARN from the agent. Replace GATEWAY_ID with your gateway ID.


aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier "GATEWAY_ID" \
  --name "hello" \
  --target-configuration '{
    "mcp": {
      "connector": {
        "source": { "connectorId": "states" },
        "configurations": [
          {
            "name": "StartExecution",
            "parameterValues": {
              "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld"
            }
          },
          {
            "name": "ListExecutions",
            "parameterValues": {
              "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld"
            }
          },
          {
            "name": "DescribeStateMachine",
            "parameterValues": {
              "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld"
            }
          },
          { "name": "DescribeExecution" },
          { "name": "GetExecutionHistory" },
          { "name": "StopExecution" }
        ]
      }
    }
  }' \
  --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \
  --region region

Wait until the target status is READY. This can take a few minutes. Replace TARGET_ID with the targetId from the create-gateway-target response.


aws bedrock-agentcore-control get-gateway-target \
  --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \
  --query status --output text --region region

The gateway now exposes six MCP tools: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, and hello___StopExecution. The gateway prefixes each tool name with the target name.

Step 4: Start an execution through the gateway

An MCP client calls the gateway with JSON-RPC requests. Because the gateway uses AWS_IAM authorization, requests must be signed with Signature Version 4. The following examples use awscurl, which signs requests with your AWS CLI credentials. See Prerequisites. In each command, replace GATEWAY_URL with the gatewayUrl from Step 3.

To start an execution

List the tools the agent sees.
```
awscurl --service bedrock-agentcore --region region \
  -X POST "GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
The response lists the six tools with their input schemas. Notice that hello___StartExecution advertises only input: the pinned stateMachineArn is hidden from the agent and cannot be overridden.

Start an execution.


awscurl --service bedrock-agentcore --region region \
  -X POST "GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "hello___StartExecution",
      "arguments": { "input": "{\"who\": \"agent\"}" }
    }
  }'

The tool result contains the Step Functions response with the new execution's ARN.


{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": false,
    "content": [
      {
        "type": "text",
        "text": "{\"executionArn\":\"arn:aws:states:region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",\"startDate\":1.7597E9}"
      }
    ]
  }
}

Note the executionArn for the next step.

Step 5: Confirm the result

Use the execution-level tools to check whether the execution succeeded and to read its output.

To confirm the execution result

Describe the execution. By default, the response contains metadata only. To include the input and output, set includedData to ALL_DATA. Replace EXECUTION_ARN with the executionArn from Step 4.


awscurl --service bedrock-agentcore --region region \
  -X POST "GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "hello___DescribeExecution",
      "arguments": {
        "executionArn": "EXECUTION_ARN",
        "includedData": "ALL_DATA"
      }
    }
  }'

For this state machine, status is SUCCEEDED and output is "Hello from Step Functions". If an execution fails, status is FAILED and the response includes the error and cause fields from the failing state.

Read the event history to see each step the execution took.


awscurl --service bedrock-agentcore --region region \
  -X POST "GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "hello___GetExecutionHistory",
      "arguments": { "executionArn": "EXECUTION_ARN" }
    }
  }'

List recent executions of the pinned state machine, optionally filtered by status.


awscurl --service bedrock-agentcore --region region \
  -X POST "GATEWAY_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "hello___ListExecutions",
      "arguments": { "statusFilter": "SUCCEEDED" }
    }
  }'

(Optional) Confirm the execution in the AWS Step Functions console. Choose AgentHelloWorld, and then choose the execution. An execution started by the gateway appears like any other execution, with the gateway's service role as the caller in AWS CloudTrail.

Note

To stop a running execution, call hello___StopExecution with the execution ARN. Calling it on an execution that has already finished succeeds but has no effect. The response returns the execution's original stop time. For a long-running workflow, an agent typically calls StartExecution, and then polls DescribeExecution until status is no longer RUNNING.

Step 6: Clean up

To avoid ongoing charges, delete the resources that you created.

To clean up

Delete the gateway target, and then the gateway.


aws bedrock-agentcore-control delete-gateway-target \
  --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --region region
aws bedrock-agentcore-control delete-gateway \
  --gateway-identifier "GATEWAY_ID" --region region

In the Step Functions console, delete the AgentHelloWorld state machine.
In the IAM console, delete the AgentCoreGatewayToStepFunctions role and the state machine's execution role (the role that Step Functions created for you, or AgentHelloWorldExecutionRole if you used the AWS CLI).

AWS Step Functions as Connector Target in the Amazon Bedrock AgentCore Developer Guide – all ten operations, which parameters can be pinned, Standard and Express workflow constraints, and tool schemas.
Add a Connector target with AWS Step Functions – setup with Boto3, the AWS CLI, and the AgentCore CLI, and the full service role policy including task-token operations.
Create an agent that uses your AgentCore gateway – connect an agent framework such as Strands Agents or LangGraph to the gateway.
Invoke Amazon Bedrock AgentCore harness with Step Functions – the reverse direction: call an agent from a Step Functions Task state.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Access cross-account resources

Starter templates