View a markdown version of this page

Use a elicitação com seu gateway AgentCore - Amazon Bedrock AgentCore

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 como true no 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 initialize solicitaçã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 URLElicitationRequiredError contendo. A solicitação é encerrada, o usuário conclui a ação na URL e o cliente repete a chamada original da ferramenta.

Negociação de capacidades

O gateway só declara suporte de elicitação para um destino de servidor MCP se:

  1. O cliente declarou suporte à elicitação durante. initialize

  2. A versão do protocolo MCP suporta o modo de elicitação — o form modo requer versão 2025-03-26 ou posterior, url os modos exigem versão 2025-11-25 ou posterior.

  3. 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

  1. O cliente envia uma tools/call solicitação com o Mcp-Session-Id cabeçalho.

  2. O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.

  3. O destino abre um fluxo SSE e envia uma elicitation/create solicitação como o primeiro evento.

  4. O gateway encaminha a elicitation/create solicitação para o cliente no stream SSE, substituindo a solicitaçãoid.

  5. O cliente apresenta o formulário ao usuário e coleta a resposta.

  6. O cliente envia uma nova solicitação com a resposta de elicitação (ação: accept oudecline) usando a mesma. Mcp-Session-Id

  7. O gateway encaminha a resposta para o destino do servidor MCP.

  8. O alvo confirma com HTTP 202 Accepted.

  9. O destino conclui a chamada da ferramenta e envia o resultado final no fluxo SSE original.

  10. O gateway encaminha o resultado final para o cliente e fecha o fluxo.

Fluxo de elicitação no modo URL (baseado em exceção)

  1. O cliente envia uma tools/call solicitação com o Mcp-Session-Id cabeçalho.

  2. O gateway encaminha a chamada da ferramenta para o destino do servidor MCP.

  3. O destino gera um URLElicitationRequiredError como um JSON-RPC erro, contendo o URL e um ID de elicitação.

  4. O gateway encaminha o URLElicitationRequiredError para o cliente, substituindo a solicitaçãoid.

  5. O cliente redireciona o usuário para o URL fornecido para concluir a ação (normalmente autenticação OAuth).

  6. Depois que o usuário conclui a ação, o cliente repete a solicitação originaltools/call.

  7. 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.

  8. 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 -32600(Solicitação inválida)

Nenhuma elicitação correspondente foi encontrada para esta sessão.

O cliente envia uma resposta de elicitação com uma id que não corresponde a uma elicitação pendente

JSON-RPC -32600(Solicitação inválida)

idDeve corresponder ao enviado pelo gateway na elicitation/create solicitação.

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 -32601(Método não encontrado)

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
Python requests package
  1. import requests import json import sseclient gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" headers = { "Content-Type": "application/json", "Accept": "text/event-stream", "Authorization": "Bearer YOUR_ACCESS_TOKEN" } # Step 1: Initialize with elicitation capability init_response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "init-request", "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {"elicitation": {"form": {}, "url": {}}}, "clientInfo": {"name": "my-agent", "version": "1.0.0"} } }) session_id = init_response.headers["Mcp-Session-Id"] headers["Mcp-Session-Id"] = session_id # Step 2: Call tool (streaming response) response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "use_aws", "arguments": {"command": "aws s3 rm s3://my-bucket/important-file"} } }, stream=True) # Step 3: Process SSE events client = sseclient.SSEClient(response) for event in client.events(): data = json.loads(event.data) if data.get("method") == "elicitation/create": elicitation_id = data["id"] print(f"Form elicitation received: {data['params']['message']}") # Step 4: Send elicitation response requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": elicitation_id, "result": {"action": "accept", "content": {"confirm": True}} }) elif "result" in data: print(f"Tool result: {data['result']}") break
MCP Client
  1. from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client import asyncio async def elicitation_handler(request): """Handle form elicitation requests from the server.""" print(f"Elicitation: {request.params.message}") return {"action": "accept", "content": {"confirm": True}} async def use_elicitation(url, token): headers = {"Authorization": f"Bearer {token}"} async with streamablehttp_client(url=url, headers=headers) as ( read_stream, write_stream, _ ): async with ClientSession( read_stream, write_stream, elicitation_handler=elicitation_handler ) as session: await session.initialize() result = await session.call_tool( name="use_aws", arguments={"command": "aws s3 rm s3://my-bucket/important-file"} ) print(f"Tool result: {result}") return result asyncio.run(use_elicitation( url="https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", token="YOUR_ACCESS_TOKEN" ))
