View a markdown version of this page

Usa il campionamento con il tuo gateway AgentCore - Amazon Bedrock AgentCore

Usa il campionamento con il tuo gateway AgentCore

Il campionamento è una funzionalità MCP che consente a un server MCP di richiedere il completamento di un LLM al client durante una chiamata allo strumento. Ciò consente ai server di sfruttare le funzionalità di intelligenza artificiale senza bisogno di accedere direttamente a un modello linguistico: il client gestisce l'invocazione del modello e restituisce il risultato. AgentCore Gateway inoltra le richieste di campionamento dalle destinazioni dei server MCP ai client, sostituendo la richiesta con un identificatore generato dal gateway. id

Prerequisiti

Per utilizzare il campionamento con il gateway:

  • Sessioni abilitate: il campionamento richiede il supporto della sessione. Vedi Utilizzare le sessioni MCP con il gateway.

  • Streaming di risposta abilitato: le richieste di campionamento vengono inviate come blocchi SSE durante una connessione aperta. Imposta su true nel streamingConfiguration.enableResponseStreaming tuo gateway. protocolConfiguration.mcp

  • Tipo di destinazione del server MCP: le richieste di campionamento provengono dalle destinazioni del server MCP.

  • Il client dichiara la capacità di campionamento: il client deve dichiarare il supporto per il campionamento durante la richiesta. initialize Il gateway inoltra le richieste di campionamento solo ai client che hanno dichiarato questa funzionalità.

Come funziona il campionamento

Quando un server di destinazione MCP richiede il completamento di un LLM durante l'esecuzione dello strumento, invia una richiesta. sampling/createMessage Il gateway inoltra questa richiesta al client come evento SSE, sostituendo la richiesta. id Il client richiama il proprio modello linguistico e invia il risultato al gateway, che lo inoltra alla destinazione.

La richiesta di campionamento include:

  • messages— I messaggi di conversazione da inviare al modello.

  • modelPreferences— Suggerimenti opzionali sulle funzionalità desiderate del modello (intelligenza, velocità, costi).

  • systemPrompt— Richiesta di sistema opzionale per il modello.

  • maxTokens— Numero massimo di token da generare.

Il client risponde con:

  • model— Il modello utilizzato.

  • role— Sempreassistant.

  • content— Il contenuto generato (testo o immagine).

Nota

Il cliente ha il pieno controllo sul modello da utilizzare e su come gestire la richiesta. I server modelPreferences sono suggerimenti, non requisiti. Il client può anche modificare o rifiutare la richiesta in base alle proprie politiche.

Flusso di campionamento

  1. Il client invia una tools/call richiesta con l'Mcp-Session-Idintestazione.

  2. Gateway inoltra la chiamata allo strumento alla destinazione del server MCP.

  3. Il target apre un flusso SSE e invia una richiesta. sampling/createMessage

  4. Gateway inoltra la richiesta di campionamento al client come evento SSE, sostituendo la richiesta. id

  5. Il client richiama il proprio modello linguistico con i messaggi forniti.

  6. Il client invia una nuova richiesta con il risultato del campionamento utilizzando la stessa richiesta Mcp-Session-Id e quella id proveniente dalla richiesta del gateway.

  7. Il gateway inoltra il risultato alla destinazione del server MCP.

  8. Il target continua l'elaborazione e restituisce il risultato finale dell'utensile.

  9. Gateway inoltra il risultato finale al client e chiude lo stream.

Guida per gli sviluppatori di server MCP destinati agli sviluppatori

Importante

Le destinazioni del server MCP che inviano richieste di campionamento devono racchiudere le chiamate di campionamento in blocchi try-catch e gestire il caso in cui il client non supporti il campionamento. Se il client del gateway non ha dichiarato la capacità di campionamento, il gateway non la dichiara alla destinazione. Se il target invia comunque una richiesta di campionamento, il gateway restituisce un errore -32601 (Metodo non trovato) alla destinazione.

I server devono implementare un percorso di fallback (ad esempio utilizzando un modello integrato o saltando il AI-assisted passaggio) quando il campionamento non è disponibile.

Gestione degli errori

Scenario Errore Description

Il client invia una risposta di campionamento quando nessuna richiesta di campionamento è in sospeso

JSON-RPC -32600(Richiesta non valida)

Nessuna richiesta di campionamento corrispondente trovata per questa sessione.

Il client invia una risposta di campionamento con una id che non corrisponde a una richiesta in sospeso

JSON-RPC -32600(Richiesta non valida)

idDeve corrispondere a quello inviato dal gateway nella sampling/createMessage richiesta.

Il server MCP invia una richiesta di campionamento ma il gateway non ha dichiarato il supporto

JSON-RPC -32601(Metodo non trovato)

Restituito alla destinazione del server MCP. Vedere Risoluzione dei problemi.

Risoluzione dei problemi

Errore: «Errore durante la chiamata dello strumento 'sample_tool': Metodo non trovato:" sampling/createMessage

Questo errore si verifica quando una destinazione del server MCP invia una richiesta di campionamento ma il client del gateway non ha dichiarato la capacità di campionamento durante l'operazione. initialize Il gateway restituisce un errore -32601 (Method not found) alla destinazione e la destinazione può restituirlo al client come errore di esecuzione dello strumento.

Per risolvere:

  • Se sei lo sviluppatore del server MCP: aggiungi la gestione degli errori nelle chiamate di campionamento. Implementa un percorso di fallback quando il campionamento non è supportato:

    Importante

    È necessario includere related_request_id=ctx.request_context.request_id nella chiamata. create_message Ciò è necessario affinché il gateway associ correttamente la richiesta di campionamento alla chiamata allo strumento di origine. Senza di essa, il campionamento non funzionerà.

    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 sei lo sviluppatore del client gateway: assicurati che il tuo cliente dichiari la capacità di campionamento durante: initialize

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

Esempi di codice

Nota

LangGraph MCP Client (langchain-mcp-adapters) e Strands MCP Client attualmente non supportano il campionamento. Utilizzate l'approccio MCP Client mostrato di seguito per gestire le richieste di campionamento dal vostro gateway.

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