MCP-gebeurtenissen in spraakgesprekken
Op deze pagina
MCP in de Voice Agent
Het Model Context Protocol (MCP) stelt uw spraakagent in staat verbinding te maken met externe tool-servers via een gestandaardiseerd protocol. Wanneer u een MCP-tool configureert in uw sessie, zendt de Voice Agent API specifieke gebeurtenissen uit voor elke stap van de interactie met de MCP-server.
Een MCP-tool configureren
Om een MCP-server in uw spraaksessie in te schakelen, voegt u deze toe aan de lijst met tools:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "mcp",
"server_url": "https://mon-serveur-mcp.exemple.com/sse",
"server_label": "Internal CRM"
}
]
}
}
Het veld server_url verwijst naar uw MCP-server en server_label is een leesbare naam die de server identificeert in de logs.
Tool-discovery
Wanneer de agent verbinding maakt met de MCP-server, haalt deze eerst de lijst met beschikbare tools op. Drie gebeurtenissen markeren deze fase.
mcp_list_tools.in_progress
{
"type": "mcp_list_tools.in_progress",
"server_label": "Internal CRM"
}
De MCP-server wordt ondervraagd om zijn lijst met tools.
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"
}
]
}
De lijst met tools is succesvol opgehaald. De spraakagent kan deze nu gebruiken in het gesprek.
mcp_list_tools.failed
{
"type": "mcp_list_tools.failed",
"server_label": "Internal CRM",
"error": {
"message": "Connection timeout"
}
}
De verbinding met de MCP-server is mislukt. De agent zet het gesprek voort zonder deze tools.
MCP-tool-aanroepen
Wanneer de agent besluit tijdens het gesprek een MCP-tool te gebruiken, worden er meer gebeurtenissen gegenereerd.
response.mcp_call_arguments.delta / .done
Net als bij de reguliere gebeurtenissen voor functieaanroepen, streamen deze de argumenten van de aanroep:
{
"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
Deze gebeurtenissen volgen de uitvoering van de aanroep op de MCP-server:
{
"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"
}
}
Verschil met reguliere functieaanroepen
MCP-tools draaien aan de serverzijde, via de infrastructuur van xAI, zodat u de uitvoering niet zelf hoeft af te handelen. Dat is het belangrijkste verschil met reguliere functieaanroepen, waarbij uw applicatie de functie moet uitvoeren en het resultaat moet terugsturen.
| Aspect | Functieaanroep | MCP |
|---|---|---|
| Uitvoering | Uw app | Externe MCP-server |
| Resultaat | U stuurt het terug | Automatisch |
| Latentie | Afhankelijk van uw code | Afhankelijk van de MCP-server |
| Configuratie | Lokaal JSON-schema | MCP-server-URL |
MCP-gebeurtenissen afhandelen in uw app
Hier volgt een voorbeeld van een complete handler voor MCP-gebeurtenissen:
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;
}
});
Belangrijkste punten
- MCP-tools stellen de spraakagent in staat om via een gestandaardiseerd protocol met externe servers te werken
- Tool-discovery gebeurt automatisch via de
mcp_list_tools-gebeurtenissen - MCP-aanroepen draaien aan de serverzijde, in tegenstelling tot reguliere functieaanroepen
- Elke aanroep doorloopt drie mogelijke statussen:
in_progress, gevolgd doorcompletedoffailed - Handel MCP-verbindingsfouten op een gracieuze manier af: de agent kan zonder de tools verdergaan