本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # HTTP 直通目标 您可以添加 HTTP 直通目标，将流量通过网关路由到任何 HTTP 终端节点。网关无需协议转换即可将请求转发到目标端点，充当安全代理层。这使得直通目标成为前端代理网址、外部 API 或您希望通过网关的集中式身份验证、策略执行和可观察性访问的任何 HTTP 服务的理想之选。 当您想执行以下操作时，向网关添加 HTTP 直通目标很有用： + 前端代理服务（例如 A2A 代理、外部 MCP 服务器或自定义推理端点）位于具有统一访问控制的单一网关端点后面。 + 将流量路由到外部服务，同时网关管理入站身份验证和出站凭据注入。 + 对发往外部端点的请求应用护栏和访问控制等网关策略。 + 使用基于路径的路由 (`/{targetName}/{path}`) 通过单个网关访问多个外部服务。 **Topics** + [目标配置](#gateway-target-http-passthrough-config) + [创建 HTTP 直通目标](#gateway-target-http-passthrough-create) + [调用 HTTP 直通目标](#gateway-target-http-passthrough-invoke) + [支持的 HTTP 方法](#gateway-target-http-passthrough-methods) + [出站授权](#gateway-target-http-passthrough-auth) ## 目标配置 创建 HTTP 直通目标时，需要提供目标端点 URL 和表示目标实现的应用程序协议的协议类型。网关使用协议类型进行可观察性和策略评估，但不执行协议转换。 HTTP 直通目标的目标配置使用以下结构： ``` { "http": { "passthrough": { "endpoint": "https://partner-agent.example.com", "protocolType": "A2A" } } } ``` 以下示例显示了具有自定义协议和显式 API 架构的直通目标： ``` { "http": { "passthrough": { "endpoint": "https://my-service.example.com", "protocolType": "CUSTOM", "schema": { "source": { "s3": { "uri": "s3://DOC-EXAMPLE-BUCKET/service-schema.yaml" } } } } } } ``` + **端点**（必填）— 目标服务的 HTTPS 网址。网关将请求转发到该终端节点。 + **协议类型**（必填）-目标实现的应用程序协议。有效值： + `MCP`— 目标是 MCP 服务器。在路由到要直接访问的单个 MCP 服务器（不与其他 MCP 目标聚合）时使用此选项。 + `A2A`— 目标实现 Agent-to-Agent (A2A) 协议。 + `INFERENCE`— 目标是推理端点。 + `CUSTOM`— 目标实现自定义或专有协议。 + **架构**（可选）-描述直通目标的请求和响应结构的 API 架构。网关使用此架构来启用策略引擎功能，例如护栏。架构格式会被自动检测为 OpenAPI 或 Smithy。 架构要求取决于协议类型： + 对于`MCP`和`A2A`协议类型，将自动应用默认架构。除非您想覆盖默认架构，否则无需提供架构。 + 对于使用知名提供商（OpenAI、Anthropic 或 Amazon Bedrock）的`INFERENCE`协议类型，将基于终端节点域应用默认架构。 + 对于`CUSTOM`协议类型，必须提供架构才能使用护栏。 该`schema`对象`source`包含一个用于指定架构内容所在位置的： + **s3 ** — 指向架构文件的 S3 URI（例如，`s3://DOC-EXAMPLE-BUCKET/service-schema.yaml`）。 + **inlinePayLoad ** — 直接以字符串形式提供的架构内容。 ## 创建 HTTP 直通目标 以下示例创建了路由到不同类型端点的直通目标：A2A 代理、外部 MCP 服务器、 IAM-authenticated 内部服务和使用 API 密钥进行身份验证的外部 API。 **Example** 1. 使用 OAuth 凭据路由到 A2A 代理： ``` agentcore add gateway-target \ --name partner-agent \ --type passthrough \ --passthrough-endpoint https://partner-agent.example.com \ --passthrough-protocol A2A \ --outbound-auth oauth \ --credential-name partner-oauth \ --gateway MyGateway agentcore deploy ``` 使用 OAuth 凭据路由到外部 MCP 服务器： ``` agentcore add gateway-target \ --name slack-mcp \ --type passthrough \ --passthrough-endpoint https://mcp-slack.example.com \ --passthrough-protocol MCP \ --outbound-auth oauth \ --credential-name slack-oauth \ --gateway MyGateway agentcore deploy ``` 使用 IAM (SigV4) 基于角色的身份验证、`CUSTOM`协议和 S3 架构路由到内部服务： ``` agentcore add gateway-target \ --name internal-service \ --type passthrough \ --passthrough-endpoint https://internal-service.example.com \ --passthrough-protocol CUSTOM \ --schema s3://amzn-s3-demo-bucket/internal-service-schema.yaml \ --signing-service execute-api \ --signing-region us-west-2 \ --gateway MyGateway agentcore deploy ``` 路由到外部 API 并传递调用者的 JWT： ``` agentcore add gateway-target \ --name external-api \ --type passthrough \ --passthrough-endpoint https://api.example.com \ --passthrough-protocol CUSTOM \ --outbound-auth jwt-passthrough \ --gateway MyGateway agentcore deploy ``` 1. 使用 OAuth 凭据路由到 A2A 代理： ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "partner-agent", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://partner-agent.example.com", "protocolType": "A2A" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "OAUTH", "credentialProvider": { "oauthCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/partner-oauth" } } } ] }' ``` 使用 OAuth 凭据路由到外部 MCP 服务器： ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "slack-mcp", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://mcp-slack.example.com", "protocolType": "MCP" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "OAUTH", "credentialProvider": { "oauthCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/oauthcredentialprovider/slack-oauth" } } } ] }' ``` 使用基于 IAM 角色的身份验证、`CUSTOM`协议和 S3 架构路由到内部服务： ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "internal-service", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://internal-service.example.com", "protocolType": "CUSTOM", "schema": { "source": { "s3": { "uri": "s3://DOC-EXAMPLE-BUCKET/internal-service-schema.yaml" } } } } } }, "credentialProviderConfigurations": [ {"credentialProviderType": "GATEWAY_IAM_ROLE"} ] }' ``` 使用 API 密钥凭据路由到外部 API： ``` aws bedrock-agentcore-control create-gateway-target --cli-input-json '{ "gatewayIdentifier": "GATEWAY_ID", "name": "external-api", "targetConfiguration": { "http": { "passthrough": { "endpoint": "https://api.example.com", "protocolType": "CUSTOM" } } }, "credentialProviderConfigurations": [ { "credentialProviderType": "API_KEY", "credentialProvider": { "apiKeyCredentialProvider": { "providerArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:token-vault/default/apikeycredentialprovider/my-api-key", "credentialParameterName": "x-api-key" } } } ] }' ``` ## 调用 HTTP 直通目标 要通过网关调用 HTTP 直通目标，请使用基于路径的路由向目标发送请求。URL 格式如下： ``` https://{gatewayId}.gateway.bedrock-agentcore.{region}.amazonaws.com/{targetName}/{path} ``` 网关将请求转发到目标`{endpoint}/{path}`上。`{gatewayId}`替换为您的网关 ID、`{region}` Amazon 区域、`{targetName}`目标名称和`{path}`前进路径。 以下示例通过网关向合作伙伴代理发送 A2A 消息： ``` curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/partner-agent/invocations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "jsonrpc": "2.0", "id": "req-001", "method": "message/send", "params": { "message": { "role": "user", "parts": [{"kind": "text", "text": "What is the stock price of AMZN?"}], "messageId": "msg-001" } } }' ``` 以下示例通过网关调用 MCP 服务器： ``` curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/slack-mcp/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' ``` ## 支持的 HTTP 方法 该网关支持直通目标实现的协议所使用的 HTTP 方法：MCP 服务器、A2A 代理和推理端点。这些协议依赖于特定的方法子集来调用服务和路由流量。 该网关支持以下 HTTP 方法： + `POST`— 由所有直通目标协议用作主要方法。MCP 使用 POST 发送 JSON-RPC 消息，A2A 使用 POST 发送消息和管理任务，推理端点使用 POST 处理完成和聊天请求。 + `GET`— 由 MCP 用于 SSE 流订阅，A2A 用于检索任务状态和列出任务，推理端点用于列出模型。 + `DELETE`— 由 A2A 用于删除推送通知配置，由推理端点用于删除资源。 网关不支持`PATCH`、`PUT``HEAD`、或`OPTIONS`方法。直通目标是为调用服务和路由流量而设计的，这些方法超出了该范围。 如果客户端使用不支持的 HTTP 方法发送请求，则网关会返回错误。 ## 出站授权 HTTP 直通目标支持以下出站授权类型： + **IAM (SigV4) ** (`GATEWAY_IAM_ROLE`) — 网关扮演网关服务角色来签署向目标发出的请求。 + **OAuth ** (`OAUTH`) — 网关通过亚马逊基岩身份服务从目标中配置的凭证提供商处检索 OAuth 代币。 AgentCore + **呼叫方 IAM 证书 ** (`CALLER_IAM_CREDENTIALS`) — 网关使用调用者的 IAM 身份和权限使用 Sigv4 签署向目标发出的请求。仅适用于具有`AWS_IAM`或`AUTHENTICATE_ONLY`授权方类型的网关。 + **Token passthrough ** (`JWT_PASSTHROUGH`) — 网关验证入站令牌并将其传递到目标系统，无需修改。 + **API 密钥 ** (`API_KEY`) — 网关从令牌库中配置的凭证提供商处检索 API 密钥，并将其作为指定的请求标头注入到出站请求中。