View a markdown version of this page

Use seus fluxos de trabalho do Step Functions como ferramentas para agentes de IA - AWS Step Functions

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Use seus fluxos de trabalho do Step Functions como ferramentas para agentes de IA

Você pode permitir que agentes de IA executem seus fluxos de trabalho do Step Functions expondo uma máquina de estado como ferramentas do Model Context Protocol (MCP) por meio do Amazon Bedrock AgentCore Gateway. Um agente conectado ao gateway pode iniciar execuções, verificar seu status e saída, ler o histórico de eventos e interromper as execuções. Você não precisa escrever uma função do Lambda nem definir as ferramentas sozinho. O gateway cria os esquemas da ferramenta e chama Step Functions para o agente.

Esse padrão é útil quando uma tarefa precisa executar sempre as mesmas etapas na mesma ordem. O agente decide quando executar o fluxo de trabalho e qual entrada passar. A máquina de estado decide quais etapas são executadas, para que o agente não possa ignorá-las ou reordená-las, e o histórico de execução registra cada etapa do fluxo de trabalho.

Você controla o que o agente pode fazer de duas maneiras. As ferramentas que iniciam ou listam as execuções são fixadas na máquina de estado que você escolher, e o agente não pode alterá-la. As ferramentas que atuam em uma execução específica recebem uma execução do Amazon Resource Name (ARN) do agente. O AWS Identity and Access Management a política sobre sua função de serviço de gateway limita quais execuções essas ferramentas podem acessar. Este tutorial define o escopo dessa política em uma única máquina de estado.

Neste tutorial, você cria uma máquina de estado padrão simples e um gateway com um destino de conector Step Functions que aponta para ela. Em seguida, você faz as mesmas chamadas de MCP que um agente faz, usando awscurl, para que você possa ver cada solicitação e resposta. Se você já tem uma máquina de estado padrão, pode pular para Etapa 2: criar uma função de serviço para o gateway e use seu ARN no lugar de AgentHelloWorld. Este tutorial usa um fluxo de trabalho padrão porque ListExecutions, DescribeExecution, e GetExecutionHistory não funcionam com execuções expressas. Os recursos que você cria podem gerar cobranças até que você os exclua no Etapa 6: limpar.

Importante

Os recursos deste tutorial podem gerar cobranças pelo Step Functions, pelas transições de estado e pelo Amazon Bedrock. AgentCore Chamadas da ferramenta Gateway. Para tarifas, consulte Preços do Step Functions e Rocha da Amazônia AgentCore preços. Para evitar cobranças contínuas, exclua os recursos ao terminar, conforme descrito em Etapa 6: limpar.

nota

O conector Step Functions expõe dez operações. Este tutorial configura seis deles: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, e StopExecution. Para ver a lista completa, incluindo as operações de token de tarefa e as diferenças entre os fluxos de trabalho Standard e Express, consulte AWS Funções de etapa como destino do conector na Rocha da Amazônia AgentCore Guia do desenvolvedor.

Pré-requisitos

Antes de começar, verifique se você tem o seguinte:

  • O AWS CLI versão 2, configurado com credenciais para sua conta. As etapas 3 a 6 usam o AWS CLI.

  • Um cliente que pode enviar solicitações HTTP assinadas da Signature Versão 4 para o gateway. Este tutorial usa awscurl, que você pode instalar com pip install awscurl. Qualquer cliente MCP que ofereça suporte ao Signature Version 4 funciona da mesma maneira.

  • Permissão para criar funções do IAM, máquinas de estado do Step Functions e AgentCore gateways em sua conta e o bedrock-agentcore:InvokeGateway permissão no gateway que você cria na Etapa 3 para a identidade que o chama nas Etapas 4 e 5.

Crie todos os recursos deste tutorial da mesma forma Região da AWS. O gateway chama Step Functions em sua própria região, portanto, uma máquina de estado em uma região diferente não pode ser acessada por meio do conector.

Etapa 1: Criar uma máquina de estado

Crie uma máquina de estado padrão para o agente executar. A definição a seguir tem uma única Pass estado que retorna um resultado fixo. Certifique-se de que o console esteja configurado para a região em que você criará o gateway na Etapa 3.

