

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Utilisez vos flux de travail Step Functions comme outils pour les agents IA

Vous pouvez laisser les agents IA exécuter vos flux de travail Step Functions en exposant une machine à états sous la forme d'outils MCP (Model Context Protocol) via Amazon Bedrock AgentCore Passerelle. Un agent connecté à la passerelle peut démarrer des exécutions, vérifier leur état et leur sortie, lire l'historique des événements et arrêter les exécutions. Il n'est pas nécessaire d'écrire une fonction Lambda ou de définir les outils vous-même. La passerelle crée les schémas d'outils et appelle Step Functions pour l'agent.

Ce modèle est utile lorsqu'une tâche doit exécuter les mêmes étapes dans le même ordre à chaque fois. L'agent décide quand exécuter le flux de travail et quelles entrées transmettre. La machine à états décide des étapes à exécuter, afin que l'agent ne puisse pas les ignorer ou les réorganiser, et l'historique des exécutions enregistre chaque étape du flux de travail.

Vous contrôlez ce que l'agent peut faire de deux manières. Les outils qui démarrent ou répertorient les exécutions sont épinglés à la machine d'état que vous choisissez et l'agent ne peut pas la modifier. Les outils qui agissent sur une exécution spécifique prennent une exécution Amazon Resource Name (ARN) auprès de l'agent. Le Gestion des identités et des accès AWS la politique relative au rôle de votre service de passerelle limite les exécutions auxquelles ces outils peuvent accéder. Ce didacticiel applique cette politique à une machine à état unique.

