本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

交互式外壳（终端）

该InvokeAgentRuntimeCommandShell操作将在正在运行的 AgentCore 运行时会话中打开一个持续的交互式终端会话 WebSocket。与一次性命令执行不同，shell 会话维护状态——环境变量、工作目录和命令历史记录会传递输入。这样可以在应用程序中进行调试、环境检查和构建终端体验。

要拨打电话InvokeAgentRuntimeCommandShell，你需要bedrock-agentcore:InvokeAgentRuntimeCommandShell权限。

工作原理

InvokeAgentRuntimeCommandShell WebSocket 与在代理会话中运行的交互式 shell 进程建立连接。该连接使用二进制帧来双向传输终端输入和输出。

同一个代理，同一个会话

InvokeAgentRuntimeCommandShell与InvokeAgentRuntime和在相同的代理运行时上运行InvokeAgentRuntimeCommand。你不能创建单独的资源。您部署的代理CreateAgentRuntime接受任何活动会话上的 shell 连接。

该连接支持：

先决条件

使用 AgentCore CLI

有关安装和设置说明，请参阅 AgentCore CLI 入门。

CLI 提供了内置的终端体验agentcore exec。

agentcore exec --it

要连接到特定的运行时，请执行以下操作：

agentcore exec --it --runtime <runtime-arn> --region us-west-2

按下Ctrl+]即可在不关闭外壳的情况下将其从外壳上拆下。CLI 打印一个重新连接命令：

agentcore exec --it \
  --runtime <arn> \
  --region <region> \
  --session-id <uuid> \
  --shell-id <id>

对于单发命令，请省略--it：

agentcore exec "ls -la /tmp"

对于机器可读的输出，请使用 JSON 模式：

agentcore exec --json "echo hello"
# Output: {"success":true,"exitCode":0,"stdout":"hello\n","stderr":""}

有关其他 CLI 示例，请参阅上的示AgentCore 例 GitHub。

使用 AgentCore SDK

安装 Python SDK：

pip install bedrock-agentcore

重新连接

一种常见的模式是在断开连接后重新连接到 shell，保留所有会话状态。shellId

import asyncio

from bedrock_agentcore.runtime import AgentCoreRuntimeClient

async def main():
    client = AgentCoreRuntimeClient(region="us-west-2")
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    session_id = "my-session-0000000000000000000000"
    shell_id = "my-shell"

    shell = await client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ).__aenter__()
    print(f"connected (reconnected={shell.reconnected})")
    await shell.send("export GREETING='hello'\n")
    await asyncio.sleep(1)

    async with client.open_shell(
        runtime_arn,
        session_id=session_id,
        shell_id=shell_id,
    ) as shell2:
        print(f"reconnected (reconnected={shell2.reconnected})")
        assert shell2.reconnected


if __name__ == "__main__":
    asyncio.run(main())

Auto-reconnect

当连接断开时，SDK 也可以自动重新 WebSocket 连接。使用ReconnectConfig来启用此功能：

import asyncio
from bedrock_agentcore.runtime import AgentCoreRuntimeClient, ReconnectConfig, ShellChannel

async def on_reconnect(reconnected: bool):
    print(f"Reconnected: {reconnected}")

async def main():
    runtime_arn = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent"
    shell_id = "my-persistent-shell"
    config = ReconnectConfig(max_retries=5, base_delay=0.5, on_reconnect=on_reconnect)

    client = AgentCoreRuntimeClient(region="us-west-2")
    async with client.open_shell(runtime_arn, shell_id=shell_id, reconnect_config=config) as shell:
        # If the connection drops, the SDK retries automatically
        await shell.send("long-running-command\n")
        async for frame in shell:
            if frame.channel == ShellChannel.STDOUT:
                print(frame.text, end="")

asyncio.run(main())

有关其他 SDK 示例，请参阅上的示AgentCore 例 GitHub。

常见使用案例

关键设计选择

安全注意事项

外壳会话（终端）的安全边界是 microVM。每个 AgentCore 运行时会话都在具有自己的内核、内存和文件系统的独立微虚拟机中运行。Shell 会话无法访问其他客户的工作负载或逃离虚拟机边界。但是，在您的虚拟机中，shell 命令可以完全访问容器文件系统以及您配置的任何凭据或机密。

使用 CloudWatch 日志进行审计

AgentCore Runtime 将请求 ID 和连接元数据发送到您的代理的 Amazon Logs CloudWatch 日志组。您可以使用这些日志来监控 shell 连接活动并维护审计记录。终端 I/O 内容 (stdin/stdout) 将流式传输到您的客户端，不由该服务记录。

审计 CloudTrail

AWS CloudTrail 在您的账户中记录 InvokeAgentRuntimeCommandShell API 调用。每条记录都包含呼叫者身份、时间戳、源 IP 地址和响应状态等元数据。 CloudTrail 不记录请求或响应负载。 CloudTrail 用于审核谁打开了 shell 会话以及何时打开，然后使用请求 ID 与 CloudWatch 日志关联以获取连接详细信息。

对于敏感工作负载，可以考虑实施其他控制措施，例如：

错误处理

建立 shell 会话连接时，在 WebSocket 升级期间可能会遇到以下错误：

连接后，以下关闭代码表示连接终止的原因：

最佳实践

使用时请遵循以下最佳实践InvokeAgentRuntimeCommandShell：

限额和限制

有关完整的服务限制，请参阅亚马逊 Bedrock AgentCore 的配额。