View a markdown version of this page

Coques interactives (terminaux) - Substrat rocheux d'Amazon AgentCore

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.

Note

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 session_id et shellId pour vous reconnecter au même shell après une déconnexion. Le service relit jusqu'à 256 Ko de sortie mise en mémoire tampon.

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

Note

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 sur GitHub.

À l'aide du AgentCore SDK

Installez le SDK Python :

pip install bedrock-agentcore
Exemple
SigV4 (default)
  1. L'exemple suivant montre comment ouvrir une session shell par défaut AWS informations d'identification.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn) as shell: print(f"Connected. Shell ID: {shell.shell_id}") # Send a command await shell.send("echo Hello from AgentCore Shell\n") # Read output frames async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") if "Hello from AgentCore Shell" in frame.text: break asyncio.run(main())
Pre-signed URL
  1. L'exemple suivant montre comment ouvrir une session shell à l'aide d'une URL pré-signée.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, PresignedAuth, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, auth=PresignedAuth(expires=120)) as shell: await shell.send("whoami\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") break asyncio.run(main())
OAuth
  1. L'exemple suivant montre comment ouvrir une session shell à l'aide d'un jeton porteur OAuth.

    import asyncio from bedrock_agentcore.runtime import AgentCoreRuntimeClient, OAuthAuth, ShellChannel async def main(): runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent" bearer_token = "your_oauth_token_here" client = AgentCoreRuntimeClient(region="us-west-2") async with client.open_shell(runtime_arn, auth=OAuthAuth(bearer_token=bearer_token)) as shell: await shell.send("echo oauth-connected\n") async for frame in shell: if frame.channel == ShellChannel.STDOUT: print(frame.text, end="") if "oauth-connected" in frame.text: break asyncio.run(main())

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 sur GitHub.

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, cd modifications) 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é

Astuce

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.

Important

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:InvokeAgentRuntimeCommandShell autorisation.

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 error champ 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 shellId simultané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 que InvokeAgentRuntimeCommandShell est 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

1000

Fermeture normale : la coque est sortie proprement ou débranchée gracieusement

Affichage « déconnecté ». Résiliation normale.

1001

Départ : déploiement ou arrêt du serveur

Auto-reconnect avec stocké shellId.

1003

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.

1006

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é shellId.

1008

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.

1009

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.

1011

Erreur de serveur : défaillance interne inattendue

Réessayez avec backoff.

4000

Remplacé : un autre client connecté au même shellId

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 le shellId côté client.

  • Utiliser ReconnectConfig dans 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 shellId pour 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é 1009.

Fréquence de trames

250 frames/sec

Le dépassement de cette limite déclenche un code de fermeture 1008.

Durée de connexion maximale

1 heure

La connexion se ferme avec un code 1008. Reconnectez-vous en utilisant le même shellId pour continuer.

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.