Comment ça marche Conditions préalables Connect via l' WebSocket API Protocole de trame binaire Reconnexion à un shell Cas d’utilisation courants Considérations sur la sécurité Gestion des erreurs Bonnes pratiques Quotas et limites Rubriques associées

Coques interactives (terminaux)

L'InvokeAgentRuntimeCommandShellopération ouvre un terminal interactif persistant dans le cadre d'une session AgentCore Harness en cours d'exécution WebSocket. L'API identifie cette session de harnais à l'aide d'un ID de session d'exécution. Contrairement à l'exécution de commandes ponctuelle, un shell interactif conserve ses variables d'environnement, son répertoire de travail, son historique des commandes et ses processus en cours d'exécution sur les entrées.

Utilisez un shell interactif pour le débogage, le développement itératif ou les processus de longue durée lorsque vous devez préserver l'état du shell dans toutes les commandes.

Pour les demandes pré-signées SigV4 et SigV4, l'appelant a besoin d'une bedrock-agentcore:InvokeAgentRuntimeCommandShell autorisation sur le harnais. Bearer-token les demandes doivent plutôt satisfaire l'autorisateur entrant du harnais.

Important

Au lancement, les commandes AgentCore CLI et les assistants shell de haut niveau du AgentCore SDK ne prennent pas en charge les cibles de harnais. Connectez-vous directement à un harnais via l'InvokeAgentRuntimeCommandShell WebSocket API, comme indiqué sur cette page.

Comment ça marche

InvokeAgentRuntimeCommandShellétablit une WebSocket connexion à un processus shell interactif dans la microVM qui exécute votre session Harness. La connexion utilise des trames binaires pour diffuser les entrées et sorties du terminal dans les deux sens.

Si le harnais utilise l'environnement par défaut, le shell s'exécute dans l'environnement de harnais géré. Si le harnais utilise un conteneur personnalisé, la coque passe dans ce conteneur. Les terminaux interactifs Harness ne supportent actuellement que Bash.

La connexion prend en charge :

Fonctionnalité	Description
État persistant	Les variables d'environnement, le répertoire de travail, l'historique des commandes et les processus en cours d'exécution sont conservés dans le même shell.
Reconnexion	Fournissez le même ID de session d'exécution et reconnectez-vous `shellId` à un shell détaché. Le service rejoue jusqu'à 256 Ko de sortie mise en mémoire tampon.
Plusieurs coques simultanées	Ouvrez jusqu'à 10 sessions shell actives lors d'une session harnais. Les coques détachées ne sont pas prises en compte dans cette limite. Chaque shell possède un processus de terminal indépendant et partage le système de fichiers de session.

Conditions préalables

Un harnais en READY état
Autorisation pour la méthode d'authentification sélectionnée : autorisation bedrock-agentcore:InvokeAgentRuntimeCommandShell IAM pour SigV4, ou jeton porteur accepté par l'autorisateur entrant du harnais
Un WebSocket client qui prend en charge les cadres binaires et les en-têtes de requête ou les URL pré-signées
Pour un conteneur personnalisé, Bash est installé à/bin/bash. Les autres shells, y compris sh etdash, ne sont actuellement pas pris en charge.

Pour plus d'informations sur le modèle complet d'autorisations du harnais, consultezAutorisations IAM requises pour les appelants.

Connect via l' WebSocket API

Ouvrez une WebSocket connexion à l'URL suivante :


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells

Utilisez l'ARN du harnais, et non l'ARN de son environnement d'exécution géré. URL-encode l'ARN complet du harnais avant de le placer dans le chemin. Le format d'un ARN de harnais est le suivant :


arn:aws:bedrock-agentcore:<region>:<accountId>:harness/<harnessId>

Envoyez les valeurs suivantes avec la demande de WebSocket mise à niveau :

Value	Obligatoire	Description
Authentification	Oui	Signez la demande avec Signature Version 4 (SigV4), utilisez une URL Sigv4 pré-signée ou envoyez le jeton porteur configuré par l'autorisateur entrant du harnais dans l'en-tête. `Authorization` Le nom du service SigV4 est`bedrock-agentcore`.
`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`paramètre d'en-tête ou de requête	Non	Cible une session de harnais existante ou en crée une avec l'ID fourni. La valeur doit contenir au moins 33 caractères. Si vous l'omettez, le service crée un identifiant de session d'exécution et le renvoie dans la réponse.
`Sec-WebSocket-Protocol`	Non	Pour les connexions SigV4, proposez éventuellement `v1.command.agentcore.aws.dev` d'identifier le protocole binaire command-shell. Bearer-token les connexions utilisent plutôt les sous-protocoles d'authentification décrits après ce tableau.
`shellId`paramètre de requête	Non	Reconnecte à un shell existant. Utilisez-le avec le même identifiant de session d'exécution que celui qui a créé le shell.

