View a markdown version of this page

Usa i tuoi flussi di lavoro Step Functions come strumenti per gli agenti di intelligenza artificiale - AWS Step Functions

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Usa i tuoi flussi di lavoro Step Functions come strumenti per gli agenti di intelligenza artificiale

Puoi consentire agli agenti di intelligenza artificiale di eseguire i flussi di lavoro Step Functions esponendo una macchina a stati come strumenti Model Context Protocol (MCP) tramite Amazon Bedrock AgentCore Gateway. Un agente connesso al gateway può avviare le esecuzioni, controllarne lo stato e l'output, leggere la cronologia degli eventi e interrompere le esecuzioni. Non è necessario scrivere una funzione Lambda o definire gli strumenti da soli. Il gateway crea gli schemi degli strumenti e chiama Step Functions per l'agente.

Questo schema è utile quando un'attività deve eseguire sempre gli stessi passaggi nello stesso ordine. L'agente decide quando eseguire il flusso di lavoro e quale input passare. La macchina a stati decide quali passaggi eseguire, quindi l'agente non può saltarli o riordinarli e la cronologia delle esecuzioni registra ogni passaggio del flusso di lavoro.

Puoi controllare cosa può fare l'agente in due modi. Gli strumenti che avviano o elencano le esecuzioni vengono aggiunti alla macchina a stati scelta e l'agente non può modificarla. Gli strumenti che agiscono su un'esecuzione specifica ricevono un Amazon Resource Name (ARN) di esecuzione dall'agente. Il AWS Identity and Access Management la politica sul ruolo del servizio gateway limita le esecuzioni a cui tali strumenti possono accedere. Questo tutorial applica tale policy a una macchina a stato singolo.

In questo tutorial, si crea una semplice macchina a stati Standard e un gateway con un connettore Step Functions che punta ad essa. Quindi si effettuano le stesse chiamate MCP effettuate da un agente, utilizzando awscurl, in modo da poter vedere ogni richiesta e risposta. Se hai già una macchina a stati Standard, puoi passare a Passaggio 2: creare un ruolo di servizio per il gateway e usa il suo ARN al posto di AgentHelloWorld. Questo tutorial utilizza un flusso di lavoro standard perché ListExecutions, DescribeExecution, e GetExecutionHistory non funzionano con le esecuzioni Express. Le risorse che crei possono comportare costi finché non le elimini in Fase 6: pulizia.

Importante

Le risorse di questo tutorial possono comportare costi per le transizioni di stato di Step Functions e Amazon Bedrock AgentCore Chiamate allo strumento Gateway. Per le tariffe, vedi Prezzi di Step Functions e Amazon Bedrock AgentCore prezzi. Per evitare addebiti continui, elimina le risorse al termine, come descritto in Fase 6: pulizia.

Nota

Il connettore Step Functions espone dieci operazioni. Questo tutorial ne configura sei: StartExecution, ListExecutions, DescribeStateMachine, DescribeExecution, GetExecutionHistory, e StopExecution. Per l'elenco completo, incluse le operazioni con i token di attività e le differenze tra i flussi di lavoro Standard ed Express, vedi AWS Step funziona come connettore e destinazione nel Amazon Bedrock AgentCore Guida per sviluppatori.

Prerequisiti

Prima di iniziare, assicurati di disporre di:

  • Il AWS CLI versione 2, configurato con le credenziali per il tuo account. I passaggi da 3 a 6 utilizzano AWS CLI.

  • Un client in grado di inviare richieste HTTP firmate Signature Version 4 al gateway. Questo tutorial utilizza awscurl, che puoi installare con pip install awscurl. Qualsiasi client MCP che supporti la versione 4 di Signature funziona allo stesso modo.

  • Autorizzazione a creare ruoli IAM, macchine a stati Step Functions e AgentCore gateway nel tuo account e bedrock-agentcore:InvokeGateway autorizzazione sul gateway creato nel passaggio 3 per l'identità che lo richiama nei passaggi 4 e 5.

Crea tutte le risorse di questo tutorial nello stesso modo Regione AWS. Il gateway chiama Step Functions nella propria regione, quindi una macchina a stati in un'altra regione non è raggiungibile tramite il connettore.

