AWS Builder Center

Builder Center

AgentCore Gateway Turns Step Functions Into Agent Tools

Golden Jacket Field Notes. Week 23

Series: Golden Jacket Field Notes (24 articles)

  1. 1
    The Cheapest Price Per Token Can Be the Most Expensive Way to Run an LLM
  2. …
  3. 24
    AgentCore Gateway Turns Step Functions Into Agent Tools This article

Erick Mancz

AWS Golden Jacket | Co-founder Golden Jackets Brazil Community | 40 AWS Credentials
Golden Jacket Field Notes. Week 23

In Week 18 I gave some advice. If an agent comes off the whiteboard looking like a flowchart, stop bending it into a loop through prompt engineering. Push the graph into Step Functions and put harness invocations at the nodes. I still believe that. Reading the AWS announcement from October 29, though, I realized I had drawn the arrow in only one direction.
In my version, the workflow is in charge and calls the agent whenever it needs judgment. The new Step Functions connector for AgentCore Gateway works the other way. The agent runs the conversation, and when it needs something done the same way every time, it calls the workflow. AWS now offers both directions as managed features. The second one is the one that will change how I review an agent design next week.
Before going further I owe you a disclosure. I have not run this connector against a production workload. As I write this, it is four days old. Everything below comes from a close reading of the documentation and from the first practitioner test reports. Most of those reports came out of Japan within days of the launch, which says a lot about who is paying attention right now.

The Tool That Was Really a Permission

I have seen the same pattern in enough architecture reviews to stop treating it as a coincidence.
A team has a working agent. At some point it needs to do something with consequences: issue a refund, open an account, change an order, kick off a provisioning run. In most of these companies the process already exists as a Step Functions state machine. Another team built it years ago, with retries, an approval step, a Catch block for each failure mode the business ever hit, and an execution history that the auditors already know how to read.
So someone writes a Lambda function to act as the agent's tool. It takes the agent's arguments, builds a JSON payload and calls  StartExecution . Someone else writes the tool description by hand, and that description starts drifting away from the workflow the first time the workflow changes. Then someone gives the Lambda execution role  states:StartExecution , and often on a wildcard, because the agent "might need the other workflows later" and nobody wants to come back to IAM (Identity and Access Management) next sprint.
The reasoning in the room sounds solid. The workflow has the approval step, so the agent can't skip the approval. That part is true. The state machine does enforce its own sequence. What the state machine can't enforce is which state machine gets started, how often, with what input, or whether the agent can also stop an execution someone else started. All of that sits in the Lambda code and the Lambda role, two places that security teams rarely review as policy because they look like application code.
Then the security review asks the obvious question: which workflows can this agent start? The honest answer is whatever the Lambda code and its role allow, so go read the code. The second question is who started execution number four hundred and twelve, and the honest answer is the Lambda role. That covers every user and every agent session, all collapsed into one principal.
In units a manager understands, that costs a security review that stalls for three weeks waiting on someone to document a permission model that was never designed. Or something worse: a review that passes because nobody thought to ask.

We Have Moved This Kind of Control Before

Strip away the agent detail and the shape looks familiar. A control that lived in code moves into configuration owned by a managed service. When that happens, the control becomes reviewable and it also becomes concentrated.
AWS has run this play many times. Long-lived access keys hardcoded into application config turned into IAM roles attached to compute, so credential policy became something you could read in a console instead of grepping for. Hand-written bucket policies meant to keep data private became S3 Block Public Access, a setting an auditor can check in one screen. Lambda functions whose only job was to call DynamoDB or SQS from inside a workflow became direct Step Functions service integrations, which deleted a whole layer of glue code along with its IAM roles.
Every one of those moves did two things at once. It made the control legible to people who don't read code. And it concentrated the blast radius in one object, a role, a setting or an integration, which you now have to get right in one place instead of in many places that were each slightly wrong.
The Step Functions connector follows the same arc. The stakes are higher because of who calls the tool. A Lambda function behind a REST API is called by code you wrote. A tool on an agent is called by a model that reads untrusted text for a living: user messages, retrieved documents, web pages, email bodies. A successful prompt injection can make the model want to call a different workflow with a different payload. The value of this connector is that it moves the answer to "which workflow" out of the model's reach and out of the tool code's reach. The answer goes into a target configuration the model never sees.

How the Connector Splits the Work

One sentence to anchor everything

