Use a elicitação com seu gateway AgentCore
A elicitação é um recurso MCP que permite que um servidor MCP solicite informações adicionais do cliente durante uma chamada de ferramenta. Quando uma ferramenta precisa de confirmação, autenticação ou entrada adicional do usuário para continuar, o servidor envia uma solicitação de elicitação de volta ao cliente. AgentCore O gateway encaminha solicitações de elicitação dos alvos do servidor MCP para seus clientes, substituindo a solicitação por um identificador id gerado pelo gateway.
Pré-requisitos
Para usar a elicitação com seu gateway, você deve ter:
-
Sessões habilitadas — A elicitação requer suporte de sessão. Consulte Usar sessões MCP com seu gateway.
-
Streaming de resposta ativado — As solicitações de elicitação são enviadas como blocos de Server-Sent eventos (SSE) durante uma conexão aberta.
streamingConfiguration.enableResponseStreamingDefina comotrueno seu gatewayprotocolConfiguration.mcp. -
Tipo de alvo do servidor MCP — A elicitação só é suportada para alvos do servidor MCP. A elicitação se origina do servidor MCP e é encaminhada pelo gateway para o cliente.
-
O cliente declara a capacidade de elicitação — O cliente deve declarar suporte à elicitação durante a
initializesolicitação para que o gateway encaminhe as solicitações de elicitação.
Modos de elicitação suportados
AgentCore O Gateway suporta três modos de elicitação definidos pela especificação MCP:
| Modo | Description |
|---|---|
|
Modo de formulário |
O servidor envia um formulário estruturado com campos para o cliente preencher. Usado para coletar confirmações, preferências ou dados de entrada do usuário. A solicitação permanece aberta enquanto aguarda a resposta. |
|
Modo de URL (baseado em solicitação) |
O servidor envia uma URL que o usuário deve visitar para concluir uma ação (normalmente autenticação). A solicitação permanece aberta enquanto aguarda a conclusão da ação. |
|
Modo de URL (baseado em exceções) |
O servidor lança uma URL |
Negociação de capacidades
O gateway só declara suporte de elicitação para um destino de servidor MCP se:
-
O cliente declarou suporte à elicitação durante.
initialize -
A versão do protocolo MCP suporta o modo de elicitação — o
formmodo requer versão2025-03-26ou posterior,urlos modos exigem versão2025-11-25ou posterior. -
O gateway corresponde aos recursos específicos de elicitação declarados pelo cliente (formulário, URL ou ambos).
Fluxo de elicitação no modo de formulário
-
O cliente envia uma
tools/callsolicitação com oMcp-Session-Idcabeçalho. -
O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.
-
O destino abre um fluxo SSE e envia uma
elicitation/createsolicitação como o primeiro evento. -
O gateway encaminha a
elicitation/createsolicitação para o cliente no stream SSE, substituindo a solicitaçãoid. -
O cliente apresenta o formulário ao usuário e coleta a resposta.
-
O cliente envia uma nova solicitação com a resposta de elicitação (ação:
acceptoudecline) usando a mesma.Mcp-Session-Id -
O gateway encaminha a resposta para o destino do servidor MCP.
-
O alvo confirma com HTTP 202 Accepted.
-
O destino conclui a chamada da ferramenta e envia o resultado final no fluxo SSE original.
-
O gateway encaminha o resultado final para o cliente e fecha o fluxo.
Fluxo de elicitação no modo URL (baseado em exceção)
-
O cliente envia uma
tools/callsolicitação com oMcp-Session-Idcabeçalho. -
O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.
-
O destino gera um
URLElicitationRequiredErrorcomo um JSON-RPC erro, contendo o URL e um ID de elicitação. -
O gateway encaminha o
URLElicitationRequiredErrorpara o cliente, substituindo a solicitaçãoid. -
O cliente redireciona o usuário para o URL fornecido para concluir a ação (normalmente autenticação OAuth).
-
Depois que o usuário conclui a ação, o cliente repete a solicitação original
tools/call. -
O gateway encaminha a nova tentativa para o alvo. O alvo conclui a chamada da ferramenta desde que a elicitação do URL foi cumprida.
-
O Gateway encaminha o resultado final da ferramenta para o cliente.
Chamadas de ferramentas paralelas com elicitações
Um cliente pode iniciar várias tools/call solicitações na mesma sessão, mesmo quando uma elicitação está pendente. Cada elicitação é rastreada de forma independente por sua. id Ao enviar uma resposta de elicitação, o cliente deve incluir a mesma id que foi enviada pelo gateway na elicitation/create solicitação.
Orientação para desenvolvedores-alvo do servidor MCP
Importante
Os alvos do servidor MCP que enviam solicitações de elicitação devem agrupar as chamadas de elicitação em blocos try-catch e lidar com o caso em que o cliente não oferece suporte à elicitação. Se o cliente do gateway não declarou a capacidade de elicitação, o gateway não a declara para o destino. Se o alvo enviar uma elicitação de qualquer maneira, o gateway retornará um erro -32601 (Método não encontrado) para o alvo.
Os servidores devem implementar um caminho alternativo (como usar valores padrão ou ignorar a operação) quando a elicitação não estiver disponível.
Tratamento de erros
| Cenário | Erro | Description |
|---|---|---|
|
O cliente envia uma resposta de elicitação quando nenhuma elicitação está pendente |
JSON-RPC |
Nenhuma elicitação correspondente foi encontrada para esta sessão. |
|
O cliente envia uma resposta de elicitação com uma |
JSON-RPC |
|
|
Interrupções de conexão entre o gateway e o destino do servidor MCP |
JSON-RPC erro com DependencyFailedException |
O cliente deve repetir a solicitação original de chamada da ferramenta. |
|
Interrupções de conexão entre cliente e gateway |
N/A |
A elicitação pendente está limpa. O cliente deve tentar novamente a chamada da ferramenta. |
|
O servidor MCP envia elicitação, mas o gateway não declarou suporte |
JSON-RPC |
Retornado ao destino do servidor MCP. Consulte Solução de problemas. |
Solução de problemas
Erro: “Erro ao chamar a ferramenta 'sample_tool': Método não encontrado:” elicitation/create
Esse erro ocorre quando um destino do servidor MCP envia uma solicitação de elicitação, mas o cliente do gateway não declarou a capacidade de elicitação durante. initialize O gateway retorna um erro -32601 (Método não encontrado) para o destino, e o destino pode retorná-lo como um erro de execução da ferramenta para o cliente.
Para resolver:
-
Se você for o desenvolvedor do servidor MCP: adicione tratamento de erros em suas chamadas de elicitação. Implemente um caminho alternativo quando a elicitação não for suportada:
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 você for o desenvolvedor do cliente de gateway: garanta que seu cliente declare a capacidade de elicitação durante:
initialize{ "capabilities": { "elicitation": { "form": {}, "url": {} } } }
Exemplos de código
Exemplo de modo de formulário
No modo de formulário, o servidor envia um esquema estruturado para o cliente preencher. A solicitação permanece aberta enquanto aguarda a resposta.
exemplo
Exemplo do modo URL
No modo URL, o servidor envia uma URL que o usuário deve visitar para concluir uma ação (normalmente autenticação OAuth). A solicitação permanece aberta enquanto espera que o usuário conclua a ação na URL.