View a markdown version of this page

Utilisez l'échantillonnage avec votre AgentCore passerelle - Amazon Bedrock AgentCore
Conditions préalablesComment fonctionne l'échantillonnageDébit d'échantillonnageConseils pour les développeurs cibles de serveurs MCPGestion des erreursRésolution des problèmesExemples de code

Utilisez l'échantillonnage avec votre AgentCore passerelle

L'échantillonnage est une fonctionnalité MCP qui permet à un serveur MCP de demander au client de terminer un LLM lors d'un appel d'outil. Cela permet aux serveurs de tirer parti des capacités de l'IA sans avoir besoin d'un accès direct à un modèle de langage : le client gère l'invocation du modèle et renvoie le résultat. AgentCore Gateway transmet les demandes d'échantillonnage des cibles du serveur MCP à vos clients, en remplaçant la demande par un identifiant id généré par la passerelle.

Conditions préalables

Pour utiliser l'échantillonnage avec votre passerelle :

  • Sessions activées : l'échantillonnage nécessite un support de session. Consultez la section Utiliser des sessions MCP avec votre passerelle.

  • Streaming de réponses activé — Les demandes d'échantillonnage sont envoyées sous forme de fragments SSE lors d'une connexion ouverte. streamingConfiguration.enableResponseStreamingRéglez sur true celui de votre passerelleprotocolConfiguration.mcp.

  • Type de cible du serveur MCP : les demandes d'échantillonnage proviennent des cibles du serveur MCP.

  • Le client déclare la capacité d'échantillonnage — Le client doit déclarer son soutien à l'échantillonnage lors de la initialize demande. La passerelle transmet uniquement les demandes d'échantillonnage aux clients qui ont déclaré cette fonctionnalité.

Comment fonctionne l'échantillonnage

Lorsqu'une cible de serveur MCP doit terminer un LLM pendant l'exécution de l'outil, elle envoie une sampling/createMessage demande. La passerelle transmet cette demande au client en tant qu'événement SSE, en remplacement de la demandeid. Le client invoque son modèle de langage et renvoie le résultat à la passerelle, qui le transmet à la cible.

La demande d'échantillonnage inclut :

  • messages— Les messages de conversation à envoyer au modèle.

  • modelPreferences— Indications facultatives concernant les capacités souhaitées du modèle (intelligence, vitesse, coût).

  • systemPrompt— Invite système optionnelle pour le modèle.

  • maxTokens— Nombre maximum de jetons à générer.

Le client répond par :

  • model— Le modèle utilisé.

  • role— Toujoursassistant.

  • content— Le contenu généré (texte ou image).

Note

Le client a le contrôle total du modèle à utiliser et de la manière de traiter la demande. Les serveurs modelPreferences sont des conseils, pas des exigences. Le client peut également modifier ou rejeter la demande en fonction de ses propres politiques.

Débit d'échantillonnage

  1. Le client envoie une tools/call demande avec l'Mcp-Session-Iden-tête.

  2. Gateway transmet l'appel d'outil à la cible du serveur MCP.

  3. La cible ouvre un flux SSE et envoie une sampling/createMessage demande.

  4. Gateway transmet la demande d'échantillonnage au client en tant qu'événement SSE, en remplacement de la demandeid.

  5. Le client invoque son modèle de langage avec les messages fournis.

  6. Le client envoie une nouvelle demande avec le résultat de l'échantillonnage en utilisant la même demande Mcp-Session-Id et celle id de la passerelle.

  7. Gateway transmet le résultat à la cible du serveur MCP.

  8. La cible poursuit le traitement et renvoie le résultat final de l'outil.

  9. Gateway transmet le résultat final au client et ferme le flux.

Conseils pour les développeurs cibles de serveurs MCP

Important

Les cibles du serveur MCP qui envoient des demandes d'échantillonnage doivent encapsuler les appels d'échantillonnage dans des blocs try-catch et gérer le cas où le client ne prend pas en charge l'échantillonnage. Si le client de la passerelle n'a pas déclaré de capacité d'échantillonnage, la passerelle ne la déclare pas à la cible. Si la cible envoie quand même une demande d'échantillonnage, la passerelle renvoie une erreur -32601 (méthode introuvable) à la cible.

Les serveurs doivent implémenter un chemin de secours (par exemple en utilisant un modèle intégré ou en sautant l' AI-assisted étape) lorsque l'échantillonnage n'est pas disponible.

Gestion des erreurs

Scénario Erreur Description

Le client envoie une réponse d'échantillonnage lorsqu'aucune demande d'échantillonnage n'est en attente

JSON-RPC -32600(Demande non valide)

Aucune demande d'échantillonnage correspondante n'a été trouvée pour cette session.

Le client envoie un échantillon de réponse avec un id qui ne correspond pas à une demande en attente

JSON-RPC -32600(Demande non valide)

Le id doit correspondre à celui envoyé par la passerelle dans la sampling/createMessage demande.

Le serveur MCP envoie une demande d'échantillonnage mais la passerelle n'a pas déclaré le support

JSON-RPC -32601(Méthode introuvable)

Retourné à la cible du serveur MCP. Voir Résolution des problèmes.

Résolution des problèmes

Erreur : « Erreur lors de l'appel de l'outil 'sample_tool' : méthode introuvable : » sampling/createMessage

Cette erreur se produit lorsqu'une cible de serveur MCP envoie une demande d'échantillonnage mais que le client de la passerelle n'a pas déclaré de capacité d'échantillonnage pendant cette périodeinitialize. La passerelle renvoie une erreur -32601 (méthode introuvable) à la cible, et la cible peut la renvoyer sous forme d'erreur d'exécution de l'outil au client.

Pour résoudre le problème :

  • Si vous êtes le développeur du serveur MCP : ajoutez la gestion des erreurs à vos appels d'échantillonnage. Implémentez un chemin de secours lorsque l'échantillonnage n'est pas pris en charge :

    Important

    Vous devez l'inclure related_request_id=ctx.request_context.request_id dans votre create_message appel. Cela est nécessaire pour que la passerelle associe correctement la demande d'échantillonnage à l'appel d'outil d'origine. Sans cela, l'échantillonnage ne fonctionnera pas.

    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)

  • Si vous êtes le développeur du client Gateway : assurez-vous que votre client déclare la capacité d'échantillonnage pendant initialize :

    {
  "capabilities": {
    "sampling": {}
  }
}

Exemples de code

Note

Le client LangGraph MCP (langchain-mcp-adapters) et le client Strands MCP ne prennent actuellement pas en charge l'échantillonnage. Utilisez l'approche client MCP illustrée ci-dessous pour gérer les demandes d'échantillonnage provenant de votre passerelle.

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