Step Functions usa task token para colocar humano no loop de agentes de IA

Um tutorial publicado no DEV Community mostra como usar o padrão de callback do Step Functions para pausar um agente, pedir aprovação humana e escalar quando ninguém responde, sem depender de uma instrução no prompt.

Um agente de suporte que concede um crédito de 5 euros é conveniente. O mesmo agente devolvendo 480 euros depois de uma reclamação bem escrita é um problema. Essa é a linha que o desenvolvedor que assina como sascha-ms no DEV Community usa para justificar por que todo agente que age no mundo (não só que escreve texto) precisa de um humano no meio do caminho antes de ações caras ou irreversíveis, segundo o tutorial publicado no DEV Community.

O ponto central do tutorial é que essa trava não deve morar no prompt. Um modelo de linguagem pode esquecer uma instrução como "pergunte antes de estornar mais de 20 euros", interpretar mal ou ser convencido a ignorá-la via prompt injection. Uma regra de decisão dentro de um workflow do Step Functions não é convencida de nada: ela só segue o que está escrito na máquina de estados.

O que você vai construir

O projeto do tutorial é uma livraria fictícia com um agente de suporte que pode solicitar créditos para clientes. As regras não ficam no prompt do agente: elas vivem no workflow.

O agente só pode fazer duas coisas: iniciar a execução do workflow e ler o status da própria execução. Ele nunca vê um task token, não tem permissão para chamar a função de decisão e states:SendTaskSuccess não aparece em nenhum lugar do seu papel IAM. Quem decide é sempre um humano, identificado por uma assinatura SigV4 válida.

A peça que faz tudo isso funcionar é o padrão .waitForTaskToken. Quando um estado do tipo Task termina o ARN do recurso com esse sufixo, o Step Functions gera um task token, entrega esse token ao serviço chamado e congela o estado. Ele só volta a andar quando alguém chama SendTaskSuccess ou SendTaskFailure com exatamente esse token.

Com o padrão de callback, o Step Functions pode esperar até um ano por uma resposta, e a espera em si não custa nada.

With the wait for callback pattern, Step Functions can wait up to a year for an answer, and the waiting itself costs nothing.sascha-ms, autor do tutorial no DEV Community

Isso só vale para workflows Standard: Express não suporta o padrão de callback. E o preço é por transição de estado, não por tempo de espera: a fonte cita 0,000025 dólar por transição em us-east-1. Um workflow que espera três dias por uma aprovação custa exatamente o mesmo que um que segue em três segundos, o que muda o cálculo de custo de qualquer agente que precise aguardar decisão humana por horas.

Pré-requisitos

O tutorial usa o Serverless Framework para toda a infraestrutura, com TypeScript nas funções Lambda. Antes de começar, você precisa de:

1. Uma conta AWS onde você possa criar Lambda, Step Functions, DynamoDB, SNS e papéis IAM
2. Node.js 22 ou mais recente e AWS CLI v2 com login funcionando
3. Serverless Framework v4 (npm i -g serverless); a v4 exige conta gratuita ou chave de licença
4. curl 7.75 ou mais recente e jq para o script de aprovação

Na permissão IAM, o papel do agente de IA precisa poder chamar apenas states:StartExecution e states:DescribeExecution. O papel da função de decisão é o único com states:SendTaskSuccess. Separar esses dois papéis é o que torna o token inútil nas mãos de quem não deveria ter acesso a ele.

Passo a passo

1. Criar o projeto. A estrutura básica usa o package.json com "type": "module", porque o Serverless Framework v4 compila os handlers TypeScript com esbuild no deploy, sem plugin extra.

mkdir credit-approval && cd credit-approval
npm init -y
npm i @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/client-sfn @aws-sdk/client-sns
npm i -D typescript @types/node @types/aws-lambda vitest aws-sdk-client-mock asl-validator jsonata
mkdir -p src statemachine test scripts

2. Validar a decisão antes de qualquer coisa. A função approvals.ts define os tipos compartilhados e valida o corpo da requisição: o approvalId precisa ter formato de UUID, decision só aceita approved ou rejected, e o comentário é truncado em 500 caracteres.

export function parseDecision(body: string | undefined): Decision {
  if (!body) throw new Error('Body is missing');
  const data = JSON.parse(body) as Partial<Decision>;
  if (typeof data.approvalId !== 'string' || !/^[0-9a-f-]{36}$/.test(data.approvalId)) {
    throw new Error('approvalId is missing or invalid');
  }
  if (data.decision !== 'approved' && data.decision !== 'rejected') {
    throw new Error('decision must be "approved" or "rejected"');
  }
  const comment = typeof data.comment === 'string' ? data.comment.slice(0, 500) : undefined;
  return { approvalId: data.approvalId, decision: data.decision, comment };
}

3. Pedir a aprovação. O Step Functions invoca essa função com o token. Ela grava o token junto com o pedido no DynamoDB e publica uma mensagem no SNS que contém apenas o approvalId, nunca o token em si.

await db.send(new PutCommand({
  TableName: process.env.TABLE_NAME,
  Item: { approvalId, taskToken: event.taskToken, stage: event.stage,
    executionId: event.executionId, request: event.request, status: 'PENDING' },
  ConditionExpression: 'attribute_not_exists(approvalId)',
}));