The documentation states the division of labor almost exactly the way I would. 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. Everything else in this section either enforces that sentence or marks the places where it stops holding.
Mechanically, you create an AgentCore Gateway target with  connectorId: "states" . In its  configurations  list you choose which Step Functions API operations become tools. The Gateway generates the tool schemas, takes a snapshot of them and calls Step Functions on the agent's behalf with the Gateway service role. You don't write a Lambda function, you don't write an MCP (Model Context Protocol) server, and you don't define the tools yourself. Existing Standard and Express state machines can be exposed without changes. The documentation is explicit about that point, and it is the part that will matter most to companies with a decade of workflows already in production.
Tools show up in  tools/list  named after the target and the operation, joined by three underscores, so a target called  orders  produces  orders___StartExecution . The response is the raw Step Functions API response serialized as JSON inside the tool result's text content. When Step Functions returns an error, the result carries  isError: true  and names the error.

Ten operations, two families

The connector exposes ten operations, and the most useful way to understand them is to split them by how they identify their target.
Four operations act on a state machine:  StartExecution ,  StartSyncExecution ,  ListExecutions  and  DescribeStateMachine . For these, you pin a  stateMachineArn  in the target configuration. The Gateway removes the pinned parameter from the tool schema, so the agent never sees it, and enforces it on every call. If the agent tries to send a  stateMachineArn  anyway, the Gateway rejects the call with an error saying the parameter cannot be set, and no execution gets created. Each operation takes one pin per target. If you want to expose three state machines through  StartExecution , you create three targets.
The other six act on something the agent supplies.  DescribeExecution ,  StopExecution  and  GetExecutionHistory  take an execution ARN (Amazon Resource Name).  SendTaskSuccess ,  SendTaskFailure  and  SendTaskHeartbeat  take a task token. None of these can be pinned, because an execution or a token belongs to a specific run, not to a state machine you know at configuration time.
That split is the most important architectural fact about the connector. For the first family, the configuration is the perimeter. For the second, the perimeter is the Gateway service role.

The service role is the real perimeter

The documentation is direct about this: the Gateway service role is the only thing bounding the six unpinned operations, so scope its IAM policy as tightly as the operations allow. The official tutorial splits the policy into two statements. Operations that act on a state machine get granted on the state machine ARN. Operations that act on an execution get granted on  arn:aws:states:<region>:<account>:execution:<StateMachineName>:* , because execution ARNs are a different resource type from state machine ARNs. The trust policy lets  bedrock-agentcore.amazonaws.com  take the role, with  aws:SourceAccount  and an  aws:SourceArn  condition scoped to your gateway. If you read Week 02 of this series, that confused-deputy protection is the same discipline I showed in the companion Terraform.
One practitioner tested exactly this boundary within days of launch. With execution-scoped permissions in place, calls to  DescribeExecution ,  GetExecutionHistory  and  StopExecution  against an execution of a state machine outside the policy were all denied, and calls against the permitted state machine went through. The design holds when you write the policy correctly. The risk is that "correctly" now lives entirely in one role.

Standard versus Express is a visibility decision

Step Functions has two workflow types, and the connector inherits their constraints.  StartSyncExecution  works only on Express and returns status and output in the same call.  ListExecutions  works only on Standard.  DescribeExecution ,  GetExecutionHistory  and  StopExecution  work only on Standard executions, because an Express execution can't be addressed by ARN after it starts.  StartExecution ,  DescribeStateMachine  and the three task-token operations work with both.
The documentation presents this as a compatibility table. I read it as a visibility decision you make on the agent's behalf. If you expose a Standard workflow, the agent can start it, poll it, read its step history, explain where it stalled, and stop it. Standard executions can run for up to a year, so the work survives long after the agent's session ends. If you expose an Express workflow, the agent gets a fast synchronous answer and nothing else. Once an Express execution is running, the agent can't look at it again.
For the same reason, the documentation suggests a hybrid layout when you need both. Pin  StartSyncExecution  to an Express state machine for quick lookups, and pin the other operations to a Standard one for anything with consequences. The tool descriptions returned by  tools/list  state the Standard-only constraints, so a well-behaved model can choose the right tool.

The callback pattern, and the token problem

