Deep Agent SDK：让 AI Agent 真正"深"起来

一句话：一个基于 Vercel AI SDK v6 构建的深度 Agent 框架，解决"浅层 Agent"只会机械调用工具、缺乏长期规划和任务分解能力的根本问题。

痛点：如果你的 AI Agent 只会"一竿子插到底"

想象你让一个普通 Agent 帮你"做一个数据可视化 Dashboard"。它很可能：

• 直接开始写代码，中间遇到 bug 停下来
• 没有把任务拆成"数据获取 → 数据清洗 → 图表选型 → 界面实现"
• 写完后才发现缺少 API Key，整个过程重来

这就是"浅层 Agent"的典型症状——只会机械调用工具，缺乏规划、反思和任务分解能力。Deep Agent SDK 就是为了解决这个问题而生的。

项目起源：LangChain DeepAgents 的"重生"

Deep Agent 最早来自 LangChain 的 deepagentsjs 项目，由 Vercel AI SDK 团队核心成员 Chris Pang（@chrispangg）主导开发。

这个框架的核心洞察是：LLM 在循环中调用工具只是 Agent 的最简形式，真正的 Agent 需要规划、子任务委托、文件系统访问和状态持久化。LangChain 版本依赖过于重的图结构，而 Deep Agent SDK 则是一个零外部 AI 框架依赖的全新实现，直接基于 Vercel AI SDK v6 的 ToolLoopAgent 构建。

2025 年 11 月发布 v0.1，目前活跃维护中（2026 年 2 月最新提交）。

四大核心能力：规划 → 执行 → 委托 → 持久化

1. 规划工具（write_todos）：任务分解与追踪

Deep Agent 内置 write_todos 工具，让 Agent 能够主动维护一个任务列表：

// Agent 自动将"做一个 Dashboard"分解为：
write_todos([{
  content: "调研公开数据集 API",
  status: "in_progress",
  id: "1"
}, {
  content: "数据清洗与格式转换",
  status: "pending",
  id: "2"
}, {
  content: "选择合适的图表类型",
  status: "pending",
  id: "3"
}, {
  content: "实现前端界面",
  status: "pending",
  id: "4"
}])

不同于一次性规划，Deep Agent 的 todo 是动态更新的：完成一步立即 mark completed，同时评估是否需要新增子任务。

2. 子 Agent 委托（task 工具）：专业化分工

当主 Agent 遇到子任务时，可以Spawn 一个专门的子 Agent 来处理：

const subagent = await task({
  goal: "调研公开的天气数据 API，返回可用性分析和示例代码",
  agent: createDeepAgent({ model, backend: filesystemBackend })
});

子 Agent 拥有独立的消息历史、工具集和文件系统视图，主 Agent 则等待子 Agent 返回结果后继续执行。支持的子 Agent 最大步数可配置（默认 30 步），防止无限递归。

3. 文件系统访问：虚拟工作区

Deep Agent 内置虚拟文件系统工具集：

工具	功能
ls	列出目录文件
read_file	读取文件内容
write_file	写入文件
edit_file	智能编辑（基于上下文行）
glob	通配符模式匹配
grep	正则搜索

这些工具支持多种后端：本地文件系统、StateBackend（内存/临时）、PersistentBackend（持久化 KV 存储）。

4. 状态检查点与恢复

checkpointer 系统让 Agent 可以随时保存会话快照（对话历史 + Agent 状态），中断后可无缝恢复：

const checkpointer = new MemorySaver();
const agent = createDeepAgent({
  model,
  checkpointer,
  threadId: "user-session-123"
});
// 中断后恢复
await agent.resume({ threadId: "user-session-123" });

支持三种持久化后端：MemorySaver（内存）、FileSaver（磁盘文件）、KVSaver（KV Store）。

技术架构：模块化 + 插件化

核心层：ToolLoopAgent 引擎

