Richiedi intercettori Intercettori di risposta Intercettori di risposta con streaming abilitato Intercettori per destinazioni HTTP

Tipi di intercettori

Esistono due tipi di intercettori che è possibile configurare sul gateway: gli intercettori REQUEST e gli intercettori RESPONSE. La struttura del payload dell'intercettore dipende dal tipo di destinazione configurato sul gateway.

Questo argomento tratta i contratti di intercettazione sia per le destinazioni MCP che per le destinazioni HTTP (come Amazon Bedrock Runtime). AgentCore

Richiedi intercettori

L'interceptor REQUEST viene richiamato prima che il gateway effettui una chiamata alla destinazione configurata sul gateway. È possibile utilizzare l'interceptor REQUEST per eseguire convalide o autorizzazioni personalizzate.

Esempio di payload di input di Request Interceptor

L'esempio seguente mostra la struttura del payload di input ricevuta da una funzione Lambda di intercettazione delle richieste:


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

Nota

Il headers campo è incluso solo se passRequestHeaders è impostato su nella configurazione dell'intercettore. true Il gatewayResponse campo non è presente per gli intercettori di richieste poiché la risposta non è stata ancora generata.

Esempio di payload di output di Request Interceptor

L'esempio seguente mostra la struttura del payload di output che una funzione Lambda di intercettazione delle richieste dovrebbe restituire:


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

Importante

Note importanti sull'output del Request Interceptor: * Deve essere impostato su. interceptorOutputVersion "1.0" * Se l'output dell'intercettore contiene untransformedGatewayResponse, il gateway risponderà immediatamente con quel contenuto, anche se viene fornito anche. transformedGatewayRequest * Se entrambi gli intercettori REQUEST e RESPONSE sono configurati e l'output dell'intercettore REQUEST contiene untransformedGatewayResponse, l'intercettore RESPONSE verrà comunque richiamato.

Intercettori di risposta

L'intercettore RESPONSE viene richiamato prima che il gateway risponda al chiamante. È possibile utilizzare l'intercettore RESPONSE per eseguire eventuali redazioni o aggiunte personalizzate alla risposta del chiamante.

Esempio di payload di input di Response Interceptor

L'esempio seguente mostra la struttura del payload di input ricevuta da una funzione Lambda di intercettazione delle risposte:


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

Nota

Il headers campo in gatewayRequest è incluso solo se passRequestHeaders è impostato su nella configurazione dell'intercettore. true Gli intercettori di risposta ricevono sia la richiesta originale che la risposta del gateway, il che consente di modificare la risposta prima che venga restituita al chiamante.

Esempio di payload di output dell'intercettore di risposta

L'esempio seguente mostra la struttura del payload di output che una funzione Lambda di intercettazione delle risposte dovrebbe restituire:


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

Importante

Note importanti sull'output dell'intercettore di risposta: * Deve essere impostato su. interceptorOutputVersion "1.0" * Se l'output dell'intercettore contiene untransformedGatewayResponse, il gateway risponderà immediatamente con quel contenuto, anche se viene fornito anche. transformedGatewayRequest * Se entrambi gli intercettori REQUEST e RESPONSE sono configurati e l'output dell'intercettore REQUEST contiene untransformedGatewayResponse, l'intercettore RESPONSE verrà comunque richiamato.

Intercettori di risposta con streaming abilitato

Nota

Se lo streaming di risposta è abilitato sul gateway, la funzione Lambda dell'intercettore di risposta deve selezionare isStreamingResponse il campo per distinguere tra risposte gatewayResponse in streaming e non in streaming. Per le risposte in streaming, gestisci più chiamate per richiesta, una per evento idoneo, e tieni presente che solo la prima chiamata può sostituire e. headers statusCode

Quando lo streaming di risposte è abilitato sul gateway, il comportamento dell'intercettore di risposta cambia. L'intercettore viene richiamato più volte durante una risposta in streaming, una volta per evento idoneo, anziché una volta per la risposta completa.

