Tools & Exa Search
Relevant source files
The following files were used as context for generating this wiki page:
Tools and Exa Search represent the functional extension layer of the OpenLive agent system. This system allows the primary voice agent to perform actions beyond text generation, such as searching the live web, fetching page content, managing a persistent memory of facts, and delegating complex research tasks to a specialized subagent.
The architecture is divided between "Main Agent" tools, which handle high-level interaction and delegation, and "Worker" tools, which perform the actual technical labor of web interaction. By using a delegated worker model, the system maintains low latency for voice interactions while performing deep research in the background.
Tool Architecture and Interface
The system defines a standard interface for tools through the TaktTool interface. Each tool includes a name, a description for the model, a JSON Schema for parameters (generated via Zod), and an execution function.
Sources: services/agent/src/tools.ts:14-25
Core Tool Definitions
Tools are categorized by their execution context. The Main Agent typically uses delegation and UI-related tools, while the Worker Agent utilizes web-specific tools.
| Tool Name | Scope | Description |
|---|---|---|
delegate | Main | Hands off web-research tasks to a subagent to keep the main conversation fluid. |
update_todos | Main | Publishes or updates a checklist shown in the UI. |
remember | Main | Saves persistent facts across turns into agent_notes. |
web_search | Worker | Performs web searches using the Exa API. |
fetch_url | Worker | Retrieves and cleans HTML content from a specific URL. |
Sources: services/agent/src/tools.ts:91-155
Exa Search Integration
The web_search tool is powered by Exa, integrated via the Model Context Protocol (MCP). The implementation uses a long-lived StreamableHTTPClientTransport to communicate with Exa's hosted MCP server.
Sources: services/agent/src/exa.ts:9-40
The Exa integration supports an optional exa_api_key from settings or environment variables to lift rate limits, though it can operate keylessly on a free tier.
Sources: services/agent/src/exa.ts:12-19
Delegation and Worker Logic
The delegate tool is a critical architectural component. Instead of the main voice agent executing slow web searches, it hands a "task" string to a subagent. This subagent runs in a separate runWorker loop, executing up to 5 steps of tool usage.
Multi-turn Worker Flow
While the worker is grinding through web results, the system can emit "narrations"—short spoken lines that inform the user of progress (e.g., "Reading through wikipedia.org now") to prevent "dead air" during long tool executions.
Security and Utility Utilities
SSRF Protection
The fetch_url tool includes an SSRF (Server-Side Request Forgery) guard. Before fetching any URL, the system performs a DNS lookup and checks the resulting IP against private, loopback, and metadata address ranges.
Sources: services/agent/src/tools.ts:51-69
HTML Processing
The htmlToText utility prepares web content for the LLM by:
- Removing
<script>and<style>blocks. - Stripping all HTML tags.
- Unescaping common entities (e.g.,
,&). - Collapsing whitespace and trimming.
Sources: services/agent/src/tools.ts:29-41
User Interface Mapping
The toolMeta.ts file maps internal tool names to human-readable labels, active status messages, and Lucide icons for the UI transcript and status lines.
| Tool | Label | Active Status | Icon |
|---|---|---|---|
web_search | Searched the web | Searching the web | Search |
fetch_url | Read a page | Reading a page | Globe |
remember | Saved a note | Saving a note | Bookmark |
update_todos | Updated the plan | Planning | ListTodo |
Sources: apps/web/src/lib/live/toolMeta.ts:5-15
Persistent Memory
The remember tool interacts with @openlive/db via getSetting and setSetting. It manages a JSON array of strings under the agent_notes key, capping the storage at the 50 most recent unique facts to maintain a relevant system prompt injection.
Sources: services/agent/src/tools.ts:133-145
The Tools and Exa Search system provides a robust framework for agentic behavior, balancing the immediate responsiveness required for voice interaction with the depth of capability provided by modern web-search APIs and delegated sub-processing.