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
truenelstreamingConfiguration.enableResponseStreamingtuo 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.
initializeIl 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
-
Il client invia una
tools/callrichiesta con l'Mcp-Session-Idintestazione. -
Gateway inoltra la chiamata allo strumento alla destinazione del server MCP.
-
Il target apre un flusso SSE e invia una richiesta.
sampling/createMessage -
Gateway inoltra la richiesta di campionamento al client come evento SSE, sostituendo la richiesta.
id -
Il client richiama il proprio modello linguistico con i messaggi forniti.
-
Il client invia una nuova richiesta con il risultato del campionamento utilizzando la stessa richiesta
Mcp-Session-Ide quellaidproveniente dalla richiesta del gateway. -
Il gateway inoltra il risultato alla destinazione del server MCP.
-
Il target continua l'elaborazione e restituisce il risultato finale dell'utensile.
-
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 |
Nessuna richiesta di campionamento corrispondente trovata per questa sessione. |
|
Il client invia una risposta di campionamento con una |
JSON-RPC |
|
|
Il server MCP invia una richiesta di campionamento ma il gateway non ha dichiarato il supporto |
JSON-RPC |
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_idnella chiamata.create_messageCiò è 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.