Interaktive Shells (Terminals)

Der InvokeAgentRuntimeCommandShell Vorgang öffnet eine persistente, interaktive Terminalsitzung innerhalb einer laufenden AgentCore Runtime-Sitzung über WebSocket. Im Gegensatz zur einmaligen Befehlsausführung behalten Shell-Sitzungen den Status bei — Umgebungsvariablen, Arbeitsverzeichnis und Befehlsverlauf werden für alle Eingaben übernommen. Dies ermöglicht das Debuggen, die Inspektion der Umgebung und die Erstellung von Terminal-Erlebnissen in Ihrer Anwendung.

Um anzurufenInvokeAgentRuntimeCommandShell, benötigen Sie bedrock-agentcore:InvokeAgentRuntimeCommandShell Berechtigungen.

Funktionsweise

InvokeAgentRuntimeCommandShellstellt eine WebSocket Verbindung zu einem interaktiven Shell-Prozess her, der in der Sitzung Ihres Agenten ausgeführt wird. Die Verbindung verwendet binäre Frames, um Terminaleingabe und -ausgabe in beide Richtungen zu streamen.

Derselbe Agent, dieselbe Sitzung

InvokeAgentRuntimeCommandShellarbeitet auf derselben Agentenlaufzeit wie InvokeAgentRuntime undInvokeAgentRuntimeCommand. Sie erstellen keine separaten Ressourcen. Der Agent, mit dem Sie ihn bereitgestellt haben, CreateAgentRuntime akzeptiert Shell-Verbindungen in jeder aktiven Sitzung.

Anmerkung

Sie können a als Ziel session_id für eine bestimmte Runtime-Sitzung übergeben. Wenn dieser Wert weggelassen wird, wird für jede Verbindung eine neue Sitzung erstellt. Um die Wiederverbindung zu verwenden, müssen Sie sowohl als auch session_id speichern und wiederverwenden. shellId

Die Verbindung unterstützt:

Feature	Description
Dauerhafter Zustand	Umgebungsvariablen, Arbeitsverzeichnis und Befehlsverlauf werden für alle Eingaben innerhalb derselben Sitzung übernommen.
Wiederverbindung	Geben Sie dasselbe shellId an session_id und stellen Sie nach einem Verbindungsabbruch erneut eine Verbindung zur gleichen Shell her. Der Dienst gibt bis zu 256 KB an gepufferter Ausgabe wieder.
Mehrere gleichzeitige Shells	Bis zu 10 aktive Shell-Sitzungen (Terminals) pro Laufzeit. Neue Verbindungen werden abgelehnt, wenn sie ausgelastet sind.

Voraussetzungen

• bedrock-agentcore:InvokeAgentRuntimeCommandShell-IAM-Berechtigung

• Ein gültiger AgentCore Runtime-Endpunkt-ARN mit einer Laufzeit im Status READY

Anmerkung

Agenten, die nach dem 5. Juni 2026 erstellt wurden, unterstützen interaktive Shells (Terminals) automatisch. Wenn Sie Ihren Agenten vor diesem Datum bereitgestellt haben, müssen Sie ihn erneut bereitstellen, um die Agenten-Laufzeit zu aktualisieren.

Verwenden der AgentCore CLI

Anweisungen zur Installation und Einrichtung finden Sie unter Erste Schritte mit AgentCore Runtime mithilfe der CLI.

Die CLI bietet ein integriertes Terminalerlebnis mitagentcore exec.

agentcore exec --it

So stellen Sie eine Verbindung zu einer bestimmten Laufzeit her:

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

Drücken SieCtrl+], um sich von einer Shell zu trennen, ohne sie zu schließen. Die CLI druckt einen Reconnect-Befehl aus:

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

Lassen Sie bei Einmalbefehlen Folgendes weg: --it

agentcore exec "ls -la /tmp"

Verwenden Sie für maschinenlesbare Ausgaben den JSON-Modus:

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

Weitere CLI-Beispiele finden Sie unter AgentCore Beispiele unter GitHub.

Verwenden des AgentCore SDK

Installieren Sie das Python-SDK:

pip install bedrock-agentcore

Beispiel

SigV4 (default)

1. Das folgende Beispiel zeigt, wie eine Shell-Sitzung mit AWS Standardanmeldedaten geöffnet wird.

   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. Das folgende Beispiel zeigt, wie eine Shell-Sitzung mit einer vorsignierten URL geöffnet wird.

   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. Das folgende Beispiel zeigt, wie eine Shell-Sitzung mit einem OAuth-Bearer-Token geöffnet wird.

   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())

