Intercepteurs de requêtes Intercepteurs de réponse Intercepteurs de réponse avec diffusion en continu activée Intercepteurs pour cibles HTTP

Types d'intercepteurs

Il existe deux types d'intercepteurs que vous pouvez configurer sur votre passerelle : les intercepteurs REQUEST et les intercepteurs RESPONSE. La structure de charge utile de l'intercepteur dépend du type de cible configuré sur votre passerelle.

Cette rubrique couvre les contrats d'interception pour les cibles MCP et les cibles HTTP (comme Amazon Bedrock AgentCore Runtime).

Intercepteurs de requêtes

L'intercepteur REQUEST est invoqué avant que la passerelle n'appelle la cible configurée sur la passerelle. Vous pouvez utiliser l'intercepteur REQUEST pour effectuer des validations ou autorisations personnalisées.

Exemple de charge utile d'entrée d'un intercepteur de requêtes

L'exemple suivant montre la structure de charge utile d'entrée qu'une fonction Lambda d'interception de requêtes reçoit :


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "headers": {
            "Accept": "application/json",
            "Authorization": "<bearer_token>",
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>",
            "User-Agent": "<client_user_agent>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    }
  }
}

Note

Le headers champ n'est inclus que s'il passRequestHeaders est défini sur true dans la configuration de l'intercepteur. Le gatewayResponse champ n'est pas présent pour les intercepteurs de requêtes car la réponse n'a pas encore été générée.

Exemple de charge utile de sortie d'un intercepteur de requêtes

L'exemple suivant montre la structure de charge utile de sortie qu'une fonction Lambda d'interception de requêtes doit renvoyer :


{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest" : {
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "transformedGatewayResponse" : {
        "statusCode": 200,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "<result_content>": "<result_value>"
            }
        }
    }
  }
}

Important

Remarques importantes concernant la sortie de l'intercepteur de requêtes :* La interceptorOutputVersion valeur doit être définie sur. "1.0" * Si la sortie de l'intercepteur contient untransformedGatewayResponse, la passerelle répondra immédiatement avec ce contenu, même s'il transformedGatewayRequest est également fourni. * Si les intercepteurs REQUEST et RESPONSE sont configurés et que la sortie de l'intercepteur REQUEST contient untransformedGatewayResponse, l'intercepteur RESPONSE sera toujours invoqué.

Intercepteurs de réponse

L'intercepteur RESPONSE est invoqué avant que la passerelle ne réponde à l'appelant. Vous pouvez utiliser l'intercepteur RESPONSE pour effectuer des suppressions ou des ajouts personnalisés à la réponse envoyée à l'appelant.

Exemple de charge utile d'entrée d'un intercepteur de réponse

L'exemple suivant montre la structure de charge utile d'entrée qu'une fonction Lambda d'interception de réponses reçoit :


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "headers": {
            "Accept": "application/json",
            "Authorization": "<bearer_token>",
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>",
            "User-Agent": "<client_user_agent>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "gatewayResponse" : {
        "statusCode": 200,
        "headers": {
            "SomeHeader": "headerValue1",
            "Mcp-Session-Id": "<session_id>"
        },
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "tools": []
            }
        }
    }
  }
}

Note

Le headers champ in n'gatewayRequestest inclus que s'il passRequestHeaders est défini sur true dans la configuration de l'intercepteur. Les intercepteurs de réponse reçoivent à la fois la demande d'origine et la réponse de la passerelle, ce qui vous permet de modifier la réponse avant qu'elle ne soit renvoyée à l'appelant.

Exemple de charge utile de sortie d'un intercepteur de réponse

L'exemple suivant montre la structure de charge utile de sortie qu'une fonction Lambda d'interception de réponses doit renvoyer :


{
  "interceptorOutputVersion": "1.0",
  "mcp": {
    "transformedGatewayRequest" : {
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/list"
        }
    },
    "transformedGatewayResponse" : {
        "statusCode": 200,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "<result_content>": "<result_value>"
            }
        }
    }
  }
}

Important

Remarques importantes concernant la sortie de l'intercepteur de réponse :* La interceptorOutputVersion valeur doit être définie sur. "1.0" * Si la sortie de l'intercepteur contient untransformedGatewayResponse, la passerelle répondra immédiatement avec ce contenu, même s'il transformedGatewayRequest est également fourni. * Si les intercepteurs REQUEST et RESPONSE sont configurés et que la sortie de l'intercepteur REQUEST contient untransformedGatewayResponse, l'intercepteur RESPONSE sera toujours invoqué.

Intercepteurs de réponse avec diffusion en continu activée

Note

Si le streaming des réponses est activé sur votre passerelle, la fonction Lambda de votre intercepteur de réponses doit cocher isStreamingResponse le champ pour faire la distinction entre les réponses gatewayResponse en streaming et les réponses non diffusées. Pour les réponses en streaming, gérez plusieurs invocations par demande (une par événement éligible) et notez que seule la première invocation peut annuler et. headers statusCode

Lorsque le streaming des réponses est activé sur votre passerelle, le comportement de l'intercepteur de réponses change. L'intercepteur est invoqué plusieurs fois au cours d'une réponse en streaming, une fois par événement éligible, au lieu d'une fois avec la réponse complète.