Quando viene richiamato l'intercettore della risposta

L'intercettore di risposta viene richiamato per gli eventi che contengono un campo: JSON-RPC id

Primo evento: la prima JSON-RPC risposta o richiesta avviata dal server sullo stream (ad esempio, il risultato dello strumento o una richiesta/). elicitation/create sampling/createMessage
Eventi successivi: eventuali JSON-RPC risposte aggiuntive o richieste avviate dal server (ad esempio, il risultato finale dello strumento dopo il completamento di un'elicitazione).

L'intercettore di risposta non viene richiamato per:

notifications/progress— Gli aggiornamenti sullo stato di avanzamento vengono inoltrati direttamente al client.
notifications/message— I messaggi di registro vengono inoltrati direttamente al client.
Ping: i Keep-alive segnali vengono inoltrati direttamente al client.

Payload di ingresso dell'intercettore di risposta in streaming

Il payload di input include un nuovo campo impostato su. isStreamingResponse true Il gatewayResponse.body campo contiene il corpo dell'evento corrente.

Primo evento: l'intercettore riceveheaders, statusCode e: 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": {}
            }
        }
    }
  }
}

Eventi successivi: l'intercettore riceve solo body (le intestazioni e il codice di stato sono già stati inviati al 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"}]
            }
        }
    }
  }
}

Payload di uscita dell'intercettore di risposta in streaming

Ciò che l'intercettore può sovrascrivere dipende dal fatto che si tratti del primo o di un evento successivo:

Event	Può sovrascrivere	Ignorato se restituito
Primo evento	`headers`, `statusCode`, `body`	N/A
Eventi successivi	Solo `body`	`headers`, `statusCode` (già inviato al cliente)
Non-streaming (invariato)	`headers`, `statusCode`, `body`	N/A

Intercettori per destinazioni HTTP

Le destinazioni HTTP utilizzano una struttura di payload dell'intercettore diversa rispetto alle destinazioni MCP. I target HTTP (AgentCore Runtime e passthrough) e i target di inferenza utilizzano tutti questa struttura di payload. http L'inferenza è un tipo di destinazione separato che condivide la forma del payload dell'intercettore HTTP. Il payload utilizza una chiave anziché una http chiave. mcp I corpi di richiesta e risposta sono stringhe con codifica base64 anziché oggetti JSON analizzati.

Le destinazioni HTTP supportano gli intercettori REQUEST e RESPONSE in modalità bufferizzata, in cui il gateway memorizza nel buffer la risposta completa prima di richiamare l'intercettore di risposta. Gli intercettori non sono ancora supportati in modalità streaming.

L'elenco seguente riassume i comportamenti chiave degli intercettori di destinazione HTTP:

Il campo è di sola lettura. httpMethod
I body campi di richiesta e risposta sono stringhe con codifica base64.
Il headers campo è incluso nel payload della richiesta solo se passRequestHeaders è impostato su nella configurazione dell'intercettore. true
Se transformedGatewayResponse è presente nell'output di un intercettore REQUEST, il gateway restituisce immediatamente quella risposta senza chiamare il target (cortocircuito). L'intercettore RESPONSE non funziona dopo un cortocircuito.

Esempio di payload di input di Request Interceptor

L'esempio JSON seguente mostra la struttura del payload di input che la funzione Lambda di intercettazione delle richieste riceve durante l'elaborazione di una richiesta di destinazione 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>"
    }
  }
}

Nota

Nota quanto segue sul payload di input:

Il headers campo è incluso solo se passRequestHeaders è impostato su true nella configurazione dell'intercettore.
Il body campo è una stringa con codifica Base64 che rappresenta il corpo non elaborato della richiesta HTTP.
Il httpMethod campo è incluso a scopo informativo ma è di sola lettura. L'intercettore non può cambiarlo.

Esempio di payload di output di Request Interceptor