O motivo de não colocar o token no e-mail é simples: e-mails são encaminhados, ficam em caixas de entrada e aparecem em logs de gateway. Um approvalId sozinho não serve para nada a quem não tem acesso à tabela.

4. Receber a decisão. Essa é a peça central do padrão. A função fica atrás de uma Function URL com autenticação AWS_IAM, então toda requisição chega assinada, e o Lambda informa quem assinou. O tutorial faz três verificações nessa função: o princípio dos quatro olhos (quem pediu o crédito não pode aprová-lo), uma atualização condicional no DynamoDB (quem clica primeiro vence, o segundo recebe 409) e o tratamento de prazo expirado.

if (decidedBy === Item.request.requestedBy) {
  return reply(403, { message: 'You cannot approve your own request' });
}
try {
  await sfn.send(new SendTaskSuccessCommand({
    taskToken: Item.taskToken,
    output: JSON.stringify({ decision: input.decision, decidedBy, comment: input.comment ?? '' }),
  }));
} catch (error) {
  if (error instanceof TaskTimedOut || error instanceof InvalidToken) {
    return reply(410, { message: 'The deadline for this approval has passed' });
  }
  throw error;
}

Se o prazo já passou e o workflow escalou para o líder do time, o Step Functions responde com TaskTimedOut, e a função marca a entrada como expirada. O detalhe que faz o quatro olhos funcionar de verdade é que requestedBy precisa vir do código da ferramenta do agente, não do próprio modelo de linguagem: se o LLM preenche esse campo sozinho, a verificação não vale nada.

5. Aplicar o crédito. No exemplo, aplicar o crédito é um placeholder, mas a chave de idempotência é derivada do número do pedido e do valor, então um retry do Step Functions depois de um erro não gera um crédito duplicado, desde que o sistema de contabilidade use essa chave.

6. Escrever o workflow em JSONata. O tutorial usa a linguagem de consulta JSONata, mais recente que os antigos caminhos .$, e mais fácil de ler. O token chega via $states.context.Task.Token, e o Assign mantém o pedido original e a decisão disponíveis nos passos seguintes.

"AskTeam": {
  "Type": "Task",
  "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
  "Arguments": {
    "FunctionName": "${RequestApprovalArn}",
    "Payload": {
      "taskToken": "{% $states.context.Task.Token %}",
      "stage": "team",
      "request": "{% $request %}"
    }
  },
  "TimeoutSeconds": 14400,
  "Catch": [{ "ErrorEquals": ["States.Timeout"], "Next": "AskLead" }]
}

Quatorze mil e quatrocentos segundos são as 4 horas do prazo do time. Se ninguém responde, o Catch de States.Timeout leva para AskLead, que repete a mesma estrutura com TimeoutSeconds de 72000 (20 horas) para o líder do time. Se o líder também não responder, o workflow publica um aviso final no SNS e termina sem aplicar nenhum crédito.

Testando

Para testar o fluxo, o caminho é iniciar uma execução com aws stepfunctions start-execution passando um JSON com orderId, amountCents e reason, e acompanhar com aws stepfunctions describe-execution. Com um valor entre 20,01 e 500 euros, a execução para no estado AskTeam, grava o token no DynamoDB e publica no SNS uma mensagem terminando em "Decida com: ./decide.sh <ID de aprovação> approved|rejected \"comentário\"", exatamente como o SNS informa no tutorial.

Rodar o script de decisão assinado com credenciais IAM (a Function URL exige AWS_IAM) completa o estado e a execução segue para ApplyCredit. Vale testar os três caminhos separadamente: aprovação dentro do prazo, rejeição explícita e deixar o prazo estourar de propósito para confirmar que o Catch de States.Timeout escala para AskLead e que a função de decisão responde 410 se alguém tentar decidir depois que o token já expirou.

Limpando os recursos

Como toda a infraestrutura nasce do Serverless Framework, sls remove desfaz os recursos criados pelo deploy. Vale conferir manualmente no console se não sobrou nenhum log group no CloudWatch Logs antes de considerar a limpeza concluída.

O workflow em si não gera custo residual: como a espera em workflows Standard não é cobrada, não existe execução parada que precise ser encerrada manualmente por questão de fatura. O custo do exercício vem das transições de estado e das invocações Lambda de teste, cobradas por uso.

Próximos passos

O tutorial faz parte de uma série do mesmo autor sobre expor ferramentas de agentes via Step Functions e o AgentCore Gateway, onde a recomendação já era tirar aprovações da caixa de ferramentas do agente. Para quem já construiu um agente com Amazon Bedrock Agents ou com um Action Group chamando Step Functions, esse é o próximo bloco natural: o agente chama a StartExecution como uma ferramenta, e o .waitForTaskToken vira a camada de aprovação que nenhum prompt consegue contornar.

Duas extensões valem a pena para quem for adaptar o padrão: trocar o script de linha de comando por botões interativos no Slack (via AWS Chatbot) para reduzir o atrito de quem aprova, e criar um alarme no CloudWatch que dispare quando o estado NotifyExpired for atingido, porque uma aprovação que expira sem decisão é, na prática, um agente parado esperando um humano que nunca apareceu.

Fonte: DEV Community — #aws