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.
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
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:InvokeGatewayautorisation 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)
-
Ouvrez la console AWS Step Functions
et choisissez Create state machine (Créer une machine d'état). -
Choisissez Vide, puis choisissez Sélectionnez.
-
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 } } } -
Choisissez Configuration. Pour Nom de la machine d'état, entrez
AgentHelloWorld. Gardez Tapez comme Norme. -
Choisissez Créez pour créer la machine à états.
-
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.
-
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)
-
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:" }, "StringEquals": { "aws:SourceAccount": "region:123456789012:stateMachine:*123456789012" } } } ] }' -
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" \ --regionregionLa 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
-
Ouvrez le Console IAM
et choisissez Rôles, Créer un rôle. -
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-* -
Choisissez Suivant, puis Suivant encore une fois sans y associer de stratégie gérée.
-
Pour Nom du rôle, saisissez
AgentCoreGatewayToStepFunctions, puis choisissez Créer un rôle. -
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:" }, { "Sid": "ExecutionOperations", "Effect": "Allow", "Action": [ "states:DescribeExecution", "states:GetExecutionHistory", "states:StopExecution" ], "Resource": "region:123456789012:stateMachine:AgentHelloWorldarn:aws:states:" } ] }region:123456789012:execution:AgentHelloWorld:* -
Donnez un nom à la politique
StepFunctionsConnectorAccess, puis choisissez Créer une politique. -
Notez le rôle ARN, comme illustré dans l'exemple suivant.
arn:aws:iam::123456789012:role/AgentCoreGatewayToStepFunctions
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
-
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" \ --regionregionLa réponse inclut
gatewayIdetgatewayUrl. Notez les deux. -
Attendez que l'état de la passerelle soit
READY. Cette opération peut prendre quelques minutes. RemplacerGATEWAY_IDavec legatewayIdde l'étape précédente.aws bedrock-agentcore-control get-gateway \ --gateway-identifier "GATEWAY_ID" \ --query status --output text --regionregion -
Ajoutez la cible du connecteur. Le
configurationsLa liste choisit quelles opérations deviennent des outils.StartExecution,ListExecutions, etDescribeStateMachinesont épinglés à votre machine d'État.DescribeExecution,GetExecutionHistory, etStopExecutionprenez un ARN d'exécution auprès de l'agent. RemplacerGATEWAY_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:" } }, { "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 -
Attendez que l'état de la cible soit
READY. Cette opération peut prendre quelques minutes. RemplacerTARGET_IDavec letargetIddepuis lecreate-gateway-targetréponse.aws bedrock-agentcore-control get-gateway-target \ --gateway-identifier "GATEWAY_ID" --target-id "TARGET_ID" \ --query status --output text --regionregion
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
-
Répertoriez les outils que l'agent voit.
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 réponse répertorie les six outils avec leurs schémas d'entrée. Remarquez que
hello___StartExecutionfait uniquement de la publicitéinput: le épingléstateMachineArnest masqué à l'agent et ne peut pas être modifié. -
Lancez une exécution.
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\"}" } } }'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:\",\"startDate\":1.7597E9}" } ] } }region:123456789012:execution:AgentHelloWorld:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111Notez les
executionArnpour 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
-
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
includedDatapourALL_DATA. RemplacerEXECUTION_ARNavec leexecutionArnà partir de l'étape 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" } } }'Pour cette machine à états,
statusestSUCCEEDEDetoutputest"Hello from Step Functions". Si une exécution échoue,statusestFAILEDet la réponse inclut leerroretcausechamps provenant de l'état défaillant. -
Lisez l'historique des événements pour voir chaque étape de l'exécution.
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" } } }' -
Répertoriez les exécutions récentes de la machine à états épinglée, éventuellement filtrée par statut.
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" } } }' -
(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.
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
-
Supprimez la cible de la passerelle, puis la passerelle.
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 -
Dans la console Step Functions, supprimez le
AgentHelloWorldmachine d'État. -
Dans la console IAM, supprimez le
AgentCoreGatewayToStepFunctionsrôle et le rôle d'exécution de la machine à états (le rôle que Step Functions a créé pour vous, ouAgentHelloWorldExecutionRolesi vous avez utilisé AWS CLI).
Ressources connexes
-
AWS Step fonctionne en tant que cible du connecteur 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 — 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 — connectez un framework d'agents tel que Strands Agents ou LangGraph vers la passerelle.
-
AgentCore Harnais Invoke Amazon Bedrock avec Step Functions — le sens inverse : appelez un agent depuis un état Step Functions Task.