Tool Development Guide

How Tools Work

In OmniAgent, tools are business actions that the AI can invoke. Tools run in your frontend application (browser), allowing them to access your business APIs, databases, and UI directly.

Backend (Agent Loop) decides WHAT tool to call

Frontend (Your App) executes HOW the tool runs

Define a Tool

import { defineTool } from '@omniagent/core';
import { z } from 'zod';

export const querySalesTool = defineTool('query_sales', {
  description: 'Query sales data by date range and category',
  parameters: z.object({
    dateRange: z.string().describe('Date range, e.g. 2026-01-01~2026-03-31'),
    category: z.string().optional().describe('Product category'),
  }),

  // This runs in the browser — can call your APIs
  async execute(args, ctx) {
    const res = await fetch(`/api/sales?range=${args.dateRange}`);
    const data = await res.json();
    return {
      title: `Found ${data.length} records`,
      output: JSON.stringify(data),   // For the LLM
      metadata: { chart: data.chartUrl }, // For your UI
    };
  },
});

Tool Result Structure

Field Who Sees It Purpose
titleUserShort summary shown in the UI
outputLLMFull data for the AI to reason about
metadataFrontendExtra data for custom UI rendering

Require Confirmation

For dangerous operations (delete, submit, send), add confirmation:

const deleteTool = defineTool('delete_record', {
  description: 'Delete a database record',
  parameters: z.object({ id: z.string() }),
  requireConfirmation: true,  // User must confirm before execution
  async execute(args) {
    await fetch(`/api/records/${args.id}`, { method: 'DELETE' });
    return { title: 'Record deleted', output: 'Success' };
  },
});