Step Functions Workflows as AgentCore Gateway Tools: Where Agents Stop and State Machines Start
Prompt & Circuit Editorial
October 30, 2026 · 12 Min Read

Why this matters
Agents are good at deciding what to do next, but some business processes must run the same steps in the same order every time and leave a record of what ran [5]. On Oct 29, 2026, AWS announced that AWS Step Functions workflows can be used as tools for AI agents through Amazon Bedrock AgentCore Gateway [1]. The agent decides when to run a workflow and what input to pass, and Step Functions runs each step exactly as defined [1]. For architects, this is a concrete way to draw a line between flexible reasoning and controlled execution.
What the connector is
AgentCore Gateway includes a built-in Step Functions connector. You create a gateway target that uses it and choose which Step Functions operations to expose as tools, and agents discover and call them through the Model Context Protocol (MCP) [2]. The gateway creates the tool schemas and authenticates to Step Functions with the gateway service role, so you do not write a Lambda function or an MCP server and do not define the tools yourself [2]. Existing Standard and Express state machines can be exposed without changes [2].
The division of labour is explicit in the documentation: the agent decides when to run the workflow and what input to pass, while the state machine decides which steps run and in what order, so the agent cannot skip or reorder them [2]. AWS positions this for processes that must follow an approved sequence, or where you need a record of each step for audit [2].
Ten operations, two kinds
The connector exposes ten operations [2]. They split into two groups, and the split drives most of the security design.
Four operations act on a state machine that you pin when you create the target: StartExecution, StartSyncExecution, ListExecutions and DescribeStateMachine [2]. The agent does not see the pinned state machine and cannot change it, and the gateway rejects any call that tries [2]. If an agent passes stateMachineArn anyway, the call is rejected with the error "Invalid request parameters: cannot set parameter(s): [/stateMachineArn]" [2]. Each operation takes one pin in a target, so exposing several state machines for the same operation means creating a target for each one [2].
The other six operations act on an execution ARN or a task token that the agent provides: DescribeExecution, StopExecution, GetExecutionHistory, SendTaskSuccess, SendTaskFailure and SendTaskHeartbeat [2]. These are not limited to the pinned state machine, and the gateway service role's IAM policy controls what they can reach [2].
Setup and discovery flow
The documented flow has five stages [2]:
- Create a gateway and add a Step Functions target with connectorId "states", choose which operations become tools, and pin a stateMachineArn on each operation that supports it [2].
- The agent calls tools/list and discovers one tool for each configured operation; pinned parameters do not appear in the schemas, so StartExecution advertises only input [2].
- The agent calls tools/call, and the gateway merges the pinned parameters with the agent's arguments and authenticates with the gateway service role [2].
- The tool returns the Step Functions API response, such as the new execution's ARN, as JSON inside the tool result's text content [2].
- The agent chains tools, for example StartExecution, then DescribeExecution with the returned ARN, then GetExecutionHistory [2].
Each tool name is prefixed with the target name [2]. When Step Functions returns an error, the result has isError set to true and the text names the Step Functions error, such as ExecutionDoesNotExist or StateMachineTypeNotSupported [2].
One setup trap is worth noting. If you leave out parameterValues.stateMachineArn on a pinnable operation, the gateway can still create the target, but the tool fails on every call because no state machine is supplied [2].
Standard versus Express
Some operations only work with one workflow type, and Step Functions returns the resulting errors rather than the connector [2].
| Operation | Works with | What happens otherwise |
|---|---|---|
| StartSyncExecution | Express only | Fails on a Standard state machine; use StartExecution and poll with DescribeExecution [2] |
| ListExecutions | Standard only | Fails with StateMachineTypeNotSupported on an Express state machine [2] |
| DescribeExecution, GetExecutionHistory, StopExecution | Standard executions only | Fail with InvalidArn on an Express execution ARN, because Express executions cannot be addressed by ARN after they start [2] |
| StartExecution, DescribeStateMachine, SendTaskSuccess, SendTaskFailure, SendTaskHeartbeat | Both | Not applicable [2] |
If you need both types behind one target, pin StartSyncExecution to an Express state machine and the other pinnable operations to a Standard one [2]. The tool descriptions returned by tools/list state these constraints so the agent can choose the right tool [2].
The practical consequence is that Express workflows suit synchronous request-response: StartSyncExecution returns the result in the same tool call [2]. Standard workflows are the choice when you need follow-up inspection, because they record every step in an execution history and can run for up to one year, so work can continue after the agent's session ends [2].
Human-in-the-loop with task tokens
Agents and workflows can cooperate in two ways: the agent starts, checks and stops a workflow, or a workflow pauses and waits for the agent to complete a task [2]. In the second case the workflow uses a task with the callback pattern (.waitForTaskToken), and Step Functions creates a task token [2]. Your workflow must deliver the token and task details to the agent's application, for example through an Amazon SQS queue or an Activity that the application polls [2]. The agent then calls SendTaskSuccess with the result or SendTaskFailure if it cannot finish, and SendTaskHeartbeat for long tasks [2]. This pattern works only with Standard workflows, because Express workflows do not support the callback pattern [2].
The security model: pinning plus IAM
Pinning and IAM are complementary controls, not alternatives [2]. Pinning restricts which state machine the four pinnable operations touch. IAM on the gateway service role covers the rest.
You can limit DescribeExecution, StopExecution and GetExecutionHistory by scoping the role's policy to the execution ARNs of the state machines you expose, instead of granting states:* [2]. The task-token operations are different: IAM cannot limit SendTaskSuccess, SendTaskFailure and SendTaskHeartbeat to specific executions, so any agent with a valid task token can complete that task [2]. They have no resource-level permissions and must be granted on "*" [2]. The documentation's advice is to treat task tokens as secrets and send them only to the agent that should act on them [2].
By default, DescribeExecution returns metadata only, and setting includedData to ALL_DATA includes the execution's input and output [2]. Similarly, DescribeStateMachine defaults to METADATA_ONLY, and ALL_DATA includes the state machine definition [2]. Whether to expose those fields is a data-governance decision: fields such as name and traceHeader on StartExecution, or maxResults and nextToken on ListExecutions, can be made visible through parameterOverrides, and stateMachineArn can never be exposed that way [2].
When to use a workflow tool instead of a free-running agent
AWS Prescriptive Guidance recommends, as a best practice, using Step Functions for controlled processes and Amazon Bedrock Agents for natural language interaction and flexible goal fulfillment [4]. It describes Step Functions as deterministic, with steps explicitly defined and transitions condition-based [4]. For fine-grained audit trails it lists Step Functions as providing a full state trace, against a limited trace for agents that depends on agent logs [4].
The documentation lists several uses for the connector [2]:
- Triggering order-fulfillment, onboarding or data-processing workflows from conversation [2].
- Human-in-the-loop and long-running tasks on Standard workflows [2].
- Operational assistants that report which executions ran recently, why one failed, or stop a misbehaving one [2].
- Synchronous request-response through Express workflows [2].
The Step Functions documentation adds that this lets an operations assistant answer such questions without direct access to the Step Functions API [5]. The announcement gives a refund example: the agent starts the refund workflow, and Step Functions runs the eligibility check, manager approval and credit steps, so every refund follows policy [1].
The integration also runs in the other direction: a Step Functions workflow can invoke an agent as one of its steps [5].
Availability and cost
The capability is available in all AWS Regions where Amazon Bedrock AgentCore Gateway is available [1]. The gateway calls the Step Functions endpoint in the same Region as the gateway [2]. AWS states that you pay standard rates for Step Functions and AgentCore Gateway [1]. This article does not quote prices because the sources reviewed do not state them.
Architect's checklist
- Decide which processes are fixed sequences and which need agent reasoning; expose only the former as workflow tools [4].
- Pin every pinnable operation you include, and verify parameterValues.stateMachineArn is set, since an unpinned tool fails on every call [2].
- Create one target per state machine for each operation, since each operation takes one pin per target [2].
- Match operations to workflow type: StartSyncExecution for Express, ListExecutions and execution-ARN operations for Standard [2].
- Scope the gateway service role to the execution ARNs of the exposed state machines instead of granting states:* [2].
- Treat task tokens as secrets and deliver each only to the agent that should act on it [2].
- Decide deliberately whether agents may see ALL_DATA, since it exposes execution input and output [2].
- Use Standard workflows when you need an execution history for audit [2].
Sources
Numbers in square brackets refer to these sources, checked on 2026-10-30.
Responses (0)
Sign in to join the conversation and share your thoughts.

Prompt & Circuit Editorial
Contributing Editor
Articles on AI infrastructure for cloud architects, written from official vendor sources and checked claim by claim before publishing.
Continue Reading

MCPRoute on Application Gateway for Containers: One Governed Front Door for MCP Servers
Application Gateway for Containers can now route and aggregate Model Context Protocol servers running in Kubernetes. Here is what the preview changes, where it stops, and what to check before adopting it.

Web Answer on Amazon Bedrock AgentCore: When a Managed Cited-Answer Tool Beats Your Own Search Pipeline
Web Answer is now generally available on AgentCore Gateway. Here is how it differs from Web Search, what it costs, and which limits matter before you put it in front of an agent.

From "Just a Chatbot" to a Full AI System: The Layers Explained
Modern AI products are not a single model behind a text box. A layer-by-layer guide to the stack: LLMs, retrieval-augmented generation, tools and agents, the Model Context Protocol, and the runtime that keeps it all reliable.