DeepAgents 通用智能体开发指南

1. 相关面试真题1.1. DeepAgents与 LangChain createAgent、原生 LangGraph 的核心区别是什么？请分别说明它们的适用场景。1. 定位差异：DeepAgents 是 Agent Harness（智能体执行环境），提供开箱即用的生产级运行时；createAgent 是简单工具调用循环；LangGraph 是底层工作流编排引擎。2. 能力差异：DeepAgents 内置规划、虚拟文件系统、子代理、技能系统；createAgent 仅支持基础工具调用；LangGraph 需要手动实现所有能力。3. 适用场景：DeepAgents：复杂多步骤任务（代码开发、研究分析）。createAgent：单轮工具调用、简单问答。LangGraph：需要高度定制的特殊业务流程。1.2. DeepAgents 的子代理 Subagents 机制解决了什么核心问题？它与普通工具调用的本质区别是什么？1. 解决的问题：上下文污染与膨胀问题。传统工具调用的所有中间结果都会进入主代理上下文，导致窗口溢出和注意力分散。2. 本质区别：子代理拥有独立的上下文、系统提示词和工具集，执行过程完全隔离。主代理只接收子代理的最终结果，不关心中间过程。子代理可以使用不同的模型和权限，实现专业分工。3. 额外优势：子任务失败不影响主流程、支持并行执行、便于权限控制。2. DeepAgents核心认知与快速上手2.1. 什么是DeepAgents？1. 官方定义DeepAgents是一个基于LangGraph构建的独立智能体库，专为复杂多步骤任务设计。它受到Claude Code、Deep Research和Manus等前沿智能体应用的启发，内置了规划能力、文件系统上下文管理和子代理生成能力。2. 解决的三大核心痛点传统Agent开发中，你会遇到这些无法回避的问题：上下文窗口溢出：工具返回大量结果，很快填满上下文窗口。长任务不可靠：执行多步任务时，Agent容易迷失方向、忘记目标。多角色协作复杂：需要手动实现子代理的创建、通信和结果整合。DeepAgents把这些问题都变成了可配置的能力，你不需要自己从零开始实现。3. 与其他技术的对比4. 核心设计思想:Agent HarnessHarness的字面意思是"马具"，它的作用是把马（模型）套住，让它按照你的方向前进。Harness架构的核心思想：模型只负责推理决策这一件事。Harness负责所有工程化问题：环境、权限、存储、隔离、观测。把智能体放进一个可控、安全、可观测的工作台中。你可以把它想象成一个智能体的"操作系统"：模型是CPU，Harness提供了内存管理、文件系统、进程管理、安全机制等所有操作系统能力。2.2. 快速上手1. 环境准备# 创建项目 mkdir deepagents-demo cd deepagents-demo npm init -y # 安装依赖 npm install deepagents @langchain/openai @langchain/langgraph zod dotenv npm install -D tsup typescript @types/node2. 配置TypeScript// tsconfig.json { "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "esModuleInterop": true, "skipLibCheck": true, "strict": true, "outDir": "dist" }, "include": ["src/**/*"] }3. 配置环境变量// .env ARK_API_KEY=your-volcengine-ark-api-key DEEPAGENTS_MODEL=doubao-seed-2.0-mini OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/plan/v34. 最小可运行示例// src/core/index.ts import "dotenv/config"; import { createDeepAgent } from "deepagents"; import { ChatOpenAI } from "@langchain/openai"; import { tool } from "langchain"; import { z } from "zod"; // 1. 定义一个简单的业务工具 const searchKnowledgeBase = tool( async ({ topic }) = { // 模拟知识库查询 const knowledge = { "deepagents": "DeepAgents是基于LangGraph的智能体执行环境，专为复杂多步骤任务设计。", "harness": "Harness是DeepAgents的核心架构思想，将模型与工程化能力分离。" }; return knowledge[topic] || "暂无相关信息"; }, { name: "search_knowledge_base", description: "查询DeepAgents知识库", schema: z.object({ topic: z.string().describe("要查询的主题") }) } ); // 2. 初始化模型 const model = new ChatOpenAI({ model: process.env.DEEPAGENTS_MODEL!, apiKey: process.env.ARK_API_KEY!, baseURL: process.env.OPENAI_BASE_URL!, }); // 3. 创建DeepAgent（一行代码获得所有内置能力） const agent = createDeepAgent({ model, tools: [searchKnowledgeBase], // 只需要传入业务工具 systemPrompt: "你是DeepAgents课程助教。先用write_todos拆解任务，再调用必要工具。", }); // 4. 调用智能体 async function main() { const result = await agent.invoke({ messages: [{ role: "user", content: "解释什么是DeepAgents和Harness架构" }], }); console.log("最终回答：", result.messages.at(-1)?.content); } main();5. 运行验证npx tsx src/core/index.ts3. DeepAgents 四大核心能力详解3.1. 规划与任务分解传统Agent处理长任务时，就像一个没有计划的人，走一步看一步，很容易在执行过程中迷失方向，忘记最初的目标。1. DeepAgents的解决方案：内置规划系统DeepAgents内置了 write_todos 工具和自适应规划引擎，让Agent能够：将复杂目标自动拆解为可执行的离散步骤。实时跟踪每个步骤的执行状态。根据新信息动态调整计划。2. 核心概念待办事项（Todo）：一个可执行的最小任务单元。任务树：复杂任务可以嵌套多层待办事项。进度跟踪：自动更新待办事项的状态（未开始/进行中/已完成/已失败）。动态调整：当遇到意外情况时，自动修改或重新生成计划。3. 关键用法你不需要手动实现任何规划逻辑，只需要在系统提示词中简单引导：const agent = createDeepAgent({ model, systemPrompt: ` 你是一个专业的项目助理。 1. 收到任务后，首先使用write_todos工具将任务拆解为3-5个步骤 2. 每完成一个步骤，更新待办事项的状态 3. 如果�到问题，调整计划并说明原因 4. 所有步骤完成后，输出最终结果 `, });4. 执行流程演示当你请求"生成一个DeepAgents课程大纲”时，Agent会自动执行以下步骤：1. 调用write_todos生成计划： - [ ] 分析DeepAgents的核心能力 - [ ] 设计课程结构和时间分配 - [ ] 编写每个模块的详细内容 - [ ] 添加实战项目和最佳实践 - [ ] 审核并完善课程大纲 2. 逐个执行步骤，自动更新状态： - [x] 分析DeepAgents的核心能力 - [x] 设计课程结构和时间分配 - [ ] 编写每个模块的详细内容 ... 3. 遇到新信息时自动调整计划： - 发现需要添加生产部署内容，新增步骤： - [ ] 添加生产部署和安全最佳实践5. 最佳实践不要硬编码任务步骤：让Agent自己决定如何分解任务，它比你更擅长。控制计划粒度：每个步骤应该能在1-3轮工具调用内完成。允许动态调整：不要要求Agent严格按照初始计划执行，要给它调整的空间。复杂任务使用嵌套计划：对于特别复杂的任务，可以让Agent生成多层嵌套的待办事项。3.2. 虚拟文件系统大模型的上下文窗口是有限的，当工具返回大量结果(比如读取一个上千行的代码文件)时，很快就会填满上下文窗口，导致后续执行失败。1.DeepAgents的解决方案：文件系统优先的上下文管理DeepAgents的核心设计理念之一是：所有大文本、工具输出都应该写入文件，上下文只保留文件路径和摘要。当工具返回超过一定大小的结果时，DeepAgents会自动将其写入文件，然后在上下文中只保留文件路径。需要时，Agent再读取文件的具体内容。这种设计彻底解决了上下文溢出问题，让Agent能够处理任意大小的文本和数据。2.四大内置BackendBackend是虚拟文件系统的底层实现，决定了文件实际存储在哪里。DeepAgents提供了四种内置Backend：3. 关键用法：CompositeBackend路由最常用的是CompositeBackend它允许你将不同的虚拟路径映射到不同的Backend：import { CompositeBackend, StateBackend, FilesystemBackend, StoreBackend } from "deepagents"; import { InMemoryStore } from "@langchain/langgraph"; import * as path from "path"; const store = new InMemoryStore(); const workspaceRoot = path.join(process.cwd(), "data", "workspace"); // 配置多路径路由 const backend = new CompositeBackend( new StateBackend(), // 默认后端：所有未匹配的路径 { // /workspace/路径映射到本地文件系统 "/workspace/": new FilesystemBackend({ rootDir: workspaceRoot, virtualMode: true, // 启用虚拟路径映射 }), // /memories/路径映射到StoreBackend "/memories/": new StoreBackend({ store }), } ); const agent = createDeepAgent({ model, backend, // 配置文件系统权限（白名单模式） permissions: [ { operations: ["read"], paths: ["/"], mode: "allow" }, { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" }, { operations: ["read", "write"], paths: ["/memories/**"], mode: "allow" }, { operations: ["read", "write"], paths: ["/**"], mode: "deny" }, // 最后拒绝所有 ], });4. 权限系统详解DeepAgents的权限系统采用白名单优先原则：先匹配最具体的路径规则。没有匹配到的路径，使用默认规则。建议最后添加一条 deny /** 规则