View a markdown version of this page

在 AgentCore 執行期工作階段中執行 shell 命令 - Amazon Bedrock AgentCore

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

在 AgentCore 執行期工作階段中執行 shell 命令

InvokeAgentRuntimeCommand 操作可讓您直接在執行中的 AgentCore 執行期工作階段內執行 shell 命令,並透過 HTTP/2 將輸出串流回去。命令會在與代理程式相同的容器、檔案系統和環境中執行 - 與 InvokeAgentRuntime 使用的工作階段相同。這可讓您的應用程式使用 代理程式推理任務和命令進行確定性操作的工作流程,例如執行測試、git 操作或環境設定。

若要呼叫 InvokeAgentRuntimeCommand ,您需要 bedrock-agentcore:InvokeAgentRuntimeCommand 許可。

運作方式

InvokeAgentRuntimeCommand 在作用中 AgentCore 執行期工作階段的容器內執行 shell 命令,並將輸出串流回去。

相同的代理程式、相同的工作階段

InvokeAgentRuntimeCommand 在與 相同的代理程式執行時間和工作階段上運作InvokeAgentRuntime。您不會建立個別的資源。您使用 部署的代理程式CreateAgentRuntime接受任何作用中工作階段上的代理程式調用和命令執行。

注意

根據預設,AgentCore Runtime microVM 不包含開發人員工具,例如 git 、 npm 或語言執行時間。命令依賴的任何工具都必須包含在容器映像中 (透過 Dockerfile),或在執行時間動態安裝。

回應是三種事件類型的串流:

事件 當 Contains

contentStart

第一個區塊

確認命令已啟動

contentDelta

在執行期間

stdout 和/或stderr輸出

contentStop

最後一個區塊

exitCode 和 status( COMPLETED或 TIMED_OUT )

即時輸出串流。您會在結果執行時看到結果,而不是在結果完成後。

先決條件

  • bedrock-agentcore:InvokeAgentRuntimeCommand IAM 許可

  • 有效的 AgentCore 執行期端點 ARN

注意

2026 年 3 月 17 日之後建立的代理程式會自動支援命令執行。如果您在此日期之前部署代理程式,則必須重新部署它以更新代理程式執行時間。

執行命令

範例
AgentCore CLI
  1. agentcore runtime exec 使用執行期 ID 執行 。執行期 ID 是執行期 ARN 的最後一個區段。工作階段 ID 長度必須為 33 到 100 個字元:

    agentcore runtime exec \ --id <runtime-id> \ --session-id <session-id> \ --command "ls -la /workspace"

    命令會以 sessionId、command、status、 exitCode和 output 欄位列印 JSON。新增 --timeout <seconds>(1 到 3600) 以限制命令執行的時間,並將 以外的端點--qualifier <endpoint>設為目標DEFAULT。

Python
  1. 下列範例示範如何使用 boto3 在 AgentCore 執行期工作階段中執行命令。

    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. 下列範例示範如何使用適用於 Java 的 AWS 開發套件在 AgentCore 執行期工作階段中執行命令。

    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. 下列範例示範如何使用適用於 JavaScript 的 AWS SDK v3 在 AgentCore 執行期工作階段中執行命令。

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

編碼代理程式工作流程範例

常見的模式是InvokeAgentRuntime用於推理和相同工作階段中的InvokeAgentRuntimeCommand確定性操作。

End-to-end編碼代理程式工作流程範例

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"')

代理程式會撰寫程式碼。平台會執行 命令。每個 都會執行其最佳作法。

常用案例

執行測試套件

代理程式編寫程式碼後,以命令的形式執行專案的測試套件。串流回應可讓您提早偵測失敗,並將特定錯誤輸出傳回給代理程式進行反覆運算。

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

分支、遞交和推送是決定性的操作。在代理程式完成其工作後,將其做為命令執行,將版本控制邏輯保持在 LLM 之外。

/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"
相依性安裝

在叫用代理程式 -clone 儲存庫、安裝套件、設定建置工具之前引導環境。此準備會以直接命令更快速且更可靠的方式執行。

/bin/bash -c "pip install -r requirements.txt"
建置和編譯

使用應完全按照指定執行的已知命令來編譯步驟和資產產生 - 任何項目。

/bin/bash -c "cd /workspace && cargo build --release"
內嵌和驗證

在遞交之前,在代理程式寫入程式碼之後,執行程式碼品質檢查做為驗證閘道。

/bin/bash -c "cd /workspace && npx eslint src/ --format json"
環境檢查

檢查執行時間狀態、已安裝的套件、可用於偵錯代理程式失敗的可用工具。

/bin/bash -c "python --version && node --version && git --version"
資料操作

擷取資料集、上傳結果、執行資料轉換 - 網路和運算操作,以直接命令更快速地執行。

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

關鍵設計選擇

一次性、非互動式執行

每個命令都會產生新的堡壘程序、執行至完成 (或逾時),然後傳回 。命令之間沒有持久性 shell 工作階段。這符合代理程式架構如何使用命令執行 - 製作命令、執行命令、讀取輸出、決定接下來要做什麼。

透過 HTTP/2 串流回應

輸出會在產生時到達,直到完成才會緩衝。npm test 需要兩分鐘的串流即時產生。您的應用程式可以在前幾秒偵測到失敗,並提早取消,而不是等待完整執行。

