

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](#agentcore-gateway-step-2) 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](#agentcore-gateway-step-6).

**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](https://aws.amazon.com/step-functions/pricing/) e [Amazon Bedrock AgentCore prezzi](https://aws.amazon.com/bedrock/agentcore/pricing/). Per evitare addebiti continui, elimina le risorse al termine, come descritto in [Fase 6: pulizia](#agentcore-gateway-step-6).

**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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) nel *Amazon Bedrock AgentCore Guida per sviluppatori*.

## Prerequisiti
<a name="agentcore-gateway-prerequisites"></a>

Prima di iniziare, assicurati di disporre di:
+ Il [AWS CLI versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), 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](https://github.com/okigan/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
<a name="agentcore-gateway-step-1"></a>

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](https://console.aws.amazon.com/states/) e scegliere **Create a state machine (Crea macchina a stati)**.

1. Scegli **Vuoto**, quindi scegli **Seleziona**.

1. Scegli **Codice** e sostituisci la definizione con la seguente.

   ```json
   {
     "Comment": "A workflow that an AI agent starts through AgentCore Gateway",
     "StartAt": "Hello",
     "States": {
       "Hello": {
         "Type": "Pass",
         "Result": "Hello from Step Functions",
         "End": true
       }
     }
   }
   ```

1. Scegli **Config**. Per **Nome della macchina statale**, inserisci **AgentHelloWorld**. Mantieni **Tipo** come **Norma**.

1. Scegli **Crea** per creare la macchina a stati.

1. 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.

1. 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.

   ```bsh
   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}}"
             }
           }
         }
       ]
     }'
   ```

1. Salva la definizione mostrata nella procedura della console in un file denominato `definition.json`, quindi crea la macchina a stati.

   ```bsh
   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
<a name="agentcore-gateway-step-2"></a>

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](https://console.aws.amazon.com/iam/home) e scegli **Ruoli**, **Crea ruolo**.

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

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

1. Scegli **Prossimo**, e poi **Avanti** nuovamente senza allegare una policy gestita.

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

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

   ```json
   {
     "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:*}}"
       }
     ]
   }
   ```

1. Assegna un nome alla politica **StepFunctionsConnectorAccess**, quindi scegli **Crea una politica**.

1. 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
<a name="agentcore-gateway-step-3"></a>

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.

   ```bsh
   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.

1. Attendi che lo stato del gateway sia `READY`. Ciò può richiedere alcuni minuti. Sostituire {{GATEWAY\_ID}} con il `gatewayId` dal passaggio precedente.

   ```bsh
   aws bedrock-agentcore-control get-gateway \
     --gateway-identifier "{{GATEWAY_ID}}" \
     --query status --output text --region {{{{region}}}}
   ```

1. 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.

   ```bsh
   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}}}}
   ```

1. Attendi che lo stato di destinazione sia `READY`. Ciò può richiedere alcuni minuti. Sostituire {{TARGET\_ID}} con il `targetId` dal `create-gateway-target` risposta.

   ```bsh
   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
<a name="agentcore-gateway-step-4"></a>

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](#agentcore-gateway-prerequisites). In ogni comando, sostituisci {{GATEWAY\_URL}} con `gatewayUrl` dalla Fase 3.

**Per iniziare un'esecuzione**

1. Elenca gli strumenti che l'agente vede.

   ```bsh
   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.

1. Avvia un'esecuzione.

   ```bsh
   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.

   ```json
   {
     "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
<a name="agentcore-gateway-step-5"></a>

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.

   ```bsh
   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.

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

   ```bsh
   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}}" }
       }
     }'
   ```

1. Elenca le esecuzioni recenti della macchina a stati bloccata, facoltativamente filtrate per stato.

   ```bsh
   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" }
       }
     }'
   ```

1. (Facoltativo) Conferma l'esecuzione nel [AWS Step Functions plancia](https://console.aws.amazon.com/states/). 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 `StartExecution`e poi sondaggi `DescribeExecution` fino a `status` non è più `RUNNING`.

## Fase 6: pulizia
<a name="agentcore-gateway-step-6"></a>

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

**Per eliminare**

1. Elimina la destinazione del gateway e quindi il gateway.

   ```bsh
   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}}}}
   ```

1. Nella console Step Functions, elimina `AgentHelloWorld` macchina a stati.

1. 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).

## Risorse correlate
<a name="agentcore-gateway-related"></a>
+ [AWS Step funge da connettore Target](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-api-target-config.html#gateway-add-target-api-connector-step-functions) — 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-agent-integration.html) — collegare un framework di agenti come Strands Agents o LangGraph al gateway.
+ [Richiama il AgentCore cablaggio Amazon Bedrock con Step Functions](connect-bedrockagentcore.md) — la direzione opposta: chiama un agente da uno stato Step Functions Task.