Comment ça marche Conditions préalables Utilisation de la AgentCore CLI Utilisation du AgentCore SDK Cas d’utilisation courants Principaux choix de design Considérations sur la sécurité Gestion des erreurs Bonnes pratiques Quotas et limites

Coques interactives (terminaux)

L'InvokeAgentRuntimeCommandShellopération ouvre une session de terminal persistante et interactive au sein d'une session AgentCore Runtime en cours d'exécution WebSocket. Contrairement à l'exécution ponctuelle de commandes, les sessions shell conservent l'état : les variables d'environnement, le répertoire de travail et l'historique des commandes transfèrent les entrées. Cela permet le débogage, l'inspection de l'environnement et la création d'expériences de terminal dans votre application.

Pour appelerInvokeAgentRuntimeCommandShell, vous avez besoin d'bedrock-agentcore:InvokeAgentRuntimeCommandShellautorisations.

Comment ça marche

InvokeAgentRuntimeCommandShellétablit une WebSocket connexion à un processus shell interactif s'exécutant dans la session de votre agent. La connexion utilise des trames binaires pour diffuser les entrées et sorties du terminal dans les deux sens.

Même agent, même session

InvokeAgentRuntimeCommandShellfonctionne sur le même environnement d'exécution de l'agent que InvokeAgentRuntime etInvokeAgentRuntimeCommand. Vous ne créez pas de ressources distinctes. L'agent que vous avez déployé CreateAgentRuntime accepte les connexions shell sur toutes les sessions actives.

Note

Vous pouvez transmettre 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 à la fois session_id etshellId.

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 au cours d'une même session.
Reconnexion	Fournissez la même chose `session_id` et reconnectez-vous `shellId` au même shell après une déconnexion. Le service rejoue jusqu'à 256 Ko de sortie mise en mémoire tampon.
Plusieurs coques simultanées	Jusqu'à 10 sessions shell actives (terminaux) par environnement d'exécution. Les nouvelles connexions sont rejetées lorsqu'elles sont à pleine capacité.

Conditions préalables

Autorisation IAM bedrock-agentcore:InvokeAgentRuntimeCommandShell
Un ARN de point de terminaison AgentCore d'exécution valide 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.

Utilisation de la AgentCore CLI

Pour les instructions d'installation et de configuration, voir Commencer avec AgentCore Runtime à l'aide de la CLI.

La CLI fournit une expérience de terminal intégrée avecagentcore exec.


agentcore exec --it

Pour vous connecter à un environnement d'exécution spécifique :


agentcore exec --it --runtime <runtime-arn> --region us-west-2

Appuyez Ctrl+] pour le détacher d'une coque sans la fermer. La CLI imprime une commande de reconnexion :


agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

Pour les commandes ponctuelles, --it omettez :


agentcore exec "ls -la /tmp"

Pour une sortie lisible par machine, utilisez le mode JSON :


agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

Pour des exemples de CLI supplémentaires, consultez les AgentCore exemples sur GitHub.

Utilisation du AgentCore SDK

Installez le SDK Python :


pip install bedrock-agentcore

Exemple

SigV4 (default)

L'exemple suivant montre comment ouvrir une session shell à l'aide des informations d' AWS identification par défaut.


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

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

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 à se reconnecter shellId à un shell après une déconnexion, en préservant tous les états de 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 la WebSocket connexion est interrompue. Utilisez ReconnectConfig pour l'activer :


