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.
Exécutez des commandes shell dans AgentCore Sessions d'exécution
Le InvokeAgentRuntimeCommand l'opération vous permet d'exécuter des commandes shell directement dans un environnement AgentCore Exécutez une session et rediffusez la sortie HTTP/2. Les commandes s'exécutent dans le même conteneur, le même système de fichiers et le même environnement que votre agent, c'est-à-dire dans la même session que celle utilisée par InvokeAgentRuntime . Cela permet de créer des flux de travail dans lesquels votre application utilise l'agent pour raisonner des tâches et des commandes pour des opérations déterministes telles que l'exécution de tests, des opérations git ou la configuration de l'environnement.
Pour appeler InvokeAgentRuntimeCommand , il vous faut bedrock-agentcore:InvokeAgentRuntimeCommand autorisations.
Comment ça marche
InvokeAgentRuntimeCommand exécute une commande shell dans le conteneur d'un AgentCore Exécutez la session et retransmet la sortie.
Même agent, même session
InvokeAgentRuntimeCommand fonctionne sur le même environnement d'exécution et la même session d'agent que InvokeAgentRuntime . Vous ne créez pas de ressources distinctes. L'agent avec lequel vous avez déployé CreateAgentRuntime accepte à la fois les appels d'agents et l'exécution de commandes sur n'importe quelle session active.
Le AgentCore Runtime MicroVM n'inclut pas d'outils de développement tels que git , npm , ou des environnements d'exécution linguistiques par défaut. Tous les outils dont dépendent vos commandes doivent être inclus dans l'image de votre conteneur (via votre Dockerfile) ou installés dynamiquement lors de l'exécution.
La réponse est un flux de trois types d'événements :
| Événement | Lorsque | Contains |
|---|---|---|
|
|
Premier morceau |
Confirme que la commande a été lancée |
|
|
Pendant l'exécution |
Sortie dans l’ |
|
|
Dernier morceau |
|
Flux de sortie en temps réel. Vous voyez les résultats au fur et à mesure qu'ils s'exécutent, pas après la fin.
Conditions préalables
-
Autorisation IAM
bedrock-agentcore:InvokeAgentRuntimeCommand -
Un valide AgentCore ARN du point d'exécution
Les agents créés après le 17 mars 2026 prennent en charge l'exécution automatique des commandes. Si vous avez déployé votre agent avant cette date, vous devez le redéployer pour mettre à jour le runtime de l'agent.
Exécuter une commande
Exemple
Exemple de flux de travail d'agent de codage
Un modèle courant consiste à utiliser InvokeAgentRuntime pour raisonner et InvokeAgentRuntimeCommand pour des opérations déterministes au cours de la même session.
Exemple End-to-end flux de travail des agents de codage
import boto3 import json client = boto3.client('bedrock-agentcore', region_name='us-west-2') AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent' SESSION_ID = 'session-id-at-least-33-characters-long' def run_command(command, timeout=60): """Helper to run a command and return the exit code.""" response = client.invoke_agent_runtime_command( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, contentType='application/json', accept='application/vnd.amazon.eventstream', body={'command': command, 'timeout': timeout} ) for event in response.get('stream', []): if 'chunk' in event and 'contentStop' in event['chunk']: return event['chunk']['contentStop'].get('exitCode') return None # Step 1: Invoke the agent to analyze and write a fix response = client.invoke_agent_runtime( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, payload=json.dumps({"prompt": "Read JIRA-1234 and implement the fix in /workspace"}).encode() ) # Process agent response... # Step 2: Run tests deterministically exit_code = run_command('/bin/bash -c "cd /workspace && npm test"', timeout=300) # Step 3: If tests pass, commit and push if exit_code == 0: run_command('/bin/bash -c "cd /workspace && git checkout -b fix/JIRA-1234"') run_command('/bin/bash -c "cd /workspace && git add -A && git commit -m \'Fix JIRA-1234\'"') run_command('/bin/bash -c "cd /workspace && git push origin fix/JIRA-1234"')
L'agent écrit le code. La plateforme exécute les commandes. Chacun fait ce qu'il fait de mieux.
Cas d’utilisation courants
- Exécution de suites de tests
-
Une fois que l'agent a écrit le code, exécutez la suite de tests du projet sous forme de commande. La réponse en streaming vous permet de détecter les défaillances à un stade précoce et de renvoyer la sortie d'erreur spécifique à l'agent pour itération.
/bin/bash -c "cd /workspace && npm test 2>&1" - Opérations Git
-
Brancher, valider et pousser sont des opérations déterministes. Exécutez-les sous forme de commandes une fois que l'agent a terminé son travail, en gardant la logique de contrôle de version hors du LLM.
/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'" - Installation de dépendances
-
Démarrez l'environnement avant d'appeler les dépôts agent -clone, installez les packages, configurez les outils de génération. Cette préparation s'exécute plus rapidement et de manière plus fiable sous forme de commandes directes.
/bin/bash -c "pip install -r requirements.txt" - Créez et compilez
-
Étapes de compilation et génération de ressources : tout ce qui comporte une commande connue qui doit s'exécuter exactement comme spécifié.
/bin/bash -c "cd /workspace && cargo build --release" - Linting et validation
-
Exécutez des contrôles de qualité du code en tant que porte de validation une fois que l'agent a écrit le code, avant de le valider.
/bin/bash -c "cd /workspace && npx eslint src/ --format json" - Inspection environnementale
-
Vérifiez l'état d'exécution, les packages installés et les outils disponibles, ce qui est utile pour le débogage des défaillances de l'agent.
/bin/bash -c "python --version && node --version && git --version" - Opérations relatives aux données
-
Récupérez des ensembles de données, téléchargez des résultats, exécutez des transformations de données, des opérations de réseau et de calcul qui s'exécutent plus rapidement sous forme de commandes directes.
/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"
Principaux choix de conception
- One-shot, exécution non interactive
-
Chaque commande génère un nouveau processus bash, s'exécute jusqu'à la fin (ou timeout) et revient. Il n'existe pas de session shell persistante entre les commandes. Cela correspond à la façon dont les frameworks d'agents utilisent l'exécution des commandes : créez une commande, exécutez-la, lisez la sortie, décidez de la marche à suivre.
- Réponse en streaming terminée HTTP/2
-
La sortie arrive au fur et à mesure qu'elle est produite, et n'est mise en mémoire tampon qu'une fois terminée. UNE
npm testqui prend deux minutes diffuse les résultats en temps réel. Votre application peut détecter une panne dès les premières secondes et annuler prématurément au lieu d'attendre la fin de l'exécution. - Isolation du conteneur
-
Les commandes s'exécutent dans le même conteneur que le code de votre agent. Ils voient le même système de fichiers, les mêmes variables d'environnement et les mêmes packages installés. Un dossier que l'agent a écrit à
/workspace/fix.pyest immédiatement visible par une commande exécutéecat /workspace/fix.py. - Non-blocking au runtime
-
L'exécution des commandes ne bloque pas les appels d'agents. Vous pouvez invoquer l'agent et exécuter des commandes simultanément sur la même session. La plateforme gère la simultanéité.
- Stateless entre les commandes
-
Chaque commande redémarre à zéro : aucun historique du shell, aucune modification des variables d'environnement par rapport aux commandes précédentes n'est reportée. Si vous avez besoin d'un état, encodez-le dans la commande elle-même :
cd /workspace && export NODE_ENV=test && npm test.
Considérations sur la sécurité
Pour une vue consolidée de toutes les recommandations de sécurité relatives à Runtime, voir Meilleures pratiques de sécurité pour AgentCore Temps d'exécution.
Dans le cadre de la AWS modèle de responsabilité partagée, vous êtes responsable de la sécurité des commandes que vous exécutez dans votre AgentCore Sessions d'exécution. AWS fournit une infrastructure sécurisée et une isolation au niveau de la microVM. Vous êtes responsable des commandes que vous exécutez, des données que vous traitez et des contrôles d'accès que vous configurez.
La limite de sécurité pour l'exécution des commandes est la microVM. Chaque AgentCore La session d'exécution s'exécute dans une microVM isolée dotée de son propre noyau, de sa propre mémoire et de son propre système de fichiers. Les commandes que vous exécutez ne peuvent pas accéder aux charges de travail des autres clients ni échapper aux limites de la machine virtuelle. Cependant, au sein de votre machine virtuelle, les commandes ont un accès complet au système de fichiers du conteneur et à toutes les informations d'identification ou secrets que vous avez configurés.
Audit avec CloudWatch Journaux
AgentCore Runtime envoie l'ID de demande et la commande d'entrée à Amazon de votre agent CloudWatch Groupe de journaux. Vous pouvez utiliser ces journaux pour surveiller l'activité des commandes et conserver une piste d'audit des commandes exécutées au cours de vos sessions. Le résultat de l'exécution de la commande (stdout et stderr) est renvoyé à votre application et n'est pas enregistré par le service.
Audit avec CloudTrail
AWS CloudTrail disques InvokeAgentRuntimeCommand Appels d'API sur votre compte. Chaque enregistrement inclut des métadonnées telles que l'identité de l'appelant, l'horodatage, l'adresse IP source et l'état de la réponse. CloudTrail n'enregistre pas la charge utile de la demande ou de la réponse. Utiliser CloudTrail pour vérifier qui a exécuté les commandes et quand, puis établir une corrélation avec CloudWatch Enregistre les journaux à l'aide de l'ID de demande pour voir quelle commande a été exécutée.
Pour les charges de travail sensibles, envisagez de mettre en œuvre des contrôles supplémentaires tels que :
-
Utiliser les politiques IAM pour restreindre les numéros d'appel que les principaux peuvent appeler
InvokeAgentRuntimeCommand -
Configuration des points de terminaison VPC pour maintenir le trafic au sein de votre réseau
-
Configuration CloudWatch Enregistre les filtres métriques et les alarmes pour détecter les modèles de commande inattendus
-
Révision CloudTrail enregistre régulièrement les tentatives d'accès non autorisées
Gestion des erreurs
Lors de l'utilisation du InvokeAgentRuntimeCommand opération, vous pouvez rencontrer les erreurs suivantes :
- ValidationException
-
Survient lorsque les paramètres de demande ne sont pas valides. Vérifiez que l'ARN, l'ID de session et la commande de votre agent sont correctement formatés. La commande doit être comprise entre 1 octet et 64 Ko, le délai d'attente doit être compris entre 1 et 3 600 secondes et l'ID de session doit comporter au moins 33 caractères.
- ResourceNotFoundException
-
Se produit lorsque l'exécution ou la session de l'agent spécifiée est introuvable. Vérifiez que l'ARN de l'agent est correct et que la session est active.
- AccessDeniedException
-
Se produit lorsque vous ne disposez pas des autorisations nécessaires. Assurez-vous que votre politique IAM inclut
bedrock-agentcore:InvokeAgentRuntimeCommandautorisation. - ThrottlingException
-
Se produit lorsque vous dépassez la limite de taux de demande de 25 TPS. Implémentez une logique d'attente exponentielle et de nouvelle tentative dans votre application.
- RetryableConflictException
-
Se produit (HTTP 409) lorsqu'un
InvokeAgentRuntimeCommandL'opération cible une session que le service est en train de provisionner ou de supprimer. Le message estSession operation in progress, please retry. Cette condition est transitoire et peut être réessayée. Réessayez avec un court délai exponentiel au lieu de le traiter comme terminal. Le AWS Les SDK réessayent automatiquement cette exception lorsque les nouvelles tentatives par défaut sont activées. Si vous avez désactivé les nouvelles tentatives ou si vous appelez l'API directement sans AWS SDK, réessayez-le vous-même.
Une commande qui se termine par un code de sortie différent de zéro ne constitue pas une erreur d'API. Vérifiez le exitCode dans le contentStop événement pour déterminer si la commande elle-même a réussi. UNE status de TIMED_OUT indique que la commande a dépassé le délai spécifié.
Bonnes pratiques
Suivez ces bonnes pratiques lors de l'utilisation du InvokeAgentRuntimeCommand opération :
-
Utiliser
InvokeAgentRuntimeCommandpour les opérations déterministes (tests, git, builds) etInvokeAgentRuntimepour les tâches de raisonnement. N'acheminez pas les opérations déterministes via le LLM. -
Incluez tous les outils de développement dont dépendent vos commandes (tels que
git,npm, ou langages d'exécution) dans l'image de votre conteneur via votre Dockerfile. -
Vérifiez toujours
exitCodedans lecontentStopévénement pour déterminer si la commande a réussi. -
Définissez des délais d'attente appropriés. Une suite de tests peut nécessiter 5 minutes, tandis qu'un
git pushpourrait n'avoir besoin que de 30 secondes. -
Traitez la sortie en continu de manière incrémentielle pour détecter les défaillances à un stade précoce. Vous pouvez annuler une commande de longue durée plutôt que d'attendre qu'elle soit terminée.
-
Encodez l'état dans la commande elle-même en utilisant
&&chaînage (par exemple,cd /workspace && export NODE_ENV=test && npm test), car chaque commande lance un nouveau processus bash. -
Utilisez des UUID pour les ID de session afin de respecter l'exigence minimale de 33 caractères (par exemple,
12345678-1234-1234-1234-123456789012).