# Verwenden Sie Sampling mit Ihrem AgentCore Gateway
Sampling ist eine MCP-Funktion, die es einem MCP-Server ermöglicht, während eines Tool-Aufrufs vom Client eine LLM-Fertigstellung anzufordern. Dadurch können Server KI-Funktionen nutzen, ohne direkten Zugriff auf ein Sprachmodell zu benötigen — der Client verarbeitet den Modellaufruf und gibt das Ergebnis zurück. AgentCore Gateway leitet Sampling-Anfragen von MCP-Serverzielen an Ihre Clients weiter und ersetzt die Anfrage durch eine vom Gateway `id` generierte Kennung.
## Voraussetzungen
So verwenden Sie Sampling mit Ihrem Gateway:
+ **Sitzungen aktiviert** — Für das Sampling ist Sitzungsunterstützung erforderlich. Weitere Informationen finden [Sie unter Verwenden von MCP-Sitzungen mit Ihrem Gateway](gateway-sessions.md).
+ **Antwort-Streaming aktiviert** — Sampling-Anfragen werden während einer offenen Verbindung als SSE-Chunks gesendet. `true`In `streamingConfiguration.enableResponseStreaming` Ihren Gateways auf eingestellt. `protocolConfiguration.mcp`
+ **MCP-Serverzieltyp** — Sampling-Anfragen stammen von MCP-Serverzielen.
+ **Der Client gibt die Sampling-Fähigkeit** an — Der Client muss während der Anfrage angeben, dass er Sampling unterstützt. `initialize` Das Gateway leitet Sampling-Anfragen nur an Clients weiter, die diese Fähigkeit deklariert haben.
## Wie funktioniert Sampling
Wenn ein MCP-Serverziel während der Ausführung des Tools einen LLM-Abschluss benötigt, sendet es eine `sampling/createMessage` Anfrage. Das Gateway leitet diese Anfrage als SSE-Ereignis an den Client weiter und ersetzt so die Anfrage. `id` Der Client ruft sein Sprachmodell auf und sendet das Ergebnis zurück an das Gateway, das es an das Ziel weiterleitet.
Die Sampling-Anfrage beinhaltet:
+ `messages`— Die Konversationsnachrichten, die an das Modell gesendet werden sollen.
+ `modelPreferences`— Optionale Hinweise zu den gewünschten Modellfunktionen (Intelligenz, Geschwindigkeit, Kosten).
+ `systemPrompt`— Optionale Systemaufforderung für das Modell.
+ `maxTokens`— Maximale Anzahl der zu generierenden Token.
Der Kunde antwortet mit:
+ `model`— Das Modell, das verwendet wurde.
+ `role`— Immer`assistant`.
+ `content`— Der generierte Inhalt (Text oder Bild).
**Anmerkung**
Der Kunde hat die volle Kontrolle darüber, welches Modell verwendet werden soll und wie mit der Anfrage umgegangen werden soll. Bei den Servern `modelPreferences` handelt es sich um Hinweise, nicht um Anforderungen. Der Client kann die Anfrage auch auf der Grundlage seiner eigenen Richtlinien ändern oder ablehnen.
## Ablauf der Probenahme
1. Der Client sendet eine `tools/call` Anfrage mit dem `Mcp-Session-Id` Header.
1. Das Gateway leitet den Tool-Aufruf an das MCP-Serverziel weiter.
1. Das Ziel öffnet einen SSE-Stream und sendet eine `sampling/createMessage` Anfrage.
1. Gateway leitet die Sampling-Anfrage als SSE-Ereignis an den Client weiter und ersetzt so die Anfrage`id`.
1. Der Client ruft sein Sprachmodell mit den bereitgestellten Nachrichten auf.
1. Der Client sendet eine neue Anfrage mit dem Sampling-Ergebnis unter Verwendung derselben `Mcp-Session-Id` und `id` der Anfrage des Gateways.
1. Das Gateway leitet das Ergebnis an das MCP-Serverziel weiter.
1. Das Ziel setzt die Verarbeitung fort und gibt das endgültige Werkzeugergebnis zurück.
1. Gateway leitet das Endergebnis an den Client weiter und schließt den Stream.
## Anleitung für Entwickler von MCP-Servern
**Wichtig**
MCP-Serverziele, die Sampling-Anfragen senden, **sollten** Sampling-Aufrufe in Try-Catch-Blöcke packen und den Fall behandeln, dass der Client Sampling nicht unterstützt. Wenn der Client des Gateways keine Sampling-Fähigkeit deklariert hat, deklariert das Gateway diese auch nicht gegenüber dem Ziel. Wenn das Ziel trotzdem eine Sampling-Anfrage sendet, gibt das Gateway einen Fehler `-32601` (Methode nicht gefunden) an das Ziel zurück.
Server sollten einen Fallback-Pfad implementieren (z. B. ein integriertes Modell verwenden oder den AI-assisted Schritt überspringen), wenn Sampling nicht verfügbar ist.
## Fehlerbehandlung
| Szenario | Fehler | Description |
| --- | --- | --- |
| Der Client sendet eine Sampling-Antwort, wenn keine Sampling-Anfrage aussteht | JSON-RPC `-32600`(Ungültige Anfrage) | Für diese Sitzung wurde keine passende Sampling-Anfrage gefunden. |
| Der Client sendet eine Stichprobenantwort mit einer`id`, die keiner ausstehenden Anfrage entspricht | JSON-RPC `-32600`(Ungültige Anfrage) | Die `id` muss mit der vom Gateway in der `sampling/createMessage` Anfrage gesendeten übereinstimmen. |
| Der MCP-Server sendet eine Sampling-Anfrage, aber das Gateway hat keine Unterstützung deklariert | JSON-RPC `-32601`(Methode nicht gefunden) | Zum MCP-Serverziel zurückgekehrt. Siehe [Problembehandlung](#gateway-mcp-sampling-troubleshooting). |
## Fehlerbehebung
**Fehler: „Fehler beim Aufrufen des Tools 'sample\_tool': Methode nicht gefunden:" sampling/createMessage**
Dieser Fehler tritt auf, wenn ein MCP-Serverziel eine Sampling-Anfrage sendet, der Client des Gateways jedoch währenddessen keine Sampling-Funktion deklariert hat. `initialize` Das Gateway gibt einen Fehler `-32601` (Methode nicht gefunden) an das Ziel zurück, und das Ziel gibt dies möglicherweise als Fehler bei der Ausführung des Tools an den Client zurück.
Um dies zu lösen:
+ **Wenn Sie der MCP-Serverentwickler sind**: Fügen Sie eine Fehlerbehandlung zu Ihren Sampling-Aufrufen hinzu. Implementieren Sie einen Fallback-Pfad, wenn Sampling nicht unterstützt wird:
**Wichtig**
Sie **müssen** `related_request_id=ctx.request_context.request_id` in Ihrem `create_message` Anruf Folgendes angeben. Dies ist erforderlich, damit das Gateway die Sampling-Anfrage korrekt dem ursprünglichen Tool-Aufruf zuordnen kann. Ohne sie funktioniert die Probennahme nicht.
```
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)
```
+ **Wenn Sie der Gateway-Client-Entwickler sind**: Stellen Sie sicher, dass Ihr Kunde die Sampling-Funktion für folgende Fälle deklariert: `initialize`
```
{
"capabilities": {
"sampling": {}
}
}
```
## Codebeispiele
**Anmerkung**
Der LangGraph MCP Client (`langchain-mcp-adapters`) und der Strands MCP Client unterstützen derzeit kein Sampling. Verwenden Sie den unten gezeigten MCP Client-Ansatz, um Sampling-Anfragen von Ihrem Gateway aus zu bearbeiten.
**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"
))
```