Para criar a máquina de estado (console)
  1. Abra o console do AWS Step Functions e escolha Create state machine (Criar máquina de estado).

  2. Escolha Em brancoe, em seguida, escolha Selecione.

  3. Escolha Código e substitua a definição pela seguinte.

    { "Comment": "A workflow that an AI agent starts through AgentCore Gateway", "StartAt": "Hello", "States": { "Hello": { "Type": "Pass", "Result": "Hello from Step Functions", "End": true } } }
  4. Escolha Configuração. Para Nome da máquina de estado, insira AgentHelloWorld. Mantenha Tipo como Padrão.

  5. Escolha Criar para criar a máquina de estado.

  6. Permita que o Step Functions crie uma função de execução quando solicitado. Se você usar o AWS CLI em vez disso, crie você mesmo a função, conforme mostrado no procedimento a seguir.

  7. Na página de detalhes da máquina de estado, observe o ARN, conforme mostrado no exemplo a seguir.

    arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld

Para criar a mesma máquina de estado com o AWS CLI em vez disso, use o procedimento a seguir. Ao contrário do console, o AWS CLI não cria uma função de execução para você, então crie uma primeiro. Isso Pass- somente o fluxo de trabalho não chama nenhum outro serviço, portanto, a função não precisa de política de permissões.

Para criar a máquina de estado (AWS CLI)
  1. Crie uma função de execução que o Step Functions possa assumir. Substitua a região e o ID da conta pelo seu.

    aws iam create-role \ --role-name AgentHelloWorldExecutionRole \ --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:states:region:123456789012:stateMachine:*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] }'
  2. Salve a definição mostrada no procedimento do console em um arquivo chamado definition.jsone, em seguida, crie a máquina de estado.

    aws stepfunctions create-state-machine \ --name AgentHelloWorld \ --type STANDARD \ --definition file://definition.json \ --role-arn "arn:aws:iam::123456789012:role/AgentHelloWorldExecutionRole" \ --region region

    A resposta contém o stateMachineArn. Anote isso nas etapas 2 e 3.

Etapa 2: criar uma função de serviço para o gateway

O gateway chama Step Functions com uma função de serviço. Escale a função para a máquina de estado que você criou para que o agente não possa atuar em outros fluxos de trabalho em sua conta.

Para criar a função de serviço de gateway
  1. Abra o Console IAM e escolha Funções, Criar função.

  2. Para Tipo de entidade confiável, escolha Política de confiança personalizadae insira o seguinte. Substitua a região e o ID da conta pelo seu.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "bedrock-agentcore.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:bedrock-agentcore:region:123456789012:gateway/step-functions-gateway-*" } } } ] }
  3. Escolha Próximo, e depois Próximo novamente sem anexar uma política gerenciada.

  4. Em Role name (Nome da função), digite AgentCoreGatewayToStepFunctions e escolha Create role (Criar função).

  5. Abra a função, escolha Adicionar permissões, Crie uma política em linha, escolha JSONe insira a política a seguir. Substitua a região e o ID da conta pelo seu.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "StateMachineOperations", "Effect": "Allow", "Action": [ "states:StartExecution", "states:ListExecutions", "states:DescribeStateMachine" ], "Resource": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "arn:aws:states:region:123456789012:execution:AgentHelloWorld:*" } ] }
  6. Nomeie a política StepFunctionsConnectorAccesse, em seguida, escolha Crie uma política.

  7. Observe a função ARN, conforme mostrado no exemplo a seguir.

    arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
nota

Os ARNs de execução são um tipo de recurso diferente dos ARNs de máquinas de estado, e é por isso que a política tem duas declarações.

Se você expor posteriormente as operações do token de tarefa (SendTaskSuccess, SendTaskFailure, e SendTaskHeartbeat), você deve concedê-los em "*", porque o IAM não oferece suporte a permissões em nível de recurso para essas ações. O token de tarefa é, então, o único controle sobre quais tarefas o agente pode concluir, portanto, trate os tokens de tarefa como segredos e envie cada um deles somente para o agente que deve agir sobre eles.

Todos os alvos em um gateway compartilham sua função de serviço. Se fluxos de trabalho diferentes precisarem de limites de IAM diferentes, use um gateway separado para cada um.

Etapa 3: Crie um gateway e adicione o destino do conector Step Functions

Crie um gateway que aceite solicitações assinadas com AWS credenciais e, em seguida, adicione um destino que use a states conector e o conecta à sua máquina de estado.

