Step Functions vira ferramenta de agentes de IA via AgentCore Gateway

Desde 29 de outubro, workflows do Step Functions passam a ser expostos como ferramentas no Amazon Bedrock AgentCore Gateway. O agente decide quando rodar; a lógica de negócio continua intacta na state machine.

Desde 29 de outubro, workflows do Step Functions passam a ser expostos como ferramentas no Amazon Bedrock AgentCore Gateway. O agente decide quando rodar; a lógica de negócio continua intacta na state machine.

O problema

Muita automação séria já roda em Step Functions: um workflow discover → process → report que varre arquivos, processa cada um e manda um relatório. Esse padrão aparece repetido numa série de patterns serverless sobre FSx for ONTAP com S3 Access Points, mantida pelo AWS Community Builder Yoshiki Fujiwara.

O problema é o ponto de entrada. Esses workflows historicamente são disparados por um agendamento no EventBridge ou por alguém rodando um comando à mão. Não existe um jeito natural de dizer "resuma os arquivos não processados daquela pasta" e deixar o sistema decidir sozinho quando e como iniciar a execução.

Reescrever a lógica como se fosse um agente do zero (com Strands, por exemplo, escrevendo cada tool na mão) funciona, mas duplica o que já existe. O que faltava era uma ponte entre o workflow pronto e um agente de IA, sem tocar no código da state machine.

A arquitetura

Em 29 de outubro de 2026, a AWS anunciou que workflows do Step Functions passam a estar disponíveis como ferramentas de agente de IA através do Amazon Bedrock AgentCore Gateway, via um conector nativo (connectorId: "states"). Fujiwara aplicou essa novidade ao workflow de processamento de arquivos da série e publicou o resultado como um novo pattern no repositório, em solutions/genai/stepfunctions-agentcore-tools/.

O fluxo, do pedido do usuário ao dado processado, funciona assim:

1. Alguém (ou outro agente) manda uma instrução em linguagem natural para o agente, por exemplo "processe os arquivos pendentes naquela pasta".
2. O agente consulta o Gateway e enxerga as ferramentas expostas pelo target workflow, entre elas workflow___StartExecution.
3. O agente decide chamar StartExecution, passando o input (quais arquivos, qual pasta) de acordo com o que entendeu do pedido.
4. O Step Functions assume a partir daí: a etapa Discovery varre o S3 Access Point e monta a lista de arquivos a processar.
5. A etapa Processing lê cada arquivo, resume e classifica o conteúdo com um modelo do Bedrock, calcula uma pontuação de confiança e anexa uma decisão de revisão humana.
6. A etapa Report agrega os resultados, aplica um rótulo de classificação de dados e envia um resumo via SNS.
7. O agente acompanha o progresso chamando workflow___DescribeExecution para status e resultado, e workflow___GetExecutionHistory para ver as transições de etapa.

A divisão de trabalho é exatamente essa: o agente decide quando rodar e o que passar de input; a ordem das etapas e as regras de negócio continuam fixas na state machine, do jeito que foram escritas.

Os serviços envolvidos

O conector do Step Functions no AgentCore Gateway expõe dez operações no total. Quatro delas fixam um ARN de state machine no target: StartExecution, StartSyncExecution, ListExecutions e DescribeStateMachine. O ARN fixado nunca aparece como argumento da ferramenta, então o agente não consegue apontar para uma state machine diferente da que foi configurada.

As outras seis operações recebem um ARN de execução ou um task token fornecido pelo próprio agente; a fonte não nomeia todas elas, mas cita explicitamente DescribeExecution, GetExecutionHistory e SendTaskSuccess entre as envolvidas no pattern. No pattern de Fujiwara, só cinco tools apareceram no tools/list, porque o workflow é Standard (com histórico de execução) e o pattern não usa task tokens nem resposta síncrona.

A infraestrutura inteira é declarada como código. O Gateway e o target do conector são recursos nativos de CloudFormation, AWS::BedrockAgentCore::Gateway e AWS::BedrockAgentCore::GatewayTarget, então entram no mesmo template que as Lambdas, a state machine e a role de IAM. Um único sam deploy já deixa o Gateway funcional, sem comando separado para criá-lo.

Isso muda o que antes era necessário para expor um workflow a um agente. A integração que já existia no repositório usa uma Lambda como target: nesse caso, a Lambda vira a ferramenta e você escreve a definição da tool à mão. No conector, é o contrário: as operações da state machine viram as ferramentas, o Gateway gera as definições sozinho, e qualquer Lambda dentro do workflow continua invisível para o agente, chamada só como Task interna.

Trade-offs

O primeiro trade-off é de confiabilidade. Gateway e state machine precisam estar na mesma região: o Gateway chama o Step Functions na própria região em que roda, então uma state machine noutra região simplesmente não pode ser conectada. Na prática, isso significa manter Gateway e workflow na mesma região, sem poder cruzar região para aproveitar algum serviço do Bedrock que só exista em outro lugar.

O segundo é de segurança. Cada operação pinada aceita uma única state machine; para expor vários workflows, é preciso um target por workflow, o que multiplica a superfície de configuração conforme o catálogo cresce. Task tokens, por sua vez, não podem ser restritos por IAM: quem possui um token válido completa a tarefa, ponto. O pattern de Fujiwara evita esse risco simplesmente não expondo task tokens ao agente.

