View a markdown version of this page

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

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

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 et Bassin rocheux de l'Amazon AgentCore tarification. Pour éviter des frais permanents, supprimez les ressources lorsque vous avez terminé, comme décrit dans Étape 6 : Nettoyer.

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 dans le Base rocheuse de l'Amazonie AgentCore Guide du développeur.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Le AWS CLI version 2, 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, 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

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 et choisissez Create state machine (Créer une machine d'état).

  2. Choisissez Vide, puis choisissez Sélectionnez.

  3. Choisissez Code et remplacez la définition par la suivante.

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

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

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

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

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

    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

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 et choisissez Rôles, Créer un rôle.

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

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

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

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

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

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

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.

    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.

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

    aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --region region
  3. 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.

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

    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

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

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

  2. Lancez une exécution.

    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.

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

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.

    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.

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

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

    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. (Facultatif) Confirmez l'exécution dans le AWS Step Functions console. 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

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.

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

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