Tool Calling

​

How it works

1. Define tools using the OpenAI function calling schema
2. Register them when creating the VoiceAgentClient
3. Respond to the tool_call event, which fires once per call with { name, arguments, call_id } (arguments is a JSON string)
4. Submit the result with submitToolResult(call_id, result); result may be a string or an object

​

Defining tools

import { VoiceAgentClient } from '@lokutor/sdk';

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather for a city',
      parameters: {
        type: 'object',
        properties: {
          city: { type: 'string', description: 'City name' }
        },
        required: ['city']
      }
    }
  }
];

const client = new VoiceAgentClient({
  auth: getTicket, // or apiKey: process.env.LOKUTOR_API_KEY on a server
  prompt: 'You are a helpful assistant.',
  tools,
});

​

Handling tool calls

client.on('tool_call', async ({ name, arguments: args, call_id }) => {
  if (name === 'get_weather') {
    try {
      const result = await fetchWeather(JSON.parse(args).city);
      client.submitToolResult(call_id, result);
    } catch (e) {
      client.submitToolResult(call_id, { error: 'Weather service unavailable' });
    }
  }
});

import json

def on_tool_call(name, arguments, call_id):
    if name == "get_weather":
        city = json.loads(arguments)["city"]
        client.submit_tool_result(call_id, {"forecast": fetch_weather(city)})

client = VoiceAgentClient(api_key=os.environ["LOKUTOR_API_KEY"], prompt="…", tools=tools,
                          on_tool_call=on_tool_call)

​

Multi-step tool chains

​

Built-in tools

{
  "type": "function",
  "function": {
    "name": "search_knowledge_base",
    "description": "Search the knowledge base for information relevant to the user's question.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "The search query — a question or keywords about what you need to find" }
      },
      "required": ["query"]
    }
  }
}

​

web_search (opt-in)

{
  "type": "function",
  "function": {
    "name": "web_search",
    "description": "Search the web for current, public information the caller asked about ...",
    "parameters": {
      "type": "object",
      "properties": { "query": { "type": "string", "description": "A short, specific web search query." } },
      "required": ["query"]
    }
  }
}

​

Google Calendar (opt-in)

• check_availability { "date": "YYYY-MM-DD" } returns the free start times that day, e.g. { "date": "2026-09-24", "timezone": "Europe/Madrid", "appointment_minutes": 30, "free": ["09:00", "09:30", "11:00"] }.
• book_appointment { "date", "time": "HH:MM", "caller_name", "caller_phone"?, "caller_email"?, "reason"? } creates the event on your primary calendar and returns { "booked": true, ... }. With caller_email, the caller is sent the invitation, which includes a Google Meet link. If the time was taken in the meantime, it returns { "booked": false, "free": [...] } so the agent can offer another time. The agent reads the email back to the caller before booking. An address that cannot be right (not an address, a made-up subdomain of a mail provider such as [email protected], or a domain that does not exist) stops the booking with { "booked": false, "reason": ... }, and the agent confirms it with the caller instead of sending the invitation to nobody. Addresses the caller dictates (“ana punto ruiz arroba gmail punto com”, “ana dot ruiz at gmail dot com”) appear written out ([email protected]) in the transcript and the collected data.

​

Your CRM (opt-in)

• The caller is recognised. When the call starts, the agent looks the caller up by phone number (the caller’s number on an inbound phone call, the number dialled on an outbound one) or by the caller_phone / caller_email a web session passes (see Voice Chat). If the CRM has a record, the agent gets a short summary of it (name, company, email, open deals, the latest note) a few seconds into the call, and uses it instead of asking again. The lookup runs alongside the greeting; it never delays the agent’s first words.
• A caller calling from another number can still be recognised. The agent is offered one server-side tool, crm_identify_caller { "email"?, "phone"?, "name"? }, for when the caller was not recognised and tells it who they are. It returns { "found": true, "record": "..." } or { "found": false }, and takes a few seconds, so the agent says it is checking.
• The call is logged. When it ends, the call’s summary, outcome, transcript and everything the agent’s data fields collected are written on the caller’s record, as a call where the CRM has calls and as a note otherwise. Collected values fill in the contact’s name, email, phone, company or job title only where those are empty; nothing the CRM already holds is overwritten. A caller the CRM has never seen is created as a new contact (a lead in Salesforce and Zoho).

​

Transfer to a person (opt-in, phone calls)

​

Earlier calls (always on, not a tool)

​

Date and time (always on, not a tool)

​

Best practices

• Keep it fast: tool handlers should return within a few seconds. Slow tools leave the agent in a “thinking” state.
• Clear descriptions: the model relies on description to decide when to use a tool.
• Handle errors: return an error message as the result; the agent tells the user.
• Answer every call: a tool_call without a tool_result leaves the agent waiting.

​

Raw WebSocket protocol

{ "type": "tools", "data": [{ "type": "function", "function": { "name": "get_time", "description": "Current time", "parameters": { "type": "object", "properties": {} } } }] }

{ "type": "tool_call", "name": "get_time", "arguments": "{}", "call_id": "..." }

{ "type": "tool_result", "data": { "call_id": "...", "result": "..." } }