Para criar o gateway e o destino
  1. Crie o gateway com o AWS CLI. Substitua a função ARN pela da Etapa 2.

    aws bedrock-agentcore-control create-gateway \ --name "step-functions-gateway" \ --protocol-type MCP \ --authorizer-type AWS_IAM \ --role-arn "arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions" \ --region region

    A resposta inclui o gatewayId e gatewayUrl. Observe os dois.

  2. Espere até que o status do gateway seja READY. Isso pode levar alguns minutos. Substituir GATEWAY_ID com o gatewayId da etapa anterior.

    aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --region region
  3. Adicione o alvo do conector. O configurations A lista escolhe quais operações se tornam ferramentas. StartExecution, ListExecutions, e DescribeStateMachine estão fixados na sua máquina de estado. DescribeExecution, GetExecutionHistory, e StopExecution pegue um ARN de execução do agente. Substituir GATEWAY_ID com seu ID de gateway.

    aws bedrock-agentcore-control create-gateway-target \ --gateway-identifier "GATEWAY_ID" \ --name "hello" \ --target-configuration '{ "mcp": { "connector": { "source": { "connectorId": "states" }, "configurations": [ { "name": "StartExecution", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "arn:aws:states:region:123456789012:stateMachine:AgentHelloWorld" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --region region
  4. Espere até que o status do alvo seja READY. Isso pode levar alguns minutos. Substituir TARGET_ID com o targetId do create-gateway-target resposta.

    aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --region region

O gateway agora expõe seis ferramentas MCP: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, e hello___StopExecution. O gateway prefixa cada nome de ferramenta com o nome de destino.

Etapa 4: iniciar uma execução por meio do gateway

Um cliente MCP chama o gateway com JSON-RPC solicitações. Porque o gateway usa AWS_IAM autorização, as solicitações devem ser assinadas com a versão 4 do Signature. Os exemplos a seguir usam awscurl, que assina solicitações com seu AWS CLI credenciais. Consulte Pré-requisitos. Em cada comando, substitua GATEWAY_URL com o gatewayUrl da Etapa 3.

Para iniciar uma execução
  1. Liste as ferramentas que o agente vê.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

    A resposta lista as seis ferramentas com seus esquemas de entrada. Observe que hello___StartExecution anuncia apenas input: o fixado stateMachineArn está oculto do agente e não pode ser substituído.

  2. Inicie uma execução.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "hello___StartExecution", "arguments": { "input": "{\"who\": \"agent\"}" } } }'

    O resultado da ferramenta contém a resposta do Step Functions com o ARN da nova execução.

    { "jsonrpc": "2.0", "id": 2, "result": { "isError": false, "content": [ { "type": "text", "text": "{\"executionArn\":\"arn:aws:states:region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",\"startDate\":1.7597E9}" } ] } }

    Observe o executionArn para a próxima etapa.

Etapa 5: Confirme o resultado

Use as ferramentas de nível de execução para verificar se a execução foi bem-sucedida e ler sua saída.

Para confirmar o resultado da execução
  1. Descreva a execução. Por padrão, a resposta contém somente metadados. Para incluir a entrada e a saída, defina includedData para ALL_DATA. Substituir EXECUTION_ARN com o executionArn da Etapa 4.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "hello___DescribeExecution", "arguments": { "executionArn": "EXECUTION_ARN", "includedData": "ALL_DATA" } } }'

    Para esta máquina de estado, status é SUCCEEDED e output é "Hello from Step Functions". Se uma execução falhar, status é FAILED e a resposta inclui o error e cause campos do estado de falha.

  2. Leia o histórico do evento para ver cada etapa da execução.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }'
  3. Liste as execuções recentes da máquina de estado fixada, opcionalmente filtrada por status.

    awscurl --service bedrock-agentcore --region region \ -X POST "GATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }'
  4. (Opcional) Confirme a execução no AWS Step Functions console. Escolha AgentHelloWorlde, em seguida, escolha a execução. Uma execução iniciada pelo gateway aparece como qualquer outra execução, com a função de serviço do gateway como chamador em AWS CloudTrail.

nota

Para interromper uma execução em execução, chame hello___StopExecution com o ARN de execução. Invocar uma execução que já foi concluída é bem-sucedida, mas não tem efeito. A resposta retorna o tempo de parada original da execução. Para um fluxo de trabalho de longa duração, um agente normalmente liga StartExecutione, em seguida, pesquisas DescribeExecution até status não é mais RUNNING.

Etapa 6: limpar

Para evitar cobranças contínuas, exclua os recursos que você criou.

Para limpar
  1. Exclua o destino do gateway e, em seguida, o gateway.

    aws bedrock-agentcore-control delete-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --region region aws bedrock-agentcore-control delete-gateway \ --gateway-identifier "GATEWAY_ID" --region region
  2. No console do Step Functions, exclua o AgentHelloWorld máquina estadual.

  3. No console do IAM, exclua o AgentCoreGatewayToStepFunctions função e a função de execução da máquina de estado (a função que o Step Functions criou para você, ou AgentHelloWorldExecutionRole se você usou o AWS CLI).