Pour un client de navigateur qui ne peut pas définir d'Authorizationen-tête, encodez en base64url-le jeton porteur et offrez le passage à la fois ainsi qu'à la sentinelle. base64UrlBearerAuthorization.<encoded-token> base64UrlBearerAuthorization Sec-WebSocket-Protocol Ne l'offrez pas également v1.command.agentcore.aws.dev sur une connexion porteur-jeton.

La 101 Switching Protocols réponse renvoie l'ID de session d'exécution et l'ID de shell dans les X-Amzn-Bedrock-AgentCore-Shell-Id en-têtes X-Amzn-Bedrock-AgentCore-Runtime-Session-Id et. Les clients qui ne peuvent pas lire les en-têtes de réponse de WebSocket mise à niveau peuvent lire l'ID du shell dès la première STATUS image. Le cadre ne contient pas l'ID de session d'exécution. Ces clients doivent donc générer et conserver un identifiant de session d'exécution avant de se connecter. Lorsque vous créez une URL pré-signée, incluez l'ID de session d'exécution en tant que paramètre de requête avant de signer l'URL.

Le délai de WebSocket mise à niveau ne s'applique que jusqu'au retour 101 Switching Protocols du service. L'initialisation du shell et du conteneur personnalisé peut se poursuivre après la mise à niveau. Attendez l'STATUSimage initiale avant de considérer que le shell est prêt, appliquez un délai d'attente distinct à l'application pendant l'attente et gérez le code de fermeture 1011 comme une initialisation du shell ou une défaillance du serveur.

L'exemple Python suivant utilise un WebSocket client générique botocore uniquement pour signer la demande de mise à niveau. Il n'utilise pas d'assistant shell du AgentCore SDK.


pip install "boto3>=1.34" "websockets>=15"


import asyncio
import json
import urllib.parse
import uuid

import botocore.session
import websockets
from botocore.auth import SigV4Auth
from botocore.awsrequest import AWSRequest


REGION = "us-west-2"
HARNESS_ARN = (
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:"
    "harness/MyHarness-a1b2c3d4e5"
)
SESSION_ID = str(uuid.uuid4())  # 36 characters
SUBPROTOCOL = "v1.command.agentcore.aws.dev"


def signed_headers(url):
    request = AWSRequest(
        method="GET",
        url=url,
        headers={
            "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": SESSION_ID,
        },
    )
    credentials = botocore.session.Session().get_credentials()
    SigV4Auth(credentials, "bedrock-agentcore", REGION).add_auth(request)
    return dict(request.headers)


async def main():
    encoded_arn = urllib.parse.quote(HARNESS_ARN, safe="")
    host = f"bedrock-agentcore.{REGION}.amazonaws.com"
    path = f"/runtimes/{encoded_arn}/ws/shells"
    https_url = f"https://{host}{path}"
    websocket_url = f"wss://{host}{path}"

    async with websockets.connect(
        websocket_url,
        additional_headers=signed_headers(https_url),
        subprotocols=[SUBPROTOCOL],
        open_timeout=330,
    ) as websocket:
        shell_id = websocket.response.headers.get(
            "X-Amzn-Bedrock-AgentCore-Shell-Id"
        )
        print(f"Connected to shell {shell_id}")

        # Channel 0x00 carries terminal input.
        await websocket.send(b"\x00echo 'Hello from my harness'\n")
        await websocket.send(b"\x00exit\n")

        async for frame in websocket:
            if isinstance(frame, str) or not frame:
                continue

            channel, payload = frame[0], frame[1:]
            if channel == 0x01:  # PTY output (command stdout and stderr)
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x02:  # Service or platform diagnostics
                print(payload.decode("utf-8", errors="replace"), end="")
            elif channel == 0x03:  # STATUS
                status = json.loads(payload)
                shell_id = status.get("metadata", {}).get("shellId", shell_id)
                print(f"\nStatus: {status}")


asyncio.run(main())

Protocole de trame binaire

Chaque message au niveau de l'application est une trame binaire WebSocket . Le premier octet identifie le canal et les octets restants constituent la charge utile.

