Deep Agent SDK

Note: This package is developed with Bun but works with npm, pnpm, and yarn.

A TypeScript library for building controllable AI agents using Vercel AI SDK. This is a reimplementation of deepagentsjs without any LangChain/LangGraph dependencies.

What is Deep Agent?

Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks.

Deep Agent addresses these limitations through four core architectural components:

Component	Purpose	Implementation
Planning Tool	Long-term task breakdown and tracking	write_todos for maintaining task lists
Sub Agents	Task delegation and specialization	task tool for spawning specialized agents
File System Access	Persistent state and information storage	Virtual filesystem with read_file, write_file, edit_file
Detailed Prompts	Context-aware instructions	Sophisticated prompting strategies

Installation

# npm
npm install deepagentsdk

# pnpm
pnpm add deepagentsdk

# bun
bun add deepagentsdk

# yarn
yarn add deepagentsdk

CLI usage:

# Run without installing (recommended)
npx deepagentsdk

# Or with other package managers
pnpm dlx deepagentsdk
bunx deepagentsdk

Quick Start

import { createDeepAgent } from 'deepagentsdk';
import { anthropic } from '@ai-sdk/anthropic';

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  systemPrompt: 'You are an expert researcher.',
});

const result = await agent.generate({
  prompt: 'Research the topic of quantum computing and write a report',
});

console.log(result.text);
console.log('Todos:', result.state.todos);
console.log('Files:', Object.keys(result.state.files));

Features

Structured Output

Deep agents can return typed, validated objects using Zod schemas alongside text responses:

import { z } from 'zod';

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  output: {
    schema: z.object({
      summary: z.string(),
      keyPoints: z.array(z.string()),
    }),
    description: 'Research findings',
  },
});

const result = await agent.generate({
  prompt: "Research latest AI developments",
});

console.log(result.output?.summary);      // string
console.log(result.output?.keyPoints);    // string[]

Streaming with Events

Stream responses with real-time events for tool calls, file operations, and more:

for await (const event of agent.streamWithEvents({
  prompt: 'Build a todo app',
})) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.text);
      break;
    case 'tool-call':
      console.log(`Calling: ${event.toolName}`);
      break;
    case 'file-written':
      console.log(`Written: ${event.path}`);
      break;
  }
}

Built-in Tools

• Planning: write_todos for task management
• Filesystem: read_file, write_file, edit_file, ls, glob, grep
• Web: web_search, http_request, fetch_url (requires Tavily API key)
• Execute: Shell command execution with LocalSandbox backend
• Subagents: Spawn specialized agents for complex subtasks

Documentation

For comprehensive guides, API reference, and examples, visit deepagentsdk.vercel.app/docs

Key Documentation Sections

• Get Started - Installation and basic setup
• Guides - In-depth tutorials on:
  • Configuration options (models, backends, middleware)
  • Custom tools and subagents
  • Agent memory and persistence
  • Prompt caching and conversation summarization
  • Web tools and API integration
• Reference - Complete API documentation

CLI

The interactive CLI is built with Ink:

# Run without installing (recommended)
npx deepagentsdk

# With options
npx deepagentsdk --model anthropic/claude-haiku-4-5-20251001

API Keys: Load from environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, TAVILY_API_KEY) or .env file.

License

MIT