Skip to main content

​
Overview

The @deepagents/toolbox package provides ready-to-use tools for common agent tasks. All tools are compatible with the Vercel AI SDK and can be directly used with @deepagents/agent.

​
Installation

npm install @deepagents/toolbox
Dependencies:
  • ai - Vercel AI SDK
  • zod - Schema validation
  • duck-duck-scrape - DuckDuckGo search
  • nano-spawn - Process execution
  • fast-glob - File searching
  • @deepagents/retrieval - Document retrieval

​
Quick Example

import { agent, execute } from '@deepagents/agent';
import { openai } from '@ai-sdk/openai';
import { ddgSearch, hackernewsSearch, weather } from '@deepagents/toolbox';

const assistant = agent({
  name: 'assistant',
  model: openai('gpt-4o'),
  prompt: 'You help users find information.',
  tools: {
    search: ddgSearch,
    news: hackernewsSearch,
    getWeather: weather,
  },
});

const stream = execute(
  assistant,
  'What is the weather in Tokyo and latest tech news?',
  {}
);

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

​
Web Search Tools

Search the web using DuckDuckGo: 
import { ddgSearch } from '@deepagents/toolbox';

const tool = ddgSearch;

// In agent
const agent = agent({
  name: 'searcher',
  model: openai('gpt-4o'),
  prompt: 'Search the web for information.',
  tools: { search: ddgSearch },
});
Parameters:
  • query: string - Search query
  • maxResults?: number - Maximum results (default: 5)
Returns: 
{
  results: Array<{
    title: string;
    url: string;
    snippet: string;
  }>;
}

​
Web Search (General)

General web search abstraction: 
import { webSearch } from '@deepagents/toolbox';

const tool = webSearch({
  provider: 'duckduckgo', // or 'google', 'bing'
  apiKey: process.env.SEARCH_API_KEY, // if needed
});
Search HackerNews stories: 
import { hackernewsSearch } from '@deepagents/toolbox';

const tool = hackernewsSearch;

// Usage
const agent = agent({
  name: 'news_agent',
  model: openai('gpt-4o'),
  prompt: 'Find tech news on HackerNews.',
  tools: { hnSearch: hackernewsSearch },
});
Parameters:
  • query: string - Search query
  • limit?: number - Max results (default: 10)
  • sort?: 'relevance' | 'date' - Sort order
Returns: 
{
  stories: Array<{
    title: string;
    url: string;
    points: number;
    author: string;
    time: string;
    comments: number;
  }>;
}

​
Filesystem Tools

File operations for agents: 
import {
  readFile,
  writeFile,
  listFiles,
  deleteFile,
} from '@deepagents/toolbox';

const agent = agent({
  name: 'file_manager',
  model: openai('gpt-4o'),
  prompt: 'Manage files for the user.',
  tools: {
    read: readFile,
    write: writeFile,
    list: listFiles,
    delete: deleteFile,
  },
});

​
Read File

import { readFile } from '@deepagents/toolbox';

// Parameters
{
  path: string;           // File path
  encoding?: string;      // default: 'utf-8'
}

// Returns
{
  content: string;
  size: number;
  modified: string;
}

​
Write File

import { writeFile } from '@deepagents/toolbox';

// Parameters
{
  path: string;
  content: string;
  encoding?: string;
  createDirs?: boolean;   // Create parent dirs
}

// Returns
{
  success: boolean;
  path: string;
  size: number;
}

​
List Files

import { listFiles } from '@deepagents/toolbox';

// Parameters
{
  path: string;           // Directory path
  pattern?: string;       // Glob pattern
  recursive?: boolean;    // Include subdirs
}

// Returns
{
  files: Array<{
    name: string;
    path: string;
    size: number;
    modified: string;
    isDirectory: boolean;
  }>;
}
Filesystem tools can access any file the process has permissions for. Use with caution and implement proper access controls.

​
Data Tools

​
Scratchpad

Temporary note storage: 
import { scratchpad } from '@deepagents/toolbox';

const agent = agent({
  name: 'assistant',
  model: openai('gpt-4o'),
  prompt: 'Use scratchpad for temporary notes.',
  tools: { notes: scratchpad },
});
Operations:
  • write(key, value) - Save note
  • read(key) - Retrieve note
  • list() - List all notes
  • delete(key) - Remove note

​
Weather Data

Get weather information: 
import { weather } from '@deepagents/toolbox';

const tool = weather({
  apiKey: process.env.WEATHER_API_KEY,
  provider: 'openweather', // or 'weatherapi'
});
Parameters: 
{
  location: string;       // City name or coordinates
  units?: 'metric' | 'imperial';
}
Returns: 
{
  location: string;
  temperature: number;
  condition: string;
  humidity: number;
  windSpeed: number;
  forecast?: Array<{
    date: string;
    high: number;
    low: number;
    condition: string;
  }>;
}

