Minta pencegat Pencegat respons Pencegat respons dengan streaming diaktifkan Pencegat untuk target HTTP

Jenis pencegat

Ada dua jenis pencegat yang dapat Anda konfigurasi pada gateway Anda: REQUEST interceptors dan RESPONSE interceptors. Struktur muatan pencegat bergantung pada jenis target yang dikonfigurasi pada gateway Anda.

Topik ini mencakup kontrak pencegat untuk target MCP dan target HTTP (seperti Amazon Bedrock AgentCore Runtime).

Minta pencegat

Pencegat REQUEST dipanggil sebelum gateway melakukan panggilan ke target yang dikonfigurasi di gateway. Anda dapat menggunakan pencegat REQUEST untuk melakukan validasi kustom atau otorisasi.

Minta contoh muatan masukan pencegat

Contoh berikut menunjukkan struktur muatan masukan yang diterima fungsi Lambda pencegat permintaan:


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

catatan

headersBidang ini hanya disertakan jika passRequestHeaders diatur ke true dalam konfigurasi pencegat. gatewayResponseBidang tidak ada untuk pencegat permintaan karena respons belum dihasilkan.

Minta contoh muatan keluaran pencegat

Contoh berikut menunjukkan struktur payload keluaran yang harus dikembalikan oleh fungsi Lambda pencegat permintaan:


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

penting

Catatan penting tentang output pencegat permintaan: * interceptorOutputVersion Harus diatur ke. "1.0" * Jika output pencegat berisi atransformedGatewayResponse, gateway akan segera merespons dengan konten itu, bahkan jika juga transformedGatewayRequest disediakan. * Jika pencegat REQUEST dan RESPONSE dikonfigurasi dan output pencegat REQUEST berisi atransformedGatewayResponse, pencegat RESPONSE akan tetap dipanggil.

Pencegat respons

Pencegat RESPONSE dipanggil sebelum gateway merespons pemanggil. Anda dapat menggunakan pencegat RESPONSE untuk melakukan redaksi kustom atau penambahan respons kembali ke pemanggil.

Contoh muatan masukan pencegat respons

Contoh berikut menunjukkan struktur muatan masukan yang diterima oleh fungsi Lambda pencegat respons:


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

catatan

headersBidang di gatewayRequest hanya disertakan jika passRequestHeaders diatur ke true dalam konfigurasi pencegat. Pencegat respons menerima permintaan asli dan respons gateway, memungkinkan Anda memodifikasi respons sebelum dikembalikan ke pemanggil.

Contoh muatan keluaran pencegat respons

Contoh berikut menunjukkan struktur payload keluaran yang harus dikembalikan oleh fungsi Lambda pencegat respons:


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

penting

Catatan penting tentang keluaran pencegat respons: * interceptorOutputVersion Harus diatur ke. "1.0" * Jika output pencegat berisi atransformedGatewayResponse, gateway akan segera merespons dengan konten itu, bahkan jika juga transformedGatewayRequest disediakan. * Jika pencegat REQUEST dan RESPONSE dikonfigurasi dan output pencegat REQUEST berisi atransformedGatewayResponse, pencegat RESPONSE akan tetap dipanggil.

Pencegat respons dengan streaming diaktifkan

catatan

Jika streaming respons diaktifkan di gateway Anda, fungsi Lambda pencegat respons Anda harus memeriksa isStreamingResponse bidang gatewayResponse untuk membedakan antara respons streaming dan non-streaming. Untuk tanggapan streaming, tangani beberapa pemanggilan per permintaan — satu per acara yang memenuhi syarat — dan perhatikan bahwa hanya pemanggilan pertama yang dapat mengganti dan. headers statusCode

Saat streaming respons diaktifkan di gateway Anda, perilaku pencegat respons berubah. Pencegat dipanggil beberapa kali selama respons streaming - sekali per acara yang memenuhi syarat - bukan sekali dengan respons lengkap.