Canal	Direction	Charge utile
`0x00`- STDIN	Du client au service	Entrée de borne brute.
`0x01`- MAILLÉ	Service au client	Sortie PTY brute. Le PTY combine les commandes stdout et stderr sur ce canal.
`0x02`- ÉTOILE	Service au client	Diagnostic du service ou de la plateforme. La commande stderr fait partie de la sortie `0x01` PTY.
`0x03`- STATUT	Service au client	UTF-8 JSON contenant les métadonnées de connexion ou l'état de sortie du shell.
`0x04`- REDIMENSIONNER	Du client au service	UTF-8 JSON dans le formulaire`{"width":120,"height":40}`. Chaque dimension doit être comprise entre 1 et 1 000.
`0x05`- BATTEMENT DE CŒUR	Dans les deux directions	Application facultative Heartbeat. Le service fait écho à la charge utile. WebSocket les cadres ping sont également pris en charge.
`0xFF`- FERMER	Dans les deux directions	Met fin à la session shell.

Les blocs de texte ne font pas partie du protocole. Le service ignore les zones de texte isolées et ferme la connexion avec le code 1003 après cinq zones de texte consécutives.

La première STATUS image confirme la connexion et inclut des métadonnées similaires aux suivantes :


{
  "kind": "Status",
  "apiVersion": "v1",
  "metadata": {
    "shellId": "my-shell",
    "reconnected": false
  },
  "status": "Success"
}

Lorsque le shell sort avec un statut différent de zéro, la dernière STATUS image inclut une ExitCode cause. details.causes

Reconnexion à un shell

Stockez à la fois l'ID de session d'exécution et l'ID de shell. Pour vous reconnecter, utilisez le même en-tête d'ID de session d'exécution et ajoutez l'ID de URL-encoded shell en tant que paramètre de requête :


wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-harness-arn>/ws/shells?shellId=<shell-id>

Le processus shell continue de s'exécuter tant que la connexion est déconnectée. Lors de la reconnexion, le service rejoue jusqu'à 256 Ko de sortie mise en mémoire tampon. Le STATUS cadre de connexion définit metadata.reconnected true et inclut metadata.bytesDropped si la coque détachée a produit plus de sortie que ce que la mémoire tampon de rediffusion pouvait en conserver.

L'ouverture d'une autre connexion avec le même identifiant de shell remplace la connexion existante. Le client remplacé reçoit le code de fermeture4000.

Cas d’utilisation courants

Débogage interactif: Inspectez les packages, les fichiers, les processus et la configuration de l'environnement installés dans le même environnement que l'agent Harness.
Validation de l'environnement personnalisé: Pour un harnais doté d'un conteneur personnalisé, vérifiez les dépendances installées et les montages du système de fichiers depuis l'intérieur de ce conteneur.
Accès au terminal de l'agent de codage: Fournissez un environnement d'exécution permanent pour les agents de codage qui doivent créer des fichiers, exécuter des tests, inspecter les résultats et itérer.
Long-running processus: Démarrez un processus, détachez-le et reconnectez-vous ultérieurement pour vérifier la progression ou fournir des informations. WebSocket

Considérations sur la sécurité

Important

Un principal qui peut ouvrir un shell Harness dispose d'un accès de commande interactif à la session Harness. Limitez-vous bedrock-agentcore:InvokeAgentRuntimeCommandShell aux principes fiables et aux ARN de harnais spécifiques.

Le shell peut accéder aux données, aux fichiers et aux secrets fournis par le client dans l'environnement sélectionné ou sur des systèmes de fichiers montés. Il peut également se connecter à des destinations réseau accessibles par la session. L'environnement shell utilise une liste d'autorisation et n'injecte pas d'informations d'identification de AgentCore plate-forme ou de charge de travail. Le shell reste dans la microVM isolée de la session et ne peut pas accéder à la charge de travail d'un autre client.

AgentCore envoie l'ID de demande et les métadonnées de connexion au groupe de journaux Harness Runtime dans Amazon CloudWatch Logs. Le service n'enregistre pas les entrées ou sorties du terminal.

AWS CloudTrail enregistre les appels InvokeAgentRuntimeCommandShell d'API, y compris l'identité de l'appelant, l'horodatage, l'adresse IP source, la ressource d'exécution résolue et le statut de la réponse. CloudTrail n'enregistre pas l'entrée ou la sortie du terminal.

Pour plus de conseils sur la sécurité Harness, voirSécurité et contrôles d'accès.

Gestion des erreurs

La WebSocket mise à niveau peut renvoyer les erreurs suivantes :

