# 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](gateway-sessions.md).
+ **Streaming respons diaktifkan** - Permintaan pengambilan sampel dikirim sebagai potongan SSE selama koneksi terbuka. Setel `streamingConfiguration.enableResponseStreaming` ke `true` dalam gateway Anda`protocolConfiguration.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:
+ `model`Model yang digunakan.
+ `role`— Selalu`assistant`.
+ `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.
1. Gateway meneruskan panggilan alat ke target server MCP.
1. Target membuka aliran SSE dan mengirimkan `sampling/createMessage` permintaan.
1. Gateway meneruskan permintaan sampling ke klien sebagai peristiwa SSE, menggantikan permintaan. `id`
1. Klien memanggil model bahasanya dengan pesan yang disediakan.
1. Klien mengirimkan permintaan baru dengan hasil sampling menggunakan permintaan yang sama `Mcp-Session-Id` dan `id` dari gateway.
1. Gateway meneruskan hasil ke target server MCP.
1. Target terus memproses dan mengembalikan hasil alat akhir.
1. 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) | `id`Harus 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](#gateway-mcp-sampling-troubleshooting). |
## 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.
**Example**
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
```
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"
))
```