Fase 1: Creare una macchina a stati

Creare una macchina a stati standard per l'esecuzione dell'agente. La seguente definizione ha una sola Pass stato che restituisce un risultato fisso. Assicurati che la console sia impostata sulla regione in cui creerai il gateway nel passaggio 3.

Per creare la macchina a stati (console)
  1. Accedere alla console AWS Step Functions e scegliere Create a state machine (Crea macchina a stati).

  2. Scegli Vuoto, quindi scegli Seleziona.

  3. Scegli Codice e sostituisci la definizione con la seguente.

    { "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. Scegli Config. Per Nome della macchina statale, inserisci AgentHelloWorld. Mantieni Tipo come Norma.

  5. Scegli Crea per creare la macchina a stati.

  6. Consenti a Step Functions di creare un ruolo di esecuzione quando richiesto. Se si utilizza il AWS CLI create invece il ruolo voi stessi, come illustrato nella procedura seguente.

  7. Nella pagina dei dettagli della macchina a stato, annota il GUADAGNA, come mostrato nell'esempio seguente.

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

Per creare la stessa macchina a stati con AWS CLI utilizzare invece la procedura seguente. A differenza della console, AWS CLI non crea un ruolo di esecuzione per te, quindi creane prima uno. Questo Pass-only workflow non richiede altri servizi, quindi il ruolo non richiede criteri di autorizzazione.

Per creare la macchina a stati (AWS CLI)
  1. Crea un ruolo di esecuzione che Step Functions possa assumere. Sostituisci la regione e l'ID dell'account con i tuoi.

    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. Salva la definizione mostrata nella procedura della console in un file denominato definition.json, quindi crea la macchina a stati.

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

    La risposta contiene stateMachineArn. Annotalo per i passaggi 2 e 3.

Passaggio 2: creare un ruolo di servizio per il gateway

Il gateway chiama Step Functions con un ruolo di servizio. Assegna il ruolo alla macchina a stati che hai creato in modo che l'agente non possa agire su altri flussi di lavoro nel tuo account.

Per creare il ruolo del servizio gateway
  1. Aprire il Console IAM e scegli Ruoli, Crea ruolo.

  2. Per Tipo di entità attendibile, scegli Politica di fiducia personalizzatae inserisci quanto segue. Sostituisci la regione e l'ID dell'account con i tuoi.

    { "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. Scegli Prossimo, e poi Avanti nuovamente senza allegare una policy gestita.

  4. In Role name (Nome ruolo) immettere AgentCoreGatewayToStepFunctions e quindi selezionare Create role (Crea ruolo).

  5. Apri il ruolo, scegli Aggiungi autorizzazioni, Crea una politica in linea, scegli JSONe inserisci la seguente politica. Sostituisci la regione e l'ID dell'account con i tuoi.

    { "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. Assegna un nome alla politica StepFunctionsConnectorAccess, quindi scegli Crea una politica.

  7. Nota il ruolo ARN, come mostrato nell'esempio seguente.

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

Gli ARN di esecuzione sono un tipo di risorsa diverso dagli ARN con macchine a stati, motivo per cui la policy contiene due istruzioni.

Se in seguito si espongono le operazioni task-token (SendTaskSuccess, SendTaskFailure, e SendTaskHeartbeat), devi concederli "*", perché IAM non supporta le autorizzazioni a livello di risorsa per queste azioni. Il token di attività è quindi l'unico controllo su quali attività l'agente può completare, quindi trattate i token di attività come segreti e inviateli solo all'agente che dovrebbe intervenire su di essi.

Tutte le destinazioni su un gateway condividono il suo ruolo di servizio. Se flussi di lavoro diversi richiedono limiti IAM diversi, utilizza un gateway separato per ciascuno.

Fase 3: Creare un gateway e aggiungere la destinazione del connettore Step Functions

Crea un gateway che accetti le richieste firmate con AWS credenziali, quindi aggiungi una destinazione che utilizzi states connettore e lo collega al computer di stato.

Per creare il gateway e il target
  1. Crea il gateway con AWS CLI. Sostituisci il ruolo ARN con quello della Fase 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

    La risposta include gatewayId e gatewayUrl. Annota entrambi.

  2. Attendi che lo stato del gateway sia READY. Ciò può richiedere alcuni minuti. Sostituire GATEWAY_ID con il gatewayId dal passaggio precedente.

    aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --region region
  3. Aggiungere la destinazione del connettore. Il configurations l'elenco sceglie quali operazioni diventano strumenti. StartExecution, ListExecutions, e DescribeStateMachine sono bloccati nel tuo computer di stato. DescribeExecution, GetExecutionHistory, e StopExecution richiedi un ARN di esecuzione dall'agente. Sostituisci GATEWAY_ID con il tuo ID 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. Attendi che lo stato di destinazione sia READY. Ciò può richiedere alcuni minuti. Sostituire TARGET_ID con il targetId dal create-gateway-target risposta.

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

Il gateway ora espone sei strumenti MCP: hello___StartExecution, hello___ListExecutions, hello___DescribeStateMachine, hello___DescribeExecution, hello___GetExecutionHistory, e hello___StopExecution. Il gateway prefissa il nome di ogni strumento con il nome di destinazione.

Fase 4: Avviare un'esecuzione tramite il gateway

Un client MCP chiama il gateway con JSON-RPC richieste. Perché il gateway utilizza AWS_IAM autorizzazione, le richieste devono essere firmate con Signature Version 4. I seguenti esempi utilizzano awscurl, che firma le richieste con il tuo AWS CLI credenziali. Consulta Prerequisiti. In ogni comando, sostituisci GATEWAY_URL con gatewayUrl dalla Fase 3.

Per iniziare un'esecuzione
  1. Elenca gli strumenti che l'agente vede.

    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":{}}'

    La risposta elenca i sei strumenti con i relativi schemi di input. Notate che hello___StartExecution pubblicizza solo input: il appuntato stateMachineArn è nascosto all'agente e non può essere sovrascritto.

  2. Avvia un'esecuzione.

    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\"}" } } }'

    Il risultato dello strumento contiene la risposta Step Functions con l'ARN della nuova esecuzione.

    { "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}" } ] } }

    Nota il executionArn per il passaggio successivo.

