tool-generation

# Tool Generation for DEVS Tools are capabilities that LLM agents can invoke during conversations. They enable agents to search documents, execute code, interact with external services, and perform specialized operations. This guide covers the complete process of creating, registering, and testing new tools. ## Architecture Overview ``` Tool Definition (types.ts) → Tool Handler (service.ts) ↓ ↓ ToolDefinition Handler Function (JSON Schema) (async function) ↓ ↓ Tool Registration (executor.ts) ↓ KnowledgeToolRegistry.register() ↓ Available to all agents via chat.ts ``` ## Directory Structure Tools are organized by feature domain: ``` src/lib/ ├── tool-executor/ │ ├── types.ts # Core tool executor types │ ├── executor.ts # Registry, executor, registration functions │ └── index.ts # Public exports ├── knowledge-tools/ # Document search/read tools │ ├── types.ts # Params, results, and KNOWLEDGE_TOOL_DEFINITIONS │ └── service.ts # Handler implementations ├── math-tools/ # Calculation tools │ ├── types.ts # MATH_TOOL_DEFINITIONS │ └── service.ts # calculate() handler ├── code-tools/ # Code execution tools │ ├── types.ts # CODE_TOOL_DEFINITIONS │ └── service.ts # execute() handler └── features/connectors/tools/ # External service tools ├── types.ts # CONNECTOR_TOOL_DEFINITIONS └── service.ts # Gmail, Drive, etc. handlers ``` ## Step 1: Define Types Create parameter and result interfaces in `types.ts`: ```typescript /** * My Tool Types * @module lib/my-tools/types */ import type { ToolDefinition } from '@/lib/llm/types' // ============================================================================ // Tool Parameter Types // ============================================================================ /** * Parameters for the my_tool operation. * Document each parameter with JSDoc. */ export interface MyToolParams { /** * Required parameter description. */ requiredParam: string /** * Optional parameter with default value. * @default 10 */ optionalParam?: number /** * Filter by specific values. */ filter?: ('value1' | 'value2' | 'value3')[] } // ============================================================================ // Tool Result Types // ============================================================================ /** * Result of my_tool operation. */ export interface MyToolResult { /** Whether the operation succeeded */ success: boolean /** Error message if failed */ error?: string /** The operation result data */ data: MyToolData | null /** Execution duration in milliseconds */ duration_ms: number } /** * Data returned by my_tool. */ export interface MyToolData { id: string name: string // ... other fields } // ============================================================================ // Tool Name Type // ============================================================================ /** * Names of all tools in this module. */ export type MyToolName = 'my_tool' | 'my_other_tool' // ============================================================================ // Tool Definitions // ============================================================================ /** * Pre-defined tool definitions for my tools. * These can be directly passed to LLM requests. */ export const MY_TOOL_DEFINITIONS: Record<MyToolName, ToolDefinition> = { my_tool: { type: 'function', function: { name: 'my_tool', description: 'Brief description of what the tool does. ' + 'Include usage context: when to use it, what it returns. ' + 'Mention any important limitations or requirements.', parameters: { type: 'object', properties: { requiredParam: { type: 'string', description: 'What this parameter does and expected values', }, optionalParam: { type: 'integer', description: 'Optional description (default: 10)', minimum: 1, maximum: 100, }, filter: { type: 'array', description: 'Filter results by these values', items: { type: 'string', enum: ['value1', 'value2', 'value3'], }, }, }, required: ['requiredParam'], }, }, }, my_other_tool: { // ... another tool definition }, } ``` ## Step 2: Implement Handler Create handler functions in `service.ts`: ````typescript /** * My Tool Service * @module lib/my-tools/service */ import type { MyToolParams, MyToolResult } from './types' import { db } from '@/lib/db' /** * Execute the my_tool operation. * * @param params - Tool parameters * @returns Operation result * * @example * ```typescript * const result = await myTool({ requiredParam: 'value' }) * if (result.success) { * console.log(result.data) * } * ``` */ export async function myTool(params: MyToolParams): Promise<MyToolResult> { const startTime = performance.now() try { // 1. Validate parameters if (!params.requiredParam) { return { success: false, error: 'requiredParam is required', data: null, duration_ms: performance.now() - startTime, } } // 2. Perform operation const data = await performOperation(params) // 3. Return success result return { success: true, data, duration_ms: performance.now() - startTime, } } catch (error) { // 4. Handle errors gracefully return { success: false, error: error instanceof Error ? error.message : String(error), data: null, duration_ms: performance.now() - startTime, } } } // Re-export definitions for convenience export { MY_TOOL_DEFINITIONS } from './types' ```` ## Step 3: Register Tools Add registration in `src/lib/tool-executor/executor.ts`: ### 3a. Import Dependencies ```typescript // At top of executor.ts import { myTool, MY_TOOL_DEFINITIONS } from '@/lib/my-tools/service' import type { MyToolParams, MyToolResult } from '@/lib/my-tools/types' ``` ### 3b. Create Registration Function ```typescript // ============================================================================ // My Tools Registration // ============================================================================ /** * Register all my tools with the default registry. * Call this during application initialization. */ export function registerMyTools(): void { defaultRegistry.register<MyToolParams, MyToolResult>( MY_TOOL_DEFINITIONS.my_tool, async (args, context) => { // Check for abort signal if (context.abortSignal?.aborted) { throw new Error('Aborted') } return myTool(args) }, { tags: ['my-category'], // Used for filtering tools estimatedDuration: 500, // Helps with timeout estimation requiresConfirmation: false, // Set true for destructive operations }, ) } /** * Check if my tools are registered. */ export function areMyToolsRegistered(): boolean { return defaultRegistry.has('my_tool') } /** * Unregister all my tools from the default registry. */ export function unregisterMyTools(): void { defaultRegistry.unregister('my_tool') } ``` ### 3c. Call Registration at App Init In `src/app/App.tsx` or initialization code: ```typescript import { registerMyTools } from '@/lib/tool-executor' // In initialization effect useEffect(() => { registerMyTools() }, []) ``` ## Step 4: Make Tools Available to Agents ### Universal Tools (Available to All Agents) Add to `getAgentToolDefinitions` in `src/lib/chat.ts`: ```typescript import { MY_TOOL_DEFINITIONS } from '@/lib/my-tools' function getAgentToolDefinitions(_agent: Agent): ToolDefinition[] { return [ ...Object.values(KNOWLEDGE_TOOL_DEFINITIONS), ...Object.values(MATH_TOOL_DEFINITIONS), ...Object.values(CODE_TOOL_DEFINITIONS), ...Object.values(MY_TOOL_DEFINITIONS), // Add here ] } ``` ### Conditional Tools (Based on Agent Config) For tools that should only be available to specific agents: ```typescript function getAgentToolDefinitions(agent: Agent): ToolDefinition[] {