Strands MCP Client
  1. from mcp.client.streamable_http import streamablehttp_client from mcp.types import ElicitResult from strands import Agent from strands.tools.mcp import MCPClient mcp_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" access_token = "YOUR_ACCESS_TOKEN" async def elicitation_callback(context, params): """Handle form elicitation requests from the MCP server target.""" print(f"Elicitation: {params.message}") user_response = get_user_input(params) # Your UI logic return ElicitResult(action="accept", content=user_response) mcp_client = MCPClient( lambda: streamablehttp_client( mcp_url, headers={"Authorization": f"Bearer {access_token}"} ), elicitation_callback=elicitation_callback, ) with mcp_client: agent = Agent(tools=mcp_client.list_tools_sync()) response = agent("Delete the file s3://my-bucket/important-file using AWS CLI") print(response)
LangGraph MCP Client
  1. from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_mcp_adapters.callbacks import Callbacks, CallbackContext from langchain.agents import create_agent from mcp.shared.context import RequestContext from mcp.types import ElicitRequestParams, ElicitResult async def on_elicitation( mcp_context: RequestContext, params: ElicitRequestParams, context: CallbackContext, ) -> ElicitResult: """Handle elicitation requests from MCP servers.""" print(f"[{context.server_name}] Elicitation: {params.message}") # Prompt user for input based on params.requestedSchema return ElicitResult( action="accept", content={"confirm": True}, ) client = MultiServerMCPClient( { "gateway": { "url": "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", "transport": "http", "headers": {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}, } }, callbacks=Callbacks(on_elicitation=on_elicitation), ) tools = await client.get_tools() agent = create_agent("claude-sonnet-4-20250514", tools) result = await agent.ainvoke( {"messages": [{"role": "user", "content": "Delete s3://my-bucket/important-file"}]} )

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.

exemplo
Python requests package
  1. import requests import json import sseclient import webbrowser gateway_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" headers = { "Content-Type": "application/json", "Accept": "text/event-stream", "Authorization": "Bearer YOUR_ACCESS_TOKEN", "Mcp-Session-Id": "session-abc123def456" } # Call tool that triggers URL elicitation response = requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": "tool-call-2", "method": "tools/call", "params": { "name": "access_github_repo", "arguments": {"repo": "my-org/my-repo"} } }, stream=True) # Process SSE events client = sseclient.SSEClient(response) for event in client.events(): data = json.loads(event.data) if data.get("method") == "elicitation/create": elicitation_id = data["id"] url = data["params"]["url"] print(f"URL elicitation: {data['params']['message']}") # Open browser for user to complete authentication webbrowser.open(url) input("Press Enter after completing authentication...") # Send elicitation response requests.post(gateway_url, headers=headers, json={ "jsonrpc": "2.0", "id": elicitation_id, "result": {"action": "accept"} }) elif "result" in data: print(f"Tool result: {data['result']}") break
MCP Client
  1. from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client import asyncio import webbrowser async def elicitation_handler(request): """Handle URL elicitation by opening the browser.""" if hasattr(request.params, 'url') and request.params.url: print(f"Opening URL for authentication: {request.params.url}") webbrowser.open(request.params.url) input("Press Enter after completing authentication...") return {"action": "accept"} # Form mode fallback return {"action": "accept", "content": {}} async def use_url_elicitation(url, token): headers = {"Authorization": f"Bearer {token}"} async with streamablehttp_client(url=url, headers=headers) as ( read_stream, write_stream, _ ): async with ClientSession( read_stream, write_stream, elicitation_handler=elicitation_handler ) as session: await session.initialize() result = await session.call_tool( name="access_github_repo", arguments={"repo": "my-org/my-repo"} ) print(f"Tool result: {result}") return result asyncio.run(use_url_elicitation( url="https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", token="YOUR_ACCESS_TOKEN" ))
Strands MCP Client
  1. from mcp.client.streamable_http import streamablehttp_client from mcp.types import ElicitResult from strands import Agent from strands.tools.mcp import MCPClient import webbrowser mcp_url = "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp" access_token = "YOUR_ACCESS_TOKEN" async def elicitation_callback(context, params): """Handle URL elicitation by opening the browser.""" if hasattr(params, 'url') and params.url: print(f"Opening URL: {params.url}") webbrowser.open(params.url) input("Press Enter after completing authentication...") return ElicitResult(action="accept") return ElicitResult(action="accept", content={}) mcp_client = MCPClient( lambda: streamablehttp_client( mcp_url, headers={"Authorization": f"Bearer {access_token}"} ), elicitation_callback=elicitation_callback, ) with mcp_client: agent = Agent(tools=mcp_client.list_tools_sync()) response = agent("Access the my-org/my-repo GitHub repository") print(response)
LangGraph MCP Client
  1. from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_mcp_adapters.callbacks import Callbacks, CallbackContext from langchain.agents import create_agent from mcp.shared.context import RequestContext from mcp.types import ElicitRequestParams, ElicitResult import webbrowser async def on_elicitation( mcp_context: RequestContext, params: ElicitRequestParams, context: CallbackContext, ) -> ElicitResult: """Handle URL elicitation by opening the browser.""" if params.url: print(f"[{context.server_name}] Opening URL: {params.url}") webbrowser.open(params.url) input("Press Enter after completing authentication...") return ElicitResult(action="accept") return ElicitResult(action="accept", content={}) client = MultiServerMCPClient( { "gateway": { "url": "https://mygateway-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp", "transport": "http", "headers": {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}, } }, callbacks=Callbacks(on_elicitation=on_elicitation), ) tools = await client.get_tools() agent = create_agent("claude-sonnet-4-20250514", tools) result = await agent.ainvoke( {"messages": [{"role": "user", "content": "Access the my-org/my-repo GitHub repository"}]} )