Interceptoren anfordern Antwort-Interzeptoren Antwort-Interzeptoren mit aktiviertem Streaming Interzeptoren für HTTP-Ziele

Arten von Abfangjägern

Es gibt zwei Arten von Interzeptoren, die Sie auf Ihrem Gateway konfigurieren können: REQUEST-Interzeptoren und RESPONSE-Interzeptoren. Die Struktur der Interceptor-Payloads hängt vom Zieltyp ab, der auf Ihrem Gateway konfiguriert ist.

Dieses Thema behandelt die Interceptor-Verträge sowohl für MCP-Ziele als auch für HTTP-Ziele (wie Amazon AgentCore Bedrock Runtime).

Interceptoren anfordern

Der REQUEST-Interceptor wird aufgerufen, bevor das Gateway das auf dem Gateway konfigurierte Ziel aufruft. Sie können den REQUEST-Interceptor verwenden, um benutzerdefinierte Validierungen oder Autorisierungen durchzuführen.

Beispiel für eine Payload zur Eingabe eines Request-Interceptors

Das folgende Beispiel zeigt die Eingabe-Payload-Struktur, die eine Anforderungsinterceptor-Lambda-Funktion empfängt:


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

Anmerkung

Das headers Feld ist nur enthalten, wenn es true in der passRequestHeaders Interceptor-Konfiguration auf eingestellt ist. Das gatewayResponse Feld ist für Request-Interceptoren nicht vorhanden, da die Antwort noch nicht generiert wurde.

Beispiel für eine Payload für die Ausgabe eines Request-Interceptors

Das folgende Beispiel zeigt die Ausgabe-Payload-Struktur, die eine Anforderungsinterceptor-Lambda-Funktion zurückgeben sollte:


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

Wichtig

Wichtige Hinweise zur Ausgabe von Request-Interceptoren: * Der muss auf gesetzt sein. interceptorOutputVersion "1.0" * Wenn die Interceptor-Ausgabe eine enthälttransformedGatewayResponse, antwortet das Gateway sofort mit diesem Inhalt, auch wenn transformedGatewayRequest er ebenfalls bereitgestellt wird. * Wenn sowohl der REQUEST- als auch der RESPONSE-Interzeptor konfiguriert sind und die Ausgabe des REQUEST-Interzeptors eine enthälttransformedGatewayResponse, wird der RESPONSE-Interzeptor trotzdem aufgerufen.

Antwort-Interzeptoren

Der RESPONSE-Interceptor wird aufgerufen, bevor das Gateway dem Anrufer antwortet. Sie können den RESPONSE-Interceptor verwenden, um benutzerdefinierte Änderungen oder Ergänzungen der Antwort an den Anrufer vorzunehmen.

Beispiel für die Payload „Response Interceptor Input“

Das folgende Beispiel zeigt die Eingabe-Payload-Struktur, die eine Response-Interceptor-Lambda-Funktion empfängt:


{
  "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": []
            }
        }
    }
  }
}

Anmerkung

Das headers Feld in gatewayRequest ist nur enthalten, wenn es true in der passRequestHeaders Interceptor-Konfiguration auf eingestellt ist. Response-Interceptoren empfangen sowohl die ursprüngliche Anfrage als auch die Antwort des Gateways, sodass Sie die Antwort ändern können, bevor sie an den Anrufer zurückgegeben wird.

Beispiel für die Payload „Response Interceptor Output“

Das folgende Beispiel zeigt die Ausgabe-Payload-Struktur, die eine Response-Interceptor-Lambda-Funktion zurückgeben sollte:


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

Wichtig

Wichtige Hinweise zur Response-Interceptor-Ausgabe: * Der muss auf gesetzt sein. interceptorOutputVersion "1.0" * Wenn der Interceptor-Ausgang ein enthälttransformedGatewayResponse, antwortet das Gateway sofort mit diesem Inhalt, auch wenn transformedGatewayRequest dieser ebenfalls bereitgestellt wird. * Wenn sowohl der REQUEST- als auch der RESPONSE-Interzeptor konfiguriert sind und die Ausgabe des REQUEST-Interzeptors eine enthälttransformedGatewayResponse, wird der RESPONSE-Interzeptor trotzdem aufgerufen.

Antwort-Interzeptoren mit aktiviertem Streaming

Anmerkung

Wenn Response-Streaming auf Ihrem Gateway aktiviert ist, muss Ihre Response Interceptor-Lambda-Funktion das isStreamingResponse Feld aktivieren, um zwischen Streaming-Antworten und Nicht-Streaming-Antworten gatewayResponse zu unterscheiden. Behandeln Sie bei Streaming-Antworten mehrere Aufrufe pro Anfrage — einen pro berechtigtem Ereignis — und beachten Sie, dass nur der erste Aufruf und überschreiben kann. headers statusCode