Fase 5: Conferma il risultato

Usa gli strumenti a livello di esecuzione per verificare se l'esecuzione è riuscita e per leggerne l'output.

Per confermare il risultato dell'esecuzione
  1. Descrivi l'esecuzione. Per impostazione predefinita, la risposta contiene solo metadati. Per includere l'input e l'output, imposta includedData a ALL_DATA. Sostituire EXECUTION_ARN con il executionArn dalla Fase 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" } } }'

    Per questa macchina a stati, status è SUCCEEDED e output è "Hello from Step Functions". Se un'esecuzione fallisce, status è FAILED e la risposta include error e cause campi provenienti dallo stato di errore.

  2. Leggi la cronologia degli eventi per vedere ogni passaggio eseguito dall'esecuzione.

    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. Elenca le esecuzioni recenti della macchina a stati bloccata, facoltativamente filtrate per stato.

    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. (Facoltativo) Conferma l'esecuzione nel AWS Step Functions plancia. Scegli AgentHelloWorld, quindi scegli l'esecuzione. Un'esecuzione avviata dal gateway appare come qualsiasi altra esecuzione, con il ruolo di servizio del gateway come chiamante in AWS CloudTrail.

Nota

Per interrompere un'esecuzione in corso, chiama hello___StopExecution con l'esecuzione ARN. Richiamarlo su un'esecuzione che è già terminata ha successo ma non ha alcun effetto. La risposta restituisce l'ora di arresto originale dell'esecuzione. Per un flusso di lavoro di lunga durata, in genere un agente chiama StartExecutione poi sondaggi DescribeExecution fino a status non è più RUNNING.

Fase 6: pulizia

Per evitare addebiti continui, elimina le risorse che hai creato.

Per eliminare
  1. Elimina la destinazione del gateway e quindi il 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. Nella console Step Functions, elimina AgentHelloWorld macchina a stati.

  3. Nella console IAM, elimina AgentCoreGatewayToStepFunctions ruolo e il ruolo di esecuzione della macchina a stati (il ruolo che Step Functions ha creato per te, oppure AgentHelloWorldExecutionRole se hai usato il AWS CLI).