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 InvokeHarnesscet é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 InvokeHarnessla 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 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 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 aux sections etTransmission de paramètres à une API de service dans Step Functions.
Principales caractéristiques de l'intégration optimisée des AgentCore harnais
-
Seul le modèle Réponse à la requête d'intégration est pris en charge. Les Attendre un rappel avec un jeton de tâche modèles Exécuter une tâche (.sync) et ne sont pas pris en charge.
-
La réponse est transformée en une structure JSON en forme de Converse. 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 (
InputTokensOutputTokens,,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, voirQuotas liés à l'exécution des tâches.
-
La durée d'exécution maximale de l'état
InvokeHarnessTask est de 15 minutes (900 secondes), même si laTimeoutSecondsvaleur 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
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 InvokeHarnessmanuel 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'startSyncExecutionaction 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. ContientRole(toujours"assistant") etContent(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 unTextchamp 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. ContientInputTokensOutputTokens, etTotalTokens. -
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).
Exemple 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
}Exemple 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'TestStateAPI avant d'exécuter une exécution complète.
Gestion des erreurs
L'InvokeHarnessAPI 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 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 et Découvrez les modèles d'intégration des services dans Step Functions.
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
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 dans le guide de l' AgentCore utilisateur d'Amazon Bedrock.