import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {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 des exemples de SDK supplémentaires, consultez les AgentCore exemples 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 lors du diagnostic des défaillances des agents ou de la validation de la configuration de 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 AI 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 le AgentCore Runtime et exécute des 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 le résultat 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 processus

Lancez des processus qui survivent à une seule requête HTTP. Utilisez la reconnexion pour vérifier les progrès ou fournir des informations supplémentaires au fil du temps.


nohup python train.py > /tmp/train.log 2>&1 &

Principaux choix de design

Sessions interactives persistantes: Chaque connexion correspond à un processus shell de longue durée. Vous pouvez envoyer plusieurs commandes sans rétablir la connexion, et l'état accumulé par les commandes précédentes (variables exportées, cd modifications) est disponible pour les commandes ultérieures.
Cadrage binaire sur WebSocket: I/O Le terminal est diffusé sous forme de WebSocket trames binaires. Cela prend en charge les séquences de contrôle des terminaux brutes, les couleurs, le mouvement du curseur et les applications en plein écran sans surcharge de codage.
Reconnexion avec rediffusion de sortie: Lorsque vous vous reconnectez en utilisant le mêmeshellId, le service rejoue jusqu'à 256 Ko de sortie récente. Cela vous permet de récupérer après une interruption du réseau sans perdre le contexte. Le processus shell continue de s'exécuter pendant la déconnexion.
Limite de sessions: Lorsque 10 sessions shell (terminaux) sont déjà ouvertes sur un environnement d'exécution, 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, consultez la section Bonnes pratiques en matière de sécurité pour AgentCore Runtime.

Important

Dans le cadre du modèle de responsabilité AWS partagée, vous êtes responsable des commandes que vous exécutez dans vos sessions AgentCore d'exécution. AWS fournit l'infrastructure sécurisée et l'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 session AgentCore 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 à la limite des machines virtuelles. Toutefois, au sein de votre machine virtuelle, les commandes shell ont un accès complet au système de fichiers du conteneur et à tous les identifiants ou secrets que vous avez configurés.

Audit à l'aide de CloudWatch journaux

AgentCore Runtime envoie l'ID de demande et les métadonnées de connexion au groupe de CloudWatch journaux Amazon Logs de votre agent. Vous pouvez utiliser ces journaux pour surveiller l'activité de connexion au shell et conserver une piste d'audit. I/O Le contenu du terminal (stdin/stdout) est diffusé à votre client et n'est pas enregistré par le service.

Audit avec CloudTrail

AWS CloudTrail enregistre les appels d'InvokeAgentRuntimeCommandShellAPI dans votre compte. Chaque enregistrement inclut des métadonnées telles que l'identité de l'appelant, l'horodatage, l'adresse IP source et le statut de la réponse. CloudTrail n'enregistre pas la charge utile de la demande ou de la réponse. CloudTrail À utiliser pour vérifier qui a ouvert les sessions du shell et à quel moment, puis établir une corrélation avec les CloudWatch journaux à 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 :

Utilisation de politiques IAM pour restreindre les appels que les principaux peuvent effectuer InvokeAgentRuntimeCommandShell
Configuration des points de terminaison VPC pour maintenir le trafic au sein de votre réseau
Configuration CloudWatch des journaux, des filtres métriques et des alarmes pour détecter les modèles de connexion inattendus
Examiner régulièrement CloudTrail les journaux pour détecter 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 la WebSocket mise à niveau :

ValidationException: Se produit lorsque les paramètres de demande ne sont pas valides. Cela peut se produire si l'identifiant de session est inférieur à 33 caractères, si la fonctionnalité n'est pas activée dans la région cible ou si l'agent n'est pas à l'état PRÊT.
AccessDeniedException: Survient lorsque vous ne disposez pas des autorisations nécessaires. Assurez-vous que votre politique IAM inclut l'bedrock-agentcore:InvokeAgentRuntimeCommandShellautorisation.
ResourceNotFoundException: Se produit lorsque le runtime 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 maximal de sessions shell simultanées (terminaux) atteint (10 ouvertes) — fermez une session existante et réessayez. (2) Le format de l'identifiant Shell n'est pas valide : il doit comporter de 1 à 128 caractères alphanumériques, traits de soulignement ou traits d'union. (3) Runtime inaccessible — réessayez après une pause. Analysez le error champ JSON du corps de la réponse pour distinguer les causes.
ThrottlingException: Survient lorsque vous dépassez la limite de débit de l'API. Implémentez une logique de ralentissement exponentiel et de nouvelle tentative.
ConflictException: Une autre connexion revendique la même chose shellId simultanément. Réessayez après 1 seconde. Il s'agit d'une condition de course limitée (et non d'un état persistant) qui se résout immédiatement lors d'une nouvelle tentative.

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 se déconnecte gracieusement	Afficher « déconnecté ». Terminaison normale.
`1001`	Disparition : déploiement ou arrêt du serveur	Auto-reconnect avec entreposé`shellId`.
`1003`	Données non prises en charge : envoyées après 5 zones de texte consécutives (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 entreposé`shellId`.
`1008`	Violation de la politique : expiration du TTL de connexion (1 heure), limite de fréquence d'images 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 : faites marche arrière, puis reconnectez-vous.
`1009`	Message trop volumineux : la charge utile des trames a dépassé 64 Ko	Réduisez la taille du cadre (bloc à <64 Ko), puis reconnectez-vous. La session est toujours active.
`1011`	Erreur du 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 de InvokeAgentRuntimeCommandShell :

Utilisez un identifiant unique shellId (tel qu'un UUID) pour chaque session logique afin de permettre la reconnexion. shellIdStockez-les côté client.
Utilisez-le ReconnectConfig dans le SDK pour gérer automatiquement les interruptions transitoires du réseau sans logique de reconnexion manuelle.
Lisez rapidement les images de sortie. Si le client prend du retard, la mémoire tampon d'écriture du serveur se remplit et la connexion se ferme avec du code1008.
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 le code fermé. 1009
Définissez des délais de connexion appropriés. La durée maximale de connexion est d'une heure. Reconnectez-vous à la même connexion shellId pour continuer au-delà.
Fermez les sessions de manière explicite lorsque vous avez terminé. Les sessions individuelles sont prises en compte dans le calcul de la limite de 10 sessions.

Quotas et limites

Limite	Value	Description
Charge utile maximale 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 ce seuil déclenche le 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 environnement d'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	Sortie maximale rejouée lors de la reconnexion à un shell.

Pour connaître les limites de service complètes, consultez la section Quotas pour Amazon Bedrock AgentCore.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Exécuter des commandes shell

Observez les agents