DeepAgents官方文档（一）

桜吹雪
1,401 阅读5分钟

DeepAgents.js官方文档：Deep Agents

Deep Agents 概览

构建能够规划、使用 subagents 以及利用文件系统处理复杂任务的 agents

deepagents 是一个独立的库，专为构建能够处理复杂、多步骤任务的 agents 而设计。它基于 LangGraph 构建，灵感来源于 Claude Code、Deep Research 和 Manus 等应用。Deep agents 自带规划能力、用于上下文管理的文件系统，以及生成 (spawn) subagents 的能力。

何时使用 deep agents

当您需要具备以下能力的 agents 时，请使用 deep agents：

  • 处理需要规划和分解的复杂、多步骤任务
  • 通过文件系统 tools 管理大量上下文
  • 将工作委托给专门的 subagents 以实现上下文隔离
  • 跨对话和 threads 持久化 memory

对于更简单的用例，请考虑使用 LangChain 的 create_agent 或构建自定义的 LangGraph workflow。

核心能力 (Core capabilities)

规划与任务分解 (Planning and task decomposition)

Deep agents 包含一个内置的 write_todos tool，使 agents 能够将复杂任务分解为离散的步骤，跟踪进度，并随着新信息的出现动态调整计划。

上下文管理 (Context management)

文件系统 tools (ls, read_file, write_file, edit_file) 允许 agents 将大量上下文卸载 (offload) 到 memory 中，从而防止 context window 溢出，并支持处理变长的 tool 结果。

Subagent 生成 (Subagent spawning)

内置的 task tool 允许 agents 生成专门的 subagents 以进行上下文隔离。这既保持了主 agent 的上下文整洁，又能针对特定的子任务进行深入处理。

长期记忆 (Long-term memory)

利用 LangGraph 的 Store 扩展 agents，使其具备跨 threads 的持久化 memory。Agents 可以保存并检索先前对话中的信息。

与 LangChain 生态系统的关系

Deep agents 构建于以下基础之上：

  • LangGraph - 提供底层的 graph 执行和 state 管理
  • LangChain - Tools 和 model 集成可与 deep agents 无缝协作
  • LangSmith - 提供 Observability (可观测性)、评估和部署支持

Deep agents 应用程序可以通过 LangSmith Deployment 进行部署，并使用 LangSmith Observability 进行监控。

快速开始 (Quickstart)

在几分钟内构建您的第一个DeepAgent

本指南将指导您创建具备规划、文件系统工具和子Agent功能的DeepAgent。您将构建一个能够进行研究并撰写报告的研究Agent。

先决条件

开始前，请确保已从模型提供商（如 Anthropic、OpenAI）获取 API 密钥。

步骤1：安装依赖项

首先，安装 deepagents 包以及必要的依赖项。

npm install deepagents @langchain/tavily  
# 或  
yarn add deepagents @langchain/tavily  
# 或  
pnpm add deepagents @langchain/tavily

步骤2：设置 API 密钥

export ANTHROPIC_API_KEY="your-api-key"  
export TAVILY_API_KEY="your-tavily-api-key"

步骤3：创建搜索工具

import { tool } from "langchain";  
import { TavilySearch } from "@langchain/tavily";  
import { z } from "zod";  

