Overview

Loquent agents use tools in two contexts: voice tools run during live phone calls via the realtime API, and task tools run after calls when the todo execution agent processes approved tasks.

Two Tool Systems

Voice Tools

Used by the realtime voice model during a live call. Registered at session start via collect_agent_tools, dispatched through handle_tool_call. Results are spoken to the caller.

Tool	When Registered	Parameters
query_knowledge	Agent has linked knowledge bases	query: String
lookup_caller	Org has client_lookup_url configured	None (phone injected)

Definition type: AgentToolDefinition — provider-agnostic, converted to OpenAI/Gemini formats at session start.

pub struct AgentToolDefinition {
    pub name: String,
    pub description: String,
    pub parameters: serde_json::Value,  // JSON Schema
}

Task Tools

Used by the todo execution AI agent (GPT-5) when processing approved todos. Registered per-todo based on the TodoType’s assigned tools. Run in a standard chat completion agentic loop, not a realtime session.

Tool	What It Does
send_email_to_caller	Compose and send a follow-up email to the caller

Definition type: aisdk::Tool — includes an executable closure, capped at 10 tool-calling steps per todo.

Voice Tool Pipeline

Session start → collect_agent_tools(agent_id, org_id)
  → build_knowledge_tool_definition(agent_id)
  → build_client_lookup_tool_definition(org_id)
  → Return (Vec<AgentToolDefinition>, prompt_addendum)

During call → Model invokes a tool
  → handle_tool_call routes by function_name
  → Handler executes and returns result string
  → Result sent back to realtime model as tool response

Task Tool Pipeline

Todo approved → execute_todos_job picks it up (every 30s)
  → execute_todo(todo_id)
      Load TodoType → get assigned SystemTools
      Build aisdk::Tool for each
      Run GPT-5 agentic loop (max 10 steps)
      AI decides which tools to call and with what arguments

Error Handling

Both systems convert errors to strings and return them to the AI model. The conversation or task continues even if a tool fails. Errors are logged via tracing::error!.

Adding a New Tool

Voice Tool

1. Create a builder returning Option<AgentToolDefinition>
2. Call it in collect_agent_tools and push to the tools vector
3. Add a match arm in handle_tool_call
4. Implement the handler function

Task Tool

1. Add a variant to the SystemTool enum
2. Implement display_name(), description(), as_str(), from_str()
3. Add a match arm in execute_todo to build the aisdk::Tool
4. Implement the execution function

Related Pages

• Agent — owns the voice tool pipeline
• Todos — owns the task tool pipeline