L'esempio JSON seguente mostra la struttura del payload di output che la funzione Lambda di intercettazione delle richieste deve restituire durante la trasformazione di una richiesta di destinazione 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>"
    }
  }
}

Importante

Note importanti sull'output dell'intercettore di richieste HTTP:

interceptorOutputVersionDeve essere impostato su. "1.0"
Se l'output contiene untransformedGatewayResponse, il gateway restituisce immediatamente quella risposta senza chiamare la destinazione.
Il body campo deve essere una stringa con codifica Base64.
Non httpMethod è incluso nell'output perché non può essere modificato.

Esempio di payload di input di Response Interceptor

Quando configuri un intercettore RESPONSE per una destinazione HTTP, il gateway memorizza nel buffer la risposta di destinazione e la passa alla funzione Lambda. Il seguente esempio JSON mostra la struttura del payload di input:


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

Nota

Nota quanto segue sul payload di input della risposta:

Il body campo è una stringa con codifica in base64 che rappresenta il corpo di risposta HTTP non elaborato.
Il body campo è null se si esclude il corpo della risposta con un filtro di payload. Per ulteriori informazioni, consulta Gestire payload di risposta di grandi dimensioni.

Esempio di payload in uscita da un intercettore di risposta

L'esempio JSON seguente mostra la struttura del payload di output restituito dalla funzione Lambda dell'intercettore di risposte quando si trasforma una risposta di destinazione HTTP:


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

Importante

Note importanti sull'output dell'intercettore di risposta HTTP:

interceptorOutputVersionDeve essere impostato su. "1.0"
I contentType campi statusCodebody, e sostituiscono ciascuno il valore di risposta originale. Se si omette un campo (o lo si imposta sunull), il gateway utilizza il valore originale.
Il body campo deve essere una stringa con codifica Base64.
Per passare la risposta invariata, restituisci un oggetto vuoto:. http {"interceptorOutputVersion": "1.0", "http": {}}

Gestisci payload di risposta di grandi dimensioni

La chiamata sincrona Lambda ha un limite di carico utile di 6 MB per la richiesta e la risposta combinate. Se un target restituisce un corpo di grandi dimensioni, cosa comune nei modelli di inferenza, il payload con codifica in base64 può superare questo limite e causare un errore.

Per evitare ciò, escludi il corpo della risposta dall'input dell'intercettore configurando un filtro di payload che escluda il campo. RESPONSE_BODY L'intercettore può comunque ispezionare ilstatusCode, e headers può inserire intestazioni o sovrascrivere il contentType codice di stato. Quando il corpo della risposta è escluso, il body campo nel payload di input è enull, se la funzione ritornabody: null, il gateway utilizza il corpo di risposta originale (non modificato).

Contesto del client

Per le destinazioni HTTP, il gateway passa i metadati della richiesta alla funzione Lambda attraverso il contesto client della chiamata. La tua funzione può leggere i seguenti valori personalizzati:GATEWAY_ARN,, eGATEWAY_ACCOUNT_ID. REQUEST_ID SOURCE_IP I REQUEST_ID valori GATEWAY_ARNGATEWAY_ACCOUNT_ID,, e sono sempre presenti. Il SOURCE_IP valore viene incluso solo quando è disponibile un IP di origine, pertanto la funzione deve considerarlo facoltativo.

Principali differenze tra i payload degli intercettori MCP e HTTP

La tabella seguente riassume le differenze tra i payload degli intercettori di destinazione MCP e HTTP.

Campo	Obiettivo MCP	Obiettivo HTTP
Formato del corpo	Mappa<String, Object> (JSON analizzato)	Stringa (codificata in base 64)
Path	Sempre «/mcp»	Percorso HTTP effettivo (ad esempio, «/my-target- «) name/invocations
httpMethod	Non modificabile	Non modificabile
crudo GatewayRequest	Incluso	Non incluso
intercettore di risposta	Supportata	Supportato in modalità bufferizzata (non ancora supportato in modalità streaming)

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Autorizzazioni per gli intercettori

Configurazione