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)

L'InvokeAgentRuntimeCommandShellopération ouvre une session de terminal interactive et persistante dans le cadre d'une session AgentCore Runtime 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 appelerInvokeAgentRuntimeCommandShell, vous avez besoin d'bedrock-agentcore:InvokeAgentRuntimeCommandShellautorisations.

Comment ça marche

InvokeAgentRuntimeCommandShellétablit une WebSocket connexion à un processus shell interactif qui s'exécute 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

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 utilisé pour le déploiement CreateAgentRuntime accepte les connexions shell sur n'importe quelle session active.

La connexion prend en charge :

Conditions préalables

Utilisation de la AgentCore CLI

Pour obtenir des instructions d'installation et de configuration, voir Commencer à utiliser l' AgentCore interface de ligne de commande.

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 détacher la 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 d'autres exemples de CLI, consultez les AgentCore exemples sur GitHub.

Utilisation du AgentCore SDK

Installez le SDK Python :

pip install bedrock-agentcore

Reconnexion

Un modèle courant est utilisé pour se reconnecter shellId à un shell après une déconnexion, tout 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 la WebSocket connexion est interrompue. Utilisez ReconnectConfig pour activer ceci :

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 d'autres exemples de SDK, consultez les AgentCore exemples sur GitHub.

Cas d’utilisation courants

Principaux choix de conception

Considérations sur la sécurité

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 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 à 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é des connexions shell et conserver une piste d'audit. I/O Le contenu du terminal (stdin/stdout) est diffusé vers votre client et n'est pas enregistré par le service.

Audit avec CloudTrail

AWS CloudTrail enregistre les appels d'InvokeAgentRuntimeCommandShellAPI 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. Utilisez-le CloudTrail pour vérifier qui a ouvert les sessions shell et quand, puis établissez une corrélation avec CloudWatch les journaux en utilisant 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 :

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 :

Une fois la connexion établie, les codes de fermeture suivants indiquent pourquoi la connexion a été interrompue :

Bonnes pratiques

Suivez ces bonnes pratiques lors de l'utilisation de InvokeAgentRuntimeCommandShell :

Quotas et limites

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