Deep Agent Overview

ai-sdk-deep-agent is a TypeScript library for building agents that can tackle complex, multi-step tasks. Built on Vercel AI SDK v6 and inspired by applications like Claude Code, Deep Research, and LangChain's DeepAgents, this library provides:

• Planning and task decomposition via built-in write_todos tool
• Virtual filesystem for context management across tool calls
• Subagent spawning for context isolation and specialized work
• Long-term memory for cross-conversation persistence
• Human-in-the-loop workflows for sensitive operations
• Composable middleware for custom behavior

When to Use Deep Agent

Use deep agents when you need agents that can:

• ✅ Handle complex, multi-step tasks that require planning and decomposition
• ✅ Manage large amounts of context through filesystem tools
• ✅ Delegate work to specialized subagents for context isolation
• ✅ Persist memory across conversations and threads
• ✅ Support human-in-the-loop workflows for safety

For simpler use cases, consider using AI SDK's generateText or building a custom ToolLoopAgent.

Core Capabilities

Planning and Task Decomposition

Deep agents include a built-in write_todos tool that enables agents to break down complex tasks into discrete steps, track progress, and adapt plans as new information emerges.

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

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
});

const result = await agent.generate({
  prompt: 'Build a REST API with authentication',
});

console.log(result.state.todos);
// [
//   { content: 'Design API endpoints', status: 'completed' },
//   { content: 'Implement authentication middleware', status: 'in_progress' },
//   { content: 'Add input validation', status: 'pending' }
// ]

Context Management

Filesystem tools (ls, read_file, write_file, edit_file) allow agents to offload large context to memory, preventing context window overflow and enabling work with variable-length tool results.

const result = await agent.generate({
  prompt: 'Analyze this codebase and document the architecture',
});

// Agent writes findings to files for reference
console.log(Object.keys(result.state.files));
// ['/architecture.md', '/components.md', '/data-flow.md']

Subagent Spawning

A built-in task tool enables agents to spawn specialized subagents for context isolation. This keeps the main agent's context clean while still going deep on specific subtasks.

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  subagents: [
    {
      name: 'code-reviewer',
      description: 'Reviews code for bugs and best practices',
      systemPrompt: 'You are an expert code reviewer...',
    },
    {
      name: 'test-writer',
      description: 'Writes comprehensive tests',
      systemPrompt: 'You are a testing specialist...',
    },
  ],
});

// Main agent can delegate to subagents
const result = await agent.generate({
  prompt: 'Review this code and write tests for it',
});

Long-term Memory

Extend agents with persistent memory across threads using pluggable backends. Agents can save and retrieve information from previous conversations.

import { CompositeBackend, StateBackend, PersistentBackend } from 'ai-sdk-deep-agent';

const backend = new CompositeBackend(
  new StateBackend(), // Ephemeral by default
  {
    '/memories/': new PersistentBackend({ store: myStore }),
  }
);

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  backend,
  systemPrompt: `Save user preferences to /memories/preferences.txt
  and read them at the start of each conversation.`,
});

Human-in-the-Loop

Configure tools to require human approval before execution, enabling safe workflows for sensitive operations.

const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  interruptOn: {
    write_file: true, // Require approval
    edit_file: true,
    execute: true,
  },
});

for await (const event of agent.streamWithEvents({
  prompt: 'Delete all test files',
  onApprovalRequest: async ({ toolName, args }) => {
    console.log(`Tool ${toolName} requires approval`);
    return await askUser();
  },
})) {
  // Handle events...
}

Relationship to the AI SDK Ecosystem

ai-sdk-deep-agent is built on top of:

• Vercel AI SDK v6 - Provides the underlying ToolLoopAgent, tools, and model integrations
• Language Model Providers - Works with Anthropic, OpenAI, Azure, and more via @ai-sdk/* packages
• TypeScript - Full type safety and excellent developer experience

The library extends AI SDK's ToolLoopAgent with:

• State management for todos and files
• Built-in filesystem and planning tools
• Subagent spawning capabilities
• Checkpointing and session persistence
• Human-in-the-loop workflows

Get Started

Key Differences from Basic Tool-Calling Agents

Basic Tool-Calling Agent

// Single tool call, no state, no planning
const result = await generateText({
  model: anthropic('claude-sonnet-4-5-20250929'),
  tools: {
    web_search: mySearchTool,
  },
  prompt: 'Search for information about X',
});

Limitations:

• ❌ No task planning or decomposition
• ❌ No state across tool calls
• ❌ Context fills up with intermediate results
• ❌ Can't delegate to specialized helpers
• ❌ No persistent memory

Deep Agent

// Multi-step planning, stateful execution, subagents
const agent = createDeepAgent({
  model: anthropic('claude-sonnet-4-5-20250929'),
  tools: { web_search: mySearchTool },
});

const result = await agent.generate({
  prompt: 'Research X and write a comprehensive report',
});

Advantages:

• ✅ Automatic task planning via write_todos
• ✅ Stateful execution (todos, files persist)
• ✅ Context offloading to filesystem
• ✅ Subagent delegation for complex subtasks
• ✅ Persistent memory across conversations
• ✅ Human-in-the-loop approval workflows

Architecture

ai-sdk-deep-agent wraps AI SDK's ToolLoopAgent with additional capabilities:

This approach means:

• Compatibility: Works with any AI SDK model provider
• Composability: Use with other AI SDK features
• Upgradability: Benefits from AI SDK improvements
• Simplicity: Clean API, no hidden magic

Feature Parity with LangChain DeepAgents

This library implements the same core features as LangChain's DeepAgents framework:

Key difference: Built on AI SDK v6 instead of LangGraph, with TypeScript-first design and full type safety.

Next Steps

1. Quickstart Guide - Build your first agent
2. Customization Guide - Configure prompts, tools, and backends
3. Agent Harness - Deep dive into capabilities
4. Examples - Learn by doing
5. CLI - Interactive development experience