容器隔離

命令會在與代理程式程式碼相同的容器內執行。他們看到相同的檔案系統、環境變數和已安裝的套件。執行 的命令/workspace/fix.py會立即看到代理程式在 寫入的檔案cat /workspace/fix.py。

非封鎖執行時間

命令執行不會封鎖代理程式叫用。您可以叫用代理程式,並在相同的工作階段同時執行命令。平台會處理並行。

命令之間的無狀態

每個命令都會啟動全新 - 無 Shell 歷史記錄,先前的命令不會有環境變數變更。如果您需要狀態,請在命令本身中進行編碼:cd /workspace && export NODE_ENV=test && npm test。

安全考量

提示

如需所有執行期安全建議的合併檢視,請參閱 AgentCore 執行期的安全最佳實務。

重要

在 AWS 共同責任模型下,您必須負責您在 AgentCore 執行期工作階段中執行之命令的安全性。 在 microVM 層級 AWS 提供安全基礎設施和隔離。您必須負責執行的命令、處理的資料,以及您設定的存取控制。

命令執行的安全界限是 microVM。每個 AgentCore 執行期工作階段都會在具有自己的核心、記憶體和檔案系統的隔離 microVM 中執行。您執行的命令無法存取其他客戶的工作負載或逸出 VM 界限。不過,在您的 VM 中,命令可以完整存取容器檔案系統,以及您設定的任何登入資料或秘密。

使用 CloudWatch Logs 稽核

AgentCore 執行期會將請求 ID 和輸入命令傳送至代理程式的 Amazon CloudWatch Logs 日誌群組。您可以使用這些日誌來監控命令活動,並維護工作階段中執行哪些命令的稽核線索。命令執行輸出 (stdout 和 stderr) 會串流回您的應用程式,且不會由服務記錄。

使用 CloudTrail 稽核

AWS CloudTrail 會在您的帳戶中記錄 InvokeAgentRuntimeCommand API 呼叫。每個記錄都包含中繼資料,例如發起人身分、時間戳記、來源 IP 地址和回應狀態。CloudTrail 不會記錄請求或回應承載。使用 CloudTrail 來稽核執行命令的人員和時間,然後使用請求 ID 與 CloudWatch Logs 日誌建立關聯,以查看執行了哪些命令。

對於敏感工作負載,請考慮實作其他控制項,例如:

  • 使用 IAM 政策來限制哪些主體可以呼叫 InvokeAgentRuntimeCommand

  • 設定 VPC 端點以將流量保留在您的網路中

  • 設定 CloudWatch Logs 指標篩選條件和警示,以偵測非預期的命令模式

  • 定期檢閱 CloudTrail 日誌是否有未經授權的存取嘗試

錯誤處理

使用 InvokeAgentRuntimeCommand操作時,您可能會遇到下列錯誤:

ValidationException

當請求參數無效時發生。檢查您的客服人員 ARN、工作階段 ID 和命令格式是否正確。命令必須介於 1 位元組和 64 KB 之間,逾時必須介於 1 到 3600 秒之間,且工作階段 ID 必須至少為 33 個字元。

ResourceNotFoundException

當找不到指定的代理程式執行時間或工作階段時發生。確認客服人員 ARN 正確且工作階段處於作用中狀態。

AccessDeniedException

當您沒有必要的許可時發生。確保您的 IAM 政策包含 bedrock-agentcore:InvokeAgentRuntimeCommand許可。

ThrottlingException

當您超過請求率限制 25 TPS 時發生。在應用程式中實作指數退避和重試邏輯。

RetryableConflictException

當 InvokeAgentRuntimeCommand操作以服務佈建或銷毀的工作階段為目標時發生 (HTTP 409)。訊息為 Session operation in progress, please retry。此條件為暫時性且可重試。以短指數退避重試,而不是將其視為終端機。啟用預設重試時 AWS SDKs 會自動重試此例外狀況。如果您停用重試或直接呼叫 API,而沒有 AWS SDK,請自行重試。

以非零結束碼完成的命令不是 API 錯誤。在 contentStop 事件exitCode中檢查 ,以判斷命令本身是否成功。status 的 TIMED_OUT表示命令超過指定的逾時。

最佳實務

使用 InvokeAgentRuntimeCommand操作時,請遵循下列最佳實務:

  • InvokeAgentRuntimeCommand 用於確定性操作 (測試、git、組建) 和推InvokeAgentRuntime理任務。請勿透過 LLM 路由決定性操作。

  • 透過 Dockerfile,在容器映像中包含命令依賴的任何開發人員工具 git (例如 npm 、 或語言執行時間)。

  • 一律在 contentStop 事件exitCode中檢查 ,以判斷命令是否成功。

  • 設定適當的逾時。測試套件可能需要 5 分鐘,而 git push可能只需要 30 秒。

  • 逐步處理串流輸出,以提早偵測失敗。您可以取消長時間執行的命令,而不是等待它完成。

  • 使用&&鏈結在命令本身中編碼狀態 cd /workspace && export NODE_ENV=test && npm test (例如 ),因為每個命令都會啟動新的堡壘程序。

  • 針對工作階段 IDs 使用 UUIDs,以符合 33 個字元的最低需求 (例如 12345678-1234-1234-1234-123456789012 )。