Usa l'elicitazione con il tuo gateway AgentCore
L'elicitazione è una funzionalità MCP che consente a un server MCP di richiedere informazioni aggiuntive al client durante una chiamata allo strumento. Quando uno strumento richiede la conferma dell'utente, l'autenticazione o un input aggiuntivo per procedere, il server invia una richiesta di elicitazione al client. AgentCore Gateway inoltra le richieste di elicitazione dalle destinazioni del server MCP ai client, sostituendo la richiesta id con un identificatore generato dal gateway.
Prerequisiti
Per utilizzare l'elicitazione con il gateway, è necessario disporre di:
-
Sessioni abilitate: Elicitation richiede il supporto della sessione. Vedi Utilizzare le sessioni MCP con il gateway.
-
Streaming di risposta abilitato: le richieste di elicitazione vengono inviate come blocchi di Server-Sent eventi (SSE) durante una connessione aperta. Imposta su
truenelstreamingConfiguration.enableResponseStreamingtuo gateway.protocolConfiguration.mcp -
Tipo di destinazione del server MCP: l'elicitazione è supportata solo per le destinazioni del server MCP. L'elicitazione proviene dal server MCP e viene inoltrata al client tramite il gateway.
-
Il client dichiara la capacità di elicitazione: il client deve dichiarare il supporto per l'elicitazione durante la richiesta al gateway di inoltrare le
initializerichieste di elicitazione.
Modalità di elicitazione supportate
AgentCore Gateway supporta tre modalità di elicitazione definite dalla specifica MCP:
| Modalità | Description |
|---|---|
|
modalità Form |
Il server invia un modulo strutturato con campi da compilare per il client. Utilizzato per raccogliere conferme utente, preferenze o dati di input. La richiesta rimane aperta in attesa della risposta. |
|
Modalità URL (basata su richiesta) |
Il server invia un URL che l'utente deve visitare per completare un'azione (in genere l'autenticazione). La richiesta rimane aperta in attesa del completamento dell'azione. |
|
Modalità URL (basata su eccezioni) |
Il server genera un URL |
Negoziazione delle capacità
Il gateway dichiara il supporto per l'elicitazione su una destinazione del server MCP solo se:
-
Il client ha dichiarato il supporto per l'elicitazione durante.
initialize -
La versione del protocollo MCP supporta la modalità elicitazione: la
formmodalità richiede una versione2025-03-26o successiva, leurlmodalità richiedono una versione2025-11-25o successiva. -
Il gateway corrisponde alle funzionalità di elicitazione specifiche dichiarate dal client (modulo, url o entrambi).
Flusso di elicitazione in modalità Form
-
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
elicitation/createrichiesta come primo evento. -
Gateway inoltra la
elicitation/createrichiesta al client nel flusso SSE, sostituendo la richiesta.id -
Il client presenta il modulo all'utente e raccoglie la risposta.
-
Il client invia una nuova richiesta con la risposta di elicitazione (action:
acceptordecline) utilizzando la stessa.Mcp-Session-Id -
Gateway inoltra la risposta alla destinazione del server MCP.
-
La destinazione riconosce con HTTP 202 Accepted.
-
Il target completa la chiamata allo strumento e invia il risultato finale sul flusso SSE originale.
-
Gateway inoltra il risultato finale al client e chiude lo stream.
Flusso di elicitazione in modalità URL (basato su eccezioni)
-
Il client invia una
tools/callrichiesta con l'intestazione.Mcp-Session-Id -
Gateway inoltra la chiamata allo strumento alla destinazione del server MCP.
-
La destinazione genera un
URLElicitationRequiredErrormessaggio di JSON-RPC errore, contenente l'URL e un ID di elicitazione. -
Gateway inoltra il file
URLElicitationRequiredErroral client, sostituendo la richiesta.id -
Il client reindirizza l'utente all'URL fornito per completare l'azione (in genere l'autenticazione OAuth).
-
Dopo che l'utente ha completato l'azione, il client ritenta la richiesta originale.
tools/call -
Gateway inoltra il nuovo tentativo alla destinazione. Il target completa la chiamata allo strumento non appena è stata completata la richiesta dell'URL.
-
Gateway inoltra il risultato finale dello strumento al client.
Lo strumento parallelo chiama con elicitazioni
Un client può avviare più tools/call richieste all'interno della stessa sessione, anche se un'elicitazione è in sospeso. Ogni elicitazione viene tracciata indipendentemente dalla sua. id Quando invia una risposta di elicitazione, il client deve includere nella richiesta la stessa id che è stata inviata dal gateway. elicitation/create
Linee guida per gli sviluppatori di server MCP destinati agli sviluppatori
Importante
I target del server MCP che inviano richieste di elicitazione devono racchiudere le chiamate di elicitazione in blocchi try-catch e gestire il caso in cui il client non supporti l'elicitazione. Se il client del gateway non ha dichiarato la capacità di elicitazione, il gateway non la dichiara alla destinazione. Se il target invia comunque un'elicitazione, il gateway restituisce un errore -32601 (Metodo non trovato) al bersaglio.
I server devono implementare un percorso di fallback (ad esempio utilizzando valori predefiniti o saltando l'operazione) quando l'elicitazione non è disponibile.
Gestione degli errori
| Scenario | Errore | Description |
|---|---|---|
|
Il client invia una risposta di elicitazione quando nessuna elicitazione è in sospeso |
JSON-RPC |
Nessuna elicitazione corrispondente trovata per questa sessione. |
|
Il client invia una risposta di elicitazione con una |
JSON-RPC |
|
|
Interruzioni di connessione tra il gateway e la destinazione del server MCP |
JSON-RPC errore con DependencyFailedException |
Il client deve riprovare la richiesta originale di chiamata allo strumento. |
|
Interruzioni di connessione tra client e gateway |
N/A |
L'elicitazione in sospeso viene ripulita. Il client deve ripetere la chiamata allo strumento. |
|
Il server MCP invia l'elicitazione 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:" elicitation/create
Questo errore si verifica quando una destinazione del server MCP invia una richiesta di elicitazione ma il client del gateway non ha dichiarato la capacità di elicitazione 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 elicitazione. Implementa un percorso di fallback quando l'elicitazione non è supportata:
try: result = await context.session.create_elicitation( message="Confirm this action?", requested_schema={"type": "object", "properties": {"confirm": {"type": "boolean"}}} ) except Exception as e: # Fallback when client doesn't support elicitation logger.warning(f"Elicitation not supported: {e}") result = default_action() -
Se sei lo sviluppatore del client gateway: assicurati che il cliente dichiari la capacità di elicitazione durante:
initialize{ "capabilities": { "elicitation": { "form": {}, "url": {} } } }
Esempi di codice
Esempio di modalità Form
In modalità modulo, il server invia al client uno schema strutturato da compilare. La richiesta rimane aperta in attesa della risposta.
Esempio
Esempio di modalità URL
In modalità URL, il server invia un URL che l'utente deve visitare per completare un'azione (in genere l'autenticazione OAuth). La richiesta rimane aperta in attesa che l'utente completi l'azione sull'URL.