The connector supports two cooperation patterns. In the first, the agent starts a workflow, watches it and stops it if needed. In the second, the workflow pauses on a  .waitForTaskToken  task, hands a task token to the agent's application through something like an Amazon SQS (Simple Queue Service) queue, and waits for the agent to finish its part and call  SendTaskSuccess  or  SendTaskFailure . For long tasks, the agent sends  SendTaskHeartbeat  to show it's still working. This pattern works only with Standard workflows, because Express doesn't support callbacks.
The second pattern is powerful and it's where the sharpest edge sits. The three task-token operations have no resource-level permissions in IAM, so the service role must grant them on  "*" . The documentation says it plainly: the task token is the only control, and any agent holding a valid token can complete that task. Treat tokens as secrets.

Cedar sits on top, and it works on tool names

If your Gateway has a Policy Engine attached, Cedar policies evaluate every tool call before it reaches Step Functions. One of the Classmethod engineers who tested the launch wrote a policy that allowed  order___StopExecution  only for a principal whose role name matched a store-manager pattern. For everyone else, the tool disappeared from  tools/list , and calling it directly was denied with a policy enforcement error. That's a clean way to separate who can start a workflow from who can cancel one, without touching the state machine.

The arrow now points both ways

Back in June, AWS shipped the opposite integration: a Step Functions Task state that invokes an AgentCore harness, called  bedrockagentcore:invokeHarness , with per-invocation overrides for model, system prompt and tools. Combine it with the October connector and the loop closes. A workflow can call an agent for judgment at a decision point, and an agent can call a workflow when it needs a guaranteed sequence.
That symmetry is elegant, and I'll come back to the danger it creates in the documentation section. For now, the reference shape I'd draw on a whiteboard looks like this. The agent sits on harness or Runtime. The Gateway fronts the tools, with Cedar policy attached. Read-only workflow operations go on one gateway, consequential start operations on a second gateway with their own service role, and task-token operations on a third, exposed only to the agent that should ever receive tokens. Every consequential write to a system of record goes through a Standard workflow that already has its own approval and history.

What it costs, as a model

AWS lists no separate fee for the connector. You pay standard Step Functions pricing for state transitions, and Express is billed by request and duration. You pay standard AgentCore Gateway pricing for the tool invocations. I'm leaving unit prices out on purpose. They change, and an article with stale numbers looks wrong six months later. Model the bill as one Gateway invocation per tool call plus whatever the workflow consumes once it runs.

The Bigger Picture

The most interesting thing about this launch is what it does to the value of boring infrastructure.
For the last two years, the industry treated agents as the place where new value gets created and workflows as legacy plumbing. Step Functions state machines, the ones written in 2019 to handle refunds or onboarding, with eleven Catch blocks and a human approval step that legal insisted on, were the kind of thing an AI roadmap politely ignored. This connector flips that. Those state machines are now the safest action surface an agent can have. They already encode the sequence the business approved. They already have retries that someone tuned after an incident. They already produce an execution history that an auditor accepts. Overnight, the most AI-ready asset in a regulated company may turn out to be its workflow catalog.

I think the industry is converging on a pattern that Week 07 of this series called deterministic-first, and this launch makes it concrete. The probabilistic part, the model, decides intent and timing. The deterministic part, a state machine, owns any step that writes to a system of record. A policy layer, Cedar on the Gateway, decides who may trigger which deterministic path. Each of those three layers can be reviewed by a different kind of person: a product owner for the agent's behavior, an engineering owner for the workflow, and a security owner for the policy. That separation is what finally makes an agent explainable to a risk committee.

My opinion, plainly stated: within a year, "does this agent write to a system of record through a workflow, or through a direct API tool?" will become a standard question in AWS architecture reviews for regulated workloads, in the same slot where we ask about encryption at rest today. Teams that answer "direct API tool" will need a very good reason.

There is a second trend worth naming. Look at what AgentCore Gateway can front natively as of this month: Managed Knowledge Bases, Web Search, AgentCore Memory, and now Step Functions. Every capability AWS hands to agents lands on the same object. The Gateway is becoming the agent's perimeter in the same way a VPC (Virtual Private Cloud) became the perimeter for compute. That's good news for governance, because there's one place to put policy. It's also a concentration of risk, because one service role, one policy engine and one target list now decide what an agent can touch. Platform teams that treated the Gateway as a convenience layer will need to start treating it as a security boundary, with change control to match.