Lorsque l'intercepteur de réponse est invoqué

L'intercepteur de réponse est invoqué pour les événements contenant un JSON-RPC id champ :

Premier événement : première JSON-RPC réponse ou demande initiée par le serveur sur le flux (par exemple, le résultat de l'outil ou une sampling/createMessage requêteelicitation/create/).
Événements ultérieurs — Toute JSON-RPC réponse supplémentaire ou demande initiée par le serveur (par exemple, le résultat final de l'outil une fois qu'une demande a été satisfaite).

L'intercepteur de réponse n'est pas invoqué pour :

notifications/progress— Les mises à jour de progression sont transmises directement au client.
notifications/message— Les messages du journal sont transmis directement au client.
Pings : les Keep-alive signaux sont transmis directement au client.

Charge utile d'entrée de l'intercepteur de réponse en streaming

La charge utile d'entrée inclut un nouveau isStreamingResponse champ défini sur. true Le gatewayResponse.body champ contient le corps de l'événement en cours.

Premier événement — L'intercepteur reçoit headersstatusCode, et body :


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "myTool",
                "arguments": {}
            }
        }
    },
    "gatewayResponse" : {
        "statusCode": 200,
        "headers": {
            "Mcp-Session-Id": "<session_id>"
        },
        "isStreamingResponse": true,
        "body": {
            "jsonrpc": "2.0",
            "id": "elicit-1",
            "method": "elicitation/create",
            "params": {
                "message": "Confirm this action?",
                "requestedSchema": {}
            }
        }
    }
  }
}

Événements suivants — L'intercepteur reçoit uniquement body (les en-têtes et le code d'état ont déjà été envoyés au client) :


{
  "interceptorInputVersion": "1.0",
  "mcp": {
    "rawGatewayRequest": {
        "body": "<raw_request_body>"
    },
    "gatewayRequest" : {
        "path": "/mcp",
        "httpMethod": "POST",
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "myTool",
                "arguments": {}
            }
        }
    },
    "gatewayResponse" : {
        "isStreamingResponse": true,
        "body": {
            "jsonrpc": "2.0",
            "id": 1,
            "result": {
                "content": [{"type": "text", "text": "Tool result"}]
            }
        }
    }
  }
}

Charge utile de sortie de l'intercepteur de réponse en streaming

Ce que l'intercepteur peut ignorer dépend du premier événement ou d'un événement ultérieur :

Événement	Peut annuler	Ignoré en cas de renvoi
Premier événement	`headers`, `statusCode`, `body`	N/A
Évènements ultérieurs	`body` uniquement	`headers`, `statusCode` (déjà envoyé au client)
Non-streaming (inchangé)	`headers`, `statusCode`, `body`	N/A

Intercepteurs pour cibles HTTP

Les cibles HTTP utilisent une structure de charge utile d'intercepteur différente de celle des cibles MCP. Les cibles HTTP (AgentCore Runtime et passthrough) et les cibles d'inférence utilisent toutes cette structure de http charge utile. L'inférence est un type de cible distinct qui partage la forme de la charge utile de l'intercepteur HTTP. La charge utile utilise une http clé au lieu d'une mcp clé. Les corps de requête et de réponse sont des chaînes codées en base64 plutôt que des objets JSON analysés.

Les cibles HTTP prennent en charge les intercepteurs REQUEST et RESPONSE en mode tampon, dans lequel la passerelle met en mémoire tampon la réponse complète avant d'appeler l'intercepteur de réponse. Les intercepteurs ne sont pas encore pris en charge en mode streaming.

La liste suivante récapitule les principaux comportements des intercepteurs de cibles HTTP :

Le httpMethod champ est en lecture seule.
Les body champs de demande et de réponse sont des chaînes codées en base64.
Le headers champ est inclus dans la charge utile de la demande uniquement lorsqu'il passRequestHeaders est défini sur true dans la configuration de l'intercepteur.
S'il transformedGatewayResponse est présent dans la sortie d'un intercepteur REQUEST, la passerelle renvoie cette réponse immédiatement sans appeler la cible (court-circuit). L'intercepteur RESPONSE ne fonctionne pas après un court-circuit.

Exemple de charge utile d'entrée d'un intercepteur de requêtes

L'exemple JSON suivant montre la structure de la charge utile d'entrée que reçoit votre fonction Lambda d'interception de requêtes lors du traitement d'une requête cible HTTP :


{
  "interceptorInputVersion": "1.0",
  "http": {
    "gatewayRequest": {
      "path": "/my-target-name/invocations",
      "httpMethod": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "<bearer_token>"
      },
      "body": "<base64_encoded_body>"
    }
  }
}

Note

Notez ce qui suit à propos de la charge utile d'entrée :

Le headers champ n'est inclus que s'il passRequestHeaders est défini sur true dans la configuration de l'intercepteur.
Le body champ est une chaîne codée en base64 qui représente le corps brut de la requête HTTP.
Le httpMethod champ est inclus à titre informatif mais est en lecture seule. L'intercepteur ne peut pas le modifier.

