# 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](gateway-sessions.md).
+ **Streaming de resposta ativado** — As solicitações de amostragem são enviadas como partes SSE durante uma conexão aberta. `streamingConfiguration.enableResponseStreaming`Defina como `true` no seu gateway`protocolConfiguration.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ção`id`. 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`— Sempre`assistant`.
+ `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.
1. O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.
1. O destino abre um fluxo SSE e envia uma `sampling/createMessage` solicitação.
1. O gateway encaminha a solicitação de amostragem para o cliente como um evento SSE, substituindo a solicitação. `id`
1. O cliente invoca seu modelo de linguagem com as mensagens fornecidas.
1. 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.
1. O gateway encaminha o resultado para o destino do servidor MCP.
1. O alvo continua processando e retorna o resultado final da ferramenta.
1. 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) | `id`Deve 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](#gateway-mcp-sampling-troubleshooting). |
## 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.
**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"
))
```