Wiederverbindung

Ein gängiges Muster besteht darin, shellId nach einem Verbindungsabbruch wieder eine Verbindung zu einer Shell herzustellen, wobei der gesamte Sitzungsstatus erhalten bleibt.

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

Das SDK kann auch automatisch wieder eine Verbindung herstellen, wenn die WebSocket Verbindung unterbrochen wird. Verwenden SieReconnectConfig, um dies zu aktivieren:

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())

Weitere SDK-Beispiele finden Sie unter AgentCore Beispiele auf GitHub.

Häufige Anwendungsfälle

Interaktives Debuggen

Öffnen Sie eine Shell, um die Laufzeitumgebung Ihres Agenten zu überprüfen — überprüfen Sie die installierten Pakete, lesen Sie Protokolldateien, untersuchen Sie das Dateisystem oder testen Sie Befehle, bevor Sie sie Ihrem Agentencode hinzufügen.

python --version && pip list | head -20

Inspektion der Umgebung

Überprüfen Sie die Umgebungsvariablen, die Netzwerkkonnektivität, die verfügbaren Tools und den Status des Dateisystems. Nützlich bei der Diagnose von Agentenausfällen oder bei der Validierung der Bereitstellungskonfiguration.

env | grep AWS && curl -s http://169.254.169.254/latest/meta-data/

Terminalzugriff für Codierungsagenten

KI-Codierungsagenten verwenden interaktive Shells (Terminals) als Ausführungsumgebung. Wenn ein Codierungsagent Code ausführen, Pakete installieren oder Tests ausführen muss, öffnet er eine Shell-Sitzung zur AgentCore Runtime und führt Befehle direkt aus — genauso, wie ein Entwickler ein Terminal verwenden würde. Beispielsweise stellen Claude Code, Amazon Kiro und OpenAI Codex jeweils eine Verbindung zu einer Shell-Sitzung her, in der sie iterativ Code schreiben, ausführen, die Ausgabe beobachten und Fehler in einer Schleife beheben können. Der persistente Status bedeutet, dass der Agent eine Folge von Befehlen ausführen kann, ohne den Kontext zwischen den Schritten zu verlieren.

# 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 Prozesse

Starten Sie Prozesse, die eine einzelne HTTP-Anfrage überdauern. Verwenden Sie die Wiederverbindung, um den Fortschritt zu überprüfen oder im Laufe der Zeit zusätzliche Eingaben zu liefern.

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

Die wichtigsten Designoptionen

Dauerhafte interaktive Sitzungen

Jede Verbindung ist einem langlebigen Shell-Prozess zugeordnet. Sie können mehrere Befehle senden, ohne die Verbindung erneut herzustellen, und der Status, der durch frühere Befehle (exportierte Variablen, cd Änderungen) gesammelt wurde, ist für spätere Befehle verfügbar.

Binäres Framing ist vorbei WebSocket

I/O Das Terminal wird als binäre WebSocket Frames gestreamt. Dies unterstützt unformatierte Terminalsteuersequenzen, Farben, Cursorbewegungen und Vollbildanwendungen ohne Codierungsaufwand.

Wiederverbindung mit Wiedergabe der Ausgabe

Wenn Sie die Verbindung erneut herstellenshellId, gibt der Dienst bis zu 256 KB der letzten Ausgabe wieder. Auf diese Weise können Sie sich nach Netzwerkunterbrechungen erholen, ohne den Kontext zu verlieren. Der Shell-Prozess läuft auch während des Verbindungsabbruchs weiter.

Sitzungslimit

Wenn während einer Laufzeit bereits 10 Shell-Sitzungen (Terminals) geöffnet sind, werden neue Verbindungen mit einem Fehler zurückgewiesen. Sie müssen eine bestehende Sitzung schließen, bevor Sie eine neue öffnen können.

Sicherheitsüberlegungen

Tipp

Eine konsolidierte Übersicht aller Runtime-Sicherheitsempfehlungen finden Sie unter Bewährte Sicherheitsmethoden für AgentCore Runtime.

Wichtig

Im Rahmen des Modells der AWS gemeinsamen Verantwortung sind Sie für die Befehle verantwortlich, die Sie in Ihren AgentCore Runtime-Sitzungen ausführen. AWS bietet die sichere Infrastruktur und Isolierung auf MicroVM-Ebene. Sie sind verantwortlich für die Befehle, die Sie ausführen, die Daten, die Sie verarbeiten, und die von Ihnen konfigurierten Zugriffskontrollen.