Dans ce didacticiel, vous allez créer une machine à état standard simple et une passerelle avec une cible de connecteur Step Functions qui pointe vers elle. Vous effectuez ensuite les mêmes appels MCP qu'un agent, en utilisant `awscurl`, afin que vous puissiez voir chaque demande et chaque réponse. Si vous possédez déjà une machine à état standard, vous pouvez passer à [Étape 2 : Création d'un rôle de service pour la passerelle](#agentcore-gateway-step-2) et utilisez son ARN à la place de `AgentHelloWorld`. Ce didacticiel utilise un flux de travail standard car `ListExecutions`, `DescribeExecution`, et `GetExecutionHistory` ne fonctionnent pas avec les exécutions Express. Les ressources que vous créez peuvent être facturées jusqu'à ce que vous les supprimiez dans [Étape 6 : Nettoyer](#agentcore-gateway-step-6).

**Important**  
Les ressources de ce didacticiel peuvent entraîner des frais pour Step Functions, les transitions d'état et Amazon Bedrock. AgentCore Appels à l'outil Gateway. Pour les tarifs, voir [Tarification Step Functions](https://aws.amazon.com/step-functions/pricing/) et [Bassin rocheux de l'Amazon AgentCore tarification](https://aws.amazon.com/bedrock/agentcore/pricing/). Pour éviter des frais permanents, supprimez les ressources lorsque vous avez terminé, comme décrit dans [Étape 6 : Nettoyer](#agentcore-gateway-step-6).

**Note**  
Le connecteur Step Functions propose dix opérations. Ce tutoriel permet de configurer six d'entre eux : `StartExecution`, `ListExecutions`, `DescribeStateMachine`, `DescribeExecution`, `GetExecutionHistory`, et `StopExecution`. Pour la liste complète, y compris les opérations liées aux jetons de tâche et les différences entre les flux de travail Standard et Express, voir [AWS Step fonctionne en tant que cible du connecteur](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) dans le *Base rocheuse de l'Amazonie AgentCore Guide du développeur*.

## Conditions préalables
<a name="agentcore-gateway-prerequisites"></a>

Avant de commencer, assurez-vous de disposer des éléments suivants :
+ Le [AWS CLI version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), configuré avec les informations d'identification de votre compte. Pour les étapes 3 à 6, utilisez AWS CLI.
+ Un client qui peut envoyer des requêtes HTTP signées Signature Version 4 à la passerelle. Ce didacticiel utilise [curl aws](https://github.com/okigan/awscurl), que vous pouvez installer avec `pip install awscurl`. Tous les clients MCP prenant en charge la version 4 de Signature fonctionnent de la même manière.
+ Autorisation de créer des rôles IAM, des machines d'état Step Functions et AgentCore les passerelles de votre compte, et `bedrock-agentcore:InvokeGateway` autorisation sur la passerelle que vous créez à l'étape 3 pour l'identité qui l'appelle aux étapes 4 et 5.

Créez toutes les ressources de ce didacticiel de la même manière Région AWS. La passerelle appelle Step Functions dans sa propre région, de sorte qu'une machine d'état située dans une autre région n'est pas accessible via le connecteur.

## Étape 1 : Création d'une machine à états
<a name="agentcore-gateway-step-1"></a>

Créez une machine d'état standard pour que l'agent s'exécute. La définition suivante comporte une seule `Pass` état qui renvoie un résultat fixe. Assurez-vous que la console est réglée sur la région dans laquelle vous allez créer la passerelle à l'étape 3.

**Pour créer la machine à états (console)**

1. Ouvrez la [console AWS Step Functions](https://console.aws.amazon.com/states/) et choisissez **Create state machine (Créer une machine d'état)**.

1. Choisissez **Vide**, puis choisissez **Sélectionnez**.

1. Choisissez **Code** et remplacez la définition par la suivante.

   ```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. Choisissez **Configuration**. Pour **Nom de la machine d'état**, entrez **AgentHelloWorld**. Gardez **Tapez** comme **Norme**.

1. Choisissez **Créez** pour créer la machine à états.

1. Autorisez Step Functions à créer un rôle d'exécution lorsque vous y êtes invité. Si vous utilisez AWS CLI créez plutôt le rôle vous-même, comme indiqué dans la procédure suivante.

1. Sur la page des détails de la machine d'état, notez **ARN**, comme illustré dans l'exemple suivant.

   ```
   arn:aws:states:{{region}}:123456789012:stateMachine:AgentHelloWorld
   ```

Pour créer la même machine à états avec AWS CLI utilisez plutôt la procédure suivante. Contrairement à la console, AWS CLI ne crée pas de rôle d'exécution pour vous, créez-en un d'abord. Ce `Pass`-seul le flux de travail n'appelle aucun autre service, le rôle n'a donc pas besoin de politique d'autorisations.

**Pour créer la machine à états (AWS CLI)**

1. Créez un rôle d'exécution que Step Functions peut assumer. Remplacez la région et l'identifiant de compte par les vôtres.

   ```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. Enregistrez la définition affichée dans la procédure de console dans un fichier nommé `definition.json`, puis créez la machine à états.

   ```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 réponse contient `stateMachineArn`. Veuillez en tenir compte pour les étapes 2 et 3.

## Étape 2 : Création d'un rôle de service pour la passerelle
<a name="agentcore-gateway-step-2"></a>

La passerelle appelle Step Functions avec un rôle de service. Étendez le rôle à la machine à états que vous avez créée afin que l'agent ne puisse pas agir sur les autres flux de travail de votre compte.

**Pour créer le rôle de service de passerelle**

1. Ouvrez le [Console IAM](https://console.aws.amazon.com/iam/home) et choisissez **Rôles**, **Créer un rôle**.

1. Pour **Type d'entité de confiance**, choisissez **Politique de confiance personnalisée**, et saisissez ce qui suit. Remplacez la région et l'identifiant de compte par les vôtres.

   ```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. Choisissez **Suivant**, puis **Suivant** encore une fois sans y associer de stratégie gérée.

1. Pour **Nom du rôle**, saisissez **AgentCoreGatewayToStepFunctions**, puis choisissez **Créer un rôle**.

1. Ouvrez le rôle, choisissez **Ajouter des autorisations**, **Création d'une politique en ligne**, choisissez **JSON**, et entrez la politique suivante. Remplacez la région et l'identifiant de compte par les vôtres.

   ```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. Donnez un nom à la politique **StepFunctionsConnectorAccess**, puis choisissez **Créer une politique**.

1. Notez le rôle ARN, comme illustré dans l'exemple suivant.

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

**Note**  
Les ARN d'exécution sont un type de ressource différent des ARN des machines à états. C'est pourquoi la politique comporte deux instructions.  
Si vous exposez ultérieurement les opérations des jetons de tâche (`SendTaskSuccess`, `SendTaskFailure`, et `SendTaskHeartbeat`), vous devez les accorder le `"*"`, car IAM ne prend pas en charge les autorisations au niveau des ressources pour ces actions. Le jeton de tâche est alors le seul contrôle sur les tâches que l'agent peut effectuer. Traitez donc les jetons de tâche comme des secrets et envoyez-les uniquement à l'agent qui doit agir dessus.  
Toutes les cibles d'une passerelle partagent son rôle de service. Si différents flux de travail nécessitent des limites IAM différentes, utilisez une passerelle distincte pour chacun.

## Étape 3 : Création d'une passerelle et ajout de la cible du connecteur Step Functions
<a name="agentcore-gateway-step-3"></a>

Créez une passerelle qui accepte les demandes signées avec AWS informations d'identification, puis ajoutez une cible qui utilise `states` connecteur et épinglez-le à votre machine d'État.

**Pour créer la passerelle et la cible**

1. Créez la passerelle avec AWS CLI. Remplacez le rôle ARN par celui de l'étape 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 réponse inclut `gatewayId` et `gatewayUrl`. Notez les deux.

1. Attendez que l'état de la passerelle soit `READY`. Cette opération peut prendre quelques minutes. Remplacer {{GATEWAY\_ID}} avec le `gatewayId` de l'étape précédente.

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

1. Ajoutez la cible du connecteur. Le `configurations` La liste choisit quelles opérations deviennent des outils. `StartExecution`, `ListExecutions`, et `DescribeStateMachine` sont épinglés à votre machine d'État. `DescribeExecution`, `GetExecutionHistory`, et `StopExecution` prenez un ARN d'exécution auprès de l'agent. Remplacer {{GATEWAY\_ID}} à l'aide de votre identifiant de passerelle.

   ```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. Attendez que l'état de la cible soit `READY`. Cette opération peut prendre quelques minutes. Remplacer {{TARGET\_ID}} avec le `targetId` depuis le `create-gateway-target` réponse.

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

La passerelle propose désormais six outils MCP : `hello___StartExecution`, `hello___ListExecutions`, `hello___DescribeStateMachine`, `hello___DescribeExecution`, `hello___GetExecutionHistory`, et `hello___StopExecution`. La passerelle préfixe le nom de la cible à chaque nom d'outil.

## Étape 4 : démarrer une exécution via la passerelle
<a name="agentcore-gateway-step-4"></a>

Un client MCP appelle la passerelle avec JSON-RPC demandes. Parce que la passerelle utilise `AWS_IAM` autorisation, les demandes doivent être signées avec Signature Version 4. Les exemples suivants utilisent `awscurl`, qui signe les demandes avec votre AWS CLI informations d'identification. Consultez [Conditions préalables](#agentcore-gateway-prerequisites). Dans chaque commande, remplacez {{GATEWAY\_URL}} avec le `gatewayUrl` à partir de l'étape 3.

**Pour démarrer une exécution**

1. Répertoriez les outils que l'agent voit.

   ```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 réponse répertorie les six outils avec leurs schémas d'entrée. Remarquez que `hello___StartExecution` fait uniquement de la publicité `input`: le épinglé `stateMachineArn` est masqué à l'agent et ne peut pas être modifié.

1. Lancez une exécution.

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

   Le résultat de l'outil contient la réponse Step Functions avec l'ARN de la nouvelle exécution.

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

   Notez les `executionArn` pour la prochaine étape.

## Étape 5 : Confirmez le résultat
<a name="agentcore-gateway-step-5"></a>

Utilisez les outils au niveau de l'exécution pour vérifier si l'exécution a réussi et pour lire sa sortie.

**Pour confirmer le résultat de l'exécution**

1. Décrivez l'exécution. Par défaut, la réponse contient uniquement des métadonnées. Pour inclure l'entrée et la sortie, définissez `includedData` pour `ALL_DATA`. Remplacer {{EXECUTION\_ARN}} avec le `executionArn` à partir de l'étape 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"
         }
       }
     }'
   ```

   Pour cette machine à états, `status` est `SUCCEEDED` et `output` est `"Hello from Step Functions"`. Si une exécution échoue, `status` est `FAILED` et la réponse inclut le `error` et `cause` champs provenant de l'état défaillant.

1. Lisez l'historique des événements pour voir chaque étape de l'exécution.

   ```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. Répertoriez les exécutions récentes de la machine à états épinglée, éventuellement filtrée par statut.

   ```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. (Facultatif) Confirmez l'exécution dans le [AWS Step Functions console](https://console.aws.amazon.com/states/). Choisissez **AgentHelloWorld**, puis choisissez l'exécution. Une exécution démarrée par la passerelle apparaît comme n'importe quelle autre exécution, avec le rôle de service de la passerelle en tant qu'appelant dans AWS CloudTrail.

**Note**  
Pour arrêter une exécution en cours, appelez `hello___StopExecution` avec l'ARN d'exécution. L'appeler lors d'une exécution déjà terminée réussit mais n'a aucun effet. La réponse renvoie l'heure de fin initiale de l'exécution. Pour un flux de travail de longue durée, un agent appelle généralement `StartExecution`, puis les sondages `DescribeExecution` jusqu'à `status` n'est plus `RUNNING`.

## Étape 6 : Nettoyer
<a name="agentcore-gateway-step-6"></a>

Pour éviter des frais permanents, supprimez les ressources que vous avez créées.

**Pour nettoyer**

1. Supprimez la cible de la passerelle, puis la passerelle.

   ```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. Dans la console Step Functions, supprimez le `AgentHelloWorld` machine d'État.

1. Dans la console IAM, supprimez le `AgentCoreGatewayToStepFunctions` rôle et le rôle d'exécution de la machine à états (le rôle que Step Functions a créé pour vous, ou `AgentHelloWorldExecutionRole` si vous avez utilisé AWS CLI).

## Ressources connexes
<a name="agentcore-gateway-related"></a>
+ [AWS Step fonctionne en tant que cible du connecteur](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-target-connector-step-functions.html) dans le *Base rocheuse de l'Amazonie AgentCore Guide du développeur* — les dix opérations, les paramètres pouvant être épinglés, les contraintes de flux de travail Standard et Express et les schémas d'outils.
+ [Ajoutez une cible Connector avec AWS Fonctions de l'étape](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-add-target-api-target-config.html#gateway-add-target-api-connector-step-functions) — configuration avec Boto3, le AWS CLI, et le AgentCore CLI et politique de rôle de service complet, y compris les opérations de jeton de tâche.
+ [Créez un agent qui utilise votre AgentCore passerelle](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-agent-integration.html) — connectez un framework d'agents tel que Strands Agents ou LangGraph vers la passerelle.
+ [AgentCore Harnais Invoke Amazon Bedrock avec Step Functions](connect-bedrockagentcore.md) — le sens inverse : appelez un agent depuis un état Step Functions Task.