Deep Agent 的核心引擎是 Vercel AI SDK v6 的 ToolLoopAgent。这是 Vercel AI SDK 提供的结构化 Agent 循环抽象，比直接用 generateText 的工具调用模式更强大：

• 内置步数控制（stepCountIs）
• 支持中断和批准机制（interruptOn）
• 流式事件系统

工具层：可插拔工具集

src/tools/
  ├── todos.ts       → write_todos 任务规划工具
  ├── filesystem.ts  → ls/read/write/edit/glob/grep
  ├── subagent.ts    → task 子 Agent 委托工具
  ├── execute.ts     → 命令执行工具
  └── web.ts         → web_search/http_request/fetch_url

每个工具都基于 Vercel AI SDK 的 tool() 工厂函数，类型安全且可扩展。

后端层：Sandbox 隔离执行

Deep Agent 支持多种云端 Sandbox 后端，实现代码执行的完全隔离：

后端	驱动技术	特点
E2B	Firecracker 微虚拟机	冷启动 2-3 秒，自动清理
Daytona	云端沙箱	高隔离性
Modal	Serverless Container	按调用计费
Runloop	云端运行时	集成 API 客户端

本地开发也可以用 LocalSandbox 直接执行命令。

提示词工程层

src/prompts.ts 包含精心设计的系统提示词：

• BASE_PROMPT：工具使用规范
• TODO_SYSTEM_PROMPT：任务状态机定义（pending/in_progress/completed/cancelled）
• FILESYSTEM_SYSTEM_PROMPT：虚拟文件系统协议
• TASK_SYSTEM_PROMPT：子 Agent 委托规范

每个提示词都经过长期调优，确保 Agent 行为符合预期。

Langfuse 集成：Agent 行为可观测

Deep Agent 支持通过 OpenTelemetry + Langfuse 进行追踪：

import { langfuse } from "langfuse-vercel";

// 在 LLM 调用层面自动记录：
// - 每步推理的输入/输出
// - 工具调用序列和结果
// - Token 消耗
// - Agent 决策路径

这对调试复杂 Agent 行为非常有价值——你可以在 Langfuse 面板中回放每一步 Agent 思考过程。

上手体验：终端界面即开即用

Deep Agent 提供了一个精美的 CLI 终端界面（基于 Ink + React）：

npx deepagentsdk
# 启动交互式 TUI，支持：
# - 多模型选择（Anthropic/OpenAI/本地模型）
# - 实时工具调用展示
# - 子 Agent 可视化
# - 检查点管理
# - API Key 配置

也可以作为库集成到自己的项目中：

import { createDeepAgent } from "deepagentsdk";

const agent = createDeepAgent({
  model: openai("gpt-4o"),
  backend: new FilesystemBackend(),
});

const result = await agent.run({
  prompt: "帮我分析当前目录的代码结构"
});

局限性：不避讳的坦诚评估

1. 非生产级监控：缺少内置的指标导出、告警机制，Langfuse 集成需要手动配置
2. 云端 Sandbox 成本：E2B/Modal/Daytona 等云端执行按调用计费，大规模使用需考虑成本
3. 无内置 RAG：没有向量检索、文档加载器，复杂知识问答场景需额外集成
4. Vercel AI SDK 强绑定：核心依赖 Vercel AI SDK v6，换用其他框架成本较高

行业意义：Agent 工程的"工程化"里程碑

Deep Agent SDK 代表了一个重要趋势：Agent 不再是"给 LLM 装上工具"的一行代码，而是需要规划系统、记忆系统、工具系统和执行隔离的完整工程架构。

随着 Vercel AI SDK v6 的成熟，类似 Deep Agent 这样的"深度 Agent 框架"正在成为 Agent 工程实践的主流范式。它的 MIT 许可和零外部 AI 框架依赖使其成为企业自建 Agent 能力的可靠起点。

Stars 增长曲线（从 2025 年 11 月至今）：快速从 0 增长到 126，增速稳健，社区关注度持续上升。