O terceiro, também de segurança, é uma limitação concreta do Cedar hoje: autorização condicionada ao corpo da entrada (um valor, um motivo) ainda esbarra num erro de avaliação de tipo. O post do Classmethod que inspirou Fujiwara relatou o mesmo comportamento. Decisão por valor do input continua tendo que morar num estado Choice dentro do workflow, não numa política Cedar.

Há ainda um ponto de excelência operacional: as descrições das tools geradas pelo conector são genéricas, sem o formato esperado do JSON de entrada. Isso precisa ir para o system prompt do agente ou para uma skill, porque o Gateway não documenta sozinho o contrato de input de cada workflow.

O divisor é esse: não entregue tudo ao agente, fixe no workflow os passos que você quer forçados. Se você precisa decidir por valor do corpo da entrada, isso sempre foi um estado Choice no workflow.

Don't hand everything to the agent; pin the steps you want enforced into the workflow. If you want to branch on the input body, that was a Choice state in the workflow all along.Yoshiki Fujiwara, AWS Community Builder

Custo estimado

A fonte é explícita sobre não trazer números: o próprio autor chama o teste de "smoke test, não medição" e promete um follow-up com ambiente, região, modelo e quantidade de arquivos quando fizer a medição de fato. Não há, portanto, nenhum valor de custo ou latência confirmado neste material, e inventar um aqui seria dar uma precisão que a fonte não tem.

O que dá para antecipar, sem números, é onde o custo vai aparecer: nas chamadas ao AgentCore Gateway por invocação de ferramenta, nas transições de estado do Step Functions (cobradas por execução e por transição no plano Standard) e nas invocações ao modelo do Bedrock usado na etapa de resumo/classificação de cada arquivo. Para quem for estimar, o ponto de partida são as páginas de preço de Bedrock AgentCore e de Step Functions, cruzadas com o volume esperado de arquivos e execuções do seu próprio workflow.

Como adaptar

O pattern inteiro está publicado no repositório FSx-for-ONTAP-S3AccessPoints-Serverless-Patterns, em solutions/genai/stepfunctions-agentcore-tools/, e sobe com sam build seguido de sam deploy. O autor verificou o funcionamento num deploy real em ap-northeast-1 (Tóquio), em DemoMode, processando 3 de 3 arquivos com sucesso e os rótulos de categoria e classificação de dados aparecendo corretamente no resultado.

Para adaptar a um workflow próprio, o roteiro que a fonte sugere é direto:

• Se o workflow já é Standard e você só precisa de start/status/histórico, o conector cobre o caso sem escrever Lambda ou servidor MCP.
• Se você precisa de resposta síncrona, olhe para Express com StartSyncExecution; a fonte deixa isso fora do escopo do pattern atual, por enquanto sem recursos de histórico.
• Escreva no system prompt do agente (ou numa skill) o formato exato do JSON de entrada esperado pelo workflow, já que o conector não gera essa documentação sozinho.
• Para fluxos com aprovação humana via task token, trate o token como segredo e não o exponha diretamente ao agente; a fonte cita a referência da própria AWS de sinal orientado a evento acionando aprovação humana como caminho mais seguro.
• Se a autorização depende do conteúdo do corpo da requisição, modele isso como um estado Choice dentro da state machine em vez de tentar expressar em Cedar, que hoje não cobre esse caso.

Quem opera plataforma pode usar o mesmo caminho para dar entrada por conversa a qualquer workflow hoje disparado por EventBridge ou à mão, sem tocar na lógica de negócio. Quem desenvolve processamento de documentos (contratos, notas fiscais, formulários) ganha um jeito de deixar o usuário de negócio iniciar e acompanhar a execução, com os passos fixos continuando garantidos pela state machine. A fonte também registra, sem confirmar por conta própria, um relato de mojibake em texto japonês atravessando o Gateway, com workaround de escapar os caracteres para \uXXXX antes de enviar: vale testar com acentuação e caracteres não-ASCII do português antes de confiar cegamente no pattern em produção.

Fonte 1: DEV Community — AWS Community Builders (https://dev.to/aws-builders/turning-a-step-functions-workflow-into-ai-agent-tools-through-agentcore-gateway-4ld7)

Post de Yoshiki Fujiwara, AWS Community Builder, publicado em DEV Community, descrevendo como o conector nativo do Step Functions no Amazon Bedrock AgentCore Gateway (connectorId: "states") permite expor um workflow Standard já existente como ferramentas de agente, sem reescrever a lógica de negócio. O autor aplica a novidade ao pattern de processamento de arquivos com FSx for ONTAP e S3 Access Points da própria série, publica o código em solutions/genai/stepfunctions-agentcore-tools/ e detalha a arquitetura do conector, a divisão entre Lambda-target e connector-target, e os pontos de atenção em confiabilidade, segurança (task tokens, limitação atual do Cedar para autorização por corpo da requisição) e operação (descrições genéricas das tools).

O autor é explícito quanto ao que o post não cobre: números de performance e custo (chama o deploy em ap-northeast-1 de "smoke test, não medição"), workflows Express com resposta síncrona, a implementação do agente em si e um build-out completo de Cedar, deixando esses pontos para um follow-up futuro.

Fonte: DEV Community — AWS Community Builders