# HTTP 直通目标 您可以添加 HTTP 直通目标，将流量通过网关路由到任何 HTTP 终端节点。网关在不进行协议转换的情况下将请求转发到目标端点，充当安全的代理层。这使得直通目标非常适合前置代理 URL、外部 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) + [出站授权](#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 密钥凭据路由到外部 API： ``` agentcore add gateway-target \ --name external-api \ --type passthrough \ --passthrough-endpoint https://api.example.com \ --passthrough-protocol CUSTOM \ --outbound-auth api-key \ --credential-name my-api-key \ --credential-parameter-name x-api-key \ --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}` AWS 区域、`{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 直通目标支持以下出站授权类型： + **IAM (sigv4)** (`GATEWAY_IAM_ROLE`) — 网关扮演网关服务角色来签署对目标的请求。 + **OAuth** (`OAUTH`) — 网关通过 Amazon Bedrock 身份服务从目标中配置的凭证提供商那里检索 OAuth 令牌。 AgentCore + **呼叫者 IAM 证书** (`CALLER_IAM_CREDENTIALS`) — 网关使用调用者的 IAM 身份和权限使用 Sigv4 签署对目标的请求。仅适用于具有`AWS_IAM`或`AUTHENTICATE_ONLY`授权者类型的网关。 + **Token passt** hrough (`JWT_PASSTHROUGH`) — 网关验证入站令牌并将其传递给目标，无需修改。 + **API 密钥** (`API_KEY`) — 网关从令牌库中配置的凭证提供者那里检索 API 密钥，并将其作为指定的请求标头注入出站请求中。