For careers, the implication rewards a kind of engineer the hype cycle undervalued. The person who spent years writing careful state machines, who knows why a Map state needs a concurrency limit and why the approval step has a 24-hour timeout, now holds the most important design pen in an agent program. Prompt engineering skill depreciates every time a new model ships. Knowing how to cut a business process into deterministic steps with clean failure semantics doesn't depreciate at all. If you're early in your career and wondering where to invest, I'd learn Step Functions error handling well before I'd learn another agent framework.

What the Documentation Does Not Tell You

CloudTrail will tell you the Gateway did it, and nothing more. The tutorial says executions started through the Gateway show the Gateway service role as the caller. A practitioner who looked at the actual events found more detail: the session name was a fixed  gateway-session-invocation  in every event, the event had no field identifying the gateway, the agent or the end user, and the execution input was masked. The execution ARN is recorded, so you can pivot from CloudTrail to the Step Functions execution history and read the input there. If your audit requirement is to know which user's conversation caused this refund, you'll need to carry a correlation identifier inside the workflow input yourself and make the workflow record it. This is the same identity-collapse problem I described in the introduction with the Lambda tool, moved one layer down. Design for it on day one.

A task token is a bearer credential with no IAM boundary. The documentation warns about this, and the warning is easy to read past. The same practitioner proved it the uncomfortable way. They started an execution of a state machine that was not exposed on any Gateway target, took its task token, and completed the task through the Gateway's  SendTaskSuccess  tool. The execution succeeded. Pinning didn't apply and IAM couldn't help, because the action is granted on  "*" . Any token that reaches the agent's context is a key to whatever workflow issued it. Keep task-token tools on a dedicated gateway, deliver tokens only to the agent meant to act on them, and treat a token showing up in a log the way you'd treat an API key showing up in a log.

Every target on a gateway shares one service role. Targets on the same gateway share its service role, so you can't give the refund workflow a tighter IAM boundary than the reporting workflow if they live on the same gateway. The only way to separate permission boundaries per workflow is separate gateways. Feature grids won't tell you this, but it drives your gateway topology more than any other factor. Decide it before the first target exists, because moving tools between gateways later changes the endpoint your agents are configured to call.

Forget the pin and the target still reaches Ready. The documentation says this in one sentence that deserves a warning box. If you include a pinnable operation and leave out  parameterValues.stateMachineArn , the Gateway creates the target anyway, and the tool fails on every call because no state machine is supplied. You get green status in the console and a broken tool in production. This is the same family of silent failure as the Gateway role missing  bedrock:Retrieve  in Week 18, the session cap that a shared role makes decorative in Week 19, and the Lambda Function URL double permission in the Week 02 companion repository. The configuration looks complete and the system doesn't do what you think. Add a smoke test that calls every tool once after each deployment.

The console won't show you your pins. One tester found that the console shows the target type as Step Functions and the status as Ready, but doesn't display the pinned state machine ARNs. They had to read them back with  get-gateway-target  from the AWS CLI (Command Line Interface). The same tester found that an older CLI version rejected the connector configuration outright and only listed the older target types. Upgrading fixed it. If your pipeline runs a pinned CLI version, check it before you blame your template.

Exposing Express gives the agent a button it can't take back. Once an Express execution starts, the agent can't describe it, read its history or stop it. A tester confirmed that all three calls fail with  InvalidArn , even with IAM permissions in place, because the Express execution ARN is a different resource type that those operations don't accept. For a read-only lookup that's fine. For anything that writes, an Express workflow behind an agent is fire and forget. If you'd want to explain or cancel an action afterwards, it belongs in a Standard workflow, whatever that costs in latency.

 includedData: ALL_DATA  is a data exposure switch.  DescribeExecution  returns metadata by default. With  ALL_DATA , it also returns the execution's full input and output, and that goes straight into the model's context window. In regulated workloads that may mean customer identifiers, addresses or account details reaching an LLM (Large Language Model) that never needed them to answer "did my refund go through?" For anyone under LGPD (Lei Geral de Proteção de Dados), GDPR (General Data Protection Regulation) or similar regimes, this is a data minimization decision disguised as a debugging convenience. Review it with the same people who approve what goes into a prompt.

The tool schema tells the agent nothing about your workflow.  StartExecution  exposes one field,  input , typed as a JSON string, with a generic description of the Step Functions API. The agent doesn't learn from the tool what your workflow expects. Testers had to describe the payload shape in the system prompt. The contract between agent and workflow therefore lives in a prompt or a skill, and prompts get edited by people who never open the state machine definition. Make the first state of every agent-facing workflow a strict validation step that fails loudly on an unexpected shape. The workflow is the only party here that can't be talked out of its contract.

