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.

• Antwort-Streaming aktiviert — Sampling-Anfragen werden während einer offenen Verbindung als SSE-Chunks gesendet. trueIn 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— Immerassistant.

• 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.

2. Das Gateway leitet den Tool-Aufruf an das MCP-Serverziel weiter.

3. Das Ziel öffnet einen SSE-Stream und sendet eine sampling/createMessage Anfrage.

4. Gateway leitet die Sampling-Anfrage als SSE-Ereignis an den Client weiter und ersetzt so die Anfrageid.

5. Der Client ruft sein Sprachmodell mit den bereitgestellten Nachrichten auf.

6. Der Client sendet eine neue Anfrage mit dem Sampling-Ergebnis unter Verwendung derselben Mcp-Session-Id und id der Anfrage des Gateways.

7. Das Gateway leitet das Ergebnis an das MCP-Serverziel weiter.

8. Das Ziel setzt die Verarbeitung fort und gibt das endgültige Werkzeugergebnis zurück.

9. 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 einerid, 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.

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.

Beispiel

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"
   ))