const internetSearch = tool(  
  async ({
    query,
    maxResults,
    topic,
    includeRawContent,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({  
      maxResults,  
      tavilyApiKey: process.env.TAVILY_API_KEY,  
      includeRawContent,  
      topic,  
    });  
    return await tavilySearch._call({ query });  
  },  
  {  
    name: "internet_search",  
    description: "执行网络搜索",  
    schema: z.object({  
      query: z.string().describe("搜索查询"),  
      maxResults: z  
        .number()  
        .optional()  
        .default(5)  
        .describe("最大返回结果数"),  
      topic: z  
        .enum(["general", "news", "finance"])  
        .optional()  
        .default("general")  
        .describe("搜索主题分类"),  
      includeRawContent: z  
        .boolean()  
        .optional()  
        .default(false)  
        .describe("是否包含原始内容"),  
    }),  
  }  
);

步骤4：创建deep agent

import { createDeepAgent } from "deepagents";  

// 引导Agent成为专家研究员的系统提示  
const researchInstructions = `您是一位专家研究员。您的任务是进行彻底的研究，然后撰写一份精炼的报告。

您可以通过互联网搜索工具作为主要信息收集手段。

## \`internet_search\`

使用此工具针对给定查询执行网络搜索。您可以指定返回结果的最大数量、主题以及是否包含原始内容。`;  

const agent = createDeepAgent({  
  tools: [internetSearch],  
  systemPrompt: researchInstructions,  
});

步骤5：运行Agent

const result = await agent.invoke({  
  messages: [{ role: "user", content: "什么是 LangGraph？" }],  
});  

// 输出Agent的最终响应  
console.log(result.messages[result.messages.length - 1].content);

发生了什么？

您的DeepAgent自动完成了以下操作：

  • 规划策略：使用内置 write_todos工具分解研究任务
  • 开展研究：调用 internet_search工具收集信息
  • 上下文管理：使用文件系统工具（write_file、read_file）卸载大型搜索结果
  • 生成子Agent（如需）：将复杂子任务委托给专用子Agent
  • 综合报告：将发现编译为连贯的响应

下一步

完成首个DeepAgent后，您可以：

  • 自定义Agent：学习自定义选项（系统提示、工具、子Agent）
  • 理解中间件：深入探究驱动DeepAgent的中间件架构
  • 添加长期记忆：实现跨会话的持久化记忆
  • 生产部署：了解 LangGraph 应用的部署方案

定制DeepAgent

学习如何通过系统提示、工具、子Agent等方式定制DeepAgent

graph LR
    Create[create_deep_agent] --> Core[Core Config]
    Create --> Features[Features]

    Core --> Model[Model]
    Core --> Prompt[System Prompt]
    Core --> Tools[Tools]

    Features --> Backend[Backend]
    Features --> Sub[Subagents]
    Features --> Interrupt[Interrupts]

    Model --> Agent[Customized Agent]
    Prompt --> Agent
    Tools --> Agent
    Backend --> Agent
    Sub --> Agent
    Interrupt --> Agent

模型

默认情况下，deepagents使用 claude-sonnet-4-5-20250929。您可以通过传递任意 LangChain 模型对象进行自定义。

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

// 使用 Anthropic 模型  
const agent = createDeepAgent({  
  model: new ChatAnthropic({  
    model: "claude-sonnet-4-20250514",  
    temperature: 0,  
  }),  
});  

// 使用 OpenAI 模型  
const agent2 = createDeepAgent({  
  model: new ChatOpenAI({  
    model: "gpt-5",  
    temperature: 0,  
  }),  
});

系统提示

深度代理内置基于 Claude Code 系统提示的默认引导提示。该默认提示包含使用内置规划工具、文件系统工具和子代理的详细说明。

每个面向特定场景的深度代理都应包含针对该场景的自定义系统提示。

import { createDeepAgent } from "deepagents";  

const researchInstructions = `您是一位专家研究员。您的任务是进行彻底的研究，然后撰写一份精炼的报告。`;  

const agent = createDeepAgent({  
  systemPrompt: researchInstructions,  
});

工具

与工具调用代理类似，深度代理可访问一组顶层工具。

import { tool } from "langchain";  
import { TavilySearch } from "@langchain/tavily";  
import { createDeepAgent } from "deepagents";  
import { z } from "zod";  

const internetSearch = tool(  
  async ({  
    query,  
    maxResults = 5,  
    topic = "general",  
    includeRawContent = false,  
  }: {  
    query: string;  
    maxResults?: number;  
    topic?: "general" | "news" | "finance";  
    includeRawContent?: boolean;  
  }) => {  
    const tavilySearch = new TavilySearch({  
      maxResults,  
      tavilyApiKey: process.env.TAVILY_API_KEY,  
      includeRawContent,  
      topic,  
    });  
    return await tavilySearch._call({ query });  
  },  
  {  
    name: "internet_search",  
    description: "执行网络搜索",  
    schema: z.object({  
      query: z.string().describe("搜索查询"),  
      maxResults: z.number().optional().default(5),  
      topic: z.enum(["general", "news", "finance"]).optional().default("general"),  
      includeRawContent: z.boolean().optional().default(false),  
    }),  
  }  
);  

const agent = createDeepAgent({  
  tools: [internetSearch],  
});

除自定义工具外，深度代理还内置以下默认工具：

  • write_todos：更新代理的待办事项列表
  • ls：列出代理文件系统中的所有文件
  • read_file：从文件系统中读取文件
  • write_file：向文件系统中写入新文件
  • edit_file：编辑现有文件
  • task：生成子代理处理特定任务
avatar
文章
阅读
粉丝