Die Sicherheitsgrenze für Shell-Sitzungen (Terminals) ist die MicroVM. Jede AgentCore Runtime-Sitzung läuft auf einer isolierten MicroVM mit eigenem Kernel, Speicher und Dateisystem. Shell-Sitzungen können nicht auf die Workloads anderer Kunden zugreifen oder die VM-Grenze umgehen. Innerhalb Ihrer VM haben Shell-Befehle jedoch vollen Zugriff auf das Container-Dateisystem und alle von Ihnen konfigurierten Anmeldeinformationen oder Geheimnisse.

Prüfung mit Protokollen CloudWatch

AgentCore Runtime sendet die Anforderungs-ID und die Verbindungsmetadaten an die Amazon CloudWatch Logs-Protokollgruppe Ihres Agenten. Sie können diese Protokolle verwenden, um die Shell-Verbindungsaktivität zu überwachen und einen Audit-Trail zu führen. I/O Der Terminalinhalt (stdin/stdout) wird zu Ihrem Client gestreamt und nicht vom Dienst protokolliert.

Prüfung mit CloudTrail

AWS CloudTrail zeichnet InvokeAgentRuntimeCommandShell API-Aufrufe in Ihrem Konto auf. Jeder Datensatz enthält Metadaten wie die Identität des Anrufers, den Zeitstempel, die Quell-IP-Adresse und den Antwortstatus. CloudTrail protokolliert die Payload der Anfrage oder Antwort nicht. Wird verwendet, CloudTrail um zu überprüfen, wer wann Shell-Sitzungen geöffnet hat, und korreliert dann anhand der Anforderungs-ID für Verbindungsdetails mit CloudWatch Logs.

Bei sensiblen Workloads sollten Sie die Implementierung zusätzlicher Kontrollen in Betracht ziehen, z. B.:

• Verwenden Sie IAM-Richtlinien, um einzuschränken, welche Prinzipale anrufen können InvokeAgentRuntimeCommandShell

• Konfiguration von VPC-Endpunkten zur Aufrechterhaltung des Datenverkehrs in Ihrem Netzwerk

• Einrichtung von CloudWatch Protokollen, Metrikfiltern und Alarmen zur Erkennung unerwarteter Verbindungsmuster

• Regelmäßige Überprüfung der CloudTrail Protokolle auf unbefugte Zugriffsversuche

Fehlerbehandlung

Beim Herstellen einer Shell-Sitzungsverbindung können während des WebSocket Upgrades die folgenden Fehler auftreten:

ValidationException

Tritt auf, wenn die Anforderungsparameter ungültig sind. Dies kann passieren, wenn die Sitzungs-ID weniger als 33 Zeichen lang ist, die Funktion in der Zielregion nicht aktiviert ist oder sich der Agent nicht im Status READY befindet.

AccessDeniedException

Tritt auf, wenn Sie nicht über die erforderlichen Berechtigungen verfügen. Stellen Sie sicher, dass Ihre IAM-Richtlinie die bedrock-agentcore:InvokeAgentRuntimeCommandShell Erlaubnis beinhaltet.

ResourceNotFoundException

Tritt auf, wenn die angegebene Agenten-Laufzeit nicht gefunden werden kann. Stellen Sie sicher, dass der Runtime-ARN korrekt ist.

RuntimeClientError (424)

Tritt in mehreren Szenarien auf: (1) Die maximale Anzahl gleichzeitiger Shell-Sitzungen (Terminals) wurde erreicht (10 geöffnet) — schließen Sie eine bestehende Sitzung und versuchen Sie es erneut. (2) Das Shell-ID-Format ist ungültig — es muss aus 1—128 alphanumerischen Zeichen, Unterstrichen oder Bindestrichen bestehen. (3) Laufzeit nicht erreichbar — versuchen Sie es nach dem Backoff erneut. Analysieren Sie das error JSON-Feld im Antworttext, um die Ursachen zu unterscheiden.

ThrottlingException

Tritt auf, wenn Sie das API-Ratenlimit überschreiten. Implementieren Sie eine exponentielle Backoff- und Wiederholungslogik.

ConflictException

Eine andere Verbindung beansprucht dasselbe gleichzeitig. shellId Versuchen Sie es nach 1 Sekunde erneut. Dies ist ein enges Rennen (kein anhaltender Zustand) und wird bei einem erneuten Versuch sofort behoben.