​
Format Tools

​
User Story Formatter

Format requirements as user stories: 
import { userStoryFormatter } from '@deepagents/toolbox';

const tool = userStoryFormatter;

// Parameters
{
  feature: string;        // Feature description
  role?: string;          // User role
  benefit?: string;       // Expected benefit
}

// Returns
{
  userStory: string;      // Formatted user story
  acceptanceCriteria: string[];
}
Example Output: 
As a user
I want to export data to CSV
So that I can analyze it in Excel

Acceptance Criteria:
- User can select export format
- CSV includes all visible columns
- File downloads automatically

​
Container Tools

Docker container management: 
import { containerTool } from '@deepagents/toolbox';

const tool = containerTool({
  dockerSocket: '/var/run/docker.sock',
});

const agent = agent({
  name: 'devops',
  model: openai('gpt-4o'),
  prompt: 'Manage Docker containers.',
  tools: { container: tool },
});
Operations:
  • list() - List containers
  • start(containerId) - Start container
  • stop(containerId) - Stop container
  • logs(containerId) - Get logs
  • inspect(containerId) - Inspect container

​
Custom Tool Wrappers

​
Rate Limited Tool

Add rate limiting to any tool: 
import { rateLimited } from '@deepagents/toolbox';

const limitedSearch = rateLimited(ddgSearch, {
  maxCalls: 10,
  windowMs: 60000, // 1 minute
});

​
Cached Tool

Cache tool results: 
import { cached } from '@deepagents/toolbox';

const cachedSearch = cached(ddgSearch, {
  ttl: 300000, // 5 minutes
  maxSize: 100,
});

​
Logged Tool

Add logging to tool calls: 
import { logged } from '@deepagents/toolbox';

const loggedSearch = logged(ddgSearch, {
  logFn: (params, result) => {
    console.log('Search:', params.query, '→', result.results.length, 'results');
  },
});

​
Creating Custom Tools

Build your own tools: 
import { tool } from 'ai';
import { z } from 'zod';

export const customTool = tool({
  description: 'Your tool description',
  parameters: z.object({
    param1: z.string(),
    param2: z.number().optional(),
  }),
  execute: async ({ param1, param2 }) => {
    // Your implementation
    return {
      result: 'data',
    };
  },
});

​
Tool with Context

import { toState } from '@deepagents/agent';

interface MyContext {
  userId: string;
}

export const contextAwareTool = tool({
  description: 'Tool that uses context',
  parameters: z.object({
    action: z.string(),
  }),
  execute: async ({ action }, options) => {
    const ctx = toState<MyContext>(options);
    
    // Use context
    console.log('User:', ctx.userId);
    
    return { success: true };
  },
});

​
Tool Composition

Combine multiple tools: 
import { composeTool } from '@deepagents/toolbox';

const searchAndFormat = composeTool({
  tools: [ddgSearch, userStoryFormatter],
  combine: async (searchResults, formatted) => {
    return {
      data: searchResults,
      formatted: formatted,
    };
  },
});

​
Best Practices

Error Handling

Always handle errors gracefully in tools

Timeouts

Set reasonable timeouts for network calls

Validation

Validate all inputs with Zod schemas

Documentation

Write clear descriptions and examples

Rate Limits

Respect API rate limits

Security

Never expose sensitive data in responses

​
Complete Example

import { agent, execute } from '@deepagents/agent';
import { openai } from '@ai-sdk/openai';
import {
  ddgSearch,
  hackernewsSearch,
  weather,
  readFile,
  writeFile,
  scratchpad,
  rateLimited,
  cached,
} from '@deepagents/toolbox';

// Create rate-limited and cached tools
const safeSearch = rateLimited(
  cached(ddgSearch, { ttl: 300000 }),
  { maxCalls: 20, windowMs: 60000 }
);

const assistant = agent({
  name: 'assistant',
  model: openai('gpt-4o'),
  prompt: `You are a helpful assistant with access to:
    - Web search
    - HackerNews
    - Weather data
    - File operations
    - Temporary notes`,
  tools: {
    search: safeSearch,
    news: hackernewsSearch,
    weather: weather({ apiKey: process.env.WEATHER_KEY }),
    read: readFile,
    write: writeFile,
    notes: scratchpad,
  },
});

const stream = execute(
  assistant,
  'Research the latest in AI and save a summary to research.md',
  {}
);

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}

​
Package Info

@deepagents/agent

Use tools with agents

@deepagents/retrieval

Document retrieval tools

Build docs developers (and LLMs) love

Get started for freeTalk to us