Utilisez l'élicitation avec votre passerelle AgentCore
L'élicitation est une fonctionnalité MCP qui permet à un serveur MCP de demander des informations supplémentaires au client lors d'un appel d'outil. Lorsqu'un outil a besoin d'une confirmation de l'utilisateur, d'une authentification ou d'une saisie supplémentaire pour continuer, le serveur renvoie une demande d'élicitation au client. AgentCore Gateway transmet les demandes de sollicitation des cibles du serveur MCP à vos clients, en remplaçant la demande id par un identifiant généré par la passerelle.
Conditions préalables
Pour utiliser l'élicitation avec votre passerelle, vous devez disposer des éléments suivants :
-
Sessions activées — L'élicitation nécessite un support de session. Consultez la section Utiliser des sessions MCP avec votre passerelle.
-
Streaming de réponses activé — Les demandes d'élicitation sont envoyées sous forme de segments d' Server-Sent événements (SSE) lors d'une connexion ouverte.
streamingConfiguration.enableResponseStreamingRéglez surtruecelui de votre passerelleprotocolConfiguration.mcp. -
Type de cible de serveur MCP — L'élicitation n'est prise en charge que pour les cibles de serveur MCP. L'élicitation provient du serveur MCP et est transmise au client par le biais de la passerelle.
-
Le client déclare sa capacité d'élicitation — Le client doit déclarer son soutien à l'élicitation lors de la
initializedemande à la passerelle de transférer les demandes d'élicitation.
Modes de sollicitation pris en charge
AgentCore Gateway prend en charge trois modes d'élicitation définis par la spécification MCP :
| Mode | Description |
|---|---|
|
Mode formulaire |
Le serveur envoie un formulaire structuré avec des champs que le client doit remplir. Utilisé pour collecter les confirmations, les préférences ou les données d'entrée des utilisateurs. La demande reste ouverte en attendant la réponse. |
|
Mode URL (basé sur les demandes) |
Le serveur envoie une URL que l'utilisateur doit consulter pour effectuer une action (généralement une authentification). La demande reste ouverte en attendant que l'action soit terminée. |
|
Mode URL (basé sur les exceptions) |
Le serveur renvoie une URL |
Négociation des capacités
La passerelle déclare la prise en charge de l'élicitation à une cible de serveur MCP uniquement si :
-
Le client a déclaré un soutien à l'élicitation au cours de.
initialize -
La version du protocole MCP prend en charge le mode d'élicitation : le
formmode nécessite une version2025-03-26ou une version ultérieure, lesurlmodes nécessitent une version ou une version2025-11-25ultérieure. -
La passerelle correspond aux capacités d'élicitation spécifiques déclarées par le client (formulaire, URL ou les deux).
Flux d'élicitation en mode formulaire
-
Le client envoie une
tools/calldemande avec l'Mcp-Session-Iden-tête. -
Gateway transmet l'appel d'outil à la cible du serveur MCP.
-
La cible ouvre un flux SSE et envoie une
elicitation/createdemande en tant que premier événement. -
Gateway transmet la
elicitation/createdemande au client sur le flux SSE, en remplaçant la demandeid. -
Le client présente le formulaire à l'utilisateur et recueille la réponse.
-
Le client envoie une nouvelle demande avec la réponse à l'élicitation (action :
acceptoudecline) en utilisant celle-ci.Mcp-Session-Id -
Gateway transmet la réponse à la cible du serveur MCP.
-
La cible accuse réception avec HTTP 202 Accepted.
-
La cible termine l'appel à l'outil et envoie le résultat final sur le flux SSE d'origine.
-
Gateway transmet le résultat final au client et ferme le flux.
Flux d'élicitation en mode URL (basé sur les exceptions)
-
Le client envoie une
tools/calldemande avec l'Mcp-Session-Iden-tête. -
Gateway transmet l'appel d'outil à la cible du serveur MCP.
-
La cible renvoie un JSON-RPC message
URLElicitationRequiredErrord'erreur contenant l'URL et un identifiant d'élicitation. -
Gateway le transmet
URLElicitationRequiredErrorau client en remplaçant la demandeid. -
Le client redirige l'utilisateur vers l'URL fournie pour terminer l'action (généralement l'authentification OAuth).
-
Une fois que l'utilisateur a terminé l'action, le client réessaie la
tools/calldemande d'origine. -
Gateway transmet la nouvelle tentative à la cible. La cible termine l'appel à l'outil puisque l'obtention de l'URL a été effectuée.
-
Gateway transmet le résultat final de l'outil au client.
Appels d'outils parallèles avec sollicitations
Un client peut lancer plusieurs tools/call demandes au cours d'une même session, même si une demande est en attente. Chaque sollicitation est suivie indépendamment par son. id Lors de l'envoi d'une réponse à une sollicitation, le client doit inclure la même réponse id que celle envoyée par la passerelle dans la elicitation/create demande.
Conseils pour les développeurs cibles de serveurs MCP
Important
Les cibles du serveur MCP qui envoient des demandes d'élicitation doivent encapsuler les appels dans des blocs trycatch et gérer les cas où le client ne prend pas en charge l'élicitation. Si le client de la passerelle n'a pas déclaré de capacité d'élicitation, la passerelle ne la déclare pas à la cible. Si la cible envoie quand même une élicitation, la passerelle renvoie une erreur -32601 (Method not found) à la cible.
Les serveurs doivent implémenter un chemin de secours (par exemple en utilisant des valeurs par défaut ou en sautant l'opération) lorsque l'élicitation n'est pas disponible.
Gestion des erreurs
| Scénario | Erreur | Description |
|---|---|---|
|
Le client envoie une réponse à une sollicitation lorsqu'aucune sollicitation n'est en attente |
JSON-RPC |
Aucune élicitation correspondante n'a été trouvée pour cette session. |
|
Le client envoie une réponse à une sollicitation avec un message |
JSON-RPC |
Le |
|
Interruptions de connexion entre la passerelle et la cible du serveur MCP |
JSON-RPC erreur avec DependencyFailedException |
Le client doit réessayer la demande d'appel d'outil d'origine. |
|
Interruptions de connexion entre le client et la passerelle |
N/A |
L'élicitation en attente est nettoyée. Le client doit réessayer d'appeler l'outil. |
|
Le serveur MCP envoie une demande mais la passerelle n'a pas déclaré de support |
JSON-RPC |
Retourné à la cible du serveur MCP. Consultez la section Résolution des problèmes. |
Résolution des problèmes
Erreur : « Erreur lors de l'appel de l'outil 'sample_tool' : méthode introuvable : » elicitation/create
Cette erreur se produit lorsqu'une cible du serveur MCP envoie une demande d'élicitation mais que le client de la passerelle n'a pas déclaré de capacité d'élicitation au cours de cette opération. initialize La passerelle renvoie une erreur -32601 (Method not found) à la cible, et la cible peut la renvoyer sous forme d'erreur d'exécution de l'outil au client.
Pour résoudre le problème :
-
Si vous êtes le développeur du serveur MCP : ajoutez la gestion des erreurs à vos appels de sollicitation. Implémentez un chemin de secours lorsque l'élicitation n'est pas prise en charge :
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() -
Si vous êtes le développeur du client Gateway : assurez-vous que votre client déclare sa capacité d'élicitation pendant :
initialize{ "capabilities": { "elicitation": { "form": {}, "url": {} } } }
Exemples de code
Exemple de mode formulaire
En mode formulaire, le serveur envoie un schéma structuré que le client doit remplir. La demande reste ouverte en attendant la réponse.
Exemple
Exemple de mode URL
En mode URL, le serveur envoie une URL que l'utilisateur doit consulter pour effectuer une action (généralement une authentification OAuth). La demande reste ouverte en attendant que l'utilisateur termine l'action sur l'URL.