本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
在 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 |
|---|---|---|
|
|
第一個區塊 |
確認命令已啟動 |
|
|
在執行期間 |
|
|
|
最後一個區塊 |
|
即時輸出串流。您會在結果執行時看到結果,而不是在結果完成後。
先決條件
-
bedrock-agentcore:InvokeAgentRuntimeCommandIAM 許可 -
有效的 AgentCore 執行期端點 ARN
2026 年 3 月 17 日之後建立的代理程式會自動支援命令執行。如果您在此日期之前部署代理程式,則必須重新部署它以更新代理程式執行時間。
執行命令
範例
編碼代理程式工作流程範例
常見的模式是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)。