View a markdown version of this page

微型虚拟机 - 亚马逊基岩 AgentCore
关键组件平台版本身份验证和安全其他功能实施概述

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

微型虚拟机

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

关键组件

AgentCore 运行时间

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

您可以使用 AgentCore CLI 、 AgentCore Python 软件开发工具包或直接通过AWS 软件开发工具包构建代理并将其部署到 AgentCore 运行时。使用 AgentCore Python 软件开发工具包，你可以使用流行的框架，如 LangGraph CrewaI 或 Strands Agents 来定义代理。SDK 可处理基础设施的复杂性，使您可以专注于代理的逻辑和功能。

每次 AgentCore 运行时间：

  • 拥有独一无二的身份

  • 版本控制以支持受控部署和更新

版本

每个 AgentCore 运行时都维护不可变的版本，这些版本在特定时间点捕获配置的完整快照：

  • 创建 AgentCore 运行时时，将自动创建版本 1 (V1)

  • 每次更新配置（容器映像、协议设置、网络设置）都会创建一个新版本

  • 每个版本都包含执行所需的所有必要配置

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

端点

终端节点为特定版本的 AgentCore Runtime 提供可寻址的接入点。每个端点：

  • 有唯一的 ARN 用于调用

  • 引用您的代理运行时的特定版本

  • 即使在更新实现时也能提供对代理的稳定访问权限

关键终端节点详情：

  • 当您调用时会自动创建 “默认” 端点CreateAgentRuntime并指向最新版本

  • 当您更新 R AgentCore untime 时，会创建新版本，但DEFAULT终端节点会自动更新以引用该版本

  • 您可以使用该CreateAgentRuntimeEndpoint操作为不同的环境（开发、测试、生产）创建自定义终端节点

  • 当用户向终端节点发出请求时，该请求将解析为该端点引用的特定代理版本

端点具有不同的生命周期状态：

  • CREATING-端点创建期间的初始状态

  • CREATE_FAILED-表示由于权限或其他问题导致创建失败

  • READY-端点正在运行并正在接受请求

  • UPDATING-正在修改端点以引用新版本

  • UPDATE_FAILED-表示更新操作失败

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

会话

会话代表用户和 AgentCore 运行时之间的个人交互上下文。每节课：

  • 由您的应用程序runtimeSessionId提供的唯一标识，或者在第一次调用时由运行时本身标识（runtimeSessionId如果留空）

  • 在具有完全隔离的 CPU、内存和文件系统资源的专用 microVM 中运行

  • 保留同一个对话中多次互动的背景信息

  • 总运行时间最多可持续 8 小时

会话状态包括：

  • 活动 -当前正在处理请求或正在执行后台任务

  • 空闲 -不处理任何请求，但在等待下一次交互时保持上下文

  • 已终止 -会话因不活动（15 分钟）、达到最长生命周期（8 小时）或被视为运行状况不佳而终止

重要的会话特征：

  • 会话终止后，整个 microVM 将终止并清理内存

  • 终止runtimeSessionId后具有相同内容的后续请求将创建新的执行环境

  • 会话隔离可防止跨会话数据污染并确保安全性

  • 会话状态是短暂的，不应用于长期耐久性（使用 AgentCore 内存来保持上下文耐久性）

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

平台版本

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

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

持续的冷启动

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

降低常开或突发代理的成本

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

注意

从快照恢复会更改代理代码的结构。要了解如何优化代理并充分利用平台版本 V2，请参阅针对 AgentCore Runtime V2 优化代理。

支持的区域：

V2 在以下 AWS 地区可用：

  • 美国东部（弗吉尼亚北部），us-east-1

  • 美国东部（俄亥俄州），us-east-2

  • 美国西部（俄勒冈州），us-west-2

  • 欧洲（爱尔兰），eu-west-1

  • 亚太地区（东京），ap-northeast-1

启用 V2

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

例
AWS Management Console

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

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

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

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

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

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

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

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

AWS CLI

  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

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

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

  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",
)

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

预计将发生的情况

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。

快照生命周期

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

创建时间

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

已更新

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

已删除

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

基础设施即代码

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

身份验证和安全

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

入站身份验证

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

身份验证方法

  • AWS IAM (SigV4)：使用 AWS 证书进行身份验证

  • OAuth 2.0：与外部身份提供商集成

OAuth 配置选项

  • 发现 URL：您的身份提供商的 OpenID Connect 发现端点

  • 允许的受众群体：您的代币应包含的有效受众数值列表

  • 允许的客户端：可以访问此代理的客户机标识符列表

身份验证流程

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

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

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

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

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

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

出站身份验证

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

身份验证方法

  • OAuth：用于支持 OAuth 流的服务

  • API 密钥：适用于使用基于密钥的身份验证的服务

身份验证模式

  • User-delegated: 使用其证书代表最终用户行事

  • 自治：凭借服务级别证书独立行事

受支持的服务

  • 企业系统，例如 Slack、Zoom 和 GitHub

  • AWS 服务

  • 自定义 API 和数据源

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

其他功能

异步处理

AgentCore 运行时通过以下方式支持长时间运行的工作负载：

  • 对超过 request/response 周期的操作进行后台任务处理

  • 通过/ping终端自动跟踪状态

  • 支持长达 8 小时的运营

有关更多信息，请参阅使用 Amazon Bedrock AgentCore Runtime 处理异步和长时间运行的代理。

流式响应

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

WebSocket API

AgentCore 运行时WebSocket支持交互式代理通信的实时双向流连接。这样可以实现更具响应性和交互性的代理体验。有关更多信息，请参阅使用 WebSocket开始双向流式传输。

协议支持

AgentCore 运行时支持多种通信协议：

实施概述

以下是开始使用 AgentCore 运行时的方法。有关完整示例，请参阅 AgentCore CLI 入门。

准备代理或工具代码

  • 使用任何 AI 框架或自定义代码定义代理逻辑

  • 使用 AgentCore SDK 或自定义实现添加所需的 HTTP 端点

  • requirements.txt 文件中的软件包依赖关系

部署您的代理或工具

  • 直接或通过软件开发工具包构建容器映像并将其推送到 Amazon ECR AgentCore

  • 使用容器镜像创建 AgentCore 运行时

  • 初始版本 (V1) 和 DEFAULT 端点是自动创建的

调用您的代理或工具

管理和观察会话并进行更新

  • 使用相同的会话 ID 进行后续互动，以保持上下文

  • 查看日志、跟踪和可观测性指标

  • 通过修改 AgentCore 运行时来部署更新（创建新版本）

  • 通过更新端点以指向新版本来控制部署