Step Functions as AI Agent Tools: The Model Decides When, the Workflow Decides How

On October 29, 2026, AWS made it possible to expose existing AWS Step Functions workflows as tools for AI agents through Amazon Bedrock AgentCore Gateway. It sounds like just another integration, but it answers a question every team putting agents into production eventually hits: how much of a business process should the model be allowed to decide?

AWS's answer is a clean split. The agent decides when to start a process and with what input. How that process runs (step order, retries, approvals, timeouts) stays in a Step Functions definition you wrote, versioned and tested. The model cannot skip the manager approval step because it "seemed reasonable".

Who decides what when an agent calls a workflow through the connector (labels in Spanish). Diagram: CloudAcademy.ar.

TL;DR

AgentCore Gateway gets a managed connector (connectorId: "states") that turns Step Functions API operations into MCP tools. No glue Lambda, no custom MCP server.
Ten operations are available: StartExecution, StartSyncExecution, DescribeStateMachine, ListExecutions, DescribeExecution, GetExecutionHistory, StopExecution, and the three SendTask* calls.
Pinning fixes the stateMachineArn in the target configuration. The agent never sees it and cannot override it.
Both Standard and Express workflows work, but history, describe, stop and task-token callbacks are Standard-only.
All targets on a gateway share one service role. Different IAM boundaries mean different gateways.
Available wherever AgentCore Gateway is, including São Paulo. No extra charge beyond standard Step Functions and Gateway pricing.

What the connector actually is

It is a managed target type for AgentCore Gateway. You create a target with connectorId: "states", choose which Step Functions operations become tools, and the gateway publishes them over MCP with a narrow input schema. Tool names are prefixed with the target name, for example refunds___StartExecution.

When the agent calls a tool, the gateway authenticates the caller (IAM/SigV4 or JWT), adds the pinned parameters, and calls Step Functions with its own service role, in its own Region. A state machine in another Region is unreachable.

What it is not: it is not an agent inside Step Functions (that is the separate AgentCore integration from a workflow), it does not let the model design or change your workflow, and it is not business authorization. Being allowed to call StartExecution on the refund workflow says nothing about whether this refund makes sense. That still belongs inside the workflow.

Operations and pinning

StartExecution, StartSyncExecution (Express only), ListExecutions (Standard only) and DescribeStateMachine accept a pin. The rest act on an execution ARN or a task token that the agent has to provide.

By default StartExecution exposes only input. You can opt into name and traceHeader with parameterOverrides. stateMachineArn can never be exposed. If the agent sends one anyway, the call is rejected with cannot set parameter(s): [/stateMachineArn] and nothing runs.

One documented gotcha worth repeating: if you expose a pinnable operation and forget the pin, the target is created successfully and the tool fails on every call. The console doesn't show pinned values either, so verify with get-gateway-target.

Standard vs. Express matters

With Standard, the agent can start, list, describe, read history, stop, and complete callback steps. Executions can last up to a year. With Express, you get StartSyncExecution, which returns the result in the same call, but DescribeExecution, GetExecutionHistory and StopExecution return InvalidArn on Express executions, and .waitForTaskToken isn't supported. If your agent needs to "start it and check back later", use Standard.

Humans in the loop, and the catch

The callback pattern is the most interesting part. A step with .waitForTaskToken sends a token somewhere (SQS, a ticket, an approval UI) and waits until someone calls SendTaskSuccess or SendTaskFailure. A support agent can start a refund; above a threshold, the workflow parks until a human approves. The agent can only tell the customer "it's under review".

The catch: IAM has no resource-level permissions for SendTaskSuccess, SendTaskFailure and SendTaskHeartbeat. They are granted on "*", so any agent holding a valid token can complete that task, even for state machines that aren't exposed on the gateway (an AWS Community Builder confirmed this in testing). Treat tokens as secrets and put SendTask* tools on a separate gateway used only by whoever is supposed to approve.

Hands-on

Everything below follows the official tutorial, adapted to a refund workflow. Use the same Region for all resources and a recent AWS CLI v2 (in community testing, 2.34.24 rejected the connector block and 2.39.3 worked).

The workflow keeps the decisions in ASL, not in the prompt:

