Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Eventos MCP em conversas de voz

Aula 12 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. MCP no Agente de Voz
  2. Configurar uma ferramenta MCP
  3. Deteção de ferramentas
  4. Chamadas de ferramentas MCP
  5. Diferenças em relação à chamada de funções normal
  6. Gerir eventos MCP na sua aplicação
  7. Pontos-chave

MCP no Agente de Voz

O Model Context Protocol (MCP) permite que o seu agente de voz se ligue a servidores de ferramentas externos através de um protocolo padronizado. Quando configura uma ferramenta MCP na sua sessão, a API do Agente de Voz emite eventos específicos para cada etapa da interação com o servidor MCP.

Configurar uma ferramenta MCP

Para ativar um servidor MCP na sua sessão de voz, adicione-o à lista de ferramentas:

{
  "type": "session.update",
  "session": {
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://mon-serveur-mcp.exemple.com/sse",
        "server_label": "Internal CRM"
      }
    ]
  }
}

O campo server_url aponta para o seu servidor MCP e o server_label é um nome legível que identifica o servidor nos registos.

Deteção de ferramentas

Quando o agente se liga ao servidor MCP, obtém primeiro a lista de ferramentas disponíveis. Três eventos marcam esta fase.

mcp_list_tools.in_progress

{
  "type": "mcp_list_tools.in_progress",
  "server_label": "Internal CRM"
}

O servidor MCP está a ser consultado para obter a sua lista de ferramentas.

mcp_list_tools.completed

{
  "type": "mcp_list_tools.completed",
  "server_label": "Internal CRM",
  "tools": [
    {
      "name": "find_customer",
      "description": "Finds a customer by name or email"
    },
    {
      "name": "create_ticket",
      "description": "Creates a support ticket"
    }
  ]
}

A lista de ferramentas foi obtida com sucesso. O agente de voz pode agora utilizá-las na conversa.

mcp_list_tools.failed

{
  "type": "mcp_list_tools.failed",
  "server_label": "Internal CRM",
  "error": {
    "message": "Connection timeout"
  }
}

A ligação ao servidor MCP falhou. O agente prosseguirá a conversa sem essas ferramentas.

Chamadas de ferramentas MCP

Quando o agente decide utilizar uma ferramenta MCP durante a conversa, são emitidos mais eventos.

response.mcp_call_arguments.delta / .done

Tal como nos eventos normais de chamada de funções, estes transmitem em fluxo os argumentos da chamada:

{
  "type": "response.mcp_call_arguments.delta",
  "delta": "{\"name\": \"Mil"
}
{
  "type": "response.mcp_call_arguments.done",
  "arguments": "{\"name\": \"Miller\"}"
}

response.mcp_call.in_progress / .completed / .failed

Estes eventos monitorizam a execução da chamada no servidor MCP:

{
  "type": "response.mcp_call.in_progress",
  "server_label": "Internal CRM",
  "tool_name": "find_customer"
}
{
  "type": "response.mcp_call.completed",
  "server_label": "Internal CRM",
  "tool_name": "find_customer",
  "result": "{\"id\": 42, \"name\": \"Miller\", \"email\": \"[email protected]\"}"
}
{
  "type": "response.mcp_call.failed",
  "server_label": "Internal CRM",
  "tool_name": "find_customer",
  "error": {
    "message": "Customer not found"
  }
}

Diferenças em relação à chamada de funções normal

As ferramentas MCP são executadas no lado do servidor, através da infraestrutura da xAI, pelo que não precisa de gerir a execução. Esta é a principal diferença em relação à chamada de funções normal, onde a sua aplicação deve executar a função e devolver o resultado.

AspetoChamada de funçõesMCP
ExecuçãoA sua aplicaçãoServidor MCP remoto
ResultadoEnvia-o de voltaAutomático
LatênciaDepende do seu códigoDepende do servidor MCP
ConfiguraçãoEsquema JSON localURL do servidor MCP

Gerir eventos MCP na sua aplicação

Eis um exemplo de um gestor completo para eventos MCP:

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "mcp_list_tools.in_progress":
      console.log(`Connecting to MCP server: ${event.server_label}`);
      break;

    case "mcp_list_tools.completed":
      console.log(`Available tools: ${event.tools.length}`);
      break;

    case "mcp_list_tools.failed":
      console.error(`MCP error: ${event.error.message}`);
      break;

    case "response.mcp_call.in_progress":
      showToolIndicator(event.tool_name);
      break;

    case "response.mcp_call.completed":
      hideToolIndicator();
      break;

    case "response.mcp_call.failed":
      hideToolIndicator();
      showError(`Tool ${event.tool_name} unavailable`);
      break;
  }
});

Pontos-chave

  • As ferramentas MCP permitem que o agente de voz trabalhe com servidores externos através de um protocolo padronizado
  • A deteção de ferramentas ocorre automaticamente através dos eventos mcp_list_tools
  • As chamadas MCP são executadas no lado do servidor, ao contrário da chamada de funções normal
  • Cada chamada passa por três estados possíveis: in_progress, seguido de completed ou failed
  • Trate as falhas de ligação MCP com resiliência: o agente pode prosseguir sem as ferramentas