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.
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
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:InvokeGatewayautorizzazione 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)
-
Accedere alla console AWS Step Functions
e scegliere Create a state machine (Crea macchina a stati). -
Scegli Vuoto, quindi scegli Seleziona.
-
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 } } } -
Scegli Config. Per Nome della macchina statale, inserisci
AgentHelloWorld. Mantieni Tipo come Norma. -
Scegli Crea per creare la macchina a stati.
-
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.
-
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)
-
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:" }, "StringEquals": { "aws:SourceAccount": "region:123456789012:stateMachine:*123456789012" } } } ] }' -
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" \ --regionregionLa 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
-
Aprire il Console IAM
e scegli Ruoli, Crea ruolo. -
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-* -
Scegli Prossimo, e poi Avanti nuovamente senza allegare una policy gestita.
-
In Role name (Nome ruolo) immettere
AgentCoreGatewayToStepFunctionse quindi selezionare Create role (Crea ruolo). -
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:" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } ] }region:123456789012:execution:AgentHelloWorld:* -
Assegna un nome alla politica
StepFunctionsConnectorAccess, quindi scegli Crea una politica. -
Nota il ruolo ARN, come mostrato nell'esempio seguente.
arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
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
-
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" \ --regionregionLa risposta include
gatewayIdegatewayUrl. Annota entrambi. -
Attendi che lo stato del gateway sia
READY. Ciò può richiedere alcuni minuti. SostituireGATEWAY_IDcon ilgatewayIddal passaggio precedente.aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --regionregion -
Aggiungere la destinazione del connettore. Il
configurationsl'elenco sceglie quali operazioni diventano strumenti.StartExecution,ListExecutions, eDescribeStateMachinesono bloccati nel tuo computer di stato.DescribeExecution,GetExecutionHistory, eStopExecutionrichiedi un ARN di esecuzione dall'agente. SostituisciGATEWAY_IDcon 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:" } }, { "name": "ListExecutions", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeStateMachine", "parameterValues": { "stateMachineArn": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } }, { "name": "DescribeExecution" }, { "name": "GetExecutionHistory" }, { "name": "StopExecution" } ] } } }' \ --credential-provider-configurations '[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]' \ --regionregion:123456789012:stateMachine:AgentHelloWorldregion -
Attendi che lo stato di destinazione sia
READY. Ciò può richiedere alcuni minuti. SostituireTARGET_IDcon iltargetIddalcreate-gateway-targetrisposta.aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --regionregion
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
-
Elenca gli strumenti che l'agente vede.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_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___StartExecutionpubblicizza soloinput: il appuntatostateMachineArnè nascosto all'agente e non può essere sovrascritto. -
Avvia un'esecuzione.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_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:\",\"startDate\":1.7597E9}" } ] } }region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111Nota il
executionArnper 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
-
Descrivi l'esecuzione. Per impostazione predefinita, la risposta contiene solo metadati. Per includere l'input e l'output, imposta
includedDataaALL_DATA. SostituireEXECUTION_ARNcon ilexecutionArndalla Fase 4.awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_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èSUCCEEDEDeoutputè"Hello from Step Functions". Se un'esecuzione fallisce,statusèFAILEDe la risposta includeerrorecausecampi provenienti dallo stato di errore. -
Leggi la cronologia degli eventi per vedere ogni passaggio eseguito dall'esecuzione.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "hello___GetExecutionHistory", "arguments": { "executionArn": "EXECUTION_ARN" } } }' -
Elenca le esecuzioni recenti della macchina a stati bloccata, facoltativamente filtrate per stato.
awscurl --service bedrock-agentcore --region\ -X POST "regionGATEWAY_URL" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "hello___ListExecutions", "arguments": { "statusFilter": "SUCCEEDED" } } }' -
(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.
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
-
Elimina la destinazione del gateway e quindi il gateway.
aws bedrock-agentcore-control delete-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" --regionaws bedrock-agentcore-control delete-gateway \ --gateway-identifier "regionGATEWAY_ID" --regionregion -
Nella console Step Functions, elimina
AgentHelloWorldmacchina a stati. -
Nella console IAM, elimina
AgentCoreGatewayToStepFunctionsruolo e il ruolo di esecuzione della macchina a stati (il ruolo che Step Functions ha creato per te, oppureAgentHelloWorldExecutionRolese hai usato il AWS CLI).
Risorse correlate
-
AWS Step funge da connettore Target nel Amazon Bedrock AgentCore Guida per sviluppatori — tutte e dieci le operazioni, i parametri che possono essere fissati, i vincoli del flusso di lavoro Standard ed Express e gli schemi degli strumenti.
-
Aggiungi una destinazione Connector con AWS Funzioni Step — configurazione con Boto3, AWS CLI, e il AgentCore CLI e la politica completa del ruolo del servizio, comprese le operazioni con i token di attività.
-
Crea un agente che utilizzi il tuo AgentCore gateway — collegare un framework di agenti come Strands Agents o LangGraph al gateway.
-
Richiama il AgentCore cablaggio Amazon Bedrock con Step Functions — la direzione opposta: chiama un agente da uno stato Step Functions Task.