Eventos MCP em conversas de voz
Nesta página
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.
| Aspeto | Chamada de funções | MCP |
|---|---|---|
| Execução | A sua aplicação | Servidor MCP remoto |
| Resultado | Envia-o de volta | Automático |
| Latência | Depende do seu código | Depende do servidor MCP |
| Configuração | Esquema JSON local | URL 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 decompletedoufailed - Trate as falhas de ligação MCP com resiliência: o agente pode prosseguir sem as ferramentas