Configurações de destino Criação de um destino de passagem HTTP Invocando um destino de passagem HTTP Métodos HTTP suportados Autorização de saída

Alvos 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 alvos de passagem ideais para URLs de agentes fronteiriços, 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 front agent (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.
Encaminhe 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 do aplicativo que o destino implementa. O gateway usa o tipo de protocolo para avaliação de observabilidade e política, 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 de 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 endpoint de inferência.
- CUSTOM— O alvo implementa um protocolo personalizado ou proprietário.
schema (opcional) — O esquema da API que descreve a estrutura de solicitação e resposta do alvo de passagem. O gateway usa esse esquema para habilitar recursos do mecanismo de políticas, como barreiras de proteção. O formato do esquema é detectado automaticamente como OpenAPI ou Smithy.

O requisito do esquema depende do tipo de protocolo:
- Para tipos MCP e A2A protocolos, 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 guardrails.
  
  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.

Criação de um destino de passagem HTTP

Os exemplos a seguir criam um destino de passagem que encaminha 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

Roteie 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

Roteie 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

Encaminhe para uma API externa e passe o JWT do chamador:


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

AWS CLI

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

Roteie 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 destino de passagem HTTP

Para invocar um destino de passagem HTTP por meio do gateway, envie uma solicitação ao destino usando 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 alvo. {gatewayId}Substitua pelo ID do gateway, {region} pela AWS região, {targetName} pelo nome do destino e pelo caminho {path} a ser encaminhado.

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

Métodos HTTP suportados

O gateway suporta os métodos HTTP usados pelos protocolos implementados pelos alvos de passagem: servidores MCP, agentes A2A e endpoints de inferência. Esses protocolos dependem de um subconjunto específico de métodos para invocar serviços e rotear tráfego.

O gateway oferece suporte aos seguintes métodos HTTP:

POST— Usado por todos os protocolos de destino de passagem como o método principal. O MCP usa POST para JSON-RPC mensagens, o A2A usa POST para enviar mensagens e gerenciar tarefas, e os endpoints de inferência usam POST para conclusões e solicitações de bate-papo.
GET— Usado pelo MCP para assinaturas de stream SSE, pela A2A para recuperar o status da tarefa e listar tarefas e por endpoints de inferência para listar modelos.
DELETE— Usado pela A2A para remover configurações de notificação push e por terminais de inferência para excluir recursos.

O gateway não suportaPATCH, PUTHEAD, ou OPTIONS métodos. Os alvos de passagem são projetados para invocar serviços e rotear tráfego, e esses métodos estão fora desse escopo.

Se um cliente enviar uma solicitação com um método HTTP não suportado, o gateway retornará um erro.

Autorização de saída

Os destinos de passagem HTTP suportam os 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 de IAM do chamador (CALLER_IAM_CREDENTIALS) — O gateway usa a identidade do IAM e as permissões do chamador para assinar solicitações ao destino usando o SigV4. Disponível somente para gateways com AWS_IAM ou tipo de AUTHENTICATE_ONLY autorizador.
Token passthrough (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 em solicitações de saída como um cabeçalho de solicitação especificado.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

AgentCore Tempo de execução

Alvos de inferência