# 亚马逊 Bedrock AgentCore Runtime 目标
<a name="gateway-target-http-runtime"></a>

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

当您想执行以下操作时，向网关添加 AgentCore 运行时目标非常有用：
+ 通过单个网关端点为您的运行时代理提供集中访问管理。
+ 为您的运行时代理使用网关的内置身份验证和可观察性。
+ 当多个目标连接到网关时，使用基于路径的路由将请求路由到特定的运行时代理。
+ 使用 Amazon Bedrock AgentCore 优化从代理跟踪中生成建议，使用网关的实时流量 A/B 测试更改，并部署成功的配置，从而优化代理的性能。有关更多信息，请参阅[AgentCore 优化](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization.html)。

**Topics**
+ [主要考虑因素和局限性](#gateway-target-http-runtime-considerations)
+ [目标配置](#gateway-target-http-runtime-config)
+ [调用 AgentCore 运行时目标](#gateway-target-http-runtime-invoke)
+ [出站授权](#gateway-target-http-runtime-auth)
+ [强制流量通过网关](#gateway-target-http-runtime-source-validation)
+ [与 MCP 目标的能力比较](#gateway-target-http-runtime-comparison)

## 主要考虑因素和局限性
<a name="gateway-target-http-runtime-considerations"></a>

使用 AgentCore 运行时目标时，请注意以下注意事项：
+ 网关将流量直接发送到 AgentCore 运行时目标，而无需聚合功能。
+ AgentCore 可以将运行时目标添加到未设置协议类型的网关。它们不能添加到 MCP 协议类型的网关。
+  AgentCore 运行时目标没有功能同步或语义工具搜索可用。客户端必须通过基于路径的路由单独寻址每个目标。
+ Server-Sent AgentCore 运行时目标支持事件 (SSE) 流式传输。
+ 缓冲模式支持请求和响应拦截器 Lambda 函数。直播模式下尚不支持拦截器。

## 目标配置
<a name="gateway-target-http-runtime-config"></a>

创建 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 运行时目标
<a name="gateway-target-http-runtime-invoke"></a>

要通过网关调用 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
```

## 出站授权
<a name="gateway-target-http-runtime-auth"></a>

AgentCore 运行时目标支持以下出站授权类型：
+  **IAM (Sigv4)** — 网关扮演网关服务角色以获取证书，用于对运行时目标的请求进行签名。配置 IAM 授权时，您可以使用 IAM 策略来限制对网关角色的访问权限，从而确保所有运行时请求都流经网关。
+  **调用方 IAM 证书** — 网关使用调用者的 IAM 凭证签署对运行时目标的请求。网关代表呼叫者扮演角色，并使用呼叫者的身份对出站请求进行签名。
+  **OAuth (JWT)** — 网关通过 Amazon Bedrock 身份服务从目标配置的凭证提供商那里检索 OAuth 令牌。 AgentCore 
+  **Token pass** hrough — 网关验证入站令牌并将其传递到运行时目标，无需修改。当运行时处理自己的授权时，这很有用。

## 强制流量通过网关
<a name="gateway-target-http-runtime-source-validation"></a>

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

您可以对运行时配置此限制。网关会对其转发的每个请求的来源进行标记，运行时会在传入的路上验证该源。具体机制取决于运行时的入站授权类型：
+  **IAM (Sigv4) 运行时** — 附加一个基于资源的策略，该策略限制对网关执行角色的调用。有关策略及其所需的信任策略强化，请参阅[限制对网关的 IAM (Sigv4) 入站](runtime-oauth.md#runtime-restrict-iam-gateway)调用。
+  **OAuth (JWT) 运行**时 — 在运行时`allowedWorkloadConfiguration`上进行配置`customJWTAuthorizer`以仅允许网关的工作负载。有关配置和字段参考，请参阅[限制对网关的调用](runtime-oauth.md#deploy-agent-allowed-workload)。

## 与 MCP 目标的能力比较
<a name="gateway-target-http-runtime-comparison"></a>

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


| 能力 | 带有 MCP 目标的 MCP 网关 | AgentCore 运行时目标 | 
| --- | --- | --- | 
| Tool/capability 聚合 | 将来自所有 MCP 目标的功能聚合到一个统一的虚拟 MCP 服务器中。客户会看到一个合并的`tools/list`回复。 | 隔离运行。网关无需合并功能即可将流量直接发送到目标。客户端必须通过基于路径的路由单独寻址每个目标。 | 
| 语义工具搜索 | 为工具描述编制索引，并允许通过自然语言查询进行发现。 | 不可用。网关不采集或索引功能。客户必须知道确切的工具名称或使用服务器自己的工具名称`tools/list`。 | 
| 响应拦截器 Lambda | 支持非流式 MCP 操作的请求和响应拦截器。 | 在缓冲模式下支持请求和响应拦截器 Lambda 函数。直播模式下尚不支持拦截器。 |