View a markdown version of this page

Destinos de acceso directo HTTP - Amazon Bedrock AgentCore
Configuración de destinoCreación de un destino de transferencia HTTPInvocar un destino de transferencia HTTPAutorización saliente

Destinos de acceso directo HTTP

Puede añadir un destino de acceso directo HTTP para enrutar el tráfico a través de la puerta de enlace a cualquier punto final HTTP. La puerta de enlace reenvía las solicitudes al punto final de destino sin traducir el protocolo y actúa como una capa de proxy segura. Esto hace que los destinos de acceso directo sean ideales para las URL de los agentes de acceso, las API externas o cualquier servicio HTTP al que desee acceder mediante la autenticación, la aplicación de políticas y la observabilidad centralizadas de la puerta de enlace.

Añadir un destino de acceso directo HTTP a la puerta de enlace resulta útil cuando se quiere:

  • Servicios de agente frontal (como agentes A2A, servidores MCP externos o puntos de enlace de inferencia personalizados) detrás de un único punto de enlace de puerta de enlace con control de acceso unificado.

  • Dirija el tráfico a servicios externos mientras la puerta de enlace gestiona la autenticación entrante y la inyección de credenciales salientes.

  • Aplique políticas de puerta de enlace, como barandas y control de acceso, a las solicitudes destinadas a puntos finales externos.

  • Utilice el enrutamiento basado en rutas (/{targetName}/{path}) para llegar a varios servicios externos a través de una única puerta de enlace.

Configuración de destino

Al crear un destino de acceso directo HTTP, proporciona la URL del punto final de destino y un tipo de protocolo que indica el protocolo de aplicación que implementa el destino. La puerta de enlace utiliza el tipo de protocolo para la observabilidad y la evaluación de políticas, pero no realiza la traducción del protocolo.

La configuración de destino de un destino de transferencia HTTP utiliza la siguiente estructura:

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

El siguiente ejemplo muestra un destino de acceso directo con un protocolo personalizado y un 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"
                    }
                }
            }
        }
    }
}

  • punto final (obligatorio): la URL HTTPS del servicio de destino. La puerta de enlace reenvía las solicitudes a este punto final.

  • Tipo de protocolo (obligatorio): el protocolo de aplicación que implementa el objetivo. Valores válidos:

    • MCP— El objetivo es un servidor MCP. Úselo al enrutar a un único servidor MCP al que desee acceder directamente (no agregado con otros destinos MCP).

    • A2A— El objetivo implementa el protocolo Agent-to-Agent (A2A).

    • INFERENCE— El objetivo es un punto final de inferencia.

    • CUSTOM— El objetivo implementa un protocolo personalizado o propietario.

  • esquema (opcional): el esquema de la API que describe la estructura de solicitudes y respuestas del objetivo de transferencia. La puerta de enlace utiliza este esquema para habilitar las funciones del motor de políticas, como las barandillas. El formato del esquema se detecta automáticamente como OpenAPI o Smithy.

    El requisito del esquema depende del tipo de protocolo:

    • Para los tipos de A2A protocolos MCP y tipos, se aplica automáticamente un esquema predeterminado. No es necesario proporcionar un esquema a menos que desee anular el predeterminado.

    • Para los tipos de INFERENCE protocolos con proveedores conocidos (OpenAI, Anthropic o Amazon Bedrock), se aplica un esquema predeterminado basado en el dominio del punto final.

    • En el CUSTOM caso de los tipos de protocolos, debe proporcionar un esquema para usar barandas.

      El schema objeto contiene una source que especifica dónde se encuentra el contenido del esquema:

    • s3: un URI de S3 que apunta al archivo de esquema (por ejemplo,s3://DOC-EXAMPLE-BUCKET/service-schema.yaml).

    • inlinePayload: el contenido del esquema que se proporciona directamente en forma de cadena.

Creación de un destino de transferencia HTTP

Los siguientes ejemplos crean un destino de acceso directo que se dirige a distintos tipos de puntos de conexión: un agente A2A, un servidor MCP externo, un servicio IAM-authenticated interno y una API externa autenticada con una clave de API.

ejemplo
AgentCore CLI

  1. Diríjase a un agente A2A mediante una credencial de 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

    Diríjase a un servidor MCP externo con una credencial de 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

    Diríjase a un servicio interno mediante la autenticación basada en roles de IAM (SiGv4), con un protocolo y un esquema S3: CUSTOM

    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

    Diríjase a una API externa mediante una credencial de clave 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. Diríjase a un agente A2A con una credencial de 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"
                }
            }
        }
    ]
}'

    Diríjase a un servidor MCP externo con una credencial de 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"
                }
            }
        }
    ]
}'

    Diríjase a un servicio interno mediante la autenticación basada en roles de IAM, con un protocolo y un esquema S3: CUSTOM

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

    Diríjase a una API externa mediante una credencial de clave 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"
                }
            }
        }
    ]
}'

Invocar un destino de transferencia HTTP

Para invocar un destino de acceso directo HTTP a través de la puerta de enlace, envíe una solicitud al destino mediante el enrutamiento basado en rutas. El formato de la dirección URL es:

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

La puerta de enlace reenvía la solicitud al {endpoint}/{path} destino. {gatewayId}Sustitúyala por tu ID de puerta de enlace, por la AWS región, {targetName} por el nombre del objetivo y {path} por la ruta de reenvío. {region}

El siguiente ejemplo envía un mensaje A2A a un agente asociado a través de la puerta de enlace:

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

El siguiente ejemplo llama a un servidor MCP a través de la puerta de enlace:

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

Autorización saliente

Los destinos de acceso directo HTTP admiten los siguientes tipos de autorización de salida:

  • IAM (SiGv4) (GATEWAY_IAM_ROLE): la puerta de enlace asume la función de servicio de puerta de enlace para firmar las solicitudes dirigidas al destino.

  • OAuth (OAUTH): la puerta de enlace recupera los tokens de OAuth de los proveedores de credenciales configurados en el objetivo a través del servicio de identidad Amazon Bedrock. AgentCore

  • Credenciales de IAM de la persona que llama (CALLER_IAM_CREDENTIALS): la puerta de enlace utiliza la identidad de IAM y los permisos de la persona que llama para firmar las solicitudes dirigidas al destino mediante SigV4. Solo está disponible para pasarelas con o tipo de autorizador. AWS_IAM AUTHENTICATE_ONLY

  • Token passthrough (JWT_PASSTHROUGH): la puerta de enlace valida el token entrante y lo pasa al destino sin modificarlo.

  • Clave de API (API_KEY): la puerta de enlace recupera una clave de API de un proveedor de credenciales configurado en la bóveda de tokens y la inyecta en las solicitudes salientes como un encabezado de solicitud específico.