View a markdown version of this page

Destinos de passagem HTTP - Amazon Bedrock AgentCore
Configurações de destinoCriando um destino de passagem HTTPInvocando um alvo de passagem HTTPAutorização de saída

Destinos de passagem HTTP

Você pode adicionar um destino de passagem HTTP para rotear o tráfego pelo gateway para qualquer endpoint HTTP. O gateway encaminha solicitações para o endpoint de destino sem tradução de protocolo, atuando como uma camada de proxy segura. Isso torna os destinos de passagem ideais para URLs de agentes frontais, APIs externas ou qualquer serviço HTTP que você queira acessar por meio da autenticação centralizada, aplicação de políticas e observabilidade do gateway.

Adicionar um destino de passagem HTTP ao seu gateway é útil quando você deseja:

  • Serviços de agente frontal (como agentes A2A, servidores MCP externos ou endpoints de inferência personalizados) por trás de um único endpoint de gateway com controle de acesso unificado.

  • Direcione o tráfego para serviços externos enquanto o gateway gerencia a autenticação de entrada e a injeção de credenciais de saída.

  • Aplique políticas de gateway, como grades de proteção e controle de acesso, às solicitações destinadas a endpoints externos.

  • Use o roteamento baseado em caminho (/{targetName}/{path}) para alcançar vários serviços externos por meio de um único gateway.

Configurações de destino

Ao criar um destino de passagem HTTP, você fornece a URL do endpoint de destino e um tipo de protocolo que indica o protocolo de aplicativo que o destino implementa. O gateway usa o tipo de protocolo para observabilidade e avaliação de políticas, mas não realiza a tradução do protocolo.

A configuração de destino para um destino de passagem HTTP usa a seguinte estrutura:

{
    "http": {
        "passthrough": {
            "endpoint": "https://partner-agent.example.com",
            "protocolType": "A2A"
        }
    }
}

O exemplo a seguir mostra um destino de passagem com um protocolo personalizado e um esquema de API explícito:

{
    "http": {
        "passthrough": {
            "endpoint": "https://my-service.example.com",
            "protocolType": "CUSTOM",
            "schema": {
                "source": {
                    "s3": {
                        "uri": "s3://DOC-EXAMPLE-BUCKET/service-schema.yaml"
                    }
                }
            }
        }
    }
}

  • endpoint (obrigatório) — O URL HTTPS do serviço de destino. O gateway encaminha solicitações para esse endpoint.

  • ProtocolType (obrigatório) — O protocolo do aplicativo que o destino implementa. Valores válidos:

    • MCP— O alvo é um servidor MCP. Use isso ao rotear para um único servidor MCP que você deseja acessar diretamente (não agregado a outros destinos MCP).

    • A2A— O alvo implementa o protocolo Agent-to-Agent (A2A).

    • INFERENCE— O alvo é um ponto final de inferência.

    • CUSTOM— O alvo implementa um protocolo personalizado ou proprietário.

  • esquema (opcional) — O esquema da API que descreve a estrutura de solicitação e resposta do destino de passagem. O gateway usa esse esquema para habilitar recursos do mecanismo de políticas, como grades de proteção. O formato do esquema é detectado automaticamente como OpenAPI ou Smithy.

    O requisito do esquema depende do tipo de protocolo:

    • Para tipos de A2A protocolo MCP e, um esquema padrão é aplicado automaticamente. Você não precisa fornecer um esquema, a menos que queira substituir o padrão.

    • Para tipos de INFERENCE protocolo com provedores conhecidos (OpenAI, Anthropic ou Amazon Bedrock), um esquema padrão é aplicado com base no domínio do endpoint.

    • Para tipos de CUSTOM protocolo, você deve fornecer um esquema para usar grades de proteção.

      O schema objeto contém um source que especifica onde o conteúdo do esquema está localizado:

    • s3 — Um URI do S3 apontando para o arquivo do esquema (por exemplo,). s3://DOC-EXAMPLE-BUCKET/service-schema.yaml

    • InlinePayload — O conteúdo do esquema fornecido diretamente como uma string.

Criando um destino de passagem HTTP

Os exemplos a seguir criam um destino de passagem que roteia para diferentes tipos de endpoints: um agente A2A, um servidor MCP externo, um serviço IAM-authenticated interno e uma API externa autenticada com uma chave de API.

exemplo
AgentCore CLI

  1. Encaminhe para um agente A2A usando uma credencial OAuth:

    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

    Roteie para um servidor MCP externo usando uma credencial OAuth:

    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

    Encaminhe para um serviço interno usando a autenticação baseada em funções do IAM (SigV4), com um CUSTOM protocolo e um esquema 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

    Roteie para uma API externa usando uma credencial de chave de 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
AWS CLI

  1. Encaminhe para um agente A2A usando uma credencial OAuth:

    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"
                }
            }
        }
    ]
}'

    Roteie para um servidor MCP externo usando uma credencial OAuth:

    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"
                }
            }
        }
    ]
}'

    Encaminhe para um serviço interno usando a autenticação baseada em funções do IAM, com um CUSTOM protocolo e um esquema 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"}
    ]
}'

    Roteie para uma API externa usando uma credencial de chave de 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"
                }
            }
        }
    ]
}'

Invocando um alvo de passagem HTTP

Para invocar um destino de passagem HTTP pelo gateway, envie uma solicitação ao destino usando o roteamento baseado em caminho. O formato do URL é:

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

O gateway encaminha a solicitação para {endpoint}/{path} o destino. {gatewayId}Substitua pelo ID do gateway, {region} pela AWS região, {targetName} pelo nome do destino e {path} pelo caminho a seguir.

O exemplo a seguir envia uma mensagem A2A para um agente parceiro por meio do gateway:

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 <token>" \
    -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"
            }
        }
    }'

O exemplo a seguir chama um servidor MCP por meio do gateway:

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 <token>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Autorização de saída

Os destinos de passagem HTTP oferecem suporte aos seguintes tipos de autorização de saída:

  • IAM (SigV4) (GATEWAY_IAM_ROLE) — O gateway assume a função de serviço do gateway para assinar solicitações para o destino.

  • OAuth (OAUTH) — O gateway recupera tokens OAuth de provedores de credenciais configurados no destino por meio do serviço de identidade Amazon Bedrock. AgentCore

  • Credenciais do IAM do chamador (CALLER_IAM_CREDENTIALS) — O gateway usa a identidade e as permissões do IAM do chamador para assinar solicitações para o destino usando SigV4. Disponível somente para gateways com AWS_IAM ou tipo de AUTHENTICATE_ONLY autorizador.

  • Passagem do token (JWT_PASSTHROUGH) — O gateway valida o token de entrada e o passa para o destino sem modificação.

  • Chave de API (API_KEY) — O gateway recupera uma chave de API de um provedor de credenciais configurado no cofre de tokens e a injeta nas solicitações de saída como um cabeçalho de solicitação especificado.