View a markdown version of this page

Cibles de relais HTTP - Base rocheuse de l'Amazonie AgentCore
Configuration cibleCréation d'une cible de relais HTTPInvocation d'une cible de relais HTTPMéthodes HTTP prises en chargeAutorisation sortante

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Cibles de relais HTTP

Vous pouvez ajouter une cible de relais HTTP pour acheminer le trafic via la passerelle vers n'importe quel point de terminaison HTTP. La passerelle transmet les demandes au terminal cible sans traduction de protocole, agissant comme une couche proxy sécurisée. Les cibles intermédiaires sont donc idéales pour les URL des agents frontaux, les API externes ou tout service HTTP auquel vous souhaitez accéder via l'authentification centralisée, l'application des politiques et l'observabilité de la passerelle.

L'ajout d'une cible de relais HTTP à votre passerelle est utile lorsque vous souhaitez :

  • Services d'agent frontal (tels que des agents A2A, des serveurs MCP externes ou des points de terminaison d'inférence personnalisés) derrière un point de terminaison de passerelle unique avec contrôle d'accès unifié.

  • Acheminez le trafic vers des services externes pendant que la passerelle gère l'authentification entrante et l'injection d'informations d'identification sortantes.

  • Appliquez des politiques de passerelle, telles que des garde-corps et un contrôle d'accès, aux demandes destinées à des points de terminaison externes.

  • Utilisez le routage basé sur le chemin (/{targetName}/{path}) pour accéder à plusieurs services externes via une passerelle unique.

Configuration cible

Lorsque vous créez une cible de relais HTTP, vous fournissez l'URL du point de terminaison cible et un type de protocole qui indique le protocole d'application mis en œuvre par la cible. La passerelle utilise le type de protocole pour l'observabilité et l'évaluation des politiques, mais n'effectue pas de traduction de protocole.

La configuration cible d'une cible relais HTTP utilise la structure suivante :

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

L'exemple suivant montre une cible intermédiaire dotée d'un protocole personnalisé et d'un schéma d'API explicite :

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

  • point de terminaison (obligatoire) : URL HTTPS du service cible. La passerelle transmet les demandes à ce point de terminaison.

  • ProtocolType (obligatoire) — Protocole d'application implémenté par la cible. Valeurs valides :

    • MCP— La cible est un serveur MCP. Utilisez-le lors du routage vers un seul serveur MCP auquel vous souhaitez accéder directement (non agrégé avec d'autres cibles MCP).

    • A2A— La cible implémente le protocole Agent-to-Agent (A2A).

    • INFERENCE— La cible est un point final d'inférence.

    • CUSTOM— La cible implémente un protocole personnalisé ou propriétaire.

  • schéma (facultatif) : schéma d'API qui décrit la structure de demande et de réponse de la cible intermédiaire. La passerelle utilise ce schéma pour activer les fonctionnalités du moteur de politiques telles que les garde-corps. Le format du schéma est détecté automatiquement en tant que OpenAPI ou Smithy.

    Le schéma requis dépend du type de protocole :

    • Pour les types de A2A protocoles MCP et les types de protocoles, un schéma par défaut est appliqué automatiquement. Il n'est pas nécessaire de fournir un schéma à moins que vous ne souhaitiez remplacer le schéma par défaut.

    • Pour les types de INFERENCE protocoles utilisant des fournisseurs connus (OpenAI, Anthropic ou Amazon Bedrock), un schéma par défaut est appliqué en fonction du domaine du point de terminaison.

    • Pour les types de CUSTOM protocoles, vous devez fournir un schéma d'utilisation des garde-corps.

      L'schemaobjet contient un source qui indique où se trouve le contenu du schéma :

    • s3 — Un URI S3 pointant vers le fichier de schéma (par exemple,s3://DOC-EXAMPLE-BUCKET/service-schema.yaml).

    • InlinePayload — Le contenu du schéma est fourni directement sous forme de chaîne.

Création d'une cible de relais HTTP

Les exemples suivants créent une cible intermédiaire qui achemine vers différents types de points de terminaison : un agent A2A, un serveur MCP externe, un service IAM-authenticated interne et une API externe authentifiée par une clé API.

Exemple
AgentCore CLI

  1. Route vers un agent A2A à l'aide d'un identifiant 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

    Routez vers un serveur MCP externe à l'aide d'un identifiant 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

    Route vers un service interne à l'aide de l'authentification basée sur les rôles IAM (Sigv4), avec un CUSTOM protocole et un schéma 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

    Acheminez vers une API externe et transmettez le JWT de l'appelant :

    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

  1. Route vers un agent A2A à l'aide d'un identifiant 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"
                }
            }
        }
    ]
}'

    Routez vers un serveur MCP externe à l'aide d'un identifiant 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"
                }
            }
        }
    ]
}'

    Acheminez vers un service interne à l'aide de l'authentification basée sur les rôles IAM, avec un CUSTOM protocole et un schéma 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"}
    ]
}'

    Acheminez vers une API externe à l'aide d'un identifiant de clé d'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"
                }
            }
        }
    ]
}'

Invocation d'une cible de relais HTTP

Pour invoquer une cible de relais HTTP via la passerelle, envoyez une demande à la cible à l'aide d'un routage basé sur le chemin. Le format de l'URL est le suivant :

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

La passerelle transmet la demande {endpoint}/{path} à la cible. Remplacez-le {gatewayId} par l'ID de votre passerelle, {region} par la AWS région, {targetName} par le nom de la cible et {path} par le chemin à suivre.

L'exemple suivant envoie un message A2A à un agent partenaire via la passerelle :

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

L'exemple suivant appelle un serveur MCP via la passerelle :

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éthodes HTTP prises en charge

La passerelle prend en charge les méthodes HTTP utilisées par les protocoles implémentés par les cibles intermédiaires : serveurs MCP, agents A2A et points de terminaison d'inférence. Ces protocoles s'appuient sur un sous-ensemble spécifique de méthodes pour appeler des services et acheminer le trafic.

La passerelle prend en charge les méthodes HTTP suivantes :

  • POST— Utilisée par tous les protocoles cibles intermédiaires comme méthode principale. MCP utilise POST pour les JSON-RPC messages, A2A utilise POST pour envoyer des messages et gérer les tâches, et les points de terminaison d'inférence utilisent POST pour les complétions et les demandes de chat.

  • GET— Utilisé par MCP pour les abonnements aux flux SSE, par A2A pour récupérer l'état des tâches et répertorier les tâches, et par inférence par les points de terminaison pour répertorier les modèles.

  • DELETE— Utilisé par A2A pour supprimer les configurations de notifications push et par inférence par les points de terminaison pour supprimer des ressources.

La passerelle ne prend pas en charge les OPTIONS méthodes PATCH PUTHEAD,, ou. Les cibles passthrough sont conçues pour invoquer des services et acheminer le trafic, et ces méthodes n'entrent pas dans ce cadre.

Si un client envoie une demande à l'aide d'une méthode HTTP non prise en charge, la passerelle renvoie une erreur.

Autorisation sortante

Les cibles de relais HTTP prennent en charge les types d'autorisation sortante suivants :

  • IAM (SigV4) (GATEWAY_IAM_ROLE) — La passerelle assume le rôle de service de passerelle pour signer les demandes adressées à la cible.

  • OAuth (OAUTH) : la passerelle récupère les jetons OAuth auprès des fournisseurs d'informations d'identification configurés dans la cible via le service d'identité Amazon Bedrock. AgentCore

  • Informations d'identification IAM de l'appelant (CALLER_IAM_CREDENTIALS) : la passerelle utilise l'identité IAM et les autorisations de l'appelant pour signer les demandes adressées à la cible à l'aide de SIGv4. Disponible uniquement pour les passerelles avec AWS_IAM ou type AUTHENTICATE_ONLY d'autorisation.

  • Token passthrough (JWT_PASSTHROUGH) — La passerelle valide le jeton entrant et le transmet à la cible sans modification.

  • Clé API (API_KEY) : la passerelle extrait une clé API auprès d'un fournisseur d'informations d'identification configuré dans le coffre à jetons et l'injecte dans les demandes sortantes sous la forme d'un en-tête de demande spécifié.