Sobald die Verbindung hergestellt wurde, geben die folgenden Schließcodes an, warum eine Verbindung beendet wurde:

Code	Bedeutung	Aktion des Clients
1000	Normaler Abschluss — Shell wurde sauber beendet oder die Verbindung wurde ordnungsgemäß getrennt	Zeigt „Verbindung unterbrochen“ an. Normale Kündigung.
1001	Verschwinden — Server wird bereitgestellt oder heruntergefahren	Auto-reconnect mit gespeichertshellId.
1003	Nicht unterstützte Daten — gesendet nach 5 aufeinanderfolgenden Textrahmen (nur binäres Protokoll)	Stellen Sie die Verbindung NICHT automatisch wieder her. Wechseln Sie zu binären Frames.
1006	Abnormales Schließen — wird lokal synthetisiert, wenn kein Close-Frame empfangen wird (Netzwerkausfall, TCP RST)	Auto-reconnect mit gespeichert. shellId
1008	Richtlinienverstoß — Verbindungs-TTL ist abgelaufen (1 Stunde), Frame-Rate-Limit überschritten (250 frames/sec) oder Schreibpufferüberlauf	Auto-reconnect für den Ablauf der TTL (neue TTL beim erneuten Verbindungsaufbau). Für die Ratenbegrenzung: Gehen Sie zurück und stellen Sie die Verbindung wieder her.
1009	Nachricht zu groß — Die Frame-Nutzlast hat 64 KB überschritten	Reduzieren Sie die Framegröße (Block auf <64 KB) und stellen Sie dann die Verbindung wieder her. Die Sitzung ist noch aktiv.
1011	Serverfehler — unerwarteter interner Fehler	Versuchen Sie es erneut mit Backoff.
4000	Ersetzt — ein anderer Client, der mit demselben verbunden ist shellId	Stellen Sie die Verbindung NICHT automatisch wieder her. Zeigt „Sitzung, die von einem anderen Client angehängt wurde“ an.

Bewährte Methoden

Folgen Sie diesen bewährten Methoden bei der Verwendung vonInvokeAgentRuntimeCommandShell:

• Verwenden Sie für jede logische Sitzung eine eindeutige Kennung shellId (z. B. eine UUID), um die Wiederverbindung zu ermöglichen. Speichern Sie das shellId auf der Clientseite.

• Wird ReconnectConfig im SDK verwendet, um vorübergehende Netzwerkunterbrechungen ohne manuelle Wiederverbindungslogik automatisch zu behandeln.

• Lesen Sie die Ausgabe-Frames umgehend. Wenn der Client ins Hintertreffen gerät, füllt sich der Schreibpuffer des Servers und die Verbindung wird mit dem Code geschlossen1008.

• Bei umfangreichen Eingaben (z. B. beim Einfügen einer Datei) sollten Sie den Inhalt in Abschnitte mit weniger als 64 KB pro Frame aufteilen, um zu verhindern, dass der Code zu eng wird. 1009

• Stellen Sie die entsprechenden Verbindungs-Timeouts ein. Die maximale Verbindungsdauer beträgt 1 Stunde. Stellen Sie die Verbindung erneut her, um nach Ablauf dieser Zeit shellId fortzufahren.

• Schließen Sie Sitzungen explizit, wenn Sie fertig sind. Getrennte Sitzungen werden auf das Limit von 10 Sitzungen angerechnet.

Kontingente und -Einschränkungen

Limit	Wert	Description
Maximale Größe der Frame-Nutzlast	64 KB	Frames, die diese Grenze überschreiten, führen zum Schließen des Codes. 1009
Bildrate	250 frames/sec	Wenn dieser Wert überschritten wird, wird der Code geschlossen1008.
Maximale Verbindungsdauer	1 Stunde	Die Verbindung wird mit dem Code geschlossen1008. Stellen Sie die Verbindung erneut her, indem Sie dasselbe verwendenshellId, um fortzufahren.
Gleichzeitige Shell-Sitzungen (Terminals) pro Laufzeit	10	Neue Verbindungen werden abgelehnt, wenn bereits 10 Sitzungen geöffnet sind. Schließen Sie eine bestehende Sitzung und versuchen Sie es erneut.
Puffer für die Wiederherstellung der Verbindung	256 KB	Maximale Ausgangsleistung, die beim erneuten Herstellen einer Verbindung zu einer Shell wiedergegeben wird.

Vollständige Servicebeschränkungen finden Sie unter Kontingente für Amazon Bedrock AgentCore.