View a markdown version of this page

Gunakan sampling dengan gateway Anda AgentCore - Batuan Dasar Amazon AgentCore

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.enableResponseStreaming ke true dalam 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. initialize Gateway 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

  1. Klien mengirimkan tools/call permintaan dengan Mcp-Session-Id header.

  2. Gateway meneruskan panggilan alat ke target server MCP.

  3. Target membuka aliran SSE dan mengirimkan sampling/createMessage permintaan.

  4. Gateway meneruskan permintaan sampling ke klien sebagai peristiwa SSE, menggantikan permintaan. id

  5. Klien memanggil model bahasanya dengan pesan yang disediakan.

  6. Klien mengirimkan permintaan baru dengan hasil sampling menggunakan permintaan yang sama Mcp-Session-Id dan id dari gateway.

  7. Gateway meneruskan hasil ke target server MCP.

  8. Target terus memproses dan mengembalikan hasil alat akhir.

  9. 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 -32600(Permintaan Tidak Valid)

Tidak ditemukan permintaan sampling yang cocok untuk sesi ini.

Klien mengirimkan respons sampling dengan id yang tidak cocok dengan permintaan yang tertunda

JSON-RPC -32600(Permintaan Tidak Valid)

idHarus cocok dengan yang dikirim oleh gateway dalam sampling/createMessage permintaan.

Server MCP mengirimkan permintaan sampling tetapi gateway tidak mendeklarasikan dukungan

JSON-RPC -32601(Metode tidak ditemukan)

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_id dalam create_message panggilan 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.

contoh
Python requests package
  1. import requests import json import sseclient gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" headers = { "Content-Type": "application/json", "Accept": "text/event-stream", "Authorization": "Bearer YOUR_ACCESS_TOKEN" } # Step 1: Initialize with sampling capability init_response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "init-request", "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {"sampling": {}}, "clientInfo": {"name": "my-agent", "version": "1.0.0"} } }) session_id = init_response.headers["Mcp-Session-Id"] headers["Mcp-Session-Id"] = session_id # Step 2: Call tool (streaming response) response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "summarizeDocument", "arguments": {"documentId": "doc-789"} } }, stream=True) # Step 3: Process SSE events client = sseclient.SSEClient(response) for event in client.events(): data = json.loads(event.data) if data.get("method") == "sampling/createMessage": sampling_id = data["id"] print(f"Sampling request: {data['params']['messages']}") # Step 4: Invoke your LLM and send result llm_result = invoke_your_model(data["params"]) # Your LLM invocation requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": sampling_id, "result": { "model": "claude-sonnet-4-20250514", "role": "assistant", "content": {"type": "text", "text": llm_result} } }) elif "result" in data: print(f"Tool result: {data['result']}") break
MCP Client
  1. from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client import asyncio async def sampling_handler(request): """Handle sampling requests from the server by invoking an LLM.""" messages = request.params.messages llm_response = await invoke_your_model(messages, max_tokens=request.params.maxTokens) return { "model": "claude-sonnet-4-20250514", "role": "assistant", "content": {"type": "text", "text": llm_response} } async def use_sampling(url, token): headers = {"Authorization": f"Bearer {token}"} async with streamablehttp_client(url=url, headers=headers) as ( read_stream, write_stream, _ ): async with ClientSession( read_stream, write_stream, sampling_handler=sampling_handler ) as session: await session.initialize() result = await session.call_tool( name="summarizeDocument", arguments={"documentId": "doc-789"} ) print(f"Tool result: {result}") return result asyncio.run(use_sampling( url="https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", token="YOUR_ACCESS_TOKEN" ))