View a markdown version of this page

Use a amostragem com seu gateway AgentCore - Amazon Bedrock AgentCore
Pré-requisitosComo funciona a amostragemFluxo de amostragemOrientação para desenvolvedores-alvo do servidor MCPTratamento de errosSolução de problemasExemplos de código

Use a amostragem com seu gateway AgentCore

A amostragem é um recurso do MCP que permite que um servidor MCP solicite a conclusão do LLM do cliente durante uma chamada de ferramenta. Isso permite que os servidores aproveitem os recursos de IA sem precisar de acesso direto a um modelo de linguagem — o cliente lida com a invocação do modelo e retorna o resultado. AgentCore O gateway encaminha solicitações de amostragem dos alvos do servidor MCP para seus clientes, substituindo a solicitação por um identificador id gerado pelo gateway.

Pré-requisitos

Para usar a amostragem com seu gateway:

  • Sessões ativadas — A amostragem requer suporte de sessão. Consulte Usar sessões MCP com seu gateway.

  • Streaming de resposta ativado — As solicitações de amostragem são enviadas como partes SSE durante uma conexão aberta. streamingConfiguration.enableResponseStreamingDefina como true no seu gatewayprotocolConfiguration.mcp.

  • Tipo de alvo do servidor MCP — As solicitações de amostragem se originam dos alvos do servidor MCP.

  • O cliente declara a capacidade de amostragem — O cliente deve declarar suporte à amostragem durante a solicitação. initialize O gateway só encaminha solicitações de amostragem para clientes que declararam essa capacidade.

Como funciona a amostragem

Quando um destino do servidor MCP precisa ser concluído no LLM durante a execução da ferramenta, ele envia uma sampling/createMessage solicitação. O gateway encaminha essa solicitação ao cliente como um evento SSE, substituindo a solicitaçãoid. O cliente invoca seu modelo de linguagem e envia o resultado de volta ao gateway, que o encaminha para o destino.

A solicitação de amostragem inclui:

  • messages— As mensagens de conversa a serem enviadas ao modelo.

  • modelPreferences— Dicas opcionais sobre os recursos desejados do modelo (inteligência, velocidade, custo).

  • systemPrompt— Solicitação opcional do sistema para o modelo.

  • maxTokens— Número máximo de tokens a serem gerados.

O cliente responde com:

  • model— O modelo que foi usado.

  • role— Sempreassistant.

  • content— O conteúdo gerado (texto ou imagem).

nota

O cliente tem controle total sobre qual modelo usar e como lidar com a solicitação. Os servidores modelPreferences são dicas, não requisitos. O cliente também pode modificar ou rejeitar a solicitação com base em suas próprias políticas.

Fluxo de amostragem

  1. O cliente envia uma tools/call solicitação com o Mcp-Session-Id cabeçalho.

  2. O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.

  3. O destino abre um fluxo SSE e envia uma sampling/createMessage solicitação.

  4. O gateway encaminha a solicitação de amostragem para o cliente como um evento SSE, substituindo a solicitação. id

  5. O cliente invoca seu modelo de linguagem com as mensagens fornecidas.

  6. O cliente envia uma nova solicitação com o resultado da amostragem usando o mesmo Mcp-Session-Id e o id da solicitação do gateway.

  7. O gateway encaminha o resultado para o destino do servidor MCP.

  8. O alvo continua processando e retorna o resultado final da ferramenta.

  9. O gateway encaminha o resultado final para o cliente e fecha o fluxo.

Orientação para desenvolvedores-alvo do servidor MCP

Importante

Os alvos do servidor MCP que enviam solicitações de amostragem devem agrupar as chamadas de amostragem em blocos try-catch e lidar com o caso em que o cliente não oferece suporte à amostragem. Se o cliente do gateway não declarou a capacidade de amostragem, o gateway não a declara para o destino. Se o alvo enviar uma solicitação de amostragem de qualquer maneira, o gateway retornará um erro -32601 (Método não encontrado) para o destino.

Os servidores devem implementar um caminho alternativo (como usar um modelo incorporado ou pular a AI-assisted etapa) quando a amostragem não estiver disponível.

Tratamento de erros

Cenário Erro Description

O cliente envia uma resposta de amostragem quando nenhuma solicitação de amostragem está pendente

JSON-RPC -32600(Solicitação inválida)

Nenhuma solicitação de amostragem correspondente foi encontrada para esta sessão.

O cliente envia uma resposta de amostragem com uma id que não corresponde a uma solicitação pendente

JSON-RPC -32600(Solicitação inválida)

idDeve corresponder ao enviado pelo gateway na sampling/createMessage solicitação.

O servidor MCP envia a solicitação de amostragem, mas o gateway não declarou suporte

JSON-RPC -32601(Método não encontrado)

Retornado ao destino do servidor MCP. Consulte Solução de problemas.

Solução de problemas

Erro: “Erro ao chamar a ferramenta 'sample_tool': Método não encontrado:” sampling/createMessage

Esse erro ocorre quando um destino do servidor MCP envia uma solicitação de amostragem, mas o cliente do gateway não declarou a capacidade de amostragem durante. initialize O gateway retorna um erro -32601 (Método não encontrado) para o destino, e o destino pode retorná-lo como um erro de execução da ferramenta para o cliente.

Para resolver:

  • Se você for o desenvolvedor do servidor MCP: adicione tratamento de erros em suas chamadas de amostragem. Implemente um caminho alternativo quando a amostragem não for suportada:

    Importante

    Você deve incluir related_request_id=ctx.request_context.request_id em sua create_message chamada. Isso é necessário para que o gateway associe corretamente a solicitação de amostragem à chamada de ferramenta de origem. Sem isso, a amostragem não 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)

  • Se você for o desenvolvedor do cliente de gateway: garanta que seu cliente declare a capacidade de amostragem durante: initialize

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

Exemplos de código

nota

Atualmente, o LangGraph MCP Client (langchain-mcp-adapters) e o Strands MCP Client não oferecem suporte à amostragem. Use a abordagem MCP Client mostrada abaixo para lidar com solicitações de amostragem do seu gateway.

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