Cedar sees the tool, and as of launch it may not see the payload. The tool-level Cedar policy in the Classmethod test worked well. The same author also tried a policy that inspected the content of  input , forbidding orders without a reason field. The policy was accepted at creation time but every call failed at evaluation with a type mismatch, and because Cedar evaluation errors deny by default, every order was blocked. That's a single practitioner's report from October 30, and AWS may already have changed the behavior, so treat it as a pointer to verify rather than a fact. The design lesson holds either way: rules about amounts, thresholds and required fields belong inside the state machine, where they're deterministic and visible in the execution history.

Two kinds of denial produce two different error shapes. A pin violation comes back from the Gateway as an  IllegalArgumentException . An IAM denial comes back from Step Functions wrapped in a  DependencyFailedException  with the  AccessDenied  details nested in a JSON string. If your agent's retry or recovery logic pattern-matches on error text, it needs to handle both, and neither one should ever be retried. A model that sees a generic failure and decides to try again with slightly different arguments is exactly the behavior you want to rule out here.

Stopping the workflow doesn't stop the agent inside it. This one comes from the June integration in the other direction, and it matters the moment you use both. The Step Functions documentation for  invokeHarness  says that stopping an execution or a Task state doesn't stop the harness, that a harness keeps running until its own configured timeout after the Task times out, and that the Task state has a fifteen-minute ceiling. It recommends keeping the harness timeout at or under fifteen minutes to avoid unexpected costs. Now picture a design where an agent starts a workflow, the workflow invokes a harness at a decision point, and that harness has the same Gateway in its tool list. Nothing in the documentation I read prevents that cycle. I haven't tested it, so this is inference from the two pages read together. If you build bidirectional designs, give agents called from workflows a different gateway, without start operations, and set conservative iteration and timeout limits.

Check the region yourself, because the documentation pages disagree. The Gateway calls Step Functions in its own region, so the state machine and the gateway have to be co-located. For those of us building for Brazilian regulated workloads, the obvious question is São Paulo. AWS's What's New post from May 1, 2026 says AgentCore launched in São Paulo with runtime, identity, gateway, policy and observability. When I checked while writing this, the Supported Regions page in the AgentCore developer guide still listed São Paulo as supporting Memory only. One of those two pages is out of date. Confirm in the console of your own account before you write sa-east-1 into a proposal.

The Takeaway

The agent chooses the moment. The state machine owns the steps. The Gateway decides who may press which button.
Pinning protects the four operations that start or describe a workflow. The service role protects the three that read or stop an execution. Only secrecy protects the three that complete a task.
If you already have Standard workflows encoding approved business processes, you're further along in agent readiness than your roadmap says.

Here's the question I keep coming back to. Once an agent can start a workflow, who owns that workflow's change control? Until now, the team that wrote the state machine could change its input contract whenever their own consumers agreed. Now one of those consumers is a model whose understanding of the contract lives in a prompt someone else maintains. I can argue it either way, and both versions leave someone holding a risk they didn't sign up for. If you've already put agents in front of shared workflows, I'd like to know whose pager went off first.


References


This is part of Golden Jacket Field Notes, a weekly practitioner series on production ML, GenAI and cloud architecture on AWS. No re:Invent recaps. No tutorials. Field notes from workloads where outages, audit gaps, and cost surprises are not tolerated. The full index lives at  golden-jacket-field-notes .

Erick Mancz is an AWS Solutions Architect with nearly 15 years in the industry, focused on production ML and GenAI workloads for regulated organizations. He holds every active AWS certification, including the Generative AI Developer Professional as an Early Adopter, the status AWS calls Golden Jacket. He is the sixth Brazilian Golden Jacket holder according to the Awstronauts list, and co-founder of Golden Jackets Brazil, now grown into Golden Jackets Global.

Opinions expressed in articles and code are my own and do not represent the views of my employer or any affiliated organization.
# ai-dlc# ai-engineering# ai-agents# ai# ai-security

Series: Golden Jacket Field Notes (24 articles)

  1. 1
    The Cheapest Price Per Token Can Be the Most Expensive Way to Run an LLM
  2. …
  3. 24
    AgentCore Gateway Turns Step Functions Into Agent Tools This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article