Gunakan sampling dengan gateway Anda AgentCore
Sampling adalah fitur MCP yang memungkinkan server MCP untuk meminta penyelesaian LLM dari klien selama panggilan alat. Ini memungkinkan server untuk memanfaatkan kemampuan AI tanpa memerlukan akses langsung ke model bahasa — klien menangani pemanggilan model dan mengembalikan hasilnya. AgentCore Gateway meneruskan permintaan sampling dari target server MCP ke klien Anda, menggantikan permintaan id dengan pengenal yang dihasilkan gateway.
Prasyarat
Untuk menggunakan sampling dengan gateway Anda:
-
Sesi diaktifkan - Pengambilan sampel membutuhkan dukungan sesi. Lihat Menggunakan sesi MCP dengan gateway Anda.
-
Streaming respons diaktifkan - Permintaan pengambilan sampel dikirim sebagai potongan SSE selama koneksi terbuka. Setel
streamingConfiguration.enableResponseStreamingketruedalam gateway AndaprotocolConfiguration.mcp. -
Jenis target server MCP — Permintaan pengambilan sampel berasal dari target server MCP.
-
Klien menyatakan kemampuan pengambilan sampel - Klien harus menyatakan dukungan untuk pengambilan sampel selama permintaan.
initializeGateway hanya meneruskan permintaan sampling ke klien yang menyatakan kemampuan ini.
Cara kerja sampling
Ketika target server MCP membutuhkan penyelesaian LLM selama eksekusi alat, ia mengirimkan permintaan. sampling/createMessage Gateway meneruskan permintaan ini ke klien sebagai acara SSE, menggantikan permintaan. id Klien memanggil model bahasanya dan mengirimkan hasilnya kembali ke gateway, yang meneruskannya ke target.
Permintaan pengambilan sampel meliputi:
-
messages— Pesan percakapan untuk dikirim ke model. -
modelPreferences— Petunjuk opsional tentang kemampuan model yang diinginkan (kecerdasan, kecepatan, biaya). -
systemPrompt— Prompt sistem opsional untuk model. -
maxTokens— Jumlah maksimum token untuk dihasilkan.
Klien merespons dengan:
-
modelModel yang digunakan. -
role— Selaluassistant. -
content— Konten yang dihasilkan (teks atau gambar).
catatan
Klien memiliki kontrol penuh atas model mana yang akan digunakan dan bagaimana menangani permintaan. Server modelPreferences adalah petunjuk, bukan persyaratan. Klien juga dapat memodifikasi atau menolak permintaan berdasarkan kebijakannya sendiri.
Aliran pengambilan sampel
-
Klien mengirimkan
tools/callpermintaan denganMcp-Session-Idheader. -
Gateway meneruskan panggilan alat ke target server MCP.
-
Target membuka aliran SSE dan mengirimkan
sampling/createMessagepermintaan. -
Gateway meneruskan permintaan sampling ke klien sebagai peristiwa SSE, menggantikan permintaan.
id -
Klien memanggil model bahasanya dengan pesan yang disediakan.
-
Klien mengirimkan permintaan baru dengan hasil sampling menggunakan permintaan yang sama
Mcp-Session-Iddaniddari gateway. -
Gateway meneruskan hasil ke target server MCP.
-
Target terus memproses dan mengembalikan hasil alat akhir.
-
Gateway meneruskan hasil akhir ke klien dan menutup aliran.
Panduan untuk pengembang target server MCP
penting
Target server MCP yang mengirim permintaan sampling harus membungkus panggilan sampling dalam blok try-catch dan menangani kasus di mana klien tidak mendukung pengambilan sampel. Jika klien gateway tidak mendeklarasikan kemampuan sampling, gateway tidak mendeklarasikannya ke target. Jika target tetap mengirimkan permintaan sampling, gateway mengembalikan kesalahan -32601 (Metode tidak ditemukan) ke target.
Server harus menerapkan jalur fallback (seperti menggunakan model bawaan atau melewatkan AI-assisted langkah) saat pengambilan sampel tidak tersedia.
Penanganan kesalahan
| Skenario | Kesalahan | Deskripsi |
|---|---|---|
|
Klien mengirimkan respons sampling ketika tidak ada permintaan sampling yang tertunda |
JSON-RPC |
Tidak ditemukan permintaan sampling yang cocok untuk sesi ini. |
|
Klien mengirimkan respons sampling dengan |
JSON-RPC |
|
|
Server MCP mengirimkan permintaan sampling tetapi gateway tidak mendeklarasikan dukungan |
JSON-RPC |
Kembali ke target server MCP. Lihat Pemecahan Masalah. |
Pemecahan masalah
Kesalahan: “Kesalahan memanggil alat 'sample_tool': Metode tidak ditemukan:" sampling/createMessage
Kesalahan ini terjadi ketika target server MCP mengirimkan permintaan sampling tetapi klien gateway tidak mendeklarasikan kemampuan sampling selama. initialize Gateway mengembalikan kesalahan -32601 (Metode tidak ditemukan) ke target, dan target dapat mengembalikan ini sebagai kesalahan eksekusi alat ke klien.
Untuk menyelesaikan:
-
Jika Anda adalah pengembang server MCP: Tambahkan penanganan kesalahan di sekitar panggilan pengambilan sampel Anda. Menerapkan jalur fallback saat pengambilan sampel tidak didukung:
penting
Anda harus memasukkan
related_request_id=ctx.request_context.request_iddalamcreate_messagepanggilan Anda. Ini diperlukan agar gateway mengaitkan permintaan pengambilan sampel dengan benar dengan panggilan alat asal. Tanpa itu, pengambilan sampel tidak akan berfungsi.try: result = await ctx.session.create_message( messages=[{"role": "user", "content": {"type": "text", "text": "Summarize this document"}}], max_tokens=500, related_request_id=ctx.request_context.request_id, ) except Exception as e: # Fallback when client doesn't support sampling logger.warning(f"Sampling not supported: {e}") result = fallback_summarization(document) -
Jika Anda adalah pengembang klien gateway: Pastikan klien Anda mendeklarasikan kemampuan pengambilan sampel selama:
initialize{ "capabilities": { "sampling": {} } }
Sampel Kode
catatan
Klien LangGraph MCP (langchain-mcp-adapters) dan Klien MCP Strands saat ini tidak mendukung pengambilan sampel. Gunakan pendekatan Klien MCP yang ditunjukkan di bawah ini untuk menangani permintaan pengambilan sampel dari gateway Anda.