運作方式先決條件執行命令編碼代理程式工作流程範例常用案例關鍵設計選擇安全考量錯誤處理最佳實務

在 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 日之後建立的代理程式會自動支援命令執行。如果您在此日期之前部署代理程式，則必須重新部署它以更新代理程式執行時間。

執行命令

範例

Python

下列範例示範如何使用 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

下列範例示範如何使用適用於 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

下列範例示範如何使用適用於 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 時發生。在應用程式中實作指數退避和重試邏輯。

以非零結束碼完成的命令不是 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 )。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

Shell 執行

互動式 Shell （終端機）