Requisitos previos ¿Cómo funciona el muestreo Flujo de muestreo Guía para desarrolladores de servidores MCP Target Gestión de errores Resolución de problemas Ejemplos de código

Utilice el muestreo con su AgentCore puerta de enlace

El muestreo es una función del MCP que permite a un servidor MCP solicitar al cliente que complete el LLM durante una llamada de herramienta. Esto permite a los servidores aprovechar las capacidades de IA sin necesidad de acceder directamente a un modelo de lenguaje: el cliente se encarga de la invocación del modelo y devuelve el resultado. AgentCore Gateway reenvía las solicitudes de muestreo de los servidores MCP a sus clientes y reemplaza la solicitud id por un identificador generado por la pasarela.

Requisitos previos

Para usar el muestreo con su pasarela:

Sesiones habilitadas: el muestreo requiere soporte de sesión. Consulte Usar sesiones de MCP con su puerta de enlace.
Transmisión de respuestas habilitada: las solicitudes de muestreo se envían como fragmentos de SSE durante una conexión abierta. streamingConfiguration.enableResponseStreamingConfigúrelo true en la puerta de enlace. protocolConfiguration.mcp
Tipo de destino del servidor MCP: las solicitudes de muestreo se originan en los destinos del servidor MCP.
El cliente declara su capacidad de muestreo: el cliente debe declarar su apoyo al muestreo durante la initialize solicitud. La pasarela solo reenvía las solicitudes de muestreo a los clientes que hayan declarado esta capacidad.

¿Cómo funciona el muestreo

Cuando un servidor MCP objetivo necesita completar un LLM durante la ejecución de la herramienta, envía una sampling/createMessage solicitud. La puerta de enlace reenvía esta solicitud al cliente como un evento SSE, en sustitución de la solicitud. id El cliente invoca su modelo de lenguaje y envía el resultado a la puerta de enlace, que lo reenvía al destino.

La solicitud de muestreo incluye:

messages— Los mensajes de conversación que se van a enviar a la modelo.
modelPreferences— Consejos opcionales sobre las capacidades deseadas del modelo (inteligencia, velocidad, coste).
systemPrompt— Indicador de sistema opcional para el modelo.
maxTokens— Número máximo de fichas que se pueden generar.

El cliente responde con:

model— El modelo que se utilizó.
role— Siempreassistant.
content— El contenido generado (texto o imagen).

nota

El cliente tiene el control total sobre qué modelo utilizar y cómo gestionar la solicitud. Los servidores modelPreferences son sugerencias, no requisitos. El cliente también puede modificar o rechazar la solicitud según sus propias políticas.

Flujo de muestreo

El cliente envía una tools/call solicitud con el Mcp-Session-Id encabezado.
Gateway reenvía la llamada a la herramienta al servidor MCP de destino.
El objetivo abre una transmisión SSE y envía una sampling/createMessage solicitud.
Gateway reenvía la solicitud de muestreo al cliente como un evento de SSE, en sustitución de la solicitudid.
El cliente invoca su modelo de lenguaje con los mensajes proporcionados.
El cliente envía una nueva solicitud con el resultado del muestreo utilizando el mismo Mcp-Session-Id y el id de la solicitud de la pasarela.
Gateway reenvía el resultado al servidor MCP de destino.
El objetivo continúa procesándose y devuelve el resultado final de la herramienta.
Gateway reenvía el resultado final al cliente y cierra la transmisión.

Guía para desarrolladores de servidores MCP Target

importante

Los destinos del servidor MCP que envían solicitudes de muestreo deben incluir las llamadas de muestreo en bloques try-catch y gestionar el caso en el que el cliente no admita el muestreo. Si el cliente de la puerta de enlace no declaró la capacidad de muestreo, la puerta de enlace no la declara al objetivo. Si el objetivo envía una solicitud de muestreo de todos modos, la puerta de enlace devuelve un error -32601 (método no encontrado) al objetivo.

Los servidores deben implementar una ruta alternativa (por ejemplo, usar un modelo integrado u omitir este AI-assisted paso) cuando el muestreo no esté disponible.

Gestión de errores

Escenario	Error	Description (Descripción)
El cliente envía una respuesta de muestreo cuando no hay ninguna solicitud de muestreo pendiente	JSON-RPC `-32600`(Solicitud no válida)	No se encontró ninguna solicitud de muestreo coincidente para esta sesión.
El cliente envía una respuesta de muestreo con una `id` que no coincide con una solicitud pendiente	JSON-RPC `-32600`(Solicitud no válida)	`id`Debe coincidir con el enviado por la pasarela en la `sampling/createMessage` solicitud.
El servidor MCP envía una solicitud de muestreo, pero la puerta de enlace no declaró su compatibilidad	JSON-RPC `-32601`(No se encontró el método)	Regresó al destino del servidor MCP. Consulte Solución de problemas

Resolución de problemas

Error: «Error al llamar a la herramienta 'sample_tool': no se ha encontrado el método:» sampling/createMessage

Este error se produce cuando un servidor MCP objetivo envía una solicitud de muestreo, pero el cliente de la pasarela no declaró la capacidad de muestreo en ese momento. initialize La puerta de enlace devuelve un error -32601 (método no encontrado) al destino, y el objetivo puede devolverlo como un error de ejecución de la herramienta al cliente.

Para resolverlo:

Si es el desarrollador del servidor MCP: añada la gestión de errores a sus llamadas de muestreo. Implemente una ruta alternativa cuando no se admita el muestreo:

importante
Debe incluirlo related_request_id=ctx.request_context.request_id en su create_message llamada. Esto es necesario para que la pasarela asocie correctamente la solicitud de muestreo con la llamada de herramienta que la originó. Sin ella, el muestreo no funcionará.
```
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 usted es el desarrollador del cliente de puerta de enlace: asegúrese de que su cliente declare la capacidad de muestreo duranteinitialize:
```
{
  "capabilities": {
    "sampling": {}
  }
}
```

Ejemplos de código

nota

El cliente LangGraph MCP (langchain-mcp-adapters) y el cliente MCP de Strands no admiten actualmente el muestreo. Utilice el enfoque de cliente MCP que se muestra a continuación para gestionar las solicitudes de muestreo desde su pasarela.

ejemplo

Python requests package


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


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Mensajes de registro

Busque una herramienta de pasarela