Utilice la elicitación con su AgentCore puerta de enlace
La elicitación es una función de MCP que permite a un servidor de MCP solicitar información adicional al cliente durante una llamada de herramienta. Cuando una herramienta necesita la confirmación del usuario, la autenticación o una entrada adicional para continuar, el servidor envía una solicitud de obtención de información al cliente. AgentCore Gateway reenvía las solicitudes de obtención de datos de los servidores MCP a sus clientes y las reemplaza por un identificador generado por la pasarela. id
Requisitos previos
Para utilizar la elicitación con su pasarela, debe tener:
-
Sesiones habilitadas: la elicitación requiere soporte de sesión. Consulte Usar sesiones de MCP con su puerta de enlace.
-
Transmisión de respuestas habilitada: las solicitudes de obtención de información se envían como fragmentos de Server-Sent eventos (SSE) durante una conexión abierta. Se configura
trueenstreamingConfiguration.enableResponseStreamingla puerta de enlace.protocolConfiguration.mcp -
Tipo de destino del servidor MCP: la elicitación solo se admite en los destinos del servidor MCP. La obtención se origina en el servidor MCP y se reenvía al cliente a través de la puerta de enlace.
-
El cliente declara su capacidad de elicitación: el cliente debe declarar su apoyo a la elicitación durante la
initializesolicitud para que la pasarela reenvíe las solicitudes de elicitación.
Modos de elicitación compatibles
AgentCore Gateway admite tres modos de obtención definidos por la especificación MCP:
| Mode | Description (Descripción) |
|---|---|
|
Modo de formulario |
El servidor envía un formulario estructurado con campos para que el cliente los complete. Se utiliza para recopilar las confirmaciones, las preferencias o los datos de entrada de los usuarios. La solicitud permanece abierta mientras espera la respuesta. |
|
Modo URL (basado en solicitudes) |
El servidor envía una URL que el usuario debe visitar para completar una acción (normalmente la autenticación). La solicitud permanece abierta mientras espera a que se complete la acción. |
|
Modo URL (basado en excepciones) |
El servidor lanza un mensaje |
Negociación de capacidades
La puerta de enlace solo declara el soporte de elicitación a un servidor MCP de destino si:
-
El cliente declaró su apoyo a la elicitación durante.
initialize -
La versión del protocolo MCP admite el modo de obtención: el
formmodo requiere una versión2025-03-26o posterior, losurlmodos requieren una versión2025-11-25o posterior. -
La puerta de enlace coincide con las capacidades de obtención específicas declaradas por el cliente (formulario, URL o ambos).
Modo de formulario: flujo de elicitación
-
El cliente envía una
tools/callsolicitud con elMcp-Session-Idencabezado. -
Gateway reenvía la llamada a la herramienta al servidor MCP de destino.
-
El objetivo abre una transmisión SSE y envía una
elicitation/createsolicitud como primer evento. -
Gateway reenvía la
elicitation/createsolicitud al cliente en la transmisión SSE y reemplaza la solicitudid. -
El cliente presenta el formulario al usuario y recopila la respuesta.
-
El cliente envía una nueva solicitud con la respuesta de provocación (acción:
acceptodecline) utilizando la mismaMcp-Session-Id. -
Gateway reenvía la respuesta al servidor MCP de destino.
-
El objetivo reconoce con HTTP 202 Accepted.
-
El objetivo completa la llamada a la herramienta y envía el resultado final a la transmisión SSE original.
-
Gateway reenvía el resultado final al cliente y cierra la transmisión.
Flujo de elicitación en modo URL (basado en excepciones)
-
El cliente envía una
tools/callsolicitud con el encabezado.Mcp-Session-Id -
Gateway reenvía la llamada a la herramienta al servidor MCP de destino.
-
El objetivo muestra un
URLElicitationRequiredErrorJSON-RPC error que contiene la URL y un identificador de obtención. -
Gateway la reenvía
URLElicitationRequiredErroral cliente y reemplaza la solicitud.id -
El cliente redirige al usuario a la URL proporcionada para completar la acción (normalmente, la autenticación OAuth).
-
Una vez que el usuario completa la acción, el cliente vuelve a intentar la solicitud original.
tools/call -
Gateway reenvía el reintento al objetivo. El objetivo completa la llamada a la herramienta desde que se obtuvo la URL.
-
Gateway reenvía el resultado final de la herramienta al cliente.
Llamadas de herramientas paralelas con notificaciones
Un cliente puede iniciar varias tools/call solicitudes en la misma sesión, incluso cuando hay una solicitud pendiente. Cada elicitación es rastreada de forma independiente por su. id Al enviar una respuesta de elicitación, el cliente debe incluir en la solicitud la misma id que envió la pasarela. elicitation/create
Guía para los desarrolladores de servidores MCP Target
importante
Los destinos del servidor MCP que envían solicitudes de elicitación deben agrupar las llamadas de elicitación en bloques try-catch y gestionar el caso en el que el cliente no admita la elicitación. Si el cliente de la puerta de enlace no declaró la capacidad de elicitación, la puerta de enlace no la declara al objetivo. Si el objetivo envía una activación de todos modos, la puerta de enlace devuelve un error -32601 (método no encontrado) al objetivo.
Los servidores deben implementar una ruta alternativa (por ejemplo, usar valores predeterminados u omitir la operación) cuando la elicitación no esté disponible.
Gestión de errores
| Escenario | Error | Description (Descripción) |
|---|---|---|
|
El cliente envía una respuesta de elicitación cuando no hay ninguna elicitación pendiente |
JSON-RPC |
No se encontró ninguna elicitación coincidente para esta sesión. |
|
El cliente envía una respuesta de elicitación con una |
JSON-RPC |
|
|
Se interrumpe la conexión entre la puerta de enlace y el servidor MCP de destino |
JSON-RPC error con DependencyFailedException |
El cliente debe volver a intentar la solicitud de llamada a la herramienta original. |
|
Se interrumpe la conexión entre el cliente y la puerta de enlace |
N/A |
Se ha eliminado la solicitud pendiente. El cliente debe volver a intentar la llamada a la herramienta. |
|
El servidor MCP envía la solicitud, pero la puerta de enlace no declaró su compatibilidad |
JSON-RPC |
Regresó al destino del servidor MCP. Consulte Solución de problemas |
Resolución de problemas
Error: «Error al llamar a la herramienta 'sample_tool': no se ha encontrado el método:» elicitation/create
Este error se produce cuando un servidor MCP objetivo envía una solicitud de elicitación, pero el cliente de la pasarela no declaró la capacidad de elicitación en ese momento. initialize La puerta de enlace devuelve un error -32601 (método no encontrado) al destino, y el objetivo puede devolverlo como un error de ejecución de la herramienta al cliente.
Para resolverlo:
-
Si es el desarrollador del servidor MCP: añada la gestión de errores a sus llamadas de captación. Implemente una ruta alternativa cuando no se admita la elicitación:
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 usted es el desarrollador del cliente de pasarela: asegúrese de que su cliente declare la capacidad de elicitación durante:
initialize{ "capabilities": { "elicitation": { "form": {}, "url": {} } } }
Ejemplos de código
Ejemplo de modo formulario
En el modo formulario, el servidor envía un esquema estructurado para que el cliente lo rellene. La solicitud permanece abierta mientras espera la respuesta.
ejemplo
Ejemplo de modo URL
En el modo URL, el servidor envía una URL que el usuario debe visitar para completar una acción (normalmente la autenticación OAuth). La solicitud permanece abierta mientras espera a que el usuario complete la acción en la URL.