Wenn das Antwort-Streaming auf Ihrem Gateway aktiviert ist, ändert sich das Verhalten des Response-Interceptors. Der Interceptor wird während einer Streaming-Antwort mehrmals aufgerufen — einmal pro berechtigtem Ereignis — statt einmal bei der vollständigen Antwort.

Wenn der Response-Interceptor aufgerufen wird

Der Response Interceptor wird für Ereignisse aufgerufen, die ein Feld enthalten: JSON-RPC id

Erstes Ereignis — Die erste JSON-RPC Antwort oder die erste vom Server initiierte Anfrage im Stream (z. B. das Tool-Ergebnis oder eine elicitation/create /-Anforderung). sampling/createMessage
Nachfolgende Ereignisse — Alle zusätzlichen JSON-RPC Antworten oder vom Server initiierten Anfragen (z. B. das endgültige Tool-Ergebnis, nachdem eine Anfrage erfüllt wurde).

Der Response Interceptor wird nicht aufgerufen für:

notifications/progress— Fortschrittsaktualisierungen werden direkt an den Client weitergeleitet.
notifications/message— Protokollnachrichten werden direkt an den Client weitergeleitet.
Pings — Keep-alive Signale werden direkt an den Client weitergeleitet.

Payload: Streaming-Antwort, Interceptor, Eingabe

Die Eingabe-Payload enthält ein neues isStreamingResponse Feld, das auf gesetzt ist. true Das gatewayResponse.body Feld enthält den Hauptteil des aktuellen Ereignisses.

Erstes Ereignis — Der Interceptor empfängtheaders,statusCode, und: 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": {}
            }
        }
    }
  }
}

Nachfolgende Ereignisse — Der Interceptor empfängt nur body (Header und Statuscode wurden bereits an den Client gesendet):


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

Payload für Streaming-Response, Interceptor-Ausgabe

Was der Interceptor außer Kraft setzen kann, hängt davon ab, ob es sich um das erste oder ein nachfolgendes Ereignis handelt:

Veranstaltung	Kann überschreiben	Wird ignoriert, wenn zurückgegeben
Erstes Ereignis	`headers`, `statusCode`, `body`	N/A
Nachfolgende Ereignisse	Nur `body`	`headers`, `statusCode` (bereits an den Kunden gesendet)
Non-streaming (unverändert)	`headers`, `statusCode`, `body`	N/A

Interzeptoren für HTTP-Ziele

HTTP-Ziele verwenden eine andere Interceptor-Payload-Struktur als MCP-Ziele. HTTP-Ziele (AgentCore Runtime und Passthrough) und Inferenzziele verwenden alle diese Payload-Struktur. http Inferenz ist ein separater Zieltyp, der zufällig die Form der HTTP-Interzeptor-Payload gemeinsam hat. Die Nutzlast verwendet einen http Schlüssel anstelle eines Schlüssels. mcp Anforderungs- und Antworttexte sind Base64-kodierte Zeichenketten und keine geparsten JSON-Objekte.

HTTP-Ziele unterstützen sowohl REQUEST- als auch RESPONSE-Interzeptoren im gepufferten Modus, in dem das Gateway die gesamte Antwort puffert, bevor es den Antwort-Interzeptor aufruft. Interzeptoren werden im Streaming-Modus noch nicht unterstützt.

In der folgenden Liste sind die wichtigsten Verhaltensweisen von HTTP-Ziel-Interzeptoren zusammengefasst:

Das httpMethod Feld ist schreibgeschützt.
Die Anforderungs- und body Antwortfelder sind Base64-kodierte Zeichenketten.
Das headers Feld ist nur dann in der Payload der Anfrage enthalten, wenn passRequestHeaders es true in der Interceptor-Konfiguration auf eingestellt ist.
Wenn in der Ausgabe eines REQUEST-Interceptors vorhanden transformedGatewayResponse ist, gibt das Gateway diese Antwort sofort zurück, ohne das Ziel aufzurufen (Kurzschluss). Der RESPONSE-Interceptor läuft nach einem Kurzschluss nicht.

Beispiel für eine Payload zur Eingabe eines Request-Interceptors

Das folgende JSON-Beispiel zeigt die Struktur der Eingabe-Payload, die Ihre Request-Interceptor-Lambda-Funktion bei der Verarbeitung einer HTTP-Zielanforderung empfängt:


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

Anmerkung

Beachten Sie Folgendes zur Eingabe-Payload:

Das headers Feld ist nur enthalten, wenn passRequestHeaders es true in der Interceptor-Konfiguration auf eingestellt ist.
Das body Feld ist eine Base64-kodierte Zeichenfolge, die den unverarbeiteten Hauptteil der HTTP-Anfrage darstellt.
Das httpMethod Feld dient zu Informationszwecken, ist aber schreibgeschützt. Der Interceptor kann es nicht ändern.

Beispiel für eine Payload für die Ausgabe eines Interceptors anfordern

