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

# 微型虚拟机
<a name="runtime-how-it-works"></a>

Amazon Bedrock AgentCore Runtime 处理扩展、会话管理、安全隔离和基础设施管理，使您可以专注于构建智能代理体验，而不是复杂的操作。通过利用此处描述的特性和功能，您可以构建、部署和管理复杂的人工智能代理，为用户创造价值，同时帮助维护企业级安全性和可靠性。

**Topics**
+ [关键组件](#runtime-key-components)
+ [平台版本](#runtime-platform-versions)
+ [身份验证和安全](#runtime-auth-security)
+ [其他功能](#runtime-additional-features)
+ [实施概述](#runtime-implementation-overview)

## 关键组件
<a name="runtime-key-components"></a>

### AgentCore 运行时间
<a name="runtime-agent-runtime"></a>

 AgentCore 运行时是托管 AI 代理或工具代码的基础组件。它代表了一个容器化应用程序，它使用人工智能功能处理用户输入、维护上下文并执行操作。创建代理时，您可以定义其行为、功能及其可以访问的工具。例如，客户支持代理可能会回答产品问题、处理退货并将复杂问题上报给人工代表。

您可以使用 [ AgentCore CLI ](develop-agents.md#agentcore-cli-configure-deploy)、[ AgentCore Python 软件开发工具包](develop-agents.md#develop-agents-bedroock-agentcore-sdk)或直接通过[Amazon 软件开发工具包构建代理并将其部署到 AgentCore 运行时。](develop-agents.md#develop-agents-bedrock-agentcore-aws-sdk)使用 AgentCore Python 软件开发工具包，你可以使用[流行的框架，](using-any-agent-framework.md)如 LangGraph CrewaI 或 Strands Agents 来定义代理。SDK 可处理基础设施的复杂性，使您可以专注于代理的逻辑和功能。

每次 AgentCore 运行时间：
+ 拥有独一无二的身份
+ 版本控制以支持受控部署和更新

### 版本
<a name="runtime-versions"></a>

每个 AgentCore 运行时都维护不可变的[版本](agent-runtime-versioning.md)，这些版本在特定时间点捕获配置的完整快照：
+ 创建 AgentCore 运行时时，将自动创建版本 1 (V1)
+ 每次更新配置（容器映像、协议设置、网络设置）都会创建一个新版本
+ 每个版本都包含执行所需的所有必要配置

该版本控制系统提供可靠的部署历史记录和回滚功能。

### 端点
<a name="runtime-endpoints"></a>

 [终端节点](agent-runtime-versioning.md)为特定版本的 AgentCore Runtime 提供可寻址的接入点。每个端点：
+ 有唯一的 ARN 用于调用
+ 引用您的代理运行时的特定版本
+ 即使在更新实现时也能提供对代理的稳定访问权限

关键终端节点详情：
+ 当您调用时会自动创建 “默认” 端点[CreateAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntime.html)并指向最新版本
+ 当您更新 R AgentCore untime 时，会创建新版本，但`DEFAULT`终端节点会自动更新以引用该版本
+ 您可以使用该[CreateAgentRuntimeEndpoint](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_CreateAgentRuntimeEndpoint.html)操作为不同的环境（开发、测试、生产）创建自定义终端节点
+ 当用户向终端节点发出请求时，该请求将解析为该端点引用的特定代理版本

端点具有不同的生命周期状态：
+  `CREATING`-端点创建期间的初始状态
+  `CREATE_FAILED`-表示由于权限或其他问题导致创建失败
+  `READY`-端点正在运行并正在接受请求
+  `UPDATING`-正在修改端点以引用新版本
+  `UPDATE_FAILED`-表示更新操作失败

您可以在不停机的情况下更新端点，从而实现无缝的版本过渡和回滚。

### 会话
<a name="runtime-sessions-overview"></a>

 [会话](runtime-sessions.md)代表用户和 AgentCore 运行时之间的个人交互上下文。每节课：
+ 由您的应用程序`runtimeSessionId`提供的唯一标识，或者在第一次调用时由运行时本身标识（`runtimeSessionId`如果留空）
+ 在具有完全隔离的 CPU、内存和文件系统资源的专用 microVM 中运行
+ 保留同一个对话中多次互动的背景信息
+ 总运行时间最多可持续 8 小时

会话状态包括：
+  **活动 **-当前正在处理请求或正在执行后台任务
+  **空闲 **-不处理任何请求，但在等待下一次交互时保持上下文
+  **已终止 **-会话因不活动（15 分钟）、达到最长生命周期（8 小时）或被视为运行状况不佳而终止

重要的会话特征：
+ 会话终止后，整个 microVM 将终止并清理内存
+ 终止`runtimeSessionId`后具有相同内容的后续请求将创建新的执行环境
+ 会话隔离可防止跨会话数据污染并确保安全性
+ 会话状态是短暂的，不应用于长期耐久性（使用 AgentCore 内存来保持上下文耐久性）

会话之间的这种完全隔离对于企业安全至关重要，尤其是在处理非确定性 AI 流程时。

## 平台版本
<a name="runtime-platform-versions"></a>

平台版本控制 AgentCore Runtime 如何启动代理。您可以在每个代理运行时使用`platformVersion`字段（`V1`或`V2`）进行设置。V1 是默认设置。平台版本适用于代理运行时本身；它与捕获配置历史记录的[运行时版本](#runtime-versions)是分开的。

Amazon Bedrock AgentCore Runtime V2 从快照启动您的代理，无论并发性或图像大小如何，它都能保持冷启动的快速和一致。 AgentCore Runtime 对您的环境进行一次准备并拍摄快照，然后为每个新实例恢复该快照，而不是在每次启动时都初始化您的环境。

持续的冷启动  
无论并发量或映像大小如何，V2 都能保持冷启动延迟的一致性，因为每个实例都会恢复准备好的快照，而不是初始化您的环境。这对于大型容器映像最为重要，否则每次冷启动时加载速度都很慢。

降低常开或突发代理的成本  
V2 根据您的代理的活跃使用量收费。 AgentCore 运行时会在代理释放内存时回收内存，从而减少平台开销。

**注意**  
从快照恢复会更改代理代码的结构。要了解如何优化代理并充分利用平台版本 V2，请参阅针对 AgentCore Runtime V2 [ 优化代理](runtime-v2-optimize.md)。

### 支持的区域：
<a name="runtime-platform-versions-regions"></a>

V2 在以下 Amazon 地区可用：
+ 美国东部（弗吉尼亚北部），`us-east-1`
+ 美国东部（俄亥俄州），`us-east-2`
+ 美国西部（俄勒冈州），`us-west-2`
+ 欧洲（爱尔兰），`eu-west-1`
+ 亚太地区（东京），`ap-northeast-1`

### 启用 V2
<a name="runtime-enable-v2"></a>

您可以为每个代理运行时设置平台版本。在创建运行时时进行设置，或者更新现有运行时以在平台版本之间移动。如果在创建运行`platformVersion`时省略，则运行时使用 V1。如果在更新运行时时将其省略，则运行时将保留其当前平台版本。

**Example**  

1. 打开亚马逊 Bedrock AgentCore 控制台并选择 ** Runtime **。

1. 在 “**运行时**” 页面上，选择 “**创建运行时” **。

1. 输入代理或工具**的**名称。

1. 对于**计算类型**，选择 ** microVMS **。

1. 在**Agent/tool 源代码下**，选择您的源类型并提供工件，例如容器镜像 URI 或您的代码。

1. 对于**平台版本**，选择 ** V2 **。

1. （可选）配置**入站身份验证**、**高级配置**和**权限**，例如 IAM 执行角色和 KMS 加密密钥。

1. 选择 “**创建运行时” **。 AgentCore 创建代理运行时版本 1 和指向该版本的`DEFAULT`端点。

1. 在`create-agent-runtime`命令`--platform-version V2`上设置。

   ```
   aws bedrock-agentcore-control create-agent-runtime \
     --agent-runtime-name "my-agent" \
     --role-arn "arn:aws:iam::111122223333:role/AgentExecutionRole" \
     --agent-runtime-artifact '{
       "containerConfiguration": {
         "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
       }
     }' \
     --network-configuration '{"networkMode": "PUBLIC"}' \
     --platform-version V2
   ```

1. 要确认平台版本，请致电`get-agent-runtime`。

   ```
   aws bedrock-agentcore-control get-agent-runtime \
     --agent-runtime-id my-agent-ABCDE12345 \
     --query platformVersion
   ```

1. 以下示例使用 boto3 在 V2 上创建代理运行时。

   ```
   import boto3
   
   client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
   
   client.create_agent_runtime(
       agentRuntimeName="my-agent",
       roleArn="arn:aws:iam::111122223333:role/AgentExecutionRole",
       agentRuntimeArtifact={
           "containerConfiguration": {
               "containerUri": "111122223333.dkr.ecr.us-west-2.amazonaws.com/my-agent:latest"
           }
       },
       networkConfiguration={"networkMode": "PUBLIC"},
       platformVersion="V2",
   )
   ```

1. `create_agent_runtime`响应不返回`platformVersion`。`get_agent_runtime`致电确认。

### 预计将发生的情况
<a name="runtime-v2-what-to-expect"></a>

V2 创建或更新操作会对您的环境进行准备和快照，因此其行为与 V1 不同。

创建和更新需要几分钟  
在 V1 上，运行时间`READY`以秒为单位。在 V2 上，准备快照会增加一次性费用，并且创建和更新会在运行时间到来之前运行几分钟`READY`。

您的容器必须在 120 秒内报告运行状况良好  
AgentCore 运行时拍摄第一个正常`/ping`响应的快照。`/ping`仅在初始化完成后才报告运行状况，以便快照捕获完全初始化的代理。如果运行时在启动后 120 秒内未报告运行状况良好，则创建将失败并出现运行状况检查错误。

轮询终端状态  
`create`和`update`操作在运行时仍处于`CREATING`或状态时返回`UPDATING`。如果您在运行时达到终端状态`delete`之前调用`update`或调用，则操作将返回`ConflictException`。轮询`get_agent_runtime`直到状态为`READY`或结束`FAILED`，并等待几分钟才能达到 V2 运行时间`READY`。  

```
import time

def wait_until_ready(client, agent_runtime_id):
    while True:
        status = client.get_agent_runtime(agentRuntimeId=agent_runtime_id)["status"]
        if status == "READY" or status.endswith("FAILED"):
            return status
        time.sleep(5)
```

**注意**  
V2 目前将代理环境变量的总大小限制为 1.5 KB（用于直接代码部署），将容器代理的环境变量的总大小限制为 2.5 KB，而 V1 的总大小为 4 KB。如果您的配置超过此限制，则请求将失败，并显示`ValidationException`。 AgentCore 运行时将提高此限制以匹配 V1。

### 快照生命周期
<a name="runtime-v2-snapshot-lifecycle"></a>

在 V2 上， AgentCore 运行时管理端点指向的每个运行时版本的快照。您不能直接创建或删除快照。它们会跟踪您的运行时和终端节点的更改。

创建时间  
AgentCore 当端点指向版本时，运行时会准备快照。创建运行时时，Runt AgentCore ime 将您的版本托管在默认终端节点上并准备其快照。一个运行时可以有多个指向不同版本的端点，因此一个运行时一次可以有多个快照。

已更新  
更新运行时时，Run AgentCore time 会在默认端点上托管新版本并准备新的快照。之前托管的版本不再被引用，因此 AgentCore Runtime 将其快照标记为待删除，并在现有会话结束后将其删除。

已删除  
AgentCore 当没有端点指向快照时，运行时会删除快照。当您更新运行时、删除端点对版本的引用或删除运行时或运行时端点时，就会发生这种情况。删除最多可能需要 8 个小时，这是会话的最大生命周期，因为已经在快照上运行的会话会一直持续到结束。

### 基础设施即代码
<a name="runtime-v2-iac"></a>

 Amazon CloudFormation 而且 Amazon CDK 目前不支持设置`platformVersion`。

## 身份验证和安全
<a name="runtime-auth-security"></a>

入站身份验证控制谁可以通过 Amazon 身份和访问管理或 OAuth 2.0 访问您的代理，在允许请求继续处理之前验证身份提供商的持有者令牌。出站身份验证使您的代理能够使用 OAuth 或 API 密钥安全地访问第三方服务，并以用户委托或自主模式进行 AgentCore 身份管理凭证。有关更多信息，请参阅[使用入站身份验证和出站身份验证进行身份验证和授权。](runtime-oauth.md)

### 入站身份验证
<a name="runtime-inbound-auth"></a>

由 I AgentCore dentity 提供支持的入站身份验证控制谁可以在 AgentCore 运行时访问和调用您的代理或工具。

#### 身份验证方法
<a name="runtime-auth-methods"></a>
+  ** Amazon IAM ** (SigV4)：使用 Amazon 证书进行身份验证
+  **OAuth 2.0**：与外部身份提供商集成

#### OAuth 配置选项
<a name="runtime-oauth-config"></a>
+  **发现 URL**：您的身份提供商的 OpenID Connect 发现端点
+  **允许的受众群体**：您的代币应包含的有效受众数值列表
+  **允许的客户端**：可以访问此代理的客户机标识符列表

#### 身份验证流程
<a name="runtime-auth-flow"></a>

1. 最终用户向您的身份提供商（亚马逊 Cognito、Okta、微软 Entra ID）进行身份验证

1. 成功进行身份验证后，您的客户端应用程序会收到持有者令牌

1. 调用代理时，客户端在授权标头中传递此令牌

1. AgentCore 运行时使用授权服务器验证令牌

1. 如果有效，则处理请求；如果无效，则拒绝

这样可以确保只有经过身份验证的具有适当授权的用户才能访问您的代理。

### 出站身份验证
<a name="runtime-outbound-auth"></a>

由亚马逊 Bedrock Identity 提供支持的出站 AgentCore 身份验证可让您的代理在 AgentCore Runtime 上安全地访问第三方服务：

#### 身份验证方法
<a name="runtime-outbound-auth-methods"></a>
+  **OAuth**：用于支持 OAuth 流的服务
+  **API 密钥**：适用于使用基于密钥的身份验证的服务

#### 身份验证模式
<a name="runtime-auth-modes"></a>
+  **User-delegated**: 使用其证书代表最终用户行事
+  **自治**：凭借服务级别证书独立行事

#### 受支持的服务
<a name="runtime-supported-services"></a>
+ 企业系统，例如 Slack、Zoom 和 GitHub
+  Amazon 服务
+ 自定义 API 和数据源

AgentCore Identity 可以安全地管理这些凭证，防止代理代码或日志中的凭据泄露。

## 其他功能
<a name="runtime-additional-features"></a>

### 异步处理
<a name="runtime-async-processing"></a>

AgentCore 运行时通过以下方式支持长时间运行的工作负载：
+ 对超过 request/response 周期的操作进行后台任务处理
+ 通过`/ping`终端自动跟踪状态
+ 支持长达 8 小时的运营

有关更多信息，请参阅使用 Amazon Bedrock AgentCore Runtime [ 处理异步和长时间运行](runtime-long-run.md)的代理。

### 流式响应
<a name="runtime-streaming-responses"></a>

代理可以在部分结果可用时对其进行流式传输，而不必等待处理完成。这使您可以提供响应更快的用户体验，特别是对于生成大量内容或需要大量时间才能完成的操作。有关更多信息，请参阅[流代理响应](response-streaming.md)。

### WebSocket API
<a name="runtime-websocket-api"></a>

 AgentCore 运行时[WebSocket](runtime-http-protocol-contract.md#ws-endpoint)支持交互式代理通信的实时双向流连接。这样可以实现更具响应性和交互性的代理体验。有关更多信息，请参阅使用[ WebSocket](runtime-get-started-websocket.md)开始双向流式传输。

### 协议支持
<a name="runtime-protocol-support"></a>

AgentCore 运行时支持多种通信协议：
+  [HTTP](runtime-http-protocol-contract.md)：传统 request/response 模式的直接 REST API 端点。有关更多信息，请参阅 AgentCore CLI [ 入门](runtime-get-started-cli.md)。
+  [MCP](runtime-mcp-protocol-contract.md)：工具和代理服务器的模型上下文协议。有关更多信息，请参见在 AgentCore 运行时[在 AgentCore 运行时部署 MCP 服务器](runtime-mcp.md)部署 MCP 服务器。
+  [A2A](runtime-a2a-protocol-contract.md)：用于多代理通信和发现的 Agent-to-Agent 协议。有关更多信息，请参见在 AgentCore 运行时[在 AgentCore 运行时部署 A2A 服务器](runtime-a2a.md)部署 A2A 服务器。

## 实施概述
<a name="runtime-implementation-overview"></a>

以下是开始使用 AgentCore 运行时的方法。有关完整示例，请参阅 AgentCore CLI [ 入门](runtime-get-started-cli.md)。

### 准备代理或工具代码
<a name="runtime-prepare-code"></a>
+ 使用任何 AI 框架或自定义代码定义代理逻辑
+ 使用 AgentCore SDK 或自定义实现添加所需的 HTTP 端点
+ requirements.txt 文件中的软件包依赖关系

### 部署您的代理或工具
<a name="runtime-deploy-agent"></a>
+ 直接或通过软件开发工具包构建容器映像并将其推送到 Amazon ECR AgentCore 
+ 使用容器镜像创建 AgentCore 运行时
+ 初始版本 (V1) 和 DEFAULT 端点是自动创建的

### 调用您的代理或工具
<a name="runtime-invoke-agent"></a>
+ 为每个用户对话生成一个唯一的会话 ID
+ 使用代理的 ARN 和会话 ID 致电[InvokeAgentRuntime](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html)或[InvokeAgentRuntimeWithWebSocketStream](runtime-get-started-websocket.md)操作部门
+ 在请求负载中传递用户输入

### 管理和观察会话并进行更新
<a name="runtime-manage-observe"></a>
+ 使用相同的会话 ID 进行后续互动，以保持上下文
+ 查看日志、跟踪和可观测性指标
+ 通过修改 AgentCore 运行时来部署更新（创建新版本）
+ 通过更新端点以指向新版本来控制部署