@nextsparkjs/plugin-langchain 0.1.0-beta.1

package/docs/02-core-concepts/03-tools.md

@@ -0,0 +1,689 @@
+# Tools
+
+Tools are how agents interact with your data. This guide covers creating, configuring, and best practices for building agent tools.
+
+## What is a Tool?
+
+A tool is a function that an agent can call to perform actions or retrieve data. Tools have:
+
+1. **Name**: Unique identifier for the tool
+2. **Description**: Explains when to use the tool (read by the LLM)
+3. **Schema**: Zod schema defining input parameters
+4. **Function**: Async function that executes the action
+
+```typescript
+interface ToolDefinition<T extends z.ZodObject<any>> {
+    name: string
+    description: string
+    schema: T
+    func: (input: z.infer<T>) => Promise<string>
+}
+```
+
+## Creating Tools
+
+### Basic Tool
+
+```typescript
+import { z } from 'zod'
+import type { ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+const listItemsTool: ToolDefinition<typeof schema> = {
+    name: 'list_items',
+    description: 'List all items for the current user',
+    schema: z.object({
+        limit: z.number().optional().default(20).describe('Max items to return'),
+    }),
+    func: async ({ limit }) => {
+        const items = await ItemService.list(userId, { limit })
+        return JSON.stringify(items)
+    },
+}
+```
+
+### Tool Factory Pattern
+
+The recommended pattern is to create a factory function that receives context:
+
+```typescript
+import { z } from 'zod'
+import type { ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+interface ToolContext {
+    userId: string
+    teamId: string
+}
+
+export function createItemTools(context: ToolContext): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        {
+            name: 'list_items',
+            description: 'List all items for the current user',
+            schema: z.object({
+                limit: z.number().optional().default(20),
+            }),
+            func: async ({ limit }) => {
+                const items = await ItemService.list(userId, { limit })
+                return JSON.stringify(items)
+            },
+        },
+        {
+            name: 'create_item',
+            description: 'Create a new item',
+            schema: z.object({
+                name: z.string().describe('Item name'),
+                description: z.string().optional().describe('Item description'),
+            }),
+            func: async (data) => {
+                const item = await ItemService.create(userId, { ...data, teamId })
+                return JSON.stringify(item)
+            },
+        },
+    ]
+}
+```
+
+## Zod Schema Best Practices
+
+### Use Descriptive Fields
+
+The `.describe()` method helps the LLM understand parameters:
+
+```typescript
+schema: z.object({
+    // Good - describes the field purpose
+    query: z.string().describe('Search term to match against item names'),
+
+    // Good - explains valid values
+    status: z.enum(['active', 'completed', 'archived'])
+        .describe('Filter by item status'),
+
+    // Good - explains defaults
+    limit: z.number().optional().default(20)
+        .describe('Maximum items to return (default: 20)'),
+})
+```
+
+### Required vs Optional Fields
+
+```typescript
+schema: z.object({
+    // Required - must be provided
+    name: z.string().min(1).describe('Item name (required)'),
+
+    // Optional with default
+    priority: z.enum(['low', 'medium', 'high'])
+        .optional()
+        .default('medium')
+        .describe('Priority level'),
+
+    // Optional, truly optional
+    notes: z.string().optional().describe('Additional notes'),
+})
+```
+
+### Common Schema Patterns
+
+```typescript
+// Pagination
+z.object({
+    limit: z.number().optional().default(20),
+    offset: z.number().optional().default(0),
+})
+
+// Search
+z.object({
+    query: z.string().min(1).describe('Search query'),
+    limit: z.number().optional().default(10),
+})
+
+// Entity ID
+z.object({
+    entityId: z.string().describe('The unique identifier of the entity'),
+})
+
+// Date handling
+z.object({
+    dueDate: z.string().optional().describe('Due date in ISO format (YYYY-MM-DD)'),
+})
+
+// Arrays
+z.object({
+    tags: z.array(z.string()).optional().describe('List of tags'),
+    days: z.array(z.enum(['mon', 'tue', 'wed', 'thu', 'fri']))
+        .optional()
+        .describe('Days of the week'),
+})
+```
+
+## Real-World Examples
+
+### Task Tools
+
+```typescript
+// tools/tasks.ts
+import { z } from 'zod'
+import { TasksService } from '@/themes/default/entities/tasks/tasks.service'
+import type { ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+interface TaskToolContext {
+    userId: string
+    teamId: string
+}
+
+export function createTaskTools(context: TaskToolContext): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        {
+            name: 'list_tasks',
+            description: 'List tasks with optional filtering by status or priority.',
+            schema: z.object({
+                status: z.enum(['todo', 'in-progress', 'review', 'done', 'blocked'])
+                    .optional()
+                    .describe('Filter by task status'),
+                priority: z.enum(['low', 'medium', 'high', 'urgent'])
+                    .optional()
+                    .describe('Filter by priority level'),
+            }),
+            func: async (params) => {
+                try {
+                    const result = await TasksService.list(userId, params)
+                    return JSON.stringify(result.tasks.map(t => ({
+                        id: t.id,
+                        title: t.title,
+                        status: t.status,
+                        priority: t.priority,
+                        dueDate: t.dueDate,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error listing tasks: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'search_tasks',
+            description: 'Search tasks by keyword in title or description.',
+            schema: z.object({
+                query: z.string().describe('Search term'),
+            }),
+            func: async ({ query }) => {
+                try {
+                    const result = await TasksService.list(userId, {})
+                    const filtered = result.tasks.filter(t =>
+                        t.title.toLowerCase().includes(query.toLowerCase()) ||
+                        t.description?.toLowerCase().includes(query.toLowerCase())
+                    )
+                    return JSON.stringify(filtered.map(t => ({
+                        id: t.id,
+                        title: t.title,
+                        status: t.status,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error searching tasks: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'get_task_details',
+            description: 'Get full details of a specific task by ID.',
+            schema: z.object({
+                taskId: z.string().describe('The task ID to retrieve'),
+            }),
+            func: async ({ taskId }) => {
+                try {
+                    const task = await TasksService.getById(taskId, userId)
+                    if (!task) {
+                        return JSON.stringify({ error: 'Task not found' })
+                    }
+                    return JSON.stringify(task, null, 2)
+                } catch (error) {
+                    return `Error getting task: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'create_task',
+            description: 'Create a new task with title and optional details.',
+            schema: z.object({
+                title: z.string().min(1).describe('Task title (required)'),
+                description: z.string().optional().describe('Task description'),
+                priority: z.enum(['low', 'medium', 'high'])
+                    .optional()
+                    .default('medium')
+                    .describe('Priority level'),
+                dueDate: z.string().optional().describe('Due date (ISO format)'),
+            }),
+            func: async (data) => {
+                try {
+                    const task = await TasksService.create(userId, {
+                        ...data,
+                        teamId,
+                        status: 'todo',
+                    })
+                    return JSON.stringify({
+                        success: true,
+                        task,
+                        message: `Task created: ${task.title}`,
+                        link: `/dashboard/tasks/${task.id}`,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error creating task: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'update_task',
+            description: 'Update an existing task. Only specify fields you want to change.',
+            schema: z.object({
+                taskId: z.string().describe('The task ID to update'),
+                title: z.string().optional().describe('New title'),
+                description: z.string().optional().describe('New description'),
+                status: z.enum(['todo', 'in-progress', 'review', 'done', 'blocked']).optional(),
+                priority: z.enum(['low', 'medium', 'high']).optional(),
+                dueDate: z.string().optional(),
+            }),
+            func: async ({ taskId, ...updates }) => {
+                try {
+                    const task = await TasksService.update(userId, taskId, updates)
+                    return JSON.stringify({
+                        success: true,
+                        task,
+                        message: `Task updated: ${task.title}`,
+                        link: `/dashboard/tasks/${task.id}`,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error updating task: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+    ]
+}
+```
+
+### Customer Tools
+
+```typescript
+// tools/customers.ts
+import { z } from 'zod'
+import { CustomersService } from '@/themes/default/entities/customers/customers.service'
+import type { ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+export function createCustomerTools(context: { userId: string; teamId: string }): ToolDefinition<any>[] {
+    const { userId, teamId } = context
+
+    return [
+        {
+            name: 'list_customers',
+            description: 'List all customers with optional pagination and sorting.',
+            schema: z.object({
+                limit: z.number().optional().default(20).describe('Max customers'),
+                offset: z.number().optional().default(0).describe('Pagination offset'),
+                orderBy: z.enum(['name', 'account', 'office', 'salesRep', 'createdAt'])
+                    .optional()
+                    .describe('Sort field'),
+                orderDir: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+            }),
+            func: async (params) => {
+                try {
+                    const result = await CustomersService.list(userId, params)
+                    return JSON.stringify({
+                        customers: result.customers.map(c => ({
+                            id: c.id,
+                            name: c.name,
+                            account: c.account,
+                            office: c.office,
+                            phone: c.phone,
+                        })),
+                        total: result.total,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'search_customers',
+            description: 'Search customers by name, account, office, or sales rep.',
+            schema: z.object({
+                query: z.string().describe('Search term'),
+                limit: z.number().optional().default(10),
+            }),
+            func: async (params) => {
+                try {
+                    const results = await CustomersService.search(userId, params)
+                    return JSON.stringify(results.map(c => ({
+                        id: c.id,
+                        name: c.name,
+                        account: c.account,
+                        office: c.office,
+                        phone: c.phone,
+                    })), null, 2)
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'get_customer',
+            description: 'Get full details of a specific customer by ID.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to retrieve'),
+            }),
+            func: async ({ customerId }) => {
+                try {
+                    const customer = await CustomersService.getById(customerId, userId)
+                    if (!customer) {
+                        return JSON.stringify({ error: 'Customer not found' })
+                    }
+                    return JSON.stringify(customer, null, 2)
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'create_customer',
+            description: 'Create a new customer. Name, account, and office are required.',
+            schema: z.object({
+                name: z.string().describe('Customer or company name'),
+                account: z.number().describe('Unique account number'),
+                office: z.string().describe('Office location or branch'),
+                phone: z.string().optional().describe('Contact phone number'),
+                salesRep: z.string().optional().describe('Assigned sales representative'),
+                visitDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('Days for in-person visits'),
+                contactDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('Days for phone/email contact'),
+            }),
+            func: async (data) => {
+                try {
+                    const customer = await CustomersService.create(userId, {
+                        ...data,
+                        teamId,
+                    })
+                    return JSON.stringify({
+                        success: true,
+                        customer,
+                        link: `/dashboard/customers/${customer.id}`,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'update_customer',
+            description: 'Update a customer. Only specify fields to change.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to update'),
+                name: z.string().optional(),
+                phone: z.string().optional(),
+                office: z.string().optional(),
+                salesRep: z.string().optional(),
+                visitDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('New visit days'),
+                contactDays: z.array(z.enum(['lun', 'mar', 'mie', 'jue', 'vie']))
+                    .optional()
+                    .describe('New contact days'),
+            }),
+            func: async ({ customerId, ...updates }) => {
+                try {
+                    const customer = await CustomersService.update(userId, customerId, updates)
+                    return JSON.stringify({
+                        success: true,
+                        customer,
+                        link: `/dashboard/customers/${customer.id}`,
+                    }, null, 2)
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+        {
+            name: 'delete_customer',
+            description: 'Delete a customer permanently. This action cannot be undone.',
+            schema: z.object({
+                customerId: z.string().describe('The customer ID to delete'),
+            }),
+            func: async ({ customerId }) => {
+                try {
+                    const success = await CustomersService.delete(userId, customerId)
+                    return JSON.stringify({
+                        success,
+                        message: success ? 'Customer deleted successfully' : 'Failed to delete customer',
+                    })
+                } catch (error) {
+                    return `Error: ${error instanceof Error ? error.message : 'Unknown'}`
+                }
+            },
+        },
+    ]
+}
+```
+
+## Orchestrator Tools
+
+Orchestrator tools are special - they route requests to other agents:
+
+```typescript
+// tools/orchestrator.ts
+import { z } from 'zod'
+import type { ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+export interface RoutingResult {
+    agent: 'task' | 'customer' | 'page'
+    message: string
+}
+
+export interface ClarificationResult {
+    action: 'clarify'
+    question: string
+    options: Array<{ label: string; description: string }>
+}
+
+export function createOrchestratorTools(): ToolDefinition<any>[] {
+    return [
+        {
+            name: 'route_to_task',
+            description: 'Route to task agent for task-related requests.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({ agent: 'task', message } as RoutingResult)
+            },
+        },
+        {
+            name: 'route_to_customer',
+            description: 'Route to customer agent for customer-related requests.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({ agent: 'customer', message } as RoutingResult)
+            },
+        },
+        {
+            name: 'route_to_page',
+            description: 'Route to page agent for content/page requests.',
+            schema: z.object({
+                message: z.string().describe('The user message to forward'),
+            }),
+            func: async ({ message }) => {
+                return JSON.stringify({ agent: 'page', message } as RoutingResult)
+            },
+        },
+        {
+            name: 'ask_clarification',
+            description: 'Ask user for clarification when intent is unclear.',
+            schema: z.object({
+                question: z.string().describe('The clarifying question'),
+                options: z.array(z.object({
+                    label: z.string(),
+                    description: z.string(),
+                })).describe('Options for the user'),
+            }),
+            func: async ({ question, options }) => {
+                return JSON.stringify({
+                    action: 'clarify',
+                    question,
+                    options,
+                } as ClarificationResult)
+            },
+        },
+    ]
+}
+```
+
+## Building Tools with buildTools
+
+The plugin provides a `buildTools` helper:
+
+```typescript
+import { buildTools, type ToolDefinition } from '@/contents/plugins/langchain/lib/tools-builder'
+
+const toolDefinitions: ToolDefinition<any>[] = [
+    { name: 'tool1', schema: z.object({}), ... },
+    { name: 'tool2', schema: z.object({}), ... },
+]
+
+// Convert to LangChain DynamicStructuredTool instances
+const langChainTools = buildTools(toolDefinitions)
+```
+
+## Tool Response Format
+
+Tools should return JSON strings:
+
+```typescript
+// Good - structured response
+func: async () => {
+    const data = await Service.getData()
+    return JSON.stringify(data, null, 2)
+}
+
+// Good - with metadata
+func: async () => {
+    const item = await Service.create(...)
+    return JSON.stringify({
+        success: true,
+        item,
+        message: 'Created successfully',
+        link: `/items/${item.id}`,
+    }, null, 2)
+}
+
+// Good - error handling
+func: async () => {
+    try {
+        const data = await Service.getData()
+        return JSON.stringify(data)
+    } catch (error) {
+        return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
+    }
+}
+```
+
+## Error Handling
+
+Always handle errors gracefully:
+
+```typescript
+{
+    name: 'risky_operation',
+    schema: z.object({ id: z.string() }),
+    func: async ({ id }) => {
+        try {
+            const result = await Service.riskyOperation(id)
+            return JSON.stringify({ success: true, result })
+        } catch (error) {
+            // Return error as string - agent can inform user
+            if (error instanceof NotFoundError) {
+                return JSON.stringify({ error: 'Item not found', id })
+            }
+            if (error instanceof PermissionError) {
+                return JSON.stringify({ error: 'Access denied' })
+            }
+            return `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
+        }
+    },
+}
+```
+
+## Security Considerations
+
+### Always Use Context
+
+Tools receive context with user/team IDs - use them:
+
+```typescript
+createTools: (context) => [
+    {
+        func: async (params) => {
+            // Use context.userId for RLS
+            const data = await Service.list(context.userId, params)
+            return JSON.stringify(data)
+        },
+    },
+]
+```
+
+### Never Expose Internal IDs
+
+Return only necessary fields:
+
+```typescript
+// Bad - exposes internal data
+return JSON.stringify(fullDatabaseRecord)
+
+// Good - curated response
+return JSON.stringify({
+    id: record.id,
+    name: record.name,
+    // Exclude: internalId, secrets, etc.
+})
+```
+
+### Validate Before Destructive Actions
+
+```typescript
+{
+    name: 'delete_item',
+    description: 'Delete an item. This action cannot be undone.',
+    schema: z.object({
+        itemId: z.string(),
+        confirm: z.boolean().describe('Must be true to confirm deletion'),
+    }),
+    func: async ({ itemId, confirm }) => {
+        if (!confirm) {
+            return JSON.stringify({
+                error: 'Deletion not confirmed',
+                message: 'Set confirm=true to proceed',
+            })
+        }
+        await Service.delete(itemId)
+        return JSON.stringify({ success: true, deleted: itemId })
+    },
+}
+```
+
+## Using Presets
+
+The plugin includes a tools preset:
+
+```bash
+cp contents/plugins/langchain/presets/lib/tools/entity-tools.ts.preset \
+   contents/themes/your-theme/lib/langchain/tools/my-entity.ts
+```
+
+## Next Steps
+
+- [Set up graph orchestration](../03-orchestration/01-graph-orchestrator.md) (recommended)
+- [Advanced customization](../05-reference/02-customization.md)
+- [Configure observability](../04-advanced/01-observability.md)