Ketika pencegat respons dipanggil

Pencegat respons dipanggil untuk peristiwa yang berisi bidang: JSON-RPC id

Peristiwa pertama — JSON-RPC Respons pertama atau permintaan yang dimulai server pada aliran (misalnya, hasil alat, atau permintaan/). elicitation/create sampling/createMessage
Peristiwa selanjutnya - Setiap JSON-RPC tanggapan tambahan atau permintaan yang dimulai server (misalnya, hasil alat akhir setelah elisitasi dipenuhi).

Pencegat respons tidak dipanggil untuk:

notifications/progress— Pembaruan kemajuan diteruskan langsung ke klien.
notifications/message— Pesan log diteruskan langsung ke klien.
Ping — Keep-alive sinyal diteruskan langsung ke klien.

Muatan masukan pencegat respons streaming

Muatan masukan mencakup isStreamingResponse bidang baru yang disetel ketrue. gatewayResponse.bodyBidang berisi badan peristiwa saat ini.

Peristiwa pertama — Pencegat menerimaheaders,statusCode, dan: 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": {}
            }
        }
    }
  }
}

Peristiwa selanjutnya — Pencegat hanya menerima body (header dan kode status telah dikirim ke klien):


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

Muatan keluaran pencegat respons streaming

Apa yang dapat diganti pencegat tergantung pada apakah itu peristiwa pertama atau selanjutnya:

Peristiwa	Dapat mengesampingkan	Diabaikan jika dikembalikan
Acara pertama	`headers`, `statusCode`, `body`	N/A
Peristiwa selanjutnya	`body`hanya	`headers`, `statusCode` (sudah dikirim ke klien)
Non-streaming (tidak berubah)	`headers`, `statusCode`, `body`	N/A

Pencegat untuk target HTTP

Target HTTP menggunakan struktur muatan pencegat yang berbeda dari target MCP. Target HTTP (AgentCore Runtime dan passthrough) dan target inferensi semuanya menggunakan struktur payload inihttp. Inferensi adalah jenis target terpisah yang kebetulan berbagi bentuk payload pencegat HTTP. Muatan menggunakan http kunci, bukan mcp kunci. Badan permintaan dan respons adalah string yang dikodekan base64 daripada objek JSON yang diurai.

Target HTTP mendukung pencegat REQUEST dan RESPONSE dalam mode buffer, di mana gateway menyangga respons penuh sebelum memanggil pencegat respons. Pencegat belum didukung dalam mode streaming.

Daftar berikut merangkum perilaku utama untuk pencegat target HTTP:

httpMethodBidang ini hanya-baca.
bodyBidang permintaan dan respons adalah string yang dikodekan base64.
headersBidang disertakan dalam payload permintaan hanya jika passRequestHeaders diatur ke true dalam konfigurasi pencegat.
Jika transformedGatewayResponse ada dalam output pencegat REQUEST, gateway mengembalikan respons itu segera tanpa memanggil target (hubung singkat). Pencegat RESPONSE tidak berjalan setelah korsleting.

Minta contoh muatan masukan pencegat

Contoh JSON berikut menunjukkan struktur payload input yang diterima fungsi Lambda pencegat permintaan permintaan Anda saat memproses permintaan target 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>"
    }
  }
}

catatan

Perhatikan hal berikut tentang muatan masukan:

headersBidang disertakan hanya jika passRequestHeaders diatur ke true dalam konfigurasi pencegat.
bodyBidang ini adalah string berenkode base64 yang mewakili badan permintaan HTTP mentah.
httpMethodBidang ini disertakan untuk tujuan informasi tetapi hanya-baca. Pencegat tidak dapat mengubahnya.

Minta contoh muatan keluaran pencegat

Contoh JSON berikut menunjukkan struktur muatan keluaran yang harus dikembalikan oleh fungsi Lambda pencegat permintaan permintaan Anda saat mengubah permintaan target 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>"
    }
  }
}