ValidationException: Les paramètres de demande ne sont pas valides. Vérifiez que l'identifiant de session d'exécution contient au moins 33 caractères, que l'identifiant du shell est valide et que la fonctionnalité est disponible dans la région cible. Utilisez l'ARN du URL-encoded harnais dans le chemin de la demande ; l'utilisation directe de l'ARN d'exécution géré est rejetée.
AccessDeniedException: L'appelant n'a pas d'bedrock-agentcore:InvokeAgentRuntimeCommandShellautorisation sur le harnais.
ResourceNotFoundException: Le harnais spécifié n'existe pas. Vérifiez que l'URL contient l'ARN du URL-encoded harnais.
ServiceQuotaExceededException (429): Le maximum de 10 shells actifs est déjà ouvert. Mettez fin à un shell actif ou détachez-le, puis réessayez.
RuntimeClientError (424): Le temps d'exécution n'a pas pu être atteint.
ThrottlingException: La demande a dépassé la limite de débit de l'API. Réessayez avec un recul exponentiel.
RetryableConflictException (409): Le service est en train de configurer ou de supprimer la session cible. Réessayez avec un court recul exponentiel.

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

Code	Signification	Action du client
`1000`	La carapace est sortie proprement.	Traitez comme une interruption normale.
`1003`	Le client a envoyé cinq blocs de texte consécutifs au protocole binaire uniquement.	Passez aux trames binaires. Ne vous reconnectez pas automatiquement avec le même comportement.
`1006`	La connexion s'est interrompue sans interruption en raison d'une panne réseau ou d'une interruption de service.	Reconnectez-vous avec l'ID de shell enregistré.
`1008`	La durée de connexion d'une heure a expiré, la fréquence d'images a dépassé 250 images par seconde ou la mémoire tampon d'écriture a été débordée.	Reconnectez-vous pour expiration de la durée. En cas de violation du débit ou de la mémoire tampon, faites une pause avant de vous reconnecter.
`1009`	La charge utile d'une trame dépassait 64 Ko.	Divisez la charge utile en trames inférieures à 64 Ko, puis reconnectez-vous.
`1011`	Une défaillance inattendue du serveur s'est produite.	Réessayez avec un recul exponentiel.
`4000`	Un autre client s'est connecté avec le même identifiant de shell.	Ne vous reconnectez pas automatiquement. Informez l'utilisateur qu'un autre client est connecté au shell.

Bonnes pratiques

Générez et conservez un identifiant de shell unique pour chaque terminal logique.
Conservez l'ID de session d'exécution avec l'ID du shell. Les deux valeurs sont requises pour la reconnexion.
Lisez la sortie rapidement afin que le tampon d'écriture de la connexion ne se remplisse pas.
Divisez les entrées volumineuses en trames binaires inférieures à 64 Ko.
Reconnectez-vous avant ou après la limite de connexion d'une heure si le shell doit rester disponible plus longtemps.
Mettez fin aux coques de manière explicite lorsqu'elles ne sont plus nécessaires. Les obus détachés ne sont pas pris en compte dans le calcul de la limite des 10 obus actifs. Le service conserve au maximum 20 entrées d'obus actifs et détachés et expulse le plus ancien obus détaché lorsque cela est nécessaire.
Utilisez un délai de mise à niveau d'au moins 330 secondes lorsqu'une connexion peut démarrer une session COLD HARNESS. Appliquez un délai d'expiration distinct en attendant le STATUS cadre initial après la mise à niveau.

Quotas et limites

Limite	Value	Description
Charge utile maximale du châssis	64 Ko	Les cadres plus grands entraînent un code fermé`1009`.
Fréquence de trames	250 images par seconde	Le dépassement de la limite entraîne un code fermé`1008`.
Durée de connexion maximale	1 heure	Reconnectez-vous avec le même identifiant de session d'exécution et le même identifiant de shell pour continuer.
Coques actifs simultanés par session de harnais	10	Les nouvelles connexions sont rejetées lorsque 10 shells sont actifs. Les coques détachées ne sont pas prises en compte dans cette limite.
Entrées de coque actives et détachées conservées	20	Lorsque la limite est atteinte, le service évacue le plus ancien shell détaché avant d'en créer un autre.
Tampon de reconnexion	256 Ko	Sortie maximale rejouée après reconnexion.

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

Rubriques associées

Environnement et système de fichiers- configurer l'environnement par défaut ou un conteneur personnalisé
Sécurité et contrôles d'accès- contrôler l'accès au harnais et à son environnement d'exécution
Observabilité et contrôle des coûts- surveiller l'activité et les coûts du harnais
Coques interactifs pour AgentCore Runtime

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

Environnement et système de fichiers

Observabilité et contrôle des coûts