Das folgende JSON-Beispiel zeigt die Struktur der Ausgabe-Payload, die Ihre Lambda-Funktion für den Anforderungsabfang zurückgeben muss, wenn eine HTTP-Zielanforderung transformiert wird:


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

Wichtig

Wichtige Hinweise zur Ausgabe des HTTP-Request-Interceptors:

Der interceptorOutputVersion muss auf gesetzt sein. "1.0"
Wenn die Ausgabe eine enthälttransformedGatewayResponse, gibt das Gateway diese Antwort sofort zurück, ohne das Ziel aufzurufen.
Das body Feld muss eine Base64-kodierte Zeichenfolge sein.
Das httpMethod ist nicht in der Ausgabe enthalten, da es nicht geändert werden kann.

Beispiel für die Payload „Response Interceptor Input“

Wenn Sie einen RESPONSE-Interceptor für ein HTTP-Ziel konfigurieren, puffert das Gateway die Zielantwort und leitet sie an Ihre Lambda-Funktion weiter. Das folgende JSON-Beispiel zeigt die Struktur der Eingabe-Payload:


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

Anmerkung

Beachten Sie Folgendes zur Nutzlast der Antworteingabe:

Das body Feld ist eine Base64-kodierte Zeichenfolge, die den rohen HTTP-Antworttext darstellt.
Das body Feld wird verwendet, null wenn Sie den Antworttext mit einem Payloadfilter ausschließen. Weitere Informationen finden Sie unter Umgang mit großen Antwortnutzlasten.

Beispiel für die Payload „Response Interceptor Output“

Das folgende JSON-Beispiel zeigt die Struktur der Ausgabe-Payload, die Ihre Response-Interceptor-Lambda-Funktion zurückgibt, wenn Sie eine HTTP-Zielantwort transformieren:


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

Wichtig

Wichtige Hinweise zur Ausgabe des HTTP-Response-Interceptors:

Das interceptorOutputVersion muss auf gesetzt sein. "1.0"
Die contentType Felder statusCodebody, und überschreiben jeweils den ursprünglichen Antwortwert. Wenn Sie ein Feld weglassen (oder es auf einstellennull), verwendet das Gateway den ursprünglichen Wert.
Das body Feld muss eine Base64-kodierte Zeichenfolge sein.
Um die Antwort unverändert weiterzuleiten, geben Sie ein leeres http Objekt zurück:. {"interceptorOutputVersion": "1.0", "http": {}}

Behandeln Sie große Antwort-Payloads

Der synchrone Lambda-Aufruf hat ein Nutzlastlimit von 6 MB für die kombinierte Anforderung und Antwort. Wenn ein Ziel einen großen Textkörper zurückgibt — was bei Inferenzmodellen üblich ist — kann die Base64-kodierte Nutzlast dieses Limit überschreiten und einen Fehler verursachen.

Um dies zu vermeiden, schließen Sie den Antworttext von der Interceptor-Eingabe aus, indem Sie einen Nutzdatenfilter konfigurieren, der das Feld ausschließt. RESPONSE_BODY Ihr Interceptor kann weiterhin diestatusCode,, und contentTypeheaders, überprüfen und Header einfügen oder den Statuscode überschreiben. Wenn der Antworttext ausgeschlossen ist, ist das body Feld in der Eingabe-Payloadnull, und wenn Ihre Funktion zurückkehrtbody: null, verwendet das Gateway den ursprünglichen (unveränderten) Antworttext.

Client-Kontext

Bei HTTP-Zielen übergibt das Gateway Anforderungsmetadaten über den Client-Kontext des Aufrufs an Ihre Lambda-Funktion. Ihre Funktion kann die folgenden benutzerdefinierten Werte lesen:GATEWAY_ARN, GATEWAY_ACCOUNT_IDREQUEST_ID, und. SOURCE_IP Die REQUEST_ID Werte GATEWAY_ARNGATEWAY_ACCOUNT_ID, und sind immer vorhanden. Der SOURCE_IP Wert ist nur enthalten, wenn eine Quell-IP verfügbar ist. Daher sollte Ihre Funktion ihn als optional behandeln.

Hauptunterschiede zwischen MCP- und HTTP-Interceptor-Payloads

In der folgenden Tabelle sind die Unterschiede zwischen MCP- und HTTP-Ziel-Interceptor-Payloads zusammengefasst.

Feld	MCP-Ziel	HTTP-Ziel
Körperformat	Karte<String, Object> (geparstes JSON)	Zeichenfolge (Base64-kodiert)
Pfad	Immer „/mcp“	Tatsächlicher HTTP-Pfad (zum Beispiel „/my-target- „) name/invocations
httpMethod	Immutable (Unveränderlich)	Immutable (Unveränderlich)
roh GatewayRequest	Enthalten	Nicht enthalten
Antwort-Interzeptor	Unterstützt	Wird im gepufferten Modus unterstützt (im Streaming-Modus noch nicht unterstützt)

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Berechtigungen für Abfangjäger

Konfiguration