deepagents-overview (JavaScript/TypeScript)

什么是 Deep Agents？

Deep Agents 是一个基于 LangChain 和 LangGraph 构建的自有代理框架，专为复杂的多步骤任务而设计。它们"开箱即用"，具有内置功能：

• 任务规划：TodoListMiddleware 用于分解复杂任务
• 上下文管理：具有可插拔后端的文件系统工具
• 任务委托：SubAgent 中间件用于启动专用代理
• 长期内存：通过 Store 跨会话持久化存储
• 人工干预：敏感操作的审批工作流

Deep Agents 使用"agent harness"架构 - 与其他框架相同的核心工具调用循环，但具有预配置的中间件和工具。

何时使用 Deep Agents

| 使用 Deep Agents 当 | 使用 LangChain 的 createAgent 当 | |---------------------|-----------------------------------| | 需要规划的多步骤任务 | 简单、单一用途的任务 | | 需要文件管理的大上下文 | 上下文适合单个提示 | | 需要专用子代理 | 单个代理足够 | | 跨会话持久化内存 | 临时的单会话工作 | | CLI 或编码助手用例 | 简单 API 或聊天应用 |

创建 Deep Agent

基本代理创建

typescript
import { createDeepAgent } from "deepagents";

// 具有默认设置的最小代理
const agent = await createDeepAgent({});

// 调用代理
const result = await agent.invoke({
  messages: [
    { role: "user", content: "东京的天气怎么样？" }
  ]
});

具有自定义工具的代理

typescript
import { createDeepAgent } from "deepagents";
import { tool } from "langchain";
import { z } from "zod";

const getWeather = tool(
  ({ city }) => `${city} 总是晴天！`,
  {
    name: "get_weather",
    description: "获取给定城市的天气",
    schema: z.object({
      city: z.string(),
    }),
  }
);

const agent = await createDeepAgent({
  tools: [getWeather],
  systemPrompt: "你是一个有用的天气助手"
});

const result = await agent.invoke({
  messages: [
    { role: "user", content: "东京的天气怎么样？" }
  ]
});

具有自定义模型的代理

typescript
import { createDeepAgent } from "deepagents";
import { ChatOpenAI } from "@langchain/openai";

// 使用 provider:model 格式
const agent = await createDeepAgent({
  model: "openai:gpt-4"
});

// 或传递模型实例
const model = new ChatOpenAI({ model: "gpt-4", temperature: 0 });
const agent2 = await createDeepAgent({
  model
});

Agent Harness 架构

Deep Agents 在创建时自动附加中间件：

typescript
import { createDeepAgent } from "deepagents";

// 此代理自动具有：
// - TodoListMiddleware（任务规划）
// - FilesystemMiddleware（文件操作）
// - SubAgentMiddleware（任务委托）
// - SummarizationMiddleware（历史管理）
// - AnthropicPromptCachingMiddleware（缓存）
// - PatchToolCallsMiddleware（工具调用修复）
const agent = await createDeepAgent({});

内置工具

每个 deep agent 都可以访问：

1. 规划工具：write_todos - 跟踪多步骤任务
2. 文件系统工具：ls、read_file、write_file、edit_file、glob、grep
3. 子代理工具：task - 将工作委托给专用代理

配置选项

typescript
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const agent = await createDeepAgent({
  name: "my-assistant",            // 可选：代理名称
  model: "claude-sonnet-4-5-20250929",  // 要使用的模型
  tools: [customTool1, customTool2],    // 附加工具
  systemPrompt: "自定义指令",   // 自定义系统提示
  middleware: [customMiddleware],        // 附加中间件
  subagents: [researchAgent, codeAgent], // 自定义子代理
  backend: new FilesystemBackend({ rootDir: "." }),  // 存储后端
  interruptOn: { write_file: true },     // 人工干预配置
  skills: ["/path/to/skills/"],     // 技能目录
  checkpointer: new MemorySaver(),  // 中断所需
  store: new InMemoryStore()        // 用于长期内存
});

决策表：要自定义哪个中间件

| 如果你需要... | 使用此中间件 | 何时自定义 | |------------------|-------------------|------------------| | 跟踪复杂的多步骤任务 | todoListMiddleware | 默认工作；需要时自定义提示 | | 管理文件上下文 | createFilesystemMiddleware | 更改后端或工具描述 | | 委托专门工作 | createSubAgentMiddleware | 添加具有特定工具的自定义子代理 | | 防止上下文溢出 | summarizationMiddleware | 默认工作；自定义摘要策略 | | 缓存提示（Anthropic） | anthropicPromptCachingMiddleware | 默认自动工作 | | 添加人工审批 | humanInTheLoopMiddleware | 配置哪些工具需要审批 | | 按需加载技能 | skillsMiddleware | 提供技能目录 | | 访问持久化内存 | memoryMiddleware | 提供 Store 实例 |

边界

Agent 可以配置的内容

✅ 模型选择和参数 ✅ 附加的自定义工具 ✅ 系统提示自定义 ✅ 后端存储策略 ✅ 哪些工具需要审批 ✅ 具有专用工具的自定义子代理 ✅ 技能目录和内容 ✅ 中间件顺序和配置

Agent 不能配置的内容

❌ 核心中间件移除（TodoList、Filesystem、SubAgent 始终存在） ❌ write_todos、task 或文件系统工具名称 ❌ 基本工具调用循环 ❌ LangGraph 的运行时执行模型 ❌ Agent Skills 协议格式

注意事项

1. 中断需要 Checkpointer

typescript
// ❌ 如果设置了 interruptOn 将会出错
const agent = await createDeepAgent({
  interruptOn: { write_file: true }
});

// ✅ Checkpointer 是必需的
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  interruptOn: { write_file: true },
  checkpointer: new MemorySaver()
});

2. 持久化内存需要 Store

typescript
// ❌ StoreBackend 需要 Store
import { StoreBackend } from "deepagents";

const agent = await createDeepAgent({
  backend: (config) => new StoreBackend(config)
});

// ✅ 传递 Store 实例
import { InMemoryStore } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: (config) => new StoreBackend(config),
  store: new InMemoryStore()
});

3. 技能需要后端设置

typescript
// ❌ 没有正确的后端技能不会加载
const agent = await createDeepAgent({
  skills: ["/path/to/skills/"]
});

// ✅ 使用 FilesystemBackend 进行本地技能
import { FilesystemBackend } from "deepagents";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"]
});

4. 有状态对话需要 Thread ID

typescript
// ❌ 没有 thread_id 每次调用都是隔离的
await agent.invoke({ messages: [{ role: "user", content: "嗨" }] });
await agent.invoke({ messages: [{ role: "user", content: "我说了什么？" }] });

// ✅ 使用一致的 thread_id 保持对话连续性
const config = { configurable: { thread_id: "user-123" } };
await agent.invoke({ messages: [{ role: "user", content: "嗨" }] }, config);
await agent.invoke({ messages: [{ role: "user", content: "我说了什么？" }] }, config);

5. 默认模型是 Anthropic Claude

typescript
// 默认使用 claude-sonnet-4-5-20250929
const agent = await createDeepAgent({});

// 需要 ANTHROPIC_API_KEY 环境变量
// 如果使用 OpenAI 模型，设置 OPENAI_API_KEY
process.env.ANTHROPIC_API_KEY = "your-key";

6. 等待 createDeepAgent

typescript
// ❌ 缺少 await
const agent = createDeepAgent({});

// ✅ createDeepAgent 是异步的
const agent = await createDeepAgent({});

完整文档

• Deep Agents 概述
• Agent Harness 功能
• 自定义 Deep Agents
• Deep Agents 快速入门