本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 在 AgentCore 运行时会话中执行 shell 命令 该[InvokeAgentRuntimeCommand](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntimeCommand.html)操作允许您直接在正在运行的 AgentCore 运行时会话中执行 shell 命令，并将输出传输回去 HTTP/2。命令在与代理相同的容器、文件系统和环境中运行，使用的会话也相同`InvokeAgentRuntime`。这使您的应用程序使用代理来推理任务和命令以执行确定性操作（例如运行测试、git 操作或环境设置）的工作流程。 要拨打电话`InvokeAgentRuntimeCommand`，你需要`bedrock-agentcore:InvokeAgentRuntimeCommand`权限。 ## 工作原理 `InvokeAgentRuntimeCommand`在活动 AgentCore 运行时会话的容器内运行 shell 命令并将输出流回流。 **同一个代理，同一个会话 ** `InvokeAgentRuntimeCommand`在与相同的代理运行时和会话上运行`InvokeAgentRuntime`。你不能创建单独的资源。您部署的代理在任何活动会话中`CreateAgentRuntime`接受代理调用和命令执行。 **注意** 默认情况下， AgentCore 运行时 microVM 不包含`git``npm`、等开发者工具或语言运行时。您的命令所依赖的任何工具都必须包含在容器镜像中（通过 Dockerfile）或在运行时动态安装。 响应是由三种事件类型组成的流： | 事件 | 时间 | 包含 | | --- | --- | --- | | `contentStart` | 第一块 | 确认命令已启动 | | `contentDelta` | 在执行过程中 | `stdout` and/or `stderr` 输出 | | `contentStop` | 最后一块 | `exitCode`和`status`（`COMPLETED`或`TIMED_OUT`） | 实时输出流。你可以在结果运行时看到结果，而不是在它们完成之后看到结果。 ## 先决条件 + `bedrock-agentcore:InvokeAgentRuntimeCommand` IAM 权限 + 有效的 AgentCore 运行时端点 ARN **注意** 2026 年 3 月 17 日之后创建的代理支持自动执行命令。如果您在此日期之前部署了代理，则必须重新部署它以更新代理运行时间。 ## 执行命令 **Example** 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')}") ``` 1. 以下示例说明如何使用 Amazon 适用于 Java 的开发工具包在 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 future = client.invokeAgentRuntimeCommand(request, handler); future.get(); client.close(); } } ``` 1. 以下示例说明如何使用 Amazon 适用于 JavaScript v3 的 SDK 在 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/" ``` ## 关键设计选择 One-shot，非交互式执行 每个命令都会生成一个新的 bash 进程，运行到完成（或超时），然后返回。命令之间没有持久的 shell 会话。这与代理框架使用命令执行的方式相匹配——创建命令、运行命令、读取输出、决定下一步要做什么。 直播回复结束 HTTP/2 输出在生成时到达，直到完成才进行缓冲。`npm test`需要两分钟才能实时传输结果。您的应用程序可以在最初的几秒钟内检测到故障，并提早取消，而不是等待完全运行。 容器隔离 命令与代理代码在同一个容器内执行。他们看到相同的文件系统、环境变量和已安装的软件包。`/workspace/fix.py`正在运行的命令会立即看到代理写入的文件`cat /workspace/fix.py`。 Non-blocking 到运行时 命令执行不会阻止代理调用。您可以在同一个会话中调用代理并同时运行命令。该平台处理并发性。 命令之间无状态 每条命令都是从新开始的-没有 shell 历史记录，没有与先前命令相比的环境变量更改。如果你需要状态，请在命令本身中对其进行编码：`cd /workspace && export NODE_ENV=test && npm test`。 ## 安全注意事项 **提示** 有关所有运行时安全建议的综合视图，请参阅 AgentCore 运行时[安全最佳实践](runtime-security-best-practices.md)。 **重要** 在责任 Amazon 共担模式下，您对在 AgentCore 运行时会话中执行的命令的安全性负责。 Amazon 在 microVM 级别提供安全的基础设施和隔离。您对运行的命令、处理的数据和配置的访问控制负责。 命令执行的安全边界是 microVM。每个 AgentCore 运行时会话都在具有自己的内核、内存和文件系统的独立微虚拟机中运行。您执行的命令无法访问其他客户的工作负载或逃离虚拟机边界。但是，在您的虚拟机中，命令可以完全访问容器文件系统以及您配置的任何凭据或机密。 **使用 CloudWatch 日志进行审计 ** AgentCore 运行时将请求 ID 和输入命令发送到您的代理的 Amazon Logs CloudWatch 日志组。您可以使用这些日志来监控命令活动，并对会话中执行的命令进行审计跟踪。命令执行输出（stdout 和 stderr）将流式传输回您的应用程序，不由该服务记录。 **使用审计 CloudTrail ** Amazon CloudTrail 在您的账户中记录 `InvokeAgentRuntimeCommand` API 调用。每条记录都包含呼叫者身份、时间戳、源 IP 地址和响应状态等元数据。 CloudTrail 不记录请求或响应负载。 CloudTrail 用于审核谁执行了命令以及何时执行了命令，然后使用请求 ID 与 CloudWatch 日志日志关联以查看执行了什么命令。 对于敏感工作负载，可以考虑实施其他控制措施，例如： + 使用 IAM 策略限制哪些委托人可以致电 `InvokeAgentRuntimeCommand` + 配置 VPC 终端节点以保持网络内的流量 + 设置 CloudWatch 日志指标筛选器和警报以检测意外命令模式 + 定期查看 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`。这种情况是暂时的，可以重试。使用短指数退避重试，而不是将其视为终端。启用默认重试后， Amazon SDK 会自动重试此异常。如果您禁用了重试或在没有 Amazon SDK 的情况下直接调用 API，请自己重试。 以非零退出代码完成的命令不是 API 错误。检查`contentStop`事件`exitCode`中的以确定命令本身是否成功。o `status` f `TIMED_OUT` 表示命令超过了指定的超时时间。 ## 最佳实践 使用该`InvokeAgentRuntimeCommand`操作时，请遵循以下最佳实践： + `InvokeAgentRuntimeCommand`用于确定性操作（测试、git、构建）和推`InvokeAgentRuntime`理任务。不要通过 LLM 路由确定性运算。 + 通过 Dockerfile 在容器镜像中加入您的命令所依赖的任何开发者工具（例如`git``npm`、或语言运行时）。 + 务必`exitCode`在`contentStop`事件中检查，以确定命令是否成功。 + 设置适当的超时时间。测试套件可能需要 5 分钟，而测试套件`git push`可能只需要 30 秒。 + 以增量方式处理流输出，以尽早发现故障。您可以取消长时间运行的命令，而不是等待其完成。 + 使用`&&`链接（例如`cd /workspace && export NODE_ENV=test && npm test`）在命令本身中对状态进行编码，因为每个命令都会启动一个新的 bash 进程。 + 使用 UUID 作为会话 ID 以满足 33 个字符的最低要求（例如，）。`12345678-1234-1234-1234-123456789012`