View a markdown version of this page

亚马逊 Bedrock AgentCore Runtime 目标 - Amazon Bedrock AgentCore
主要考虑因素和局限性目标配置调用 AgentCore 运行时目标出站授权强制流量通过网关与 MCP 目标的能力比较

亚马逊 Bedrock AgentCore Runtime 目标

您可以将 Amazon Bedrock AgentCore 运行时代理添加为网关目标。网关将流量直接发送到运行时代理，无需聚合或协议转换。与将工具功能整合到统一的虚拟 MCP 服务器中的 MCP 目标不同，R AgentCore untime 目标无需修改即可在客户端和运行时代理之间转发请求和响应。

当您想执行以下操作时，向网关添加 AgentCore 运行时目标非常有用：

  • 通过单个网关端点为您的运行时代理提供集中访问管理。

  • 为您的运行时代理使用网关的内置身份验证和可观察性。

  • 当多个目标连接到网关时，使用基于路径的路由将请求路由到特定的运行时代理。

  • 使用 Amazon Bedrock AgentCore 优化从代理跟踪中生成建议，使用网关的实时流量 A/B 测试更改，并部署成功的配置，从而优化代理的性能。有关更多信息，请参阅AgentCore 优化。

主要考虑因素和局限性

使用 AgentCore 运行时目标时，请注意以下注意事项：

  • 网关将流量直接发送到 AgentCore 运行时目标，而无需聚合功能。

  • AgentCore 可以将运行时目标添加到未设置协议类型的网关。它们不能添加到 MCP 协议类型的网关。

  • AgentCore 运行时目标没有功能同步或语义工具搜索可用。客户端必须通过基于路径的路由单独寻址每个目标。

  • Server-Sent AgentCore 运行时目标支持事件 (SSE) 流式传输。

  • 缓冲模式支持请求和响应拦截器 Lambda 函数。直播模式下尚不支持拦截器。

目标配置

创建 AgentCore 运行时目标时，需要提供运行时 ARN 和可选限定符。网关在内部解析运行时端点，因此您无需自己构造运行时网址。

AgentCore 运行时目标的目标配置使用以下结构：

{
    "http": {
        "agentcoreRuntime": {
            "arn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
            "qualifier": "DEFAULT",
            "schema": {
                "source": {
                    "s3": {
                        "uri": "s3://DOC-EXAMPLE-BUCKET/agent-schema.yaml"
                    }
                }
            }
        }
    }
}

  • arn（必填）— 亚马逊 B AgentCore edrock 运行时代理的 ARN。

  • 限定符（可选）-运行时限定符。默认值为 DEFAULT。

  • 架构（可选）— 描述运行时目标的请求和响应结构的 API 架构。网关使用此架构来启用策略引擎功能，例如护栏。架构格式会自动检测为 OpenAPI 或 Smithy。

    对于使用 MCP 或 A2A 协议的运行时代理，系统会自动应用默认架构，您无需提供默认架构。对于使用 HTTP 协议的运行时代理，必须提供架构才能使用护栏。

    该schema对象source包含一个用于指定架构内容所在位置的：

    • s3 — 指向架构文件的 S3 URI（例如s3://DOC-EXAMPLE-BUCKET/agent-schema.yaml）。

    • InlinePayload — 直接以字符串形式提供的架构内容。

注意

如果您的运行时代理使用 HTTP 协议，并且您想通过网关的策略引擎应用护栏，则必须提供架构。对于使用 MCP 或 A2A 协议的运行时代理，将自动应用默认架构。

调用 AgentCore 运行时目标

要通过网关调用 AgentCore 运行时目标，请向目标的调用 URL 发送 POST 请求。URL 格式如下：

https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/{targetName}/invocations

{gatewayId}用您的网关 ID、{region} AWS 地区和目标{targetName}名称替换。

以下示例使用 curl 调用 AgentCore 运行时目标：

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/my-target/invocations \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"input": {"prompt": "Hello"}}'

您也可以使用带有终端节点网址覆盖功能的 Amazon Bedrock AgentCore SDK：

aws bedrock-agentcore invoke-agent-runtime \
    --endpoint-url https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/my-target \
    --runtimeArn arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID

出站授权

AgentCore 运行时目标支持以下出站授权类型：

  • IAM (Sigv4) — 网关扮演网关服务角色以获取证书，用于对运行时目标的请求进行签名。配置 IAM 授权时，您可以使用 IAM 策略来限制对网关角色的访问权限，从而确保所有运行时请求都流经网关。

  • 调用方 IAM 证书 — 网关使用调用者的 IAM 凭证签署对运行时目标的请求。网关代表呼叫者扮演角色，并使用呼叫者的身份对出站请求进行签名。

  • OAuth (JWT) — 网关通过 Amazon Bedrock 身份服务从目标配置的凭证提供商那里检索 OAuth 令牌。 AgentCore

  • Token pass hrough — 网关验证入站令牌并将其传递到运行时目标，无需修改。当运行时处理自己的授权时，这很有用。

强制流量通过网关

您可以在 Runtime 前面使用 AgentCore 网关，使网关成为 AgentCore 运行时的单一受管控入口点，为您提供基于策略的授权、Amazon Bedrock Guardrails、请求和响应拦截器以及统一的可观察性，所有这些都应用于代理自己的环境之外。有关完整理由，请参阅使用 Gate AgentCore way 预置运行时。但这只有在你无法绕过网关直接访问运行时时才有用。现在，无论运行时使用 IAM (Sigv4) 还是 OAuth (JWT) 入站授权，您都可以实现此目的。

您可以对运行时配置此限制。网关会对其转发的每个请求的来源进行标记，运行时会在传入的路上验证该源。具体机制取决于运行时的入站授权类型：

  • IAM (Sigv4) 运行时 — 附加一个基于资源的策略，该策略限制对网关执行角色的调用。有关策略及其所需的信任策略强化，请参阅限制对网关的 IAM (Sigv4) 入站调用。

  • OAuth (JWT) 运行时 — 在运行时allowedWorkloadConfiguration上进行配置customJWTAuthorizer以仅允许网关的工作负载。有关配置和字段参考，请参阅限制对网关的调用。

与 MCP 目标的能力比较

您可以使用两种方法将 MCP 服务器与 Amazon Bedrock AgentCore 网关集成：在聚合模式下使用 MCP 目标类型或使用 AgentCore 运行时目标类型。下表比较了每种方法的功能。

能力 带有 MCP 目标的 MCP 网关 AgentCore 运行时目标

Tool/capability 聚合

将来自所有 MCP 目标的功能聚合到一个统一的虚拟 MCP 服务器中。客户会看到一个合并的tools/list回复。

隔离运行。网关无需合并功能即可将流量直接发送到目标。客户端必须通过基于路径的路由单独寻址每个目标。

语义工具搜索

为工具描述编制索引，并允许通过自然语言查询进行发现。

不可用。网关不采集或索引功能。客户必须知道确切的工具名称或使用服务器自己的工具名称tools/list。

响应拦截器 Lambda

支持非流式 MCP 操作的请求和响应拦截器。

在缓冲模式下支持请求和响应拦截器 Lambda 函数。直播模式下尚不支持拦截器。