View a markdown version of this page

Shell-Befehle in AgentCore Runtime-Sitzungen ausführen - Amazon Grundgestein AgentCore

Shell-Befehle in AgentCore Runtime-Sitzungen ausführen

Mit InvokeAgentRuntimeCommanddiesem Vorgang können Sie Shell-Befehle direkt in einer laufenden AgentCore Runtime-Sitzung ausführen und die Ausgabe erneut streamen HTTP/2. Befehle werden in demselben Container, Dateisystem und derselben Umgebung wie Ihr Agent ausgeführt — in derselben Sitzung, die von InvokeAgentRuntime verwendet wird. Dies ermöglicht Workflows, bei denen Ihre Anwendung den Agenten für Argumentationsaufgaben und Befehle für deterministische Operationen wie das Ausführen von Tests, Git-Operationen oder die Einrichtung der Umgebung verwendet.

Um anzurufenInvokeAgentRuntimeCommand, benötigen bedrock-agentcore:InvokeAgentRuntimeCommand Sie Berechtigungen.

Funktionsweise

InvokeAgentRuntimeCommandführt einen Shell-Befehl im Container einer aktiven AgentCore Runtime-Sitzung aus und streamt die Ausgabe zurück.

Derselbe Agent, dieselbe Sitzung

InvokeAgentRuntimeCommandarbeitet auf derselben Agentenlaufzeit und Sitzung wieInvokeAgentRuntime. Sie erstellen keine separaten Ressourcen. Der Agent, mit dem Sie ihn bereitgestellt haben, CreateAgentRuntime akzeptiert sowohl Agentenaufrufe als auch die Befehlsausführung in jeder aktiven Sitzung.

Anmerkung

Die AgentCore Runtime MicroVM enthält standardmäßig keine Entwicklertools wie gitnpm, oder Sprachlaufzeiten. Alle Tools, von denen Ihre Befehle abhängen, müssen in Ihrem Container-Image (über Ihr Dockerfile) enthalten oder zur Laufzeit dynamisch installiert werden.

Die Antwort ist ein Stream von drei Ereignistypen:

Veranstaltung Wann Enthält

contentStart

Erster Abschnitt

Bestätigt, dass der Befehl gestartet wurde

contentDelta

Während der Ausführung

stdout and/or stderr-Ausgabe

contentStop

Letzter Brocken

exitCodeund status (COMPLETEDoderTIMED_OUT)

Gibt Streams in Echtzeit aus. Sie sehen die Ergebnisse, während sie ausgeführt werden, nicht nachdem sie abgeschlossen sind.

Voraussetzungen

  • bedrock-agentcore:InvokeAgentRuntimeCommand-IAM-Berechtigung

  • Ein gültiger AgentCore Runtime-Endpunkt-ARN

Anmerkung

Agenten, die nach dem 17. März 2026 erstellt wurden, unterstützen die automatische Ausführung von Befehlen. Wenn Sie Ihren Agenten vor diesem Datum bereitgestellt haben, müssen Sie ihn erneut bereitstellen, um die Agenten-Laufzeit zu aktualisieren.

Führen Sie einen Befehl aus