penting

Catatan penting tentang output pencegat permintaan HTTP:

interceptorOutputVersionHarus diatur ke"1.0".
Jika output berisi atransformedGatewayResponse, gateway mengembalikan respons itu segera tanpa memanggil target.
bodyBidang harus berupa string yang dikodekan base64.
httpMethodTidak termasuk dalam output karena tidak dapat dimodifikasi.

Contoh muatan masukan pencegat respons

Saat Anda mengonfigurasi pencegat RESPONSE untuk target HTTP, gateway menyangga respons target dan meneruskannya ke fungsi Lambda Anda. Contoh JSON berikut menunjukkan struktur payload masukan:


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

catatan

Perhatikan hal berikut tentang payload masukan respons:

bodyBidang ini adalah string berenkode base64 yang mewakili badan respons HTTP mentah.
bodyBidangnya adalah null jika Anda mengecualikan badan respons dengan filter muatan. Untuk informasi selengkapnya, lihat Menangani muatan respons besar.

Contoh muatan keluaran pencegat respons

Contoh JSON berikut menunjukkan struktur payload keluaran yang ditampilkan oleh fungsi Lambda pencegat respons Anda saat mengubah respons target HTTP:


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

penting

Catatan penting tentang keluaran pencegat respons HTTP:

interceptorOutputVersionHarus diatur ke"1.0".
contentTypeBidang statusCodebody,, dan masing-masing mengganti nilai respons asli. Jika Anda menghilangkan bidang (atau menyetelnya kenull), gateway menggunakan nilai asli.
bodyBidang harus berupa string yang dikodekan base64.
Untuk meneruskan respons melalui tidak berubah, kembalikan http objek kosong:{"interceptorOutputVersion": "1.0", "http": {}}.

Menangani muatan respons yang besar

Pemanggilan sinkron Lambda memiliki batas muatan 6 MB untuk gabungan permintaan dan respons. Jika target mengembalikan tubuh besar — yang umum dengan model inferensi — muatan yang dikodekan base64 dapat melebihi batas ini dan menyebabkan kesalahan.

Untuk menghindari hal ini, kecualikan badan respons dari input pencegat dengan mengonfigurasi filter muatan yang mengecualikan bidang. RESPONSE_BODY Pencegat Anda masih dapat memeriksa,, dan statusCode contentTypeheaders, dan dapat menyuntikkan header atau mengganti kode status. Ketika badan respons dikecualikan, body bidang dalam muatan input adalahnull, dan jika fungsi Anda kembalibody: null, gateway menggunakan badan respons asli (tidak dimodifikasi).

Konteks klien

Untuk target HTTP, gateway meneruskan metadata permintaan ke fungsi Lambda Anda melalui konteks klien pemanggilan. Fungsi Anda dapat membaca nilai kustom berikut:GATEWAY_ARN,GATEWAY_ACCOUNT_ID,REQUEST_ID, danSOURCE_IP. REQUEST_IDNilai GATEWAY_ARNGATEWAY_ACCOUNT_ID,, dan selalu ada. SOURCE_IPNilai disertakan hanya ketika IP sumber tersedia, jadi fungsi Anda harus memperlakukannya sebagai opsional.

Perbedaan utama antara muatan pencegat MCP dan HTTP

Tabel berikut merangkum perbedaan antara muatan pencegat target MCP dan HTTP.

Bidang	Sasaran MCP	Target HTTP
Format tubuh	Peta<String, Object> (diurai JSON)	String (dikodekan base64)
Jalan	Selalu “/mcp”	Jalur HTTP aktual (misalnya, “/my-target- “) name/invocations
httpMethod	Tetap	Tetap
mentah GatewayRequest	Termasuk	Tidak termasuk
Pencegat respons	Didukung	Didukung dalam mode buffer (belum didukung dalam mode streaming)

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Izin untuk pencegat

Konfigurasi