{ "StartAt": "CheckEligibility", "States": { "CheckEligibility": { "Type": "Task", "Resource": "arn:aws:states:::lambda:invoke", "Parameters": { "FunctionName": "check-refund", "Payload.$": "$" }, "OutputPath": "$.Payload", "Retry": [{ "ErrorEquals": ["States.TaskFailed"], "MaxAttempts": 2, "BackoffRate": 2 }], "Next": "NeedsApproval" }, "NeedsApproval": { "Type": "Choice", "Choices": [{ "Variable": "$.amount", "NumericGreaterThan": 500, "Next": "WaitForApproval" }], "Default": "IssueCredit" }, "WaitForApproval": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/approvals", "MessageBody": { "order.$": "$", "taskToken.$": "$$.Task.Token" } }, "TimeoutSeconds": 86400, "Next": "IssueCredit" }, "IssueCredit": { "Type": "Task", "Resource": "arn:aws:states:::lambda:invoke", "Parameters": { "FunctionName": "issue-credit", "Payload.$": "$" }, "OutputPath": "$.Payload", "End": true } } }

The gateway's service role trusts bedrock-agentcore.amazonaws.com and needs two statements, because execution ARNs are a different resource type than state machine ARNs: StartExecution/ListExecutions/DescribeStateMachine on arn:aws:states:REGION:ACCOUNT:stateMachine:Refunds, and DescribeExecution/GetExecutionHistory/StopExecution on arn:aws:states:REGION:ACCOUNT:execution:Refunds:*.

Create the gateway and the connector target:

aws bedrock-agentcore-control create-gateway \ --name "step-functions-gateway" \ --protocol-type MCP \ --authorizer-type AWS_IAM \ --role-arn "arn:aws:iam::${ACCOUNT_ID}:role/AgentCoreGatewayToStepFunctions" SM_ARN="arn:aws:states:${AWS_REGION}:${ACCOUNT_ID}:stateMachine:Refunds" aws bedrock-agentcore-control create-gateway-target \ --gateway-identifier "GATEWAY_ID" \ --name "refunds" \ --target-configuration '{ "mcp": { "connector": { "source": { "connectorId": "states" }, "configurations": [ { "name": "StartExecution", "parameterValues": { "stateMachineArn": "'"$SM_ARN"'" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "'"$SM_ARN"'" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]'

Call it the way an agent would, signing with SigV4 via awscurl:

awscurl --service bedrock-agentcore --region $AWS_REGION \ -X POST "$GATEWAY_URL" -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{ "name":"refunds___StartExecution", "arguments":{"input":"{\"order\":\"A-1029\",\"amount\":720}"}}}'

Note that input is a string containing JSON, not an object. It's the most common failure when a model builds the arguments.

If your agents run on Amazon EKS, give the agent's service account a Pod Identity role with only bedrock-agentcore:InvokeGateway on that gateway. The pod can reach one gateway; the gateway can reach specific state machines.

A few more things the community found: tools/list returns tools alphabetically; CloudTrail shows the gateway role with a fixed session name as the caller and hides input, so you need your own correlation ID (inside input or via traceHeader) to tie an execution back to an agent session.

Reference architectures from AWS

AWS's Architecture Blog published the complementary pattern a week earlier: a workflow that owns every routing decision while an AgentCore agent reasons inside one bounded step.

The workflow controls routing; the agent works inside a single step. Image: AWS.

And MoEngage's write-up shows where this goes at scale: around 400 internal APIs exposed as agent tools through one gateway, with Cedar policies per agent.

Gateway as the single tool catalog for an organization. Image: AWS.

Pricing

There's no connector fee. In us-east-1, Step Functions Standard costs $0.000025 per state transition (4,000 free per month), Express costs $1.00 per million requests plus $0.00001667 per GB-second, and AgentCore Gateway charges $0.005 per 1,000 invocations, $0.025 per 1,000 search calls and $0.02 per 100 indexed tools per month.

My own rough math: 100,000 refunds a month on a six-transition Standard workflow is about $14.90 in transitions; five gateway calls per refund adds $2.50. Model tokens will dwarf both. The cheapest optimization is reducing polling: every DescribeExecution is a gateway call and another model turn, so for long processes, notify at the end instead.

Availability and data residency

AgentCore Gateway, and therefore the connector, is available in 22 Regions including South America (São Paulo). Remember the gateway only calls Step Functions in its own Region, the agent's input ends up in execution history (retention and encryption apply), and includedData: "ALL_DATA" sends execution input and output back into the model's context.

My take

The connector is useful, but the real value is the division of responsibility it forces: the model picks when and with what data, the workflow owns the how, and IAM plus pinning define the reach. It's the same rule we apply to humans in operations (you can request a deploy; the pipeline decides the steps and gates), applied to agents. What's missing is native correlation between an execution and the agent session that started it. Start with read-only or low-impact workflows, one gateway per permission boundary, and keep SendTask* away from agents until you know exactly who approves what.

Resources