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.
Coques interactives (terminaux)
Le InvokeAgentRuntimeCommandShell l'opération ouvre une session de terminal interactive et persistante dans un environnement en cours d'exécution AgentCore Session d'exécution terminée WebSocket. Contrairement à l'exécution de commandes ponctuelle, les sessions shell conservent leur état : les variables d'environnement, le répertoire de travail et l'historique des commandes sont transmis à toutes les entrées. Cela permet le débogage, l'inspection de l'environnement et la création d'expériences terminales dans votre application.
Pour appeler InvokeAgentRuntimeCommandShell, il vous faut bedrock-agentcore:InvokeAgentRuntimeCommandShell autorisations.
Comment ça marche
InvokeAgentRuntimeCommandShell établit un WebSocket connexion à un processus shell interactif s'exécutant dans la session de votre agent. La connexion utilise des trames binaires pour diffuser l'entrée et la sortie du terminal dans les deux sens.
Même agent, même session
InvokeAgentRuntimeCommandShell fonctionne sur le même environnement d'exécution de l'agent que InvokeAgentRuntime et InvokeAgentRuntimeCommand. Vous ne créez pas de ressources distinctes. L'agent avec lequel vous avez déployé CreateAgentRuntime accepte les connexions shell sur n'importe quelle session active.
Vous pouvez passer un session_id pour cibler une session d'exécution spécifique. En cas d'omission, une nouvelle session est créée pour chaque connexion. Pour utiliser la reconnexion, vous devez stocker et réutiliser les deux session_id et shellId.
La connexion prend en charge :
| Fonctionnalité | Description |
|---|---|
|
État persistant |
Les variables d'environnement, le répertoire de travail et l'historique des commandes transfèrent les entrées d'une même session. |
|
Reconnexion |
Fournissez la même chose |
|
Plusieurs coques simultanées |
Jusqu'à 10 sessions shell actives (terminaux) par exécution. Les nouvelles connexions sont rejetées lorsqu'elles sont à pleine capacité. |
Conditions préalables
-
Autorisation IAM
bedrock-agentcore:InvokeAgentRuntimeCommandShell -
Un valide AgentCore ARN du point d'exécution avec un environnement d'exécution à l'état READY
Les agents créés après le 5 juin 2026 prennent automatiquement en charge les shells interactifs (terminaux). Si vous avez déployé votre agent avant cette date, vous devez le redéployer pour mettre à jour le runtime de l'agent.
À l'aide du AgentCore CLI
Pour les instructions d'installation et de configuration, voir Commencez avec le AgentCore CLI.
La CLI fournit une expérience de terminal interactive intégrée. Transmettez un identifiant d'exécution, et non un ARN d'exécution. Pour un temps d'exécution dans un AgentCore projet, le Runtime ID est le dernier segment du Runtime arn dans la sortie de agentcore status --json:
Pour un environnement géré par un harnais, utilisez agentcore harness shell --id <harness-id> au lieu de l'ID du Runtime géré. Voir Ouvrez une coque de harnais à l'aide du AgentCore CLI.
agentcore runtime shell --id <runtime-id>
Sans --qualifier, l'interface de ligne de commande vous invite à choisir un point de terminaison. Pour sélectionner directement un point de terminaison :
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --region us-west-2
Utiliser --session-id pour ouvrir le shell dans une session d'exécution spécifique :
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id>
Une fois la connexion établie, la CLI imprime l'ID de session d'exécution, l'ID du shell et une commande de reconnexion complète. Presse Ctrl+] pour détacher le terminal local tout en maintenant le shell distant en cours d'exécution :
Connected Session ID: <runtime-session-id> Shell ID: <shell-id> Ctrl+D or 'exit' to close · Ctrl+] to detach To reconnect: agentcore runtime shell --id <runtime-id> --qualifier DEFAULT --session-id <runtime-session-id> --shell-id <shell-id> --region us-west-2
Exécutez la commande imprimée pour vous reconnecter au même shell. Lorsque vous créez vous-même la commande, --shell-id a besoin --session-id:
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --session-id <runtime-session-id> \ --shell-id <shell-id> \ --region us-west-2
Pour un environnement d'exécution configuré avec l'autorisation CUSTOM_JWT, transmettez également son jeton porteur :
agentcore runtime shell \ --id <runtime-id> \ --qualifier DEFAULT \ --bearer-token file://token.txt
La commande de reconnexion n'inclut jamais de jeton porteur. Passe --bearer-token à nouveau lors de la reconnexion à un environnement d'exécution CUSTOM_JWT.
Entrez exit ou appuyez sur Ctrl+D pour fermer définitivement le shell de la télécommande. Presse Ctrl+] lorsque vous souhaitez vous déconnecter et vous reconnecter ultérieurement.
Pour exécuter une seule commande sans ouvrir de shell, utilisez agentcore runtime exec:
agentcore runtime exec \ --id <runtime-id> \ --command "ls -la /tmp"
Pour d'autres exemples de CLI, voir AgentCore échantillons
À l'aide du AgentCore SDK
Installez le SDK Python :
pip install bedrock-agentcore
Exemple
Reconnexion
Un modèle courant consiste à utiliser shellId pour se reconnecter à un shell après une déconnexion, en préservant l'état de la session.
import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient async def main(): client = AgentCoreRuntimeClient(region="us-west-2") runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" session_id = "my-session-0000000000000000000000" shell_id = "my-shell" shell = await client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ).__aenter__() print(f"connected (reconnected={shell.reconnected})") await shell.send("export GREETING='hello'\n") await asyncio.sleep(1) async with client.open_shell( runtime_arn, session_id=session_id, shell_id=shell_id, ) as shell2: print(f"reconnected (reconnected={shell2.reconnected})") assert shell2.reconnected if __name__ == "__main__": asyncio.run(main())
Auto-reconnect
Le SDK peut également se reconnecter automatiquement lorsque WebSocket la connexion tombe. Utiliser ReconnectConfig pour activer cela :
import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel async def on_reconnect(): print("Reconnected") async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" shell_id = "my-persistent-shell" config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect) client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell: # If the connection drops, the SDK retries automatically await shell.send("long-running-command\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") asyncio.run(main())
Pour d'autres exemples de SDK, voir AgentCore échantillons
Cas d’utilisation courants
- Débogage interactif
-
Ouvrez un shell pour inspecter l'environnement d'exécution de votre agent : vérifiez les packages installés, lisez les fichiers journaux, examinez le système de fichiers ou testez les commandes avant de les ajouter au code de votre agent.
python --version && pip list | head -20 - Inspection environnementale
-
Vérifiez les variables d'environnement, la connectivité réseau, les outils disponibles et l'état du système de fichiers. Utile pour diagnostiquer les défaillances des agents ou valider la configuration du déploiement.
env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/ - Accès au terminal de l'agent de codage
-
Les agents de codage IA utilisent des shells interactifs (terminaux) comme environnement d'exécution. Lorsqu'un agent de codage doit exécuter du code, installer des packages ou exécuter des tests, il ouvre une session shell sur AgentCore Exécute et exécute les commandes directement, de la même manière qu'un développeur utiliserait un terminal. Par exemple, Claude Code, Amazon Kiro et OpenAI Codex se connectent chacun à une session shell où ils peuvent écrire du code de manière itérative, l'exécuter, observer les résultats et corriger les erreurs en boucle. L'état persistant signifie que l'agent peut exécuter une séquence de commandes sans perdre le contexte entre les étapes.
# A coding agent opens a shell and iterates on code async with client.open_shell(runtime_arn, shell_id="agent-workspace") as shell: await shell.send("cd /workspace && git clone https://github.com/user/repo.git\n") await shell.send("cd repo && pip install -r requirements.txt\n") await shell.send("python -m pytest tests/ -v\n") # Agent reads test output, fixes failures, re-runs — all in the same shell - Long-running les processus
-
Démarrez des processus qui survivent à une seule requête HTTP. Utilisez la fonction de reconnexion pour vérifier la progression ou fournir des informations supplémentaires au fil du temps.
nohup python train.py > /tmp/train.log 2>&1 &
Principaux choix de conception
- Sessions interactives persistantes
-
Chaque connexion correspond à un processus de coque de longue durée. Vous pouvez envoyer plusieurs commandes sans rétablir la connexion et l'état cumulé par les commandes précédentes (variables exportées,
cdmodifications) est disponible pour les versions ultérieures. - Encadrement binaire WebSocket
-
Borne I/O est diffusé en tant que binaire WebSocket cadres. Cela prend en charge les séquences brutes de contrôle des terminaux, les couleurs, le mouvement du curseur et les applications en plein écran sans surcharge d'encodage.
- Reconnexion avec rediffusion de la sortie
-
Lorsque vous vous reconnectez en utilisant le même
shellId, le service relit jusqu'à 256 Ko de données récentes. Cela vous permet de vous remettre des interruptions du réseau sans perdre le contexte. Le processus shell continue de s'exécuter pendant la déconnexion. - Limite de session
-
Lorsque 10 sessions shell (terminaux) sont déjà ouvertes lors d'un runtime, les nouvelles connexions sont rejetées avec une erreur. Vous devez fermer une session existante avant d'en ouvrir une nouvelle.
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 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 les sessions shell (terminaux) 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 sessions Shell ne peuvent pas accéder aux charges de travail des autres clients ni échapper aux limites des machines virtuelles. Cependant, au sein de votre machine virtuelle, les commandes shell 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 les métadonnées de connexion à Amazon de votre agent CloudWatch Groupe de journaux. Vous pouvez utiliser ces journaux pour surveiller l'activité des connexions shell et conserver une piste d'audit. Borne I/O contenu (stdin/stdout) est diffusé sur votre client et n'est pas enregistré par le service.
Audit avec CloudTrail
AWS CloudTrail disques InvokeAgentRuntimeCommandShell 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 ouvert les sessions shell et quand, puis établir une corrélation avec CloudWatch Enregistre les données à l'aide de l'ID de demande pour les détails de connexion.
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
InvokeAgentRuntimeCommandShell -
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 connexion inattendus
-
Révision CloudTrail enregistre régulièrement les tentatives d'accès non autorisées
Gestion des erreurs
Lors de l'établissement d'une connexion à une session shell, vous pouvez rencontrer les erreurs suivantes lors de WebSocket mise à niveau :
Si la CLI indique Server rejected WebSocket connection: HTTP 400 et que le Runtime est géré par un harnais, utilisez la commande shell Harness avec l'ID du harnais. Les autres réponses HTTP 400 peuvent avoir différentes causes ; vérifiez la ressource et la demande plutôt que de supposer que chaque rejet identifie un harnais.
- ValidationException
-
Se produit lorsque les paramètres de demande ne sont pas valides. Cela peut se produire si l'ID de session comporte moins de 33 caractères, si la fonctionnalité n'est pas activée dans la région cible ou si l'agent n'est pas en état PRÊT.
- AccessDeniedException
-
Se produit lorsque vous ne disposez pas des autorisations nécessaires. Assurez-vous que votre politique IAM inclut
bedrock-agentcore:InvokeAgentRuntimeCommandShellautorisation. - ResourceNotFoundException
-
Se produit lorsque l'environnement d'exécution de l'agent spécifié est introuvable. Vérifiez que l'ARN d'exécution est correct.
- RuntimeClientError (424)
-
Cela se produit dans plusieurs scénarios : (1) Nombre maximum de sessions shell simultanées (terminaux) atteint (10 ouvertes) : fermez une session existante et réessayez. (2) Le format d'identification du shell n'est pas valide. Il doit contenir entre 1 et 128 caractères alphanumériques, des traits de soulignement ou des tirets. (3) Runtime inaccessible — réessayez après la réinitialisation. Analyser le JSON du corps de la réponse
errorchamp permettant de distinguer les causes. - ThrottlingException
-
Se produit lorsque vous dépassez la limite de débit de l'API. Implémentez une logique d'attente exponentielle et de nouvelle tentative.
- ConflictException
-
Une autre connexion prétend la même chose
shellIdsimultanément. Réessayez après 1 seconde. Il s'agit d'une condition de course restreinte (et non d'un état persistant) qui se résout immédiatement lors d'une nouvelle tentative. - RetryableConflictException (409)
-
Se produit lorsque vous ouvrez une connexion à une session shell pendant que le service provisionne ou supprime la session cible. Le message est
Session operation in progress, please retry. Cette condition est transitoire et peut être réessayée. La fenêtre est courte et les sessions déjà en cours ne sont pas affectées. Réessayez avec une courte temporisation exponentielle. Parce queInvokeAgentRuntimeCommandShellest un WebSocket API, le AWS Les kits de développement logiciel ne le réessayent pas automatiquement. Réessayez vous-même.
Une fois la connexion établie, les codes de fermeture suivants indiquent pourquoi la connexion a été interrompue :
| Code | Signification | Action du client |
|---|---|---|
|
|
Fermeture normale : la coque est sortie proprement ou débranchée gracieusement |
Affichage « déconnecté ». Résiliation normale. |
|
|
Départ : déploiement ou arrêt du serveur |
Auto-reconnect avec stocké |
|
|
Données non prises en charge : envoyées après 5 blocs de texte consécutifs (protocole binaire uniquement) |
NE VOUS RECONNECTEZ PAS automatiquement. Passez aux trames binaires. |
|
|
Fermeture anormale — synthétisée localement lorsqu'aucune trame fermée n'est reçue (mort du réseau, TCP RST) |
Auto-reconnect avec stocké |
|
|
Violation des règles : le TTL de connexion a expiré (1 heure), la limite de fréquence d'images est dépassée (250) frames/sec), ou dépassement de la mémoire tampon d'écriture |
Auto-reconnect pour l'expiration du TTL (nouveau TTL lors de la reconnexion). Pour la limite de débit : redémarrez, puis reconnectez-vous. |
|
|
Message trop volumineux : la charge utile de la trame a dépassé 64 Ko |
Réduisez la taille de l'image (segment à <64 Ko), puis reconnectez-vous. La session est toujours en cours. |
|
|
Erreur de serveur : défaillance interne inattendue |
Réessayez avec backoff. |
|
|
Remplacé : un autre client connecté au même |
NE VOUS RECONNECTEZ PAS automatiquement. Afficher « session jointe depuis un autre client ». |
Bonnes pratiques
Suivez ces bonnes pratiques lors de l'utilisation InvokeAgentRuntimeCommandShell:
-
Utilisez un
shellId(tel qu'un UUID) pour chaque session logique afin de permettre la reconnexion. Stockez leshellIdcôté client. -
Utiliser
ReconnectConfigdans le SDK pour gérer automatiquement les interruptions transitoires du réseau sans logique de reconnexion manuelle. -
Lisez rapidement les trames de sortie. Si le client est en retard, la mémoire tampon d'écriture du serveur se remplit et la connexion se ferme avec du code
1008. -
Pour les entrées volumineuses (comme le collage d'un fichier), divisez le contenu en morceaux de moins de 64 Ko par image pour éviter de fermer le code
1009. -
Définissez les délais de connexion appropriés. La durée de connexion maximale est d'une heure — reconnectez-vous avec la même
shellIdpour continuer au-delà de cela. -
Fermez les sessions de manière explicite lorsque vous avez terminé. Les sessions individuelles sont prises en compte dans la limite de 10 sessions.
Quotas et limites
| Limite | Value | Description |
|---|---|---|
|
Taille maximale de la charge utile du châssis |
64 Ko |
Les trames dépassant cette limite entraînent un code fermé |
|
Fréquence de trames |
250 frames/sec |
Le dépassement de cette limite déclenche un code de fermeture |
|
Durée de connexion maximale |
1 heure |
La connexion se ferme avec un code |
|
Sessions shell simultanées (terminaux) par exécution |
10 |
Les nouvelles connexions sont rejetées si 10 sessions sont déjà ouvertes. Fermez une session existante et réessayez. |
|
Tampon de reconnexion |
256 Ko |
Puissance maximale rejouée lors de la reconnexion à un shell. |
Pour connaître les limites de service complètes, voir Quotas pour Amazon Bedrock AgentCore.