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. # AgentCore Harnais Invoke Amazon Bedrock avec Step Functions Vous pouvez intégrer Step Functions à Amazon Bedrock AgentCore pour invoquer un harnais depuis votre machine à états. Un harnais est un environnement d'exécution géré qui orchestre l'inférence du modèle, l'utilisation des outils et les conversations à plusieurs tours. Dans Workflow Studio, recherchez **AgentCore InvokeHarness**cet état et faites-le glisser dans votre flux de travail. Dans le panneau de configuration, vous pouvez créer un nouveau harnais et un nouveau rôle d'exécution à l'aide de **Quick Create Harness**, ou sélectionner un ARN de harnais existant. Lorsque vous utilisez un harnais existant, vous pouvez remplacer les configurations par invocation : les valeurs de votre définition d'état de tâche remplacent les valeurs par défaut du harnais. Pour connaître les paramètres disponibles, consultez [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)la *référence de l' AgentCore API Amazon Bedrock*. Pour plus d'informations sur les rôles d'exécution du harnais, consultez la section [Autorisations d'exécution](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html) dans le manuel *Amazon Bedrock AgentCore Developer Guide*. **Astuce** Pour ajouter de l'observabilité à vos ressources agentiques, activez CloudWatch Transaction Search. Pour plus d'informations, consultez [Ajouter de l'observabilité à vos ressources agentic dans le guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AgentCore-GettingStarted.html#add-observability-agentic-resources) de l'utilisateur *Amazon CloudWatch *. Pour en savoir plus sur l'intégration aux AWS services dans Step Functions, reportez-vous [Intégration des services ](integrate-services.md) aux sections et[Transmission de paramètres à une API de service dans Step Functions](connect-parameters.md). **Principales caractéristiques de l'intégration optimisée des AgentCore harnais** Seul le modèle [Réponse à la requête](connect-to-resource.md#connect-default) d'intégration est pris en charge. Les [Attendre un rappel avec un jeton de tâche](connect-to-resource.md#connect-wait-token) modèles [Exécuter une tâche (.sync)](connect-to-resource.md#connect-sync) et ne sont pas pris en charge. La réponse est transformée en une structure JSON en forme de [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html#API_runtime_Converse_ResponseSyntax). Seul le dernier message de l'assistant est renvoyé ; les tours précédents dans les conversations à plusieurs tours sont ignorés. Les statistiques d'utilisation des jetons (`InputTokens``OutputTokens`,,`TotalTokens`) sont agrégées pour tous les messages de la conversation. Seul le contenu textuel est inclus dans la réponse. Les blocs relatifs à l'utilisation des outils et au raisonnement sont omis. `Output.Message.Content` La taille de sortie est soumise à la limite de sortie de l'état de la tâche. Pour la valeur actuelle, voir[Quotas liés à l'exécution des tâches](service-quotas.md#service-limits-task-executions). La durée d'exécution maximale de l'état `InvokeHarness` Task est de 15 minutes (900 secondes), même si la `TimeoutSeconds` valeur dépasse cette limite. Une fois l'état de tâche expiré, le harnais continue de s'exécuter jusqu'à ce qu'il atteigne son propre délai d'expiration configuré. Pour éviter des coûts imprévus, assurez-vous que le délai d'expiration de votre harnais ne dépasse pas 15 minutes. La vue détaillée de l'exécution de la console Step Functions affiche un CloudWatch lien à côté de l'étape de l'agent, fournissant une vue détaillée du raisonnement de l'agent, y compris l'utilisation des outils. ## API de AgentCore harnais Amazon Bedrock optimisées L'API suivante est prise en charge : ### [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html) Invoque un harnais pour exécuter un agent d'intelligence artificielle capable d'utiliser des outils, d'accéder à la mémoire et d'exécuter des conversations à plusieurs tours. **Modèle pris en charge :** demande de réponse uniquement. Pour connaître la syntaxe complète des demandes, consultez le [InvokeHarness](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html)manuel *Amazon Bedrock AgentCore API Reference*. **Paramètres dans Step Functions sont exprimés en PascalCase** Même si l'API de service native se trouve dans CamelCase, par exemple l'`startSyncExecution`action d'API, vous spécifiez des paramètres PascalCase dans, tels que :. `StateMachineArn` **Champs de réponse** + `Output.Message`— Le dernier message de l'assistant de l'agent. Contient `Role` (toujours`"assistant"`) et `Content` (un tableau de blocs de texte). Seul le dernier tour d'assistant est renvoyé ; les tours précédents dans les conversations à plusieurs tours sont ignorés. + `Output.Message.Content`— Tableau de blocs de contenu. Chaque bloc contient un `Text` champ contenant le texte de réponse de l'agent. Seul le contenu textuel est inclus ; les blocs d'utilisation des outils et de raisonnement sont omis. + `StopReason`— Pourquoi l'agent s'est arrêté. Valeurs : `end_turn`, `max_tokens`, `stop_sequence`, `tool_use`. + `Usage`— Mesures de consommation de jetons agrégées à tous les tours. Contient `InputTokens``OutputTokens`, et`TotalTokens`. + `Metrics.LatencyMs`— Latence d'invocation totale en millisecondes, agrégée à tous les tours. **Syntaxe de réponse** ``` { "Output": { "Message": { "Role": "{{string}}", "Content": [ { "Text": "{{string}}" } ] } }, "StopReason": "{{string}}", "Usage": { "InputTokens": {{long}}, "OutputTokens": {{long}}, "TotalTokens": {{long}} }, "Metrics": { "LatencyMs": {{long}} } } ``` **Note** L'arrêt d'une exécution ou de l'état de tâche n'empêche pas le harnais de continuer à fonctionner. ## Définition de l'état des tâches pour l'intégration d'Amazon Bedrock AgentCore Les exemples suivants montrent comment définir un état de tâche qui invoque un harnais Amazon Bedrock AgentCore . Le `RuntimeSessionId` champ identifie la session de conversation. Utilisez le même identifiant de session pour toutes les invocations afin de poursuivre une conversation. **Note** L'URI de la ressource Step Functions utilise `bedrockagentcore` (sans tiret), tandis que les ARN AgentCore des ressources Amazon Bedrock l'utilisent `bedrock-agentcore` (avec tiret). **Example appel de base avec remplacement du modèle et invite du système** ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-agent-harness}}", "RuntimeSessionId": "{% $uuid() %}", "Messages": [ { "Content": [{ "Text": "{% $states.input.userMessage %}" }], "Role": "user" } ], "SystemPrompt": [{ "Text": "You are a helpful customer service agent." }], "Model": { "BedrockModelConfig": { "Temperature": 0.7, "ModelId": "global.anthropic.claude-sonnet-4-6" } }, "MaxIterations": 75, "TimeoutSeconds": 600 }, "End": true } ``` **Example invocation à l'aide d'outils (navigateur)** ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{order-agent}}", "RuntimeSessionId": "{% $uuid() %}", "Messages": [ { "Content": [{ "Text": "What is the status of order #12345?" }], "Role": "user" } ], "Tools": [ { "Type": "agentcore_browser", "Name": "aws_browser_v1", "Config": { "AgentCoreBrowser": { "BrowserArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:aws:browser/aws.browser.v1" } } } ], "MaxIterations": 10, "TimeoutSeconds": 300 }, "End": true } ``` **Astuce** Vous pouvez tester cet état individuellement à l'aide de l'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API avant d'exécuter une exécution complète. ## Gestion des erreurs L'`InvokeHarness`API peut échouer avec diverses erreurs, notamment des erreurs de régulation, de validation et de refus d'accès. Pour une liste complète, consultez les [InvokeHarnesserreurs](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeHarness.html#API_InvokeHarness_Errors) dans le manuel *Amazon Bedrock AgentCore API Reference*. L'exemple suivant montre un état de tâche avec des `Catch` champs `Retry` et des champs pour la gestion des erreurs : ``` { "Type": "Task", "Resource": "arn:aws:states:::bedrockagentcore:invokeHarness", "Arguments": { "HarnessArn": "arn:aws:bedrock-agentcore:{{us-east-1}}:{{123456789012}}:harness/{{my-harness}}", "Messages": [ { "Content": [{ "Text": "{% $states.input.userMessage %}" }], "Role": "user" } ] }, "Retry": [ { "ErrorEquals": ["BedrockAgentCore.ThrottlingException"], "IntervalSeconds": 2, "MaxAttempts": 3, "BackoffRate": 2.0 } ], "Catch": [ { "ErrorEquals": ["BedrockAgentCore.ResourceNotFoundException"], "Next": "HandleNotFound" }, { "ErrorEquals": ["States.ALL"], "Next": "HandleError" } ], "End": true } ``` ## Politiques IAM pour appeler Amazon Bedrock AgentCore Les exemples de modèles suivants montrent comment AWS Step Functions générer des politiques IAM en fonction des ressources contenues dans la définition de votre machine d'état. Pour plus d’informations, consultez [Comment Step Functions génère des politiques IAM pour les services intégrés](service-integration-iam-templates.md) et [Découvrez les modèles d'intégration des services dans Step Functions](connect-to-resource.md). ### Exemples de politiques IAM pour l'intégration d'Amazon Bedrock AgentCore Les exemples suivants montrent comment créer des politiques IAM pour votre rôle d'exécution Step Functions afin d'interagir avec les ressources Amazon Bedrock AgentCore. Dans les exemples de politique suivants, remplacez les valeurs de l'espace réservé par vos propres valeurs. + [Politique IAM pour invoquer un harnais spécifique](#bedrockagentcore-policy-invoke-specific-harness) + [Politique IAM consistant à invoquer tous les harnais d'un compte](#bedrockagentcore-policy-invoke-all-harnesses) #### Politique IAM pour invoquer un harnais spécifique L'exemple de politique suivant permet d'invoquer un AgentCore harnais Amazon Bedrock spécifique par ARN. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "InvokeSpecificHarness", "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeHarness", "bedrock-agentcore:InvokeAgentRuntime" ], "Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/{{harnessName}}" } ] } ``` #### Politique IAM consistant à invoquer tous les harnais d'un compte L'exemple de politique suivant permet d'invoquer n'importe quel AgentCore harnais Amazon Bedrock dans votre compte. Nous vous recommandons de vous limiter à un ARN de harnais spécifique dans la mesure du possible. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "InvokeAllHarnesses", "Effect": "Allow", "Action": [ "bedrock-agentcore:InvokeHarness", "bedrock-agentcore:InvokeAgentRuntime" ], "Resource": "arn:aws:bedrock-agentcore:{{region}}:{{accountId}}:harness/*" } ] } ``` **Note** Si votre harnais utilise des outils tels que des passerelles, des navigateurs ou des interpréteurs de code, ces autorisations sont configurées sur le rôle d'*exécution du harnais, et non sur le rôle d'*exécution Step Functions. Pour plus d'informations, consultez la section [Autorisations relatives aux rôles d'exécution Harness](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-security.html) dans le *guide de l' AgentCore utilisateur d'Amazon Bedrock*.