Beispiel
Python
  1. Das folgende Beispiel zeigt, wie boto3 verwendet wird, um einen Befehl in einer AgentCore Runtime-Sitzung auszuführen.

    import boto3 import sys client = boto3.client('bedrock-agentcore', region_name='us-west-2') response = client.invoke_agent_runtime_command( agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent', runtimeSessionId='session-id-at-least-33-characters-long', qualifier='DEFAULT', contentType='application/json', accept='application/vnd.amazon.eventstream', body={ 'command': '/bin/bash -c "npm test"', 'timeout': 60 } ) # Process the streaming response for event in response.get('stream', []): if 'chunk' in event: chunk = event['chunk'] if 'contentStart' in chunk: print("Command execution started") if 'contentDelta' in chunk: delta = chunk['contentDelta'] if delta.get('stdout'): print(delta['stdout'], end='') if delta.get('stderr'): print(delta['stderr'], end='', file=sys.stderr) if 'contentStop' in chunk: stop = chunk['contentStop'] print(f"\nExit code: {stop.get('exitCode')}, Status: {stop.get('status')}")
Java
  1. Das folgende Beispiel zeigt, wie Sie das AWS SDK for Java verwenden, um einen Befehl in einer AgentCore Runtime-Sitzung auszuführen.

    import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.bedrockagentcore.BedrockAgentCoreAsyncClient; import software.amazon.awssdk.services.bedrockagentcore.model.*; import java.util.UUID; import java.util.concurrent.CompletableFuture; public class ExecuteCommandExample { public static void main(String[] args) throws Exception { String agentArn = "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent"; String sessionId = UUID.randomUUID().toString(); BedrockAgentCoreAsyncClient client = BedrockAgentCoreAsyncClient.builder() .region(Region.US_WEST_2) .credentialsProvider(DefaultCredentialsProvider.create()) .build(); InvokeAgentRuntimeCommandRequest request = InvokeAgentRuntimeCommandRequest.builder() .agentRuntimeArn(agentArn) .runtimeSessionId(sessionId) .qualifier("DEFAULT") .contentType("application/json") .accept("application/vnd.amazon.eventstream") .body(InvokeAgentRuntimeCommandRequestBody.builder() .command("/bin/bash -c \"npm test\"") .timeout(60) .build()) .build(); InvokeAgentRuntimeCommandResponseHandler handler = InvokeAgentRuntimeCommandResponseHandler.builder() .subscriber(InvokeAgentRuntimeCommandResponseHandler.Visitor.builder() .onChunk(chunk -> { if (chunk.contentStart() != null) { System.out.println("Command execution started"); } if (chunk.contentDelta() != null) { ContentDeltaEvent delta = chunk.contentDelta(); if (delta.stdout() != null) System.out.print(delta.stdout()); if (delta.stderr() != null) System.err.print(delta.stderr()); } if (chunk.contentStop() != null) { ContentStopEvent stop = chunk.contentStop(); System.out.println("\nExit code: " + stop.exitCode() + ", Status: " + stop.statusAsString()); } }) .build()) .build(); CompletableFuture<Void> future = client.invokeAgentRuntimeCommand(request, handler); future.get(); client.close(); } }
JavaScript
  1. Das folgende Beispiel zeigt, wie das AWS SDK für JavaScript v3 verwendet wird, um einen Befehl in einer AgentCore Runtime-Sitzung auszuführen.

    import { BedrockAgentCoreClient, InvokeAgentRuntimeCommandCommand } from "@aws-sdk/client-bedrock-agentcore"; import { randomUUID } from "crypto"; const client = new BedrockAgentCoreClient({ region: "us-west-2" }); const request = { agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent", runtimeSessionId: randomUUID(), qualifier: "DEFAULT", contentType: "application/json", accept: "application/vnd.amazon.eventstream", body: { command: '/bin/bash -c "npm test"', timeout: 60, }, }; const command = new InvokeAgentRuntimeCommandCommand(request); const response = await client.send(command); // Process the event stream for await (const event of response.stream) { if (event.chunk) { const chunk = event.chunk; if (chunk.contentStart) { console.log("Command execution started"); } if (chunk.contentDelta) { if (chunk.contentDelta.stdout) process.stdout.write(chunk.contentDelta.stdout); if (chunk.contentDelta.stderr) process.stderr.write(chunk.contentDelta.stderr); } if (chunk.contentStop) { console.log(`\nExit code: ${chunk.contentStop.exitCode}, ` + `Status: ${chunk.contentStop.status}`); } } } client.destroy();

Beispiel für einen Arbeitsablauf mit einem Codierungs

Ein gängiges Muster wird InvokeAgentRuntime zur Argumentation und InvokeAgentRuntimeCommand für deterministische Operationen in derselben Sitzung verwendet.

Beispiel für einen Arbeitsablauf mit einem End-to-end Codierungs

import boto3 import json client = boto3.client('bedrock-agentcore', region_name='us-west-2') AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent' SESSION_ID = 'session-id-at-least-33-characters-long' def run_command(command, timeout=60): """Helper to run a command and return the exit code.""" response = client.invoke_agent_runtime_command( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, contentType='application/json', accept='application/vnd.amazon.eventstream', body={'command': command, 'timeout': timeout} ) for event in response.get('stream', []): if 'chunk' in event and 'contentStop' in event['chunk']: return event['chunk']['contentStop'].get('exitCode') return None # Step 1: Invoke the agent to analyze and write a fix response = client.invoke_agent_runtime( agentRuntimeArn=AGENT_ARN, runtimeSessionId=SESSION_ID, payload=json.dumps({"prompt": "Read JIRA-1234 and implement the fix in /workspace"}).encode() ) # Process agent response... # Step 2: Run tests deterministically exit_code = run_command('/bin/bash -c "cd /workspace && npm test"', timeout=300) # Step 3: If tests pass, commit and push if exit_code == 0: run_command('/bin/bash -c "cd /workspace && git checkout -b fix/JIRA-1234"') run_command('/bin/bash -c "cd /workspace && git add -A && git commit -m \'Fix JIRA-1234\'"') run_command('/bin/bash -c "cd /workspace && git push origin fix/JIRA-1234"')

Der Agent schreibt den Code. Die Plattform führt die Befehle aus. Jeder macht das, was er am besten kann.

Häufige Anwendungsfälle

Testsuiten ausführen

Nachdem der Agent Code geschrieben hat, führen Sie die Testsuite des Projekts als Befehl aus. Mit der Streaming-Antwort können Sie Fehler frühzeitig erkennen und spezifische Fehlerausgaben zur Iteration an den Agenten zurücksenden.

/bin/bash -c "cd /workspace && npm test 2>&1"
Git-Operationen

Branching, Commit und Push sind deterministische Operationen. Führen Sie sie als Befehle aus, nachdem der Agent seine Arbeit abgeschlossen hat, sodass die Versionskontrolllogik vom LLM ferngehalten wird.

/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"
Installation von Abhängigkeiten

Booten Sie die Umgebung, bevor Sie den Agenten aufrufen -clone repos, installieren Sie Pakete, richten Sie die Build-Tools ein. Diese Vorbereitung läuft schneller und zuverlässiger als direkte Befehle ab.

/bin/bash -c "pip install -r requirements.txt"
Erstellen und kompilieren

Kompilierungsschritte und Generierung von Assets — alles mit einem bekannten Befehl, der genau wie angegeben ausgeführt werden sollte.

/bin/bash -c "cd /workspace && cargo build --release"
Linting und Validierung

Führen Sie nach dem Schreiben des Codes durch den Agenten und vor dem Commit die Codequalitätsprüfungen als Validierungstor durch.

/bin/bash -c "cd /workspace && npx eslint src/ --format json"
Inspektion der Umgebung

Überprüfen Sie den Laufzeitstatus, die installierten Pakete und die verfügbaren Tools — nützlich für das Debuggen von Agentenfehlern.

/bin/bash -c "python --version && node --version && git --version"
Datenoperationen

Datensätze abrufen, Ergebnisse hochladen, Datentransformationen ausführen — Netzwerk- und Rechenoperationen, die als direkte Befehle schneller ausgeführt werden.

/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"

Die wichtigsten Designoptionen

One-shot, nicht interaktive Ausführung

Jeder Befehl erzeugt einen neuen Bash-Prozess, wird bis zum Abschluss (oder Timeout) ausgeführt und kehrt zurück. Zwischen den Befehlen findet keine persistente Shell-Sitzung statt. Dies entspricht der Art und Weise, wie Agenten-Frameworks die Befehlsausführung verwenden — einen Befehl erstellen, ihn ausführen, die Ausgabe lesen und entscheiden, was als Nächstes zu tun ist.

Streaming-Antwort über HTTP/2

Die Ausgabe kommt so an, wie sie produziert wurde, und wird erst nach Abschluss gepuffert. Ein Vorgangnpm test, der zwei Minuten dauert, streamt Ergebnisse in Echtzeit. Ihre Anwendung kann einen Fehler in den ersten Sekunden erkennen und vorzeitig abbrechen, anstatt auf die vollständige Ausführung zu warten.

Container-Isolierung

Befehle werden in demselben Container ausgeführt wie Ihr Agentencode. Sie sehen dasselbe Dateisystem, dieselben Umgebungsvariablen und installierten Pakete. Eine Datei, in die der Agent geschrieben hat, /workspace/fix.py ist für einen laufenden cat /workspace/fix.py Befehl sofort sichtbar.

Non-blocking zur Laufzeit

Die Befehlsausführung blockiert keine Agentenaufrufe. Sie können den Agenten aufrufen und Befehle gleichzeitig in derselben Sitzung ausführen. Die Plattform kümmert sich um die Parallelität.

Zustandslos zwischen Befehlen

Jeder Befehl wird neu gestartet — kein Shell-Verlauf, es werden keine Änderungen der Umgebungsvariablen aus früheren Befehlen übernommen. Wenn Sie den Status benötigen, kodieren Sie ihn im Befehl selbst:. cd /workspace && export NODE_ENV=test && npm test

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 Sicherheit der Befehle verantwortlich, die Sie in Ihren AgentCore Runtime-Sitzungen ausführen. AWS sorgt für eine 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 die Befehlsausführung ist die MicroVM. Jede AgentCore Runtime-Sitzung läuft auf einer isolierten MicroVM mit eigenem Kernel, Speicher und Dateisystem. Befehle, die Sie ausführen, können nicht auf die Workloads anderer Kunden zugreifen oder die VM-Grenze umgehen. Innerhalb Ihrer VM haben 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 den Eingabebefehl an die Amazon CloudWatch Logs-Protokollgruppe Ihres Agenten. Sie können diese Protokolle verwenden, um die Befehlsaktivität zu überwachen und nachzuverfolgen, welche Befehle in Ihren Sitzungen ausgeführt wurden. Die Ausgabe der Befehlsausführung (stdout und stderr) wird zurück in Ihre Anwendung gestreamt und nicht vom Dienst protokolliert.

Prüfung mit CloudTrail

AWS CloudTrail zeichnet InvokeAgentRuntimeCommand 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 Befehle wann ausgeführt hat, und anhand der Anforderungs-ID anhand der Anforderungs-ID eine Korrelation mit den CloudWatch Log-Logs herzustellen, um zu sehen, welcher Befehl ausgeführt wurde.

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 InvokeAgentRuntimeCommand

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

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

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

Fehlerbehandlung

Bei der Verwendung des InvokeAgentRuntimeCommand Vorgangs können die folgenden Fehler auftreten:

ValidationException

Tritt auf, wenn die Anforderungsparameter ungültig sind. Vergewissern Sie sich, dass Ihr Agenten-ARN, Ihre Sitzungs-ID und Ihr Befehl korrekt formatiert sind. Der Befehl muss zwischen 1 Byte und 64 KB liegen, das Timeout muss zwischen 1 und 3600 Sekunden liegen und die Sitzungs-ID muss mindestens 33 Zeichen lang sein.

ResourceNotFoundException

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

AccessDeniedException

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

ThrottlingException

Tritt auf, wenn Sie das Limit für die Anforderungsrate von 25 TPS überschreiten. Implementieren Sie eine exponentielle Backoff- und Wiederholungslogik in Ihrer Anwendung.

Ein Befehl, der mit einem Exit-Code ungleich Null abgeschlossen wird, ist kein API-Fehler. Überprüfen Sie das exitCode contentStop Ereignis, um festzustellen, ob der Befehl selbst erfolgreich war. Ein TIMED_OUT Wert status von gibt an, dass der Befehl das angegebene Timeout überschritten hat.

Bewährte Methoden

Beachten Sie bei der Verwendung des InvokeAgentRuntimeCommand Vorgangs die folgenden bewährten Methoden:

  • Wird InvokeAgentRuntimeCommand für deterministische Operationen (Tests, Git, Builds) und InvokeAgentRuntime für Argumentationsaufgaben verwendet. Leitet deterministische Operationen nicht über das LLM weiter.

  • Nehmen Sie alle Entwicklertools, von denen Ihre Befehle abhängen (wiegit, oder Sprachlaufzeiten)npm, über Ihr Dockerfile in Ihr Container-Image auf.

  • Überprüfen Sie immer das exitCode contentStop Ereignis, um festzustellen, ob der Befehl erfolgreich war.

  • Stellen Sie die entsprechenden Timeouts ein. Eine Testsuite benötigt möglicherweise 5 Minuten, während eine git push möglicherweise nur 30 Sekunden benötigt.

  • Verarbeiten Sie die Streaming-Ausgabe inkrementell, um Fehler frühzeitig zu erkennen. Sie können einen Befehl, der lange ausgeführt wird, abbrechen, anstatt darauf zu warten, dass er abgeschlossen wird.

  • Kodieren Sie den Status im Befehl selbst mithilfe von && Verkettung (z. B.cd /workspace && export NODE_ENV=test && npm test), da jeder Befehl einen neuen Bash-Prozess startet.

  • Verwenden Sie UUIDs für Sitzungs-IDs, um die Mindestanforderung von 33 Zeichen zu erfüllen (z. B.). 12345678-1234-1234-1234-123456789012