Exemple de charge utile de sortie d'un intercepteur de requêtes

L'exemple JSON suivant montre la structure de la charge utile de sortie que votre fonction Lambda d'interception de requêtes doit renvoyer lors de la transformation d'une requête cible HTTP :


{
  "interceptorOutputVersion": "1.0",
  "http": {
    "transformedGatewayRequest": {
      "headers": {
        "Content-Type": "application/json",
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>"
    },
    "transformedGatewayResponse": {
      "contentType": "application/json",
      "statusCode": 200,
      "headers": {
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>"
    }
  }
}

Important

Remarques importantes concernant la sortie de l'intercepteur de requêtes HTTP :

Le interceptorOutputVersion doit être réglé sur"1.0".
Si la sortie contient untransformedGatewayResponse, la passerelle renvoie cette réponse immédiatement sans appeler la cible.
Le body champ doit être une chaîne codée en base64.
Le n'httpMethodest pas inclus dans la sortie car il ne peut pas être modifié.

Exemple de charge utile d'entrée d'un intercepteur de réponse

Lorsque vous configurez un intercepteur RESPONSE pour une cible HTTP, la passerelle met en mémoire tampon la réponse cible et la transmet à votre fonction Lambda. L'exemple JSON suivant montre la structure de la charge utile d'entrée :


{
  "interceptorInputVersion": "1.0",
  "http": {
    "gatewayRequest": null,
    "gatewayResponse": {
      "statusCode": 200,
      "headers": null,
      "body": "<base64_encoded_body>",
      "contentType": "application/json"
    }
  }
}

Note

Notez ce qui suit à propos de la charge utile d'entrée de réponse :

Le body champ est une chaîne codée en base64 qui représente le corps de la réponse HTTP brute.
C'est body le null cas si vous excluez le corps de la réponse à l'aide d'un filtre de charge utile. Pour plus d'informations, voir Gérer des charges utiles de réponse importantes.

Exemple de charge utile de sortie d'un intercepteur de réponse

L'exemple JSON suivant montre la structure de la charge utile de sortie renvoyée par votre fonction Lambda d'interception de réponse lors de la transformation d'une réponse cible HTTP :


{
  "interceptorOutputVersion": "1.0",
  "http": {
    "transformedGatewayResponse": {
      "statusCode": 200,
      "headers": {
        "X-Custom-Header": "custom-value"
      },
      "body": "<base64_encoded_body>",
      "contentType": "application/json"
    }
  }
}

Important

Remarques importantes concernant la sortie de l'intercepteur de réponse HTTP :

Le interceptorOutputVersion doit être réglé sur"1.0".
Les contentType champs statusCodebody, et remplacent chacun la valeur de réponse initiale. Si vous omettez un champ (ou si vous le définissez surnull), la passerelle utilise la valeur d'origine.
Le body champ doit être une chaîne codée en base64.
Pour transmettre la réponse inchangée, renvoyez un http objet vide :{"interceptorOutputVersion": "1.0", "http": {}}.

Gérez des charges utiles de réponse importantes

L'invocation synchrone Lambda a une limite de charge utile de 6 Mo pour la demande et la réponse combinées. Si une cible renvoie un corps volumineux, ce qui est courant dans les modèles d'inférence, la charge utile codée en base64 peut dépasser cette limite et provoquer une erreur.

Pour éviter cela, excluez le corps de la réponse de l'entrée de l'intercepteur en configurant un filtre de charge utile qui exclut le RESPONSE_BODY champ. Votre intercepteur peut toujours inspecter lestatusCode, et contentTypeheaders, et peut injecter des en-têtes ou annuler le code d'état. Lorsque le corps de réponse est exclu, le body champ de la charge utile d'entrée l'estnull, et si votre fonction revientbody: null, la passerelle utilise le corps de réponse d'origine (non modifié).

Contexte du client

Pour les cibles HTTP, la passerelle transmet les métadonnées de demande à votre fonction Lambda via le contexte client de l'appel. Votre fonction peut lire les valeurs personnalisées suivantes : GATEWAY_ARNGATEWAY_ACCOUNT_ID,REQUEST_ID, etSOURCE_IP. Les REQUEST_ID valeurs GATEWAY_ARNGATEWAY_ACCOUNT_ID, et sont toujours présentes. La SOURCE_IP valeur n'est incluse que lorsqu'une adresse IP source est disponible. Votre fonction doit donc la traiter comme facultative.

Principales différences entre les charges utiles des intercepteurs MCP et HTTP

Le tableau suivant résume les différences entre les charges utiles des intercepteurs cibles MCP et HTTP.

Champ	Cible MCP	Cible HTTP
Format du corps	Carte<String, Object> (JSON analysé)	Chaîne (encodée en base64)
Chemin	Toujours « /mcp »	Chemin HTTP réel (par exemple, « /my-target- name/invocations »)
httpMethod	Immuable	Immuable
brut GatewayRequest	Inclus	Non incluse
Intercepteur de réponse	Pris en charge	Supporté en mode tampon (pas encore pris en charge en mode streaming)

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Autorisations pour les intercepteurs

Configuration