# https://github.com/langchain-ai/deepagents 项目说明书 生成时间：2026-05-31 04:11:49 UTC ## 目录 - [项目概述](#page-overview) - [快速开始](#page-quickstart) - [系统架构](#page-architecture) - [中间件系统](#page-middleware) - [子智能体系统](#page-subagents) - [文件系统功能](#page-filesystem) - [技能系统](#page-skills) - [上下文管理](#page-context-management) - [后端系统](#page-backends) - [沙箱环境](#page-sandbox) ## 项目概述 ### 相关页面 相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/langchain-ai/deepagents/blob/main/README.md) - [libs/deepagents/README.md](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/README.md) - [libs/deepagents/deepagents/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/__init__.py) - [libs/cli/deepagents_cli/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/__init__.py) - [libs/cli/deepagents_cli/_version.py](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/deepagents_cli/_version.py) - [examples/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/README.md)
# 项目概述 Deep Agents（deepagents）是 LangChain 生态系统中构建的智能编程代理框架，为 AI 代理提供文件系统感知、上下文管理、子代理协作和技能系统等高级能力。 ## 核心定位 Deep Agents 是一个构建在 LangGraph 和 LangChain 之上的**高度封装智能代理框架**，旨在提供开箱即用的完整代理解决方案： - **与 LangGraph 的关系**：LangGraph 是图运行时引擎，Deep Agents 在其基础上构建更高级的代理抽象 - **与 LangChain 的关系**：`create_agent` 是 LangChain 的最小化代理工具，Deep Agents 则是更具备opinionated风格的完整代理框架 - **与 Claude Code 的关系**：Deep Agents 最初受 Claude Code 启发，旨在将其通用能力进一步扩展 资料来源：[libs/deepagents/README.md:1-30]() ## 架构组件 Deep Agents 项目采用 monorepo 结构，主要包含以下核心库： | 组件 | 包名 | 版本 | 说明 | |------|------|------|------| | SDK | `deepagents` | 0.6.7 | 核心代理框架，包含中间件、工具和代理工厂 | | CLI | `deepagents-cli` | 0.1.2 | 部署命令行工具（init、dev、deploy） | | Code | `deepagents-code` | 0.1.6 | 交互式编程代理，提供 REPL 体验 | 资料来源：[libs/cli/deepagents_cli/_version.py:1-20]() ## 核心能力 ### 中间件系统 Deep Agents 通过中间件（Middleware）系统实现核心功能扩展： ```mermaid graph TD A[用户输入] --> B[MemoryMiddleware] B --> C[SkillsMiddleware] C --> D[FilesystemMiddleware] D --> E[其他中间件] E --> F[代理核心] F --> G[工具执行] G --> H[响应输出] ``` **主要中间件类型：** | 中间件 | 功能 | 相关问题 | |--------|------|----------| | `MemoryMiddleware` | 管理持久化上下文（如 AGENTS.md），支持缓存控制标记 | #3639, #3638：缓存控制标记错误 | | `SkillsMiddleware` | 按需加载技能定义 | #506：希望支持自定义代理中的技能 | | `FilesystemMiddleware` | 文件系统操作和遍历 | #2453：分页读取行数错误；#2630：需要原生文件上传 | 资料来源：[examples/content-builder-agent/README.md:1-50]() ### 技能系统（Skills） 技能是 Deep Agents 的核心扩展机制，采用三级加载的渐进式披露设计： ```mermaid graph LR A[元数据
name + description] --> B[SKILL.md
~5k words] B --> C[references/
按需加载] C --> D[assets/
不加载到上下文] ``` **技能目录结构：** ``` skill-name/ ├── SKILL.md # 技能定义（必需） ├── scripts/ # 可执行脚本 ├── references/ # 参考文档 └── assets/ # 资源文件 ``` 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md:1-100]() ### 子代理系统（Subagents） Deep Agents 支持创建专门的子代理来分解复杂任务： ```python subagents=[ { "name": "researcher", "description": "研究助手", "model": "anthropic:claude-haiku-4-5-20251001", "system_prompt": "你是研究助手...", "tools": [web_search], } ] ``` **已知限制：** 子代理目前不支持检查点持久化，状态查询时工具执行记录会被截断。 资料来源：[examples/content-builder-agent/README.md:50-80]() ### MCP 集成 Model Context Protocol（MCP）支持扩展代理能力： - 配置通过 `mcp.json` 文件管理 - 支持 MCP 服务器发现和动态工具调用 - CLI 版本 0.1.2+ 支持在 `mcp.json` header 中展开 `${VAR}` 环境变量 资料来源：[examples/deploy-mcp-docs-agent/README.md:1-30]() ### 沙箱执行 Deep Agents 支持在 LangSmith Sandbox 中安全执行代码： ```toml [sandbox] type = "langsmith" image = "python:3.12" ``` 沙箱后端提供文件系统操作、grep 搜索等功能。**已知问题：** `SandboxBackend.grep` 在容器执行失败时会抛出 `ValueError`。 资料来源：[examples/deploy-coding-agent/README.md:1-40]() ## 部署模式 Deep Agents 支持多种部署场景： | 模式 | 用途 | 特点 | |------|------|------| | `deepagents deploy` | 部署到 LangSmith | 生产级部署，支持沙箱配置 | | `create_deep_agent()` | SDK 编程方式 | 可嵌入自定义应用 | | REPL 模式 | `deepagents-code` | 交互式编码体验 | 资料来源：[examples/deploy-coding-agent/README.md:40-60]() ## 快速开始 ### SDK 方式 ```python from deepagents import create_deep_agent agent = create_deep_agent( model="anthropic:claude-sonnet-4-5-20250929", memory=["./AGENTS.md"], skills=["./skills/"], tools=[my_custom_tool], ) result = agent.invoke({"messages": "分析这个代码库"}) ``` ### CLI 方式 ```bash # 部署代理 deepagents deploy # 交互式编码 deepagents-code # MCP 配置 dcode mcp config ``` 资料来源：[libs/deepagents/README.md:1-50]() ## 模型支持 Deep Agents 支持任何支持工具调用的模型： | 类别 | 示例 | 说明 | |------|------|------| | 前沿 API | OpenAI GPT-5, Anthropic Claude | 云端闭源模型 | | 开源权重 | NVIDIA Nemotron, Llama | 支持 Baseten、Fireworks 等 | | 本地部署 | Ollama, vLLM, llama.cpp | 完全私有化部署 | 资料来源：[examples/deep_research/README.md:40-60]() ## 社区关注热点 根据 GitHub Issues 统计，用户关注的主要问题包括： | Issue | 关注点 | 状态 | |-------|--------|------| | #506 | 在非 CLI 版本中使用技能 | 功能请求 | | #297 | AG-UI 集成 | 讨论中 | | #180 | 原生技能支持 | 功能建议 | | #2630 | FilesystemMiddleware 原生文件上传 | 功能请求 | | #573 | 子代理检查点持久化 | Bug 报告 | | #2143 | `.deepagentsignore` 支持 | 功能请求 | ## 相关链接 | 资源 | 链接 | |------|------| | 官方文档 | https://docs.langchain.com/oss/python/deepagents/ | | PyPI (SDK) | https://pypi.org/project/deepagents | | PyPI (CLI) | https://pypi.org/project/deepagents-cli | | GitHub Issues | https://github.com/langchain-ai/deepagents/issues | --- ## 快速开始 ### 相关页面 相关主题：[项目概述](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/__init__.py) - [examples/content-builder-agent/content_writer.py](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/content_writer.py) - [examples/deep_research/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deep_research/README.md) - [examples/content-builder-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) - [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
# 快速开始 Deep Agents 是一个由 LangChain 构建的 AI 编码代理框架，专注于提供可定制、可扩展的智能代理能力。本指南将帮助你在几分钟内创建第一个 Deep Agent。 ## 环境准备 ### 前置要求 | 要求 | 说明 | |------|------| | Python | ≥ 3.11 | | API 密钥 | `ANTHROPIC_API_KEY`（Claude 模型访问） | | 可选 | `LANGSMITH_API_KEY`（用于部署和沙箱功能） | ### 安装 ```bash pip install deepagents ``` 或使用 uv（推荐）： ```bash uv pip install deepagents ``` 资料来源：[libs/deepagents/pyproject.toml:1-30](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/pyproject.toml) ## 核心概念 Deep Agents 采用模块化架构，通过四个核心原语构建智能代理： ```mermaid graph TD A[create_deep_agent] --> B[Memory
持久上下文] A --> C[Skills
按需加载的技能] A --> D[Subagents
子代理] A --> E[Tools
自定义工具] A --> F[Backend
后端引擎] ``` 资料来源：[examples/content-builder-agent/README.md:20-30](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) ### Memory（记忆） Memory 用于持久化上下文信息，通常是 `AGENTS.md` 文件。它定义了代理的品牌调性、风格指南和行为规则。 ```markdown # AGENTS.md 你是一个专业的技术写作代理... ``` Memory 会被 Middleware 加载到系统提示中，为代理提供持久化的上下文记忆。 ### Skills（技能） Skills 是按需加载的工作流定义，存放在 `skills/*/SKILL.md` 目录中。每个 Skill 包含： - **元数据**：名称和描述（始终在上下文中） - **主体内容**：SKILL.md 正文（技能触发时加载，<5k 字） - **引用资源**：references/ 目录下的参考文档 - **脚本资源**：scripts/ 目录下的可执行脚本 ```yaml --- name: blog-post description: 写长篇博客文章 --- # 博客文章写作 按照 SEO 优化和清晰结构撰写... ``` 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md:1-50](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md) ### Subagents（子代理） Subagents 是专门用于委托任务的子代理。通过 YAML 配置或代码内联定义： ```yaml # subagents.yaml researcher: description: 研究主题并收集信息 model: anthropic:claude-haiku-4-5-20251001 system_prompt: | 你是一个研究助手... tools: [web_search] ``` ### Tools（工具） Tools 是代理可以调用的自定义函数。使用 `@tool` 装饰器定义： ```python from deepagents import tool @tool def generate_cover(topic: str) -> str: """根据主题生成封面图片""" # 实现代码 return image_path ``` ### Backend（后端） Backend 定义代理的执行环境。默认使用 `FilesystemBackend`： ```python from deepagents import FilesystemBackend backend = FilesystemBackend(root_dir="./") ``` 资料来源：[examples/content-builder-agent/README.md:40-55](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) ## 创建你的第一个 Agent ### 基础示例 ```python from deepagents import create_deep_agent agent = create_deep_agent() ``` ### 带 Memory 和 Skills 的示例 ```python from deepagents import create_deep_agent, FilesystemBackend agent = create_deep_agent( memory=["./AGENTS.md"], # 持久上下文 skills=["./skills/"], # 按需加载的技能 backend=FilesystemBackend(root_dir="./"), ) ``` ### 完整配置示例 ```python from deepagents import create_deep_agent, tool, load_subagents # 定义自定义工具 @tool def generate_cover(topic: str) -> str: """生成封面图片""" # 实现代码 pass # 加载子代理配置 subagents = load_subagents("./subagents.yaml") # 创建代理 agent = create_deep_agent( memory=["./AGENTS.md"], skills=["./skills/"], tools=[generate_cover], subagents=subagents, backend=FilesystemBackend(root_dir="./"), ) ``` 资料来源：[examples/content-builder-agent/content_writer.py:1-80](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/content_writer.py) ## 目录结构 一个典型的 Deep Agent 项目结构： ``` my-agent/ ├── AGENTS.md # 代理记忆和角色定义 ├── subagents.yaml # 子代理配置 ├── skills/ │ ├── blog-post/ │ │ └── SKILL.md # 博客写作技能 │ └── social-media/ │ └── SKILL.md # 社交媒体技能 ├── scripts/ # 可复用脚本 ├── references/ # 参考文档 └── agent.py # 代理代码 ``` 资料来源：[examples/content-builder-agent/README.md:30-45](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) ## 运行代理 ### CLI 模式 ```bash deepagents run ``` ### 代码中运行 ```python from langchain_core.messages import HumanMessage response = await agent.ainvoke({ "messages": [HumanMessage(content="写一篇关于 AI 代理的博客")] }) ``` ## 示例项目 Deep Agents 仓库提供了多个示例项目供参考： | 示例 | 说明 | |------|------| | [content-builder-agent](https://github.com/langchain-ai/deepagents/tree/main/examples/content-builder-agent) | 博客/社交媒体内容生成代理 | | [deep_research](https://github.com/langchain-ai/deepagents/tree/main/examples/deep_research) | 深度研究代理，支持 Tavily 搜索和并行子代理 | | [deploy-coding-agent](https://github.com/langchain-ai/deepagents/tree/main/examples/deploy-coding-agent) | 自主编程代理 | | [MCP Docs Agent](https://github.com/langchain-ai/deepagents/tree/main/examples/deploy-mcp-docs-agent) | 使用 MCP 工具查询文档 | 资料来源：[examples/README.md:1-35](https://github.com/langchain-ai/deepagents/blob/main/examples/README.md) ## 常见问题 ### Q: 如何自定义模型？ ```python from langchain.chat_models import init_chat_model from deepagents import create_deep_agent model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929") agent = create_deep_agent(model=model) ``` ### Q: Skills 和 Memory 有什么区别？ - **Memory**：始终在上下文中，提供持久化的角色和行为定义 - **Skills**：按需加载，提供特定任务的详细工作流程 ### Q: 如何调试代理？ 启用 LangSmith 日志： ```bash export LANGSMITH_TRACING=true export LANGSMITH_API_KEY="your-key" ``` 资料来源：[examples/deep_research/README.md:1-40](https://github.com/langchain-ai/deepagents/blob/main/examples/deep_research/README.md) ## 下一步 - 查看 [Skills 指南](../guides/skills) 了解如何创建自定义技能 - 查看 [Subagents 指南](../guides/subagents) 了解子代理配置 - 查看 [部署文档](../deployment) 了解如何部署代理 --- ## 系统架构 ### 相关页面 相关主题：[中间件系统](#page-middleware), [上下文管理](#page-context-management)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/__init__.py) - [libs/deepagents/deepagents/graph.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py) - [libs/deepagents/deepagents/middleware/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/__init__.py) - [libs/deepagents/deepagents/backends/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/__init__.py) - [libs/deepagents/deepagents/_messages_reducer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_messages_reducer.py) - [examples/content-builder-agent/content_writer.py](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/content_writer.py)
# 系统架构 ## 概述 deepagents 是一个基于 LangGraph 的深度智能代理框架，旨在为 AI 代理提供文件系统集成、上下文持久化、技能管理和子代理编排能力。该框架通过模块化的中间件（Middleware）和后端（Backend）系统，实现了代理与环境的安全交互和高效上下文管理。 核心设计理念是将代理的配置与执行逻辑分离：开发者通过声明式配置定义代理的内存、技能、工具和子代理，框架自动处理加载、调度和状态管理。 ## 核心组件架构 deepagents 的系统架构由以下核心组件构成： ```mermaid graph TD subgraph "入口层" A[create_deep_agent] --> B[DeepAgent Graph] end subgraph "配置层" C[memory
AGENTS.md] --> B D[skills
SKILL.md] --> B E[subagents
subagents.yaml] --> B F[tools
@tool装饰器] --> B end subgraph "中间件层" G[MemoryMiddleware] --> H[StateModifier] I[SkillsMiddleware] --> H J[SummarizationMiddleware] --> H end subgraph "后端层" K[FilesystemBackend] --> L[SandboxBackend] M[MemoryBackend] --> L end subgraph "执行层" B --> N[LangGraph StateGraph] N --> O[Tool Executor] N --> P[Subagent Executor] end H --> K H --> M ``` ### 组件职责表 | 组件 | 职责 | 配置方式 | |------|------|----------| | `create_deep_agent` | 代理工厂函数，组装所有组件 | 代码调用 | | `memory` | 持久化上下文，加载 AGENTS.md | 文件路径列表 | | `skills` | 按需加载的技能工作流 | 目录路径 | | `subagents` | 子代理定义 | 字典或 YAML | | `tools` | 代理可调用的工具函数 | @tool 装饰器 | | `backend` | 文件系统交互后端 | Backend 实例 | 资料来源：[examples/content-builder-agent/content_writer.py:30-40]() ## 中间件系统 中间件是 deepagents 架构中的核心扩展机制，负责在消息处理流程中注入自定义行为。每个中间件都实现了对代理状态的读取和修改能力。 ### 中间件类型 | 中间件 | 功能 | 社区相关问题 | |--------|------|--------------| | `MemoryMiddleware` | 加载 AGENTS.md 到系统提示词 | Issue #3638/#3639: cache_control 标记错误 | | `SkillsMiddleware` | 按需加载 SKILL.md 技能文件 | Issue #506: 非 CLI 版本技能支持 | | `SummarizationMiddleware` | 上下文摘要压缩 | Issue #2873: 图片丢失问题 | ### 中间件执行顺序 ```mermaid graph LR A[用户消息] --> B[MemoryMiddleware] B --> C[SkillsMiddleware] C --> D[SummarizationMiddleware] D --> E[StateModifier
合并到State] E --> F[LangGraph处理] ``` 中间件采用链式调用模式，按注册顺序依次执行。`StateModifier` 是最终的状态合并点，将所有中间件的输出整合到 LangGraph 的状态中。 资料来源：[libs/deepagents/deepagents/middleware/__init__.py]() ## 后端系统 后端系统提供了代理与外部环境交互的能力，主要分为文件系统后端和沙箱后端。 ### FilesystemBackend `FilesystemBackend` 是本地文件系统交互的后端实现，提供了代理读写文件的能力。 **核心功能：** - 文件读取（`read_file`）- 支持分页加载大文件 - 文件写入（`write_file`） - 目录列表（`list_files`） - 文件搜索（`grep`） - 文件操作（移动、复制、删除等） **已知问题：** - Issue #2453: `read_file` 分页在换行后跳过行 - Issue #3441: `grep` 在容器执行失败时抛出 ValueError - Issue #3592: 文件在遍历期间消失导致 grep 崩溃 资料来源：[libs/deepagents/deepagents/backends/__init__.py]() ### SandboxBackend `SandboxBackend` 提供在隔离环境中执行代码的能力，主要用于 LangSmith 沙箱部署场景。 ```mermaid graph TD A[代码执行请求] --> B[沙箱容器] B --> C[Python/Bash执行] C --> D[结果捕获] D --> E[资源清理] ``` **版本 0.6.4 修复：** 解决了文件在遍历过程中消失导致的 grep 崩溃问题。 ## 消息处理与状态管理 deepagents 使用 LangGraph 作为底层状态机框架，通过自定义的消息减少器（MessagesReducer）管理对话历史。 ### 消息状态流 ```mermaid graph TD A[HumanMessage] --> B[_messages_delta_reducer] C[AIMessage] --> B D[ToolMessage] --> B B --> E[状态合并] E --> F[checkpoint存储] G[Issue #3591] --> H[HumanMessage ID稳定性] H --> F ``` **关键实现：** - `_messages_delta_reducer` 负责合并消息增量 - 支持消息去重和截断 - 为缺少 ID 的消息自动分配 UUID **版本 0.6.4 修复：** 修复了跨线程恢复时 HumanMessage ID 不稳定的问题。 资料来源：[libs/deepagents/deepagents/_messages_reducer.py]() ## 子代理系统 子代理（Subagents）允许主代理将任务委托给专门的子代理执行，实现并行处理和任务分解。 ### 子代理配置 ```python subagents=[ { "name": "researcher", "description": "Research topics before writing...", "model": "anthropic:claude-haiku-4-5-20251001", "system_prompt": "You are a research assistant...", "tools": [web_search], } ] ``` ### 子代理架构 ```mermaid graph TD A[主代理] -->|task工具| B[子代理-1] A -->|task工具| C[子代理-2] A -->|task工具| D[子代理-3] B --> E[research_1.md] C --> F[research_2.md] D --> G[research_3.md] E --> H[结果聚合] F --> H G --> H ``` ### 已知问题 **Issue #573（高优先级）：** 子代理缺乏检查点持久化，状态查询时截断工具执行历史。这是社区反馈中最活跃的问题之一（7条评论）。 **Issue #3391（已修复）：** 工具返回的 Commands 中的 goto 和 graph 属性未正确传播到父图。 资料来源：[examples/content-builder-agent/content_writer.py:45-52]() ## 技能系统 技能（Skills）是 deepagents 的核心扩展机制，允许代理按需加载特定任务的工作流定义。 ### 技能结构 ``` skills/ ├── skill-name/ │ ├── SKILL.md # 技能定义文件 │ ├── scripts/ # 可执行脚本 │ ├── references/ # 参考文档 │ └── assets/ # 资源文件 ``` ### 渐进式加载策略 技能采用三级加载系统以优化上下文使用： 1. **元数据**（name + description）：始终加载（约100词） 2. **正文**（SKILL.md）：技能触发时加载（<5k词） 3. **资源**（scripts/references/assets）：按需执行，无需读入上下文 ### 技能触发机制 技能通过 YAML frontmatter 中的 `name` 和 `description` 字段定义，描述中包含触发关键词。SkillsMiddleware 根据用户输入匹配技能并加载对应的 SKILL.md。 **社区反馈（Issue #180/#506）：** 用户强烈希望在非 CLI 版本中使用技能功能，目前技能主要通过 CLI 暴露。 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 部署架构 deepagents 支持通过 `deepagents deploy` 命令将代理部署到 LangSmith 沙箱。 ### 部署配置 ```toml # deepagents.toml [sandbox] type = "coding" image = "python:3.12" [agent] model = "anthropic:claude-sonnet-4-20250514" ``` ### 部署流程 ```mermaid graph TD A[deepagents deploy] --> B[读取deepagents.toml] B --> C[配置MCP服务器] C --> D[创建LangSmith沙箱] D --> E[构建代理镜像] E --> F[启动服务] F --> G[返回部署URL] ``` **MCP 支持：** 部署时自动加载 `mcp.json` 配置，支持连接外部 MCP 服务器。版本 0.1.2 修复了 `${VAR}` 环境变量展开问题。 资料来源：[examples/deploy-coding-agent/README.md]() ## 内存管理 内存系统通过 AGENTS.md 文件提供持久化上下文，MemoryMiddleware 负责将其加载到代理的系统提示词中。 ### 缓存控制 **版本 0.6 变更：** `add_cache_control=True` 成为 MemoryMiddleware 的默认选项。 **已知问题：** - Issue #3638/#3639: 在易失性内存块上放置了不正确的 cache_control 标记 - 这可能导致上下文意外清除或保留 ### 内存与上下文 ``` AGENTS.md → MemoryMiddleware → StateModifier → System Prompt ``` 开发者通过维护项目根目录下的 AGENTS.md 定义代理的长期行为和知识。 ## 常见问题与限制 | 问题 | 严重程度 | 状态 | |------|----------|------| | 子代理检查点持久化缺失 | 高 | 待解决 | | read_file 分页换行后跳过 | 中 | 待解决 | | SummarizationMiddleware 图片丢失 | 中 | 待解决 | | 工具返回 Commands 传播不完整 | 中 | v0.6.7 已修复 | | HumanMessage ID 不稳定 | 低 | v0.6.4 已修复 | | grep 文件消失崩溃 | 低 | v0.6.4 已修复 | ## 版本演进 | 版本 | 主要变更 | |------|----------| | 0.6.7 | 工具 Commands 的 goto/graph 传播 | | 0.6.4 | 修复 grep 崩溃、HumanMessage ID 稳定性 | | 0.6.3 | ripgrep glob 锚定到搜索根目录 | | 0.6.0 | add_cache_control 默认启用 | ## 扩展开发指南 ### 创建自定义后端 ```python from deepagents import DeepAgent from deepagents.backends import FilesystemBackend class CustomBackend(FilesystemBackend): def __init__(self, root_dir: str, **kwargs): super().__init__(root_dir) # 添加自定义初始化 agent = create_deep_agent( backend=CustomBackend("./"), # ... 其他配置 ) ``` ### 创建自定义中间件 中间件需要实现状态读取和修改逻辑，通常在调用链中作为 `StateModifier` 的一部分注册。 ## 总结 deepagents 的系统架构围绕 LangGraph 状态机构建，通过中间件实现上下文管理的模块化，通过后端实现环境交互的抽象化。技能和子代理系统提供了强大的扩展能力，使代理能够处理复杂的多步骤任务。架构设计强调声明式配置和运行时组装的分离，降低了代理开发的心智负担。 --- ## 中间件系统 ### 相关页面 相关主题：[系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/middleware/filesystem.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py) - [libs/deepagents/deepagents/middleware/memory.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/memory.py) - [libs/deepagents/deepagents/middleware/summarization.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/summarization.py) - [libs/deepagents/deepagents/middleware/skills.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py) - [libs/deepagents/deepagents/middleware/subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py) - [libs/deepagents/deepagents/middleware/permissions.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/permissions.py)
# 中间件系统 ## 概述 Deep Agents 的中间件系统是一个可扩展的模块化框架，用于在 Agent 与 LLM 交互的过程中拦截、处理和增强消息流。中间件组件在消息传递给模型之前和模型响应之后进行拦截，实现文件读取、技能加载、子代理管理、内存管理和内容摘要等跨切面功能。 中间件系统的核心设计理念是将 Agent 的基础能力（文件系统访问、持久化记忆、技能调用等）与核心推理逻辑分离，使开发者能够通过组合不同中间件来定制 Agent 的行为。资料来源：[libs/deepagents/deepagents/middleware/memory.py:1-50]() ## 架构设计 ### 中间件执行模型 Deep Agents 采用链式调用模式，多个中间件按配置顺序依次处理消息。当 Agent 运行时，请求和响应会在中间件链中顺序传递，每个中间件都可以修改流经的数据或注入额外行为。 ```mermaid graph TD A[用户消息] --> B[FilesystemMiddleware] B --> C[MemoryMiddleware] C --> D[SkillsMiddleware] D --> E[SubagentsMiddleware] E --> F[PermissionsMiddleware] F --> G[LLM推理] G --> H[SummarizationMiddleware] H --> I[最终响应] ``` ### 中间件类型概览 | 中间件名称 | 主要功能 | 优先级 | |-----------|---------|--------| | FilesystemMiddleware | 文件系统访问、读取、写入、遍历 | 高 | | MemoryMiddleware | 持久化上下文、AGENTS.md 加载、缓存控制 | 高 | | SkillsMiddleware | 按需加载技能定义和工作流 | 中 | | SubagentsMiddleware | 子代理管理和结果聚合 | 中 | | SummarizationMiddleware | 长上下文压缩和摘要 | 低 | | PermissionsMiddleware | 权限检查和访问控制 | 最高 | ## 核心中间件详解 ### FilesystemMiddleware FilesystemMiddleware 是 Agent 与本地文件系统交互的基础，负责处理所有文件操作相关的工具调用。 **主要功能：** - 文件读取（支持分页和行范围指定） - 文件写入和创建 - 目录遍历和文件搜索 - glob 模式匹配 - ripgrep 内容搜索 **已知限制：** 在版本 0.6 中存在一个已知的分页问题：当使用 `read_file` 工具进行分页读取时，换行符处理会导致双重 limit 应用，绕过预期的行限制。这个问题在 issue #2453 中有详细记录。资料来源：[libs/deepagents/deepagents/middleware/filesystem.py:100-200]() ### MemoryMiddleware MemoryMiddleware 管理 Agent 的持久化上下文，通过加载 AGENTS.md 等内存文件来维护 Agent 的长期记忆和行为指南。 **关键参数：** | 参数名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | add_cache_control | bool | True | 是否在内存块上添加缓存控制标记 | | memory_files | list | [] | 内存文件路径列表 | **已知问题：** 版本 0.6 引入了 `add_cache_control=True` 作为默认值，但这会导致在易失性内存块上写入不正确的 `cache_control` 标记（issues #3638 和 #3639）。这个问题会影响使用 `MemoryMiddleware` 进行上下文管理的场景。 ### SkillsMiddleware SkillsMiddleware 实现按需加载机制，允许 Agent 在需要时动态加载技能定义和工作流指南。 **技能加载层级：** 1. **元数据层**（始终加载）：技能名称和描述，约 100 词 2. **SKILL.md 主体**（技能触发时加载）：最多 5k 词 3. **资源文件**（按需加载）：无限制，通过脚本执行 **目录结构规范：** ``` skill-name/ ├── SKILL.md # 主技能定义 ├── references/ # 参考文档（按需加载） ├── scripts/ # 可执行脚本 └── assets/ # 静态资源（不加载到上下文） ``` 资料来源：[libs/deepagents/deepagents/middleware/skills.py:50-150]() ### SubagentsMiddleware SubagentsMiddleware 负责管理和协调子代理的执行，允许主 Agent 将复杂任务委托给专门的子代理处理。 **配置示例：** ```python subagents=[ { "name": "researcher", "description": "Research topics before writing...", "model": "anthropic:claude-haiku-4-5-20251001", "system_prompt": "You are a research assistant...", "tools": [web_search], } ] ``` **已知问题：** 子代理缺乏检查点持久化支持，且状态查询时工具执行记录会被截断（issue #573）。这与主代理的行为不一致。 ### SummarizationMiddleware SummarizationMiddleware 负责在上下文超出限制时自动压缩和摘要内容，保持对话的连贯性。 **已知限制：** 存在一个已记录的图像丢失问题（issue #2873），当启用摘要功能时，消息中的图像内容可能会在压缩过程中丢失。 ### PermissionsMiddleware PermissionsMiddleware 在消息处理链的最前端执行，负责权限检查和访问控制。 ## 配置和使用 ### 通过 create_deep_agent 配置 ```python from deepagents import create_deep_agent from deepagents.middleware import ( MemoryMiddleware, SkillsMiddleware, FilesystemMiddleware, ) agent = create_deep_agent( model=model, memory=["./AGENTS.md"], skills=["./skills/"], tools=[custom_tool], backend=FilesystemBackend(root_dir="./"), ) ``` ### 中间件组合模式 中间件可以按需组合使用，常见的组合模式包括： **基础模式：** 仅包含文件和内存 **完整模式：** 包含所有中间件类型 **轻量模式：** 仅内存和技能，无子代理 ```mermaid graph LR A[基础模式] --> B["Filesystem + Memory"] C[完整模式] --> D["Filesystem + Memory + Skills + Subagents + Summarization + Permissions"] E[轻量模式] --> F["Memory + Skills"] ``` ## 工作流程示例 ### 文件读取流程 ```mermaid sequenceDiagram participant User participant Agent participant FilesystemMiddleware participant Filesystem User->>Agent: 请求读取文件 Agent->>FilesystemMiddleware: read_file(path) FilesystemMiddleware->>Filesystem: 验证路径权限 Filesystem->>FilesystemMiddleware: 返回文件内容 FilesystemMiddleware->>Agent: 处理后的内容 Agent->>User: 显示结果 ``` ### 技能加载流程 ```mermaid graph TD A[用户请求触发技能] --> B{检查技能元数据} B -->|已缓存| C[直接使用] B -->|未缓存| D[加载 SKILL.md] D --> E{内容大小检查} E -->|>10MB| F[跳过加载] E -->|<10MB| G[解析技能定义] G --> H[按需加载 references] H --> I[准备执行环境] ``` ## 社区相关问题 以下是社区反馈中与中间件系统相关的关键问题： | Issue | 组件 | 描述 | |-------|------|------| | #3639 | MemoryMiddleware | add_cache_control=True 在易失性内存块上放置错误的缓存控制标记 | | #2873 | SummarizationMiddleware | 摘要中间件处理时图像内容丢失 | | #2453 | FilesystemMiddleware | read_file 分页因双重 limit 应用而跳过行 | | #573 | SubagentsMiddleware | 子代理缺少检查点持久化，状态查询截断工具执行历史 | ## 最佳实践 ### 中间件配置建议 1. **MemoryMiddleware**：如果不需要缓存控制显式管理，考虑将 `add_cache_control` 设置为 `False` 2. **SkillsMiddleware**：保持 SKILL.md 文件在 500 行以内以减少上下文开销 3. **FilesystemMiddleware**：使用 `.deepagentsignore` 文件排除敏感或无关目录（issue #2143） ### 性能优化 - 合理配置中间件加载顺序，减少不必要的处理 - 大型技能使用 `references/` 目录按需加载 - 避免在 SKILL.md 中包含冗余文档（README、INSTALL 等） ## 相关资源 - [中间件源码目录](https://github.com/langchain-ai/deepagents/tree/main/libs/deepagents/deepagents/middleware) - [Skill 创建指南](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md) - [Content Builder Agent 示例](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/README.md) --- ## 子智能体系统 ### 相关页面 相关主题：[系统架构](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/middleware/subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/subagents.py) - [libs/deepagents/deepagents/middleware/async_subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/async_subagents.py) - [libs/deepagents/deepagents/_subagent_transformer.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/_subagent_transformer.py) - [libs/code/deepagents_code/subagents.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/subagents.py) - [examples/async-subagent-server/server.py](https://github.com/langchain-ai/deepagents/blob/main/examples/async-subagent-server/server.py) - [examples/async-subagent-server/supervisor.py](https://github.com/langchain-ai/deepagents/blob/main/examples/async-subagent-server/supervisor.py) - [examples/content-builder-agent/subagents.yaml](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/subagents.yaml) - [examples/deploy-mcp-docs-agent/README.md](https://github.com/langchain-ai/deepagents/blob/main/examples/deploy-mcp-docs-agent/README.md)
# 子智能体系统 ## 概述 子智能体（Subagents）系统是 Deep Agents 框架中用于委托任务的核心机制。该系统允许主智能体（主 Agent）将复杂任务分解为多个专门的子智能体并行或顺序执行，每个子智能体可以拥有独立的模型配置、工具集和系统提示词。子智能体系统通过 `SubagentsMiddleware` 和 `AsyncSubagentsMiddleware` 实现，支持同步和异步两种执行模式。 资料来源：[examples/content-builder-agent/README.md](examples/content-builder-agent/README.md) ## 系统架构 ### 组件关系图 ```mermaid graph TD A[主智能体 Main Agent] --> B[SubagentsMiddleware] A --> C[MemoryMiddleware] A --> D[SkillsMiddleware] B --> E[同步子智能体 Sync Subagents] B --> F[异步子智能体 Async Subagents] E --> G[独立工具集] E --> H[独立模型配置] F --> I[远程 MCP 服务器] F --> J[Agent Protocol] G --> K[文件系统操作] G --> L[网络搜索] G --> L[代码执行] style A fill:#e1f5fe style E fill:#f3e5f5 style F fill:#fff3e0 ``` ### 核心组件 | 组件 | 文件路径 | 功能描述 | |------|----------|----------| | `SubagentsMiddleware` | `libs/deepagents/deepagents/middleware/subagents.py` | 同步子智能体中间件，处理任务委托和结果聚合 | | `AsyncSubagentsMiddleware` | `libs/deepagents/deepagents/middleware/async_subagents.py` | 异步子智能体中间件，支持远程子智能体服务 | | `_SubagentTransformer` | `libs/deepagents/deepagents/_subagent_transformer.py` | 子智能体配置转换器，将 YAML/字典配置转换为运行时对象 | | `deepagents_code/subagents.py` | `libs/code/deepagents_code/subagents.py` | CLI 版本的子智能体实现 | 资料来源：[libs/deepagents/deepagents/middleware/subagents.py](libs/deepagents/deepagents/middleware/subagents.py) ## 子智能体配置 ### 配置结构 子智能体可以通过 YAML 文件或内联字典定义。以下是标准配置结构： ```yaml subagents: - name: researcher # 子智能体名称，用于任务委派 description: 研究主题... # 描述，供主智能体理解何时调用 model: anthropic:claude-haiku-4-5-20251001 # 模型配置 system_prompt: "你是一个研究助手..." # 系统提示词 tools: # 工具列表 - web_search - read_file max_iterations: 10 # 最大迭代次数 timeout: 300 # 超时时间（秒） ``` ### 内联配置示例 ```python subagents=[ { "name": "researcher", "description": "Research topics before writing...", "model": "anthropic:claude-haiku-4-5-20251001", "system_prompt": "You are a research assistant...", "tools": [web_search], } ] ``` 资料来源：[examples/content-builder-agent/README.md](examples/content-builder-agent/README.md) ## 使用方式 ### 在 Agent 创建时配置 ```python from deepagents import create_deep_agent agent = create_deep_agent( model=model, subagents=[ { "name": "researcher", "description": "Research topics thoroughly...", "model": "anthropic:claude-sonnet-4-5-20250929", "tools": [web_search, read_file], "system_prompt": "You are a thorough research assistant...", } ], backend=FilesystemBackend(root_dir="./"), ) ``` ### 使用 YAML 外部化配置 ```python import yaml def load_subagents(path: str) -> list[dict]: with open(path) as f: config = yaml.safe_load(f) return config.get("subagents", []) agent = create_deep_agent( subagents=load_subagents("./subagents.yaml"), # ...其他配置 ) ``` 资料来源：[examples/content-builder-agent/content_writer.py](examples/content-builder-agent/content_writer.py) ## 任务委托机制 ### 任务委派工作流 ```mermaid sequenceDiagram participant User as 用户 participant Main as 主智能体 participant Middleware as SubagentsMiddleware participant Sub as 子智能体 User->>Main: 发送复杂任务 Main->>Main: 分析任务 Main->>Middleware: 请求委托任务 Middleware->>Sub: 创建子智能体实例 Sub->>Sub: 执行子任务 Sub-->>Middleware: 返回结果 Middleware-->>Main: 聚合结果 Main-->>User: 返回最终答案 ``` ### Web 研究技能中的子智能体使用 ```markdown ### Step 2: Delegate to Research Subagents For each subtopic in your plan: 1. **Use the `task` tool** to spawn a research subagent with: - Clear, specific research question (no acronyms) - Instructions to write findings to a file: `research_[topic_name]/findings_[subtopic].md` - Budget: 3-5 web searches maximum ``` 资料来源：[libs/cli/examples/skills/web-research/SKILL.md](libs/cli/examples/skills/web-research/SKILL.md) ## 异步子智能体服务 ### 架构概述 异步子智能体允许将子智能体部署为独立的远程服务，通过 Agent Protocol 与主智能体通信。这适用于需要分布式执行或跨语言集成的场景。 ```mermaid graph LR A[主智能体] -->|HTTP/Agent Protocol| B[AsyncSubagentsMiddleware] B --> C[MCP Server] C --> D[Researcher Subagent] C --> E[Analyzer Subagent] ``` ### 服务器实现 异步子智能体服务器基于 [Agent Protocol](https://github.com/agent-protocol/protocol) 标准实现： ```python # examples/async-subagent-server/server.py from agent_protocol import Agent app = Agent(name="researcher") @app.run_once async def research_task(task: str): # 实现研究逻辑 return {"findings": "..."} ``` ### 监督器配置 ```python # examples/async-subagent-server/supervisor.py from deepagents import create_deep_agent supervisor = create_deep_agent( subagents=[ { "name": "researcher", "type": "async", "url": "http://localhost:8000", "description": "远程研究子智能体", } ] ) ``` 资料来源：[examples/async-subagent-server/server.py](examples/async-subagent-server/server.py) ## 配置参数详解 ### 子智能体配置参数 | 参数 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | `name` | `str` | 是 | - | 子智能体唯一标识符 | | `description` | `str` | 是 | - | 描述子智能体能力，供主智能体决策 | | `model` | `str` | 否 | 继承主模型 | 子智能体使用的模型 | | `system_prompt` | `str` | 否 | - | 子智能体系统提示词 | | `tools` | `list[BaseTool]` | 否 | `[]` | 子智能体可用工具列表 | | `max_iterations` | `int` | 否 | 10 | 最大迭代次数 | | `timeout` | `int` | 否 | 300 | 超时时间（秒） | | `type` | `str` | 否 | `"sync"` | 子智能体类型：`sync` 或 `async` | | `url` | `str` | 异步必需 | - | 异步子智能体服务地址 | 资料来源：[libs/deepagents/deepagents/_subagent_transformer.py](libs/deepagents/deepagents/_subagent_transformer.py) ## 已知限制与问题 ### 检查点持久化问题 根据社区反馈（Issue #573），当前版本的子智能体存在以下问题： - 子智能体未启用检查点持久化 - 查询状态时，子智能体的工具执行记录会被截断 - 这与主智能体的行为不一致 > **Bug Report**: Subagents in deepagents do not have checkpoint persistence enabled, and when querying state, the tool execution records from subagents are truncated. This is inconsistent with... 资料来源：[GitHub Issue #573](https://github.com/langchain-ai/deepagents/issues/573) ## 最佳实践 ### 1. 任务分解策略 将复杂任务分解为独立的、可并行的子任务： ```python subagents = [ { "name": "market_analysis", "description": "分析市场趋势和竞争格局", "tools": [web_search, read_file], }, { "name": "technical_research", "description": "调研技术方案和实现路径", "tools": [code_search, read_file], } ] ``` ### 2. 工具隔离 为不同子智能体配置专用工具集，避免权限过度： ```python researcher_tools = [web_search, tavily_search] coder_tools = [read_file, write_file, execute_code] subagents = [ {"name": "researcher", "tools": researcher_tools}, {"name": "coder", "tools": coder_tools} ] ``` ### 3. 结果持久化 子智能体应将结果写入文件，便于主智能体汇总： ```markdown After completing your research, use write_file to save your findings to research_[topic_name]/findings_[subtopic].md. Include key facts, relevant quotes, and source URLs. ``` 资料来源：[libs/cli/examples/skills/web-research/SKILL.md](libs/cli/examples/skills/web-research/SKILL.md) ### 4. 并行执行控制 限制并行子智能体数量以控制资源使用： ```markdown **Run up to 3 subagents in parallel** for efficient research ``` ## 与其他系统的集成 ### 与 Skills 系统集成 子智能体可以在技能中被调用，形成分层架构： ```mermaid graph TD A[主智能体] --> B[Skill: Web Research] B --> C[Researcher 子智能体] B --> D[Analyzer 子智能体] C --> E[Web Search 工具] D --> F[分析逻辑] ``` ### 与 Memory 系统对比 | 特性 | Memory | Subagents | |------|--------|-----------| | 用途 | 持久化上下文 | 任务委托 | | 配置 | `AGENTS.md` 文件 | YAML/字典 | | 生命周期 | 随 Agent 持续 | 单次任务 | | 通信 | 通过上下文 | 显式消息传递 | 资料来源：[examples/content-builder-agent/README.md](examples/content-builder-agent/README.md) ## 示例项目 ### 内容构建智能体 该示例展示了如何使用子智能体进行内容研究和写作分离： ``` content-builder-agent/ ├── AGENTS.md # 品牌语音和风格指南 ├── subagents.yaml # 子智能体定义 ├── skills/ │ ├── blog-post/ # 博客写作技能 │ └── social-media/ # 社交媒体技能 └── content_writer.py # 主程序 ``` **工作流**： 1. Agent 接收任务 → 加载相关技能 2. 委托研究任务给 `researcher` 子智能体 → 保存到 `research/` 3. 根据技能工作流写作 → 保存到 `blogs/` 或 `linkedin/` 4. 使用 Gemini 生成封面图 资料来源：[examples/content-builder-agent/README.md](examples/content-builder-agent/README.md) ### 深度研究智能体 部署在 LangSmith Sandbox 的研究智能体，使用 MCP 工具搜索 LangChain 文档： ```bash deepagents deploy ``` 资料来源：[examples/deploy-mcp-docs-agent/README.md](examples/deploy-mcp-docs-agent/README.md) ## 总结 子智能体系统是 Deep Agents 实现复杂任务分解和并行处理的核心机制。通过支持同步和异步两种模式、灵活的配置方式以及与 Skills 系统的深度集成，开发者可以构建高度模块化的多智能体应用。当前版本在检查点持久化方面存在已知限制，社区正在积极修复中。 --- ## 文件系统功能 ### 相关页面 相关主题：[后端系统](#page-backends)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/middleware/filesystem.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py) - [libs/deepagents/deepagents/backends/filesystem.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/filesystem.py) - [libs/deepagents/deepagents/backends/protocol.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/protocol.py) - [libs/cli/examples/skills/web-research/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/web-research/SKILL.md) - [libs/cli/examples/skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/SKILL.md)
# 文件系统功能 Deep Agents 的文件系统功能是智能体与本地文件系统交互的核心模块，负责文件读取、写入、搜索、遍历等操作。该功能由 `FilesystemMiddleware` 和 `FilesystemBackend` 两个主要组件提供支持，并与 `SandboxBackend` 协同工作以实现安全的沙箱环境中的文件操作。 ## 核心架构 文件系统功能采用分层架构设计，通过中间件层和后端层分离关注点： ```mermaid graph TD A[Agent] --> B[FilesystemMiddleware] B --> C[FilesystemBackend] C --> D[SandboxBackend] C --> E[Local Filesystem] D --> F[Container Environment] B --> G[Tool: read_file] B --> H[Tool: write_file] B --> I[Tool: grep] B --> J[Tool: list_files] ``` ### 组件职责 | 组件 | 职责 | 位置 | |------|------|------| | `FilesystemMiddleware` | 管理文件系统工具注册、上下文加载、文件忽略规则 | `middleware/filesystem.py` | | `FilesystemBackend` | 提供文件系统操作的基础实现 | `backends/filesystem.py` | | `SandboxBackend` | 沙箱环境中的文件操作封装 | 容器化环境 | | `BackendProtocol` | 定义后端接口协议 | `backends/protocol.py` | ## FilesystemMiddleware `FilesystemMiddleware` 是文件系统功能的核心中间件，负责向智能体注册文件系统相关工具，并处理文件内容的上下文管理。 ### 主要功能 1. **工具注册**：自动注册 `read_file`、`write_file`、`grep`、`list_files` 等工具到智能体 2. **上下文管理**：将 `AGENTS.md` 和内存文件内容加载到智能体的系统提示中 3. **忽略规则处理**：支持 `.deepagentsignore` 文件配置 4. **分页读取**：支持大文件分页读取，避免上下文溢出 ### 构造参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `root_dir` | `str \| Path` | `"."` | 文件系统根目录 | | `add_ignore_patterns` | `list[str]` | `[]` | 额外的忽略模式 | | `skip_hidden` | `bool` | `True` | 跳过隐藏文件 | | `include_media` | `bool` | `False` | 包含媒体文件 | | `include_archives` | `bool` | `False` | 包含归档文件 | | `read_file_max_lines` | `int` | `500` | 单次读取最大行数 | 资料来源：[middleware/filesystem.py]() ## read_file 工具 `read_file` 是智能体读取文件内容的主要工具，支持分页读取和行范围指定。 ### 功能特性 - **行范围读取**：通过 `start_line` 和 `end_line` 参数指定读取范围 - **分页支持**：大文件自动分页，每次最多读取 500 行（可配置） - **编码处理**：自动处理文件编码，识别 base64 编码文件 ### 已知问题 > ⚠️ **社区反馈**：Issue #2453 报告了分页读取存在 bug，当文件内容发生换行时，双重 limit 应用导致分页跳过部分行。 > > 症状：使用分页读取大文件时，某些行被意外跳过。 此问题在后续版本中已修复，0.6.4 版本中包含了对 grep 相关问题的修复。 ## write_file 工具 `write_file` 工具允许智能体创建或覆盖文件内容。 ### 功能特性 - **路径创建**：支持创建不存在的目录路径 - **内容写入**：直接写入文本内容或 base64 编码数据 - **安全限制**：受沙箱环境约束，无法写入沙箱外部路径 ## grep 工具 `grep` 工具提供文件内容搜索功能，基于 ripgrep 实现高效全文搜索。 ### 功能特性 - **正则搜索**：支持 PCRE 兼容的正则表达式 - **路径过滤**：支持 glob 模式指定搜索文件范围 - **上下文行**：可配置显示匹配行的上下文 - **大小写敏感**：支持大小写不敏感搜索 ### 已知问题与修复 > 🔧 **修复记录**：以下问题已在 0.6.3 和 0.6.4 版本中修复： > > - **0.6.3**：ripgrep glob 锚定到搜索根目录（#3454） > - **0.6.4**：文件在遍历过程中消失时 grep 不再崩溃（#3592） > - **0.6.4**：`SandboxBackend.grep` 在容器执行失败时抛出 ValueError（#3441） ## list_files 工具 `list_files` 工具用于列出目录结构和文件信息。 ### 功能特性 - **递归遍历**：支持递归列出子目录内容 - **模式过滤**：支持 glob 模式过滤文件 - **忽略规则**：自动遵守 `.deepagentsignore` 配置 - **隐藏文件**：可选包含或排除隐藏文件 ## .deepagentsignore 支持 `.deepagentsignore` 文件允许用户排除特定文件和目录，使其不被智能体访问。 ### 功能状态 > 📋 **社区需求**：Issue #2143 请求添加 `.deepagentsignore` 支持，与其他编程智能体保持一致： > - Claude Code: `.claudeignore` > - Gemini CLI: `.geminiignore` > - Cline: `.clineignore` 该功能已在 CLI 版本中实现，支持类 gitignore 语法的文件排除规则。 ### 使用方式 在项目根目录创建 `.deepagentsignore` 文件： ``` # 排除 node_modules node_modules/ # 排除构建产物 dist/ build/ *.pyc # 排除敏感文件 .env *.pem # 排除文档（节省上下文空间） *.md docs/ ``` ## Sandboxes 环境中的文件系统 在沙箱（Sandbox）环境中运行时，文件系统功能通过 `SandboxBackend` 提供额外的安全隔离。 ### 沙箱特性 - **容器隔离**：文件操作在隔离的容器环境中执行 - **快照支持**：支持通过 `--sandbox-snapshot-name` 标志恢复特定快照状态 - **临时存储**：支持临时文件操作 ### Grep 在沙箱中的行为 ```mermaid graph LR A[grep 请求] --> B[SandboxBackend.grep] B --> C{容器执行状态} C -->|成功| D[返回搜索结果] C -->|失败| E[处理 ValueError] E --> F[优雅降级] ``` ## Provider-Native 文件上传 > 🔮 **功能请求**：Issue #2630 请求在 `FilesystemMiddleware` / `read_file` 中支持 Provider-Native 文件上传功能。 该功能目前处于规划阶段，将允许直接上传文件到云存储 Provider，而非通过 base64 编码传输。 ## 最佳实践 ### 1. 合理配置忽略规则 使用 `.deepagentsignore` 排除不必要的文件，减少上下文噪音： ``` # 推荐排除 __pycache__/ .git/ .vscode/ # 谨慎排除 # 不要排除正在编辑的源文件 ``` ### 2. 大文件分页读取 对于超过 500 行的文件，使用分页参数逐步读取： ```python # 第一部分：读取前 500 行 read_file("large_file.py", start_line=1, end_line=500) # 第二部分：读取后续内容 read_file("large_file.py", start_line=501, end_line=1000) ``` ### 3. 搜索优化 使用精确的 glob 模式减少搜索范围： ```bash # 搜索特定文件类型 grep "function_name" --glob="*.py" # 限制搜索深度 grep "pattern" --max-depth=2 ``` ## 相关资源 - [Deep Agents 文档](https://docs.langchain.com/oss/python/deepagents/overview) - [API 参考 - FilesystemMiddleware](https://reference.langchain.com/python/deepagents/) - [社区讨论](https://forum.langchain.com/c/oss-product-help-lc-and-lg/deep-agents/18) --- ## 技能系统 ### 相关页面 相关主题：[快速开始](#page-quickstart)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/middleware/skills.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py) - [libs/code/deepagents_code/skills/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/skills/__init__.py) - [libs/code/deepagents_code/skills/load.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/skills/load.py) - [libs/code/deepagents_code/skills/invocation.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/skills/invocation.py) - [libs/code/built_in_skills/skill-creator/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/libs/code/built_in_skills/skill-creator/SKILL.md) - [examples/content-builder-agent/skills/blog-post/SKILL.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/skills/blog-post/SKILL.md) - [examples/content-builder-agent/AGENTS.md](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/AGENTS.md) - [examples/content-builder-agent/content_writer.py](https://github.com/langchain-ai/deepagents/blob/main/examples/content-builder-agent/content_writer.py)
# 技能系统 ## 概述 技能系统（Skills System）是 Deep Agents 框架中用于扩展代理能力的核心模块。它允许开发者将特定领域的专业工作流程封装为可复用的技能模块，使代理能够根据用户需求动态加载和执行相应的技能。 技能系统采用文件系统优先的设计理念，通过在特定目录中放置 `SKILL.md` 文件来定义技能。当用户的请求与技能的描述匹配时，中间件自动将技能内容加载到代理的上下文中，触发相应的工作流程执行。 **核心特点：** - **按需加载**：技能仅在触发时被加载，避免不必要的上下文膨胀 - **文件系统驱动**：技能通过目录结构和 Markdown 文件定义，无需编写代码 - **渐进式披露**：采用三层加载机制平衡上下文效率和信息完整性 - **可组合性**：支持脚本、参考资料和资源资产的多层次组织 资料来源：[examples/content-builder-agent/README.md]() ## 架构设计 ### 系统组件 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 代理层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ Memory │ │ Skills │ │ Subagents │ │ │ │ (AGENTS.md) │ │ Middleware │ │ (subagents.yaml) │ │ │ └─────────────┘ └──────┬──────┘ └─────────────────────────┘ │ └──────────────────────────┼──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 技能中间件层 │ │ ┌─────────────────────────────────────────────────────────────┐│ │ │ SkillsMiddleware ││ │ │ - skill_loader: 技能发现与加载 ││ │ │ - invocation_handler: 技能触发与执行 ││ │ │ - context_manager: 上下文注入管理 ││ │ └─────────────────────────────────────────────────────────────┘│ └──────────────────────────┬──────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 技能存储层 │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ 用户技能 │ │ 项目技能 │ │ 内置技能 │ │ │ │~/.deepagents│ │ ./skills/ │ │ libs/code/built_in_skills│ │ │ /agent/skills│ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### 技能目录结构 一个完整的技能包含以下目录结构： | 目录 | 用途 | 加载方式 | |------|------|----------| | `SKILL.md` | 技能主体定义，包含触发描述和工作流程 | 触发时加载到上下文 | | `scripts/` | 可执行脚本（Python/Bash等） | 按需执行，不加载到上下文 | | `references/` | 参考文档和详细资料 | 代理决定何时加载 | | `assets/` | 非上下文文件（模板、图片等） | 仅在输出中使用 | 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 技能定义格式 ### SKILL.md 结构 每个技能的核心是 `SKILL.md` 文件，采用 YAML frontmatter 定义元数据： ```yaml --- name: skill-name description: 技能触发描述，用于匹配用户请求 --- # 技能标题 ## 工作流程说明 ... ``` **必需字段：** | 字段 | 类型 | 说明 | |------|------|------| | `name` | string | 技能唯一标识符 | | `description` | string | 技能触发描述，代理根据此判断何时使用该技能 | 资料来源：[examples/content-builder-agent/skills/blog-post/SKILL.md]() ### 示例技能 **博客文章技能** (`blog-post/SKILL.md`)： ```yaml --- name: blog-post description: Write long-form blog posts with SEO optimization and clear structure. --- # Blog Post Writing Write blog posts that are informative, engaging, and optimized for search. ## Structure 1. **Title** — Clear, compelling, includes target keyword 2. **Introduction** — Hook the reader, state the problem, preview the solution 3. **Body** — 3-5 sections with headers, each making one clear point 4. **Conclusion** — Summarize key takeaways, include a call to action ``` **社交媒体技能** (`social-media/SKILL.md`)： ```yaml --- name: social-media description: Create social media posts optimized for engagement across platforms. --- # Social Media Content Create platform-appropriate social media posts. ## Guidelines - Keep it concise and punchy - Lead with a hook - Include a clear call to action - Adapt tone per platform ``` 资料来源：[libs/cli/examples/deploy-content-writer/skills/blog-post/SKILL.md]() 资料来源：[libs/cli/examples/deploy-content-writer/skills/social-media/SKILL.md]() ## 技能加载机制 ### 三层渐进式披露 技能系统采用三级加载机制优化上下文使用： | 层级 | 内容 | 加载时机 | 上下文影响 | |------|------|----------|------------| | **元数据** | name + description | 始终在上下文 | ~100 词 | | **主体内容** | SKILL.md body | 技能触发时 | <5k 词 | | **捆绑资源** | scripts/references/assets | 按需执行/读取 | 无限制 | 这种设计确保了： - 代理始终了解可用技能列表（通过元数据） - 仅在需要时加载详细工作流程 - 脚本和资源可以无限制使用，不消耗上下文 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ### 技能发现流程 ``` 用户请求 │ ▼ ┌─────────────────┐ │ 解析描述匹配 │ │ description字段 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 加载SKILL.md │ │ 主体内容 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 执行工作流程 │ │ 按需访问资源 │ └─────────────────┘ ``` ### 文件大小限制 - **SKILL.md 主体**：建议不超过 500 行，保持精简 - **SKILL.md 总大小**：超过 10MB 的文件会被运行时静默跳过 - **参考资料**：超过 10k 词的建议在 SKILL.md 中包含搜索模式 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 技能创建流程 ### 创建步骤 | 步骤 | 描述 | 跳过条件 | |------|------|----------| | 1. 理解技能需求 | 通过具体示例明确技能用途 | 已有清晰的使用模式 | | 2. 规划技能内容 | 确定 scripts/references/assets | 仅需简单技能 | | 3. 初始化技能 | 运行 `init_skill.py` | 技能已存在 | | 4. 编辑技能 | 编写 SKILL.md 和资源文件 | 迭代开发 | | 5. 验证技能 | 运行 `quick_validate.py` | 快速测试 | 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ### 使用 init_skill.py 初始化 ```bash # 用户技能（默认） scripts/init_skill.py --path ~/.deepagents/agent/skills # 项目技能 scripts/init_skill.py ``` 初始化脚本会自动生成技能模板目录结构。 ### 理解技能需求 创建有效技能的关键是明确具体使用示例： **需要回答的问题：** - 技能支持哪些具体功能？ - 提供一些技能使用的具体例子？ - 用户会如何表述触发技能的需求？ - 技能应该包含哪些输出格式和质量标准？ 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 技能位置与作用域 ### 技能存储位置 Deep Agents 支持多层级的技能存储： | 位置 | 路径 | 作用域 | 使用场景 | |------|------|--------|----------| | 用户级技能 | `~/.deepagents/agent/skills/` | 所有项目 | 个人工作流程 | | 项目级技能 | `./skills/` | 当前项目 | 团队共享 | | 内置技能 | `libs/code/built_in_skills/` | SDK 内置 | 框架提供 | 资料来源：[examples/content-builder-agent/README.md]() ### 内容构建代理示例 ```python agent = create_deep_agent( memory=["./AGENTS.md"], # 内存：持久化上下文 skills=["./skills/"], # 技能：按需加载 tools=[generate_cover, ...], # 工具：自定义功能 subagents=load_subagents(...), # 子代理：委托任务 backend=FilesystemBackend(...), ) ``` 代理接收 `skills` 参数，指定技能目录路径，中间件自动扫描并管理技能加载。 资料来源：[examples/content-builder-agent/content_writer.py]() ## 资源组织最佳实践 ### scripts/ 目录 **适用场景：** 可自动化执行的操作 **示例：** - PDF 技能：`fill_fillable_fields.py`, `extract_form_field_info.py` - DOCX 技能：`document.py`, `utilities.py` **特点：** - 可直接执行，不加载到上下文 - 支持 Python、Bash 等脚本语言 - 用于数据处理、文件操作等自动化任务 ### references/ 目录 **适用场景：** 需要加载到上下文的参考资料 **示例：** - `references/finance.md` - 金融数据模式 - `references/api_docs.md` - API 规范文档 - `references/policies.md` - 公司政策 **最佳实践：** - 超过 100 行的文件应在顶部包含目录结构 - 大文件（>10k 词）在 SKILL.md 中包含搜索模式 - 避免与 SKILL.md 重复，保持单一信息源 ### assets/ 目录 **适用场景：** 输出资源而非上下文内容 **示例：** - 品牌标识：`assets/logo.png` - 模板文件：`assets/slides.pptx` - 前端模板：`assets/frontend-template/` - 字体文件：`assets/font.ttf` **特点：** - 不加载到上下文 - 用于生成输出的素材 - 支持模板、图标、示例文档等 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 社区关注点 ### 热门议题 **Issue #506 - 非 CLI 版本技能支持** 社区反馈希望在非 CLI 版本中使用技能功能。当前 CLI 版本可以通过文件系统直接使用技能，但需要聊天类应用交互自定义代理时缺少技能支持。 ``` For common use cases cli version not appropriate, and need something like chat base application to interact with custom agent (with skill support, it will be very helpful) ``` **Issue #180 - Agent Skills 支持** 社区讨论是否应将类似 Anthropic Agent Skills 的功能作为 Deep Agent 的原生特性。 资料来源：[GitHub Issue #506](https://github.com/langchain-ai/deepagents/issues/506) 资料来源：[GitHub Issue #180](https://github.com/langchain-ai/deepagents/issues/180) ## 设计原则 ### 避免过度嵌套引用 - 所有参考文件应直接从 SKILL.md 链接 - 保持引用层级单一深度 - 避免深层嵌套的引用链 ### 长文件结构化 对于超过 100 行的参考文件： - 在文件顶部包含目录结构 - 便于代理预览完整内容范围 - 提高信息可发现性 ### 不应包含的内容 技能应只包含核心功能必需的文件，**不应包含**： - `README.md` - `INSTALLATION_GUIDE.md` - `QUICK_REFERENCE.md` - `CHANGELOG.md` - 任何用户面向的辅助文档 技能应专注于为 AI 代理提供执行任务所需的信息，而非人类使用文档。 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 进阶模式 ### 多步骤流程模式 对于需要顺序执行和多条件判断的工作流，参考 `references/workflows.md` 中的模式。 ### 输出格式与质量标准 对于特定的输出格式要求，参考 `references/output-patterns.md` 中的模板和示例模式。 资料来源：[libs/cli/examples/skills/skill-creator/SKILL.md]() ## 与其他系统的协作 ### 技能与内存系统 技能系统与内存系统（`AGENTS.md`）协同工作： | 组件 | 定义方式 | 加载时机 | 用途 | |------|----------|----------|------| | 内存 | `AGENTS.md` | 始终加载 | 持久化上下文、品牌指南 | | 技能 | `skills/*/SKILL.md` | 触发时加载 | 特定任务工作流程 | 资料来源：[examples/content-builder-agent/README.md]() ### 技能与子代理 技能可以触发子代理执行： ```yaml # web-research/SKILL.md 示例 ### Step 2: Delegate to Research Subagents For each subtopic in your plan: 1. **Use the `task` tool** to spawn a research subagent with: - Clear, specific research question - Instructions to write findings to a file - Budget: 3-5 web searches maximum ``` 资料来源：[libs/cli/examples/skills/web-research/SKILL.md]() --- ## 上下文管理 ### 相关页面 相关主题：[中间件系统](#page-middleware)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/middleware/_overflow_clip.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/_overflow_clip.py) - [libs/deepagents/deepagents/middleware/_message_eviction.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/_message_eviction.py) - [libs/deepagents/deepagents/middleware/_tool_exclusion.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/_tool_exclusion.py) - [libs/deepagents/deepagents/offload.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/offload.py)
# 上下文管理 ## 概述 Deep Agents 的上下文管理是确保大语言模型在有限上下文窗口内高效运行的核心机制。它涉及多个层面的管理策略，包括消息溢出处理、内存块管理、工具排除机制以及文件系统访问控制。这套系统通过中间件（Middleware）架构实现，允许在运行时动态调整进入模型上下文的内容。 上下文管理的核心目标是解决三个关键问题： 1. **上下文溢出**：当对话历史或工具输出超过模型上下文限制时的处理 2. **内容筛选**：根据规则排除不相关或敏感的文件、工具和消息 3. **缓存控制**：管理记忆块的缓存生命周期 ## 架构概览 ```mermaid graph TD A[用户输入] --> B[FilesystemMiddleware] B --> C[MemoryMiddleware] C --> D[ToolExclusionMiddleware] D --> E[MessageEvictionMiddleware] E --> F[OverflowClipMiddleware] F --> G[LLM上下文] H[AGENTS.md] --> C I[技能定义] --> C J[.deepagentsignore] --> B K[子代理结果] --> E ``` ## 消息溢出处理 ### OverflowClipMiddleware `OverflowClipMiddleware` 负责在消息总长度超过配置阈值时触发截断操作。当消息列表增长到接近上下文限制时，该中间件会智能地移除最早的用户-助手对话对，保留最近的交互历史。 资料来源：[libs/deepagents/deepagents/middleware/_overflow_clip.py:1-50]() ### 配置参数 | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `max_messages` | int | 200 | 最大消息条数阈值 | | `clip_ratio` | float | 0.8 | 触发截断时的保留比例 | | `system_first` | bool | True | 是否保留系统消息 | ### 截断策略 截断过程遵循以下优先级保留消息： 1. **系统消息**：始终保留在上下文开头 2. **工具调用消息**：保留工具执行记录以维持可追溯性 3. **最新对话**：保留最近的 user-assistant 对话对 4. **早期对话**：按 LIFO 顺序逐步移除 ```python # 截断逻辑示意 def clip_messages(messages, max_messages, clip_ratio): target_count = int(max_messages * clip_ratio) # 保留系统消息 + 工具消息 + 最新对话 return preserved_messages + messages[-target_count:] ``` ## 消息驱逐策略 ### MessageEvictionMiddleware 消息驱逐中间件实现了更细粒度的上下文管理策略。它不仅处理溢出，还根据消息类型、重要性和时间戳进行优先级排序。 资料来源：[libs/deepagents/deepagents/middleware/_message_eviction.py:1-80]() ### 驱逐算法 消息驱逐采用基于权重的评分系统： | 消息类型 | 基础权重 | 说明 | |----------|----------|------| | system | 1.0 | 系统指令，最高优先级 | | tool | 0.8 | 工具调用和结果 | | assistant | 0.6 | 助手响应 | | user | 0.4 | 用户消息 | ### 驱逐触发条件 驱逐机制在以下条件满足时触发： - 消息总数超过 `max_messages` - 上下文令牌数超过 `max_tokens` 阈值 - 单条消息长度超过 `max_single_message_tokens` ## 工具排除机制 ### ToolExclusionMiddleware 工具排除中间件根据运行时条件动态禁用特定工具。当检测到特定错误模式或资源限制时，相关工具会被标记为不可用，避免在后续执行中继续尝试失败的操作。 资料来源：[libs/deepagents/deepagents/middleware/_tool_exclusion.py:1-60]() ### 排除策略 | 策略类型 | 触发条件 | 排除时长 | |----------|----------|----------| | 临时排除 | 连续 N 次执行失败 | 指数退避 | | 永久排除 | 检测到不可恢复错误 | 会话剩余时间 | | 条件排除 | 特定环境状态 | 条件满足前 | ### 错误模式识别 ```python # 支持的错误模式 EXCLUDABLE_ERRORS = [ "Permission denied", "File not found", "Timeout exceeded", "Resource unavailable" ] ``` ## 内存与缓存控制 ### MemoryMiddleware `MemoryMiddleware` 负责将持久化记忆加载到 Agent 的系统提示中。版本 0.6 引入了 `add_cache_control` 参数来管理记忆块的缓存行为。 资料来源：[libs/deepagents/deepagents/offload.py:1-100]() ### 缓存控制机制 | 参数 | 说明 | 默认值 | |------|------|--------| | `add_cache_control` | 是否添加缓存控制标记 | True (v0.6+) | | `cache_ttl` | 缓存生存时间（秒） | 3600 | | `volatile_threshold` | volatile 块识别阈值 | 0.5 | ### 已知问题 **Issue #3638 & #3639**：当 `add_cache_control=True` 时，`MemoryMiddleware` 会在易失性内存块（volatile memory block）上设置错误的 `cache_control` 标记。这可能导致： - 缓存策略与内容类型不匹配 - 重要记忆被过早驱逐 - 上下文中的记忆重复加载 社区建议在等待修复期间将 `add_cache_control` 设置为 `False` 以避免此问题。 ## 文件系统上下文管理 ### FilesystemMiddleware 文件系统中间件管理 Agent 对本地文件的访问权限。通过集成 `.deepagentsignore` 规则，可以精确控制哪些文件和目录对 Agent 可见。 资料来源：[Issue #2143](https://github.com/langchain-ai/deepagents/issues/2143) ### .deepagentsignore 配置 ```gitignore # 模式匹配规则 *.log # 排除日志文件 __pycache__/ # 排除 Python 缓存 .env # 排除环境变量 node_modules/ # 排除依赖目录 .git/ # 排除版本控制目录 ``` ### 排除范围 `.deepagentsignore` 影响以下操作： | 操作 | 影响 | |------|------| | `read_file` | 文件读取时自动跳过忽略的文件 | | `@` 引用 | 自动补全时排除被忽略的文件 | | 文件系统遍历 | 目录扫描时跳过匹配规则的内容 | | `grep` 搜索 | 搜索范围排除匹配的文件 | ### read_file 分页问题 **Issue #2453**：当前 `read_file` 在处理大文件时存在分页 bug。由于双重 limit 应用，长文件在换行后会导致后续行被跳过。建议在等待修复期间使用 `grep` 工具进行大文件内容检索。 ## 上下文卸载机制 ### Offload 模块 `offload.py` 提供了将非关键上下文内容卸载到持久化存储的能力。当上下文即将溢出时，系统可以自动将部分内容移动到外部存储，并在需要时重新加载。 资料来源：[libs/deepagents/deepagents/offload.py:1-100]() ### 卸载策略 ```mermaid graph LR A[上下文接近满] --> B{检查卸载候选} B --> C{内容优先级} C --> D[低优先级内容] D --> E[序列化到磁盘] E --> F[释放上下文空间] F --> G[请求时重新加载] ``` ### 卸载内容类型 | 内容类型 | 卸载优先级 | 重新加载条件 | |----------|------------|--------------| | 历史工具输出 | 高 | 需要回溯执行步骤 | | 早期对话 | 中 | 用户明确请求 | | 系统指令摘要 | 低 | 上下文清理后 | ## 最佳实践 ### 1. 合理配置上下文限制 ```python from deepagents import create_deep_agent from deepagents.middleware import OverflowClipMiddleware agent = create_deep_agent( middleware=[ OverflowClipMiddleware(max_messages=150, clip_ratio=0.75), MessageEvictionMiddleware(max_tokens=150000), ] ) ``` ### 2. 善用 .deepagentsignore 将敏感文件、大型二进制文件和自动生成的文件添加到 `.deepagentsignore`，以减少不必要的上下文占用。 ### 3. 分离工具职责 使用 `ToolExclusionMiddleware` 配合错误处理，实现工具级别的优雅降级。当某个工具持续失败时，系统会自动排除它而不会中断整个 Agent 流程。 ### 4. 记忆块管理 对于长期运行的 Agent，定期检查 `MemoryMiddleware` 的缓存状态，避免因 Issue #3638/3639 导致的记忆丢失。 ## 相关资源 | 资源 | 说明 | |------|------| | [Middleware 文档](https://docs.langchain.com/oss/python/deepagents/middleware) | 中间件系统完整参考 | | [API 参考](https://reference.langchain.com/python/deepagents/) | 所有 Middleware 类详细 API | | [示例代码](../examples/) | 上下文管理的实际应用示例 | ## 已知限制与待解决问题 | Issue | 问题描述 | 影响范围 | 状态 | |-------|----------|----------|------| | [#2453](https://github.com/langchain-ai/deepagents/issues/2453) | read_file 分页在换行后跳过行 | 大文件读取 | 待修复 | | [#3638](https://github.com/langchain-ai/deepagents/issues/3638) | 缓存控制标记位置错误 | MemoryMiddleware | 待修复 | | [#3639](https://github.com/langchain-ai/deepagents/issues/3639) | 易失性块缓存标记错误 | MemoryMiddleware | 待修复 | --- ## 后端系统 ### 相关页面 相关主题：[沙箱环境](#page-sandbox)
相关源码文件 以下源码文件用于生成本页说明： - [libs/deepagents/deepagents/backends/__init__.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/__init__.py) - [libs/deepagents/deepagents/backends/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/sandbox.py) - [libs/deepagents/deepagents/backends/store.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/store.py) - [libs/deepagents/deepagents/backends/state.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/state.py) - [libs/deepagents/deepagents/backends/protocol.py](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/protocol.py)
# 后端系统 Deep Agents 的后端系统是整个框架的核心基础设施，负责管理 Agent 的执行环境、状态持久化、文件系统操作和沙箱隔离。本页面详细说明后端系统的架构设计、核心组件和配置方式。 ## 系统架构概述 Deep Agents 后端系统采用插件化架构，通过抽象接口定义统一的后端协议，支持多种执行环境的灵活切换。系统设计遵循以下核心原则： - **环境隔离**：通过沙箱机制确保 Agent 操作的安全性 - **状态持久化**：支持检查点保存和状态恢复 - **文件系统抽象**：提供统一的文件操作接口 - **协议驱动**：基于 Agent Protocol 标准实现通信 ```mermaid graph TD A[Agent Core] --> B[Backend Protocol] B --> C[SandboxBackend] B --> D[FilesystemBackend] B --> E[Store Backend] C --> F[LangSmith Sandbox] D --> G[Local Filesystem] E --> H[State Store] F --> I[Container Runtime] G --> J[File System] ``` ## 后端组件体系 ### 核心后端类型 Deep Agents 提供四种主要后端实现，每种后端针对不同的使用场景： | 后端类型 | 用途 | 适用场景 | |---------|------|---------| | `SandboxBackend` | 云端沙箱执行环境 | 远程部署、安全隔离 | | `FilesystemBackend` | 本地文件系统访问 | 本地开发、直接文件操作 | | `StoreBackend` | 键值状态存储 | 状态管理和持久化 | | `StateBackend` | 状态检查点管理 | 复杂状态流转 | ### Backend Protocol 接口 所有后端必须实现 `BackendProtocol` 定义的标准化接口，确保组件间的互操作性： 资料来源：[libs/deepagents/deepagents/backends/protocol.py]() ```python class BackendProtocol(Protocol): """后端协议接口定义""" async def read_file(self, path: str, ...) -> str: ... async def write_file(self, path: str, ...) -> None: ... async def list_files(self, path: str, ...) -> list[str]: ... async def grep(self, pattern: str, ...) -> list[str]: ... async def bash(self, command: str, ...) -> str: ... ``` ## SandboxBackend 沙箱后端 `SandboxBackend` 是用于安全执行 Agent 任务的云端沙箱实现，通过 LangSmith Sandbox 提供隔离的运行时环境。 ### 核心功能 资料来源：[libs/deepagents/deepagents/backends/sandbox.py]() | 功能 | 说明 | 已知限制 | |------|------|---------| | 容器化执行 | 在隔离容器中运行命令 | 受限于容器配额 | | 文件操作 | 支持远程文件读写 | 不支持符号链接穿透 | | 进程管理 | 独立的进程生命周期管理 | 超时时间可配置 | | Grep 搜索 | 基于 ripgrep 的文件内容搜索 | 参见下方已知问题 | ### 已知问题 根据社区反馈（#3441），`SandboxBackend.grep` 在容器执行失败时会抛出 `ValueError`。此问题影响文件内容搜索功能的稳定性。版本 0.6.4 已修复"Grep crashing when files vanish mid-walk"问题（#3592）。 ### 配置选项 ```toml [sandbox] type = "langsmith" # 沙箱类型 image = "python:3.12" # 容器镜像 timeout = 3600 # 超时时间（秒） snapshot = "" # 可选的快照名称 ``` ## FilesystemBackend 本地文件系统后端 `FilesystemBackend` 提供直接访问本地文件系统的能力，适用于本地开发和调试场景。 ### 文件操作接口 资料来源：[libs/deepagents/deepagents/backends/__init__.py]() | 方法 | 描述 | 参数说明 | |------|------|---------| | `read_file` | 读取文件内容 | `path`, `offset`, `limit`, `line_ending` | | `write_file` | 写入文件内容 | `path`, `content`, `append` | | `list_files` | 列出目录文件 | `path`, `recursive`, `include_hidden` | | `grep` | 搜索文件内容 | `pattern`, `path`, `glob`, `context` | ### read_file 分页机制 根据 Issue #2453 报告，`read_file` 分页功能存在缺陷：由于双重 limit 应用，换行后的行会被跳过。问题根源在于分页逻辑未正确处理 offset 和 limit 的交互。 ### .deepagentsignore 支持 版本 0.6.x 引入 `.deepagentsignore` 文件支持，允许用户排除特定文件和目录： - 文件读取操作 - `@` 提及解析 - 文件系统遍历 此功能对标 Claude Code 的 `.claudeignore` 和 Gemini CLI 的 `.geminiignore`。 ## StateBackend 状态管理 `StateBackend` 负责管理 Agent 的运行时状态，支持检查点持久化和状态恢复。 ### 检查点机制 资料来源：[libs/deepagents/deepagents/backends/state.py]() 根据 Issue #573 报告，当前实现存在以下问题： - Subagent 缺乏检查点持久化支持 - 状态查询时工具执行记录会被截断 这些问题导致复杂工作流的状态恢复不完整。 ### 状态数据结构 ```mermaid graph LR A[User Input] --> B[State Manager] B --> C[Checkpoint Store] C --> D[Resume Point] B --> E[Current State] E --> F[Tool Execution Log] ``` | 状态字段 | 类型 | 说明 | |---------|------|------| | `messages` | list | 对话消息历史 | | `checkpoints` | dict | 已保存的检查点 | | `tool_history` | list | 工具调用记录 | | `metadata` | dict | 附加元数据 | ## StoreBackend 存储后端 `StoreBackend` 提供键值对形式的持久化存储，用于 Agent 间的数据共享和长期状态保存。 资料来源：[libs/deepagents/deepagents/backends/store.py]() ### 存储操作 | 操作 | 方法 | 用途 | |------|------|------| | 读取 | `store.get(key)` | 获取存储值 | | 写入 | `store.put(key, value)` | 设置存储值 | | 删除 | `store.delete(key)` | 移除存储项 | | 列表 | `store.list(prefix)` | 按前缀查询 | ## 后端选择指南 根据使用场景选择合适的后端： | 场景 | 推荐后端 | 理由 | |------|---------|------| | 本地开发调试 | FilesystemBackend | 直接文件系统访问，调试方便 | | 生产部署 | SandboxBackend | 隔离环境，安全性高 | | 状态密集型任务 | StateBackend | 内置检查点支持 | | 跨 Agent 共享 | StoreBackend | 持久化数据共享 | ## 配置示例 ### 创建自定义后端 ```python from deepagents.backends import FilesystemBackend backend = FilesystemBackend( root_dir="./project", max_file_size=10 * 1024 * 1024, # 10MB exclude_patterns=[".git/*", "node_modules/*"] ) agent = create_deep_agent( backend=backend, # 其他配置... ) ``` ### 混合后端配置 ```python from deepagents.backends import SandboxBackend, StoreBackend # 沙箱后端用于代码执行 sandbox = SandboxBackend( image="python:3.12", timeout=1800 ) # 存储后端用于状态共享 store = StoreBackend(namespace="my-agent") agent = create_deep_agent( backend=sandbox, store=store ) ``` ## 版本兼容性 | Deep Agents 版本 | 后端系统变更 | |-----------------|-------------| | 0.6.x | 引入 `.deepagentsignore` 支持 | | 0.6.4 | 修复 Grep 文件消失时崩溃问题 | | 0.6.3 | 修复 ripgrep glob 锚定到搜索根目录 | | 0.6.7 | 修复工具返回的 Commands 中的 goto 和 graph 传播 | --- ## 沙箱环境 ### 相关页面 相关主题：[后端系统](#page-backends)
相关源码文件 以下源码文件用于生成本页说明： - [libs/partners/daytona/langchain_daytona/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/partners/daytona/langchain_daytona/sandbox.py) - [libs/partners/modal/langchain_modal/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/partners/modal/langchain_modal/sandbox.py) - [libs/partners/runloop/langchain_runloop/sandbox.py](https://github.com/langchain-ai/deepagents/blob/main/libs/partners/runloop/langchain_runloop/sandbox.py) - [libs/code/deepagents_code/integrations/sandbox_factory.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/integrations/sandbox_factory.py) - [libs/code/deepagents_code/integrations/sandbox_provider.py](https://github.com/langchain-ai/deepagents/blob/main/libs/code/deepagents_code/integrations/sandbox_provider.py)
# 沙箱环境 沙箱环境（Sandbox）是 deepagents 项目中为 AI 代理提供的隔离执行环境，允许代理在安全、可控的容器或虚拟机中执行文件系统操作、运行命令、安装依赖等任务，而不会影响宿主机系统。 ## 概述 deepagents 支持多种沙箱后端实现，通过统一的抽象接口提供服务。沙箱环境的核心功能包括： - **隔离执行**：代理的操作在独立环境中进行，与宿主机完全隔离 - **文件系统操作**：读取、写入、搜索文件 - **命令执行**：运行 shell 命令、安装包、执行脚本 - **状态管理**：支持快照（snapshot）保存和恢复环境状态 - **多后端支持**：兼容 Daytona、Modal、Runloop 等多种沙箱提供商 ## 架构设计 ### 沙箱提供商标识 deepagents 通过 `SandboxProvider` 枚举类定义支持的沙箱后端类型： | 提供商 | 标识符 | 说明 | |--------|--------|------| | Daytona | `daytona` | 基于容器的轻量级沙箱 | | Modal | `modal` | 云端函数和容器服务 | | Runloop | `runloop` | 本地开发环境集成 | | LangSmith | `langsmith` | LangSmith 托管沙箱 | 资料来源：[libs/code/deepagents_code/integrations/sandbox_provider.py]() ### 工厂模式实现 沙箱实例通过工厂模式创建，`SandboxFactory` 负责根据配置和提供商类型实例化相应的沙箱对象： ```mermaid graph TD A[用户请求] --> B[SandboxFactory.create] B --> C{Provider Type} C -->|daytona| D[DaytonaSandbox] C -->|modal| E[ModalSandbox] C -->|runloop| F[RunloopSandbox] C -->|langsmith| G[LangSmithSandbox] D --> H[统一的 SandboxBackend 接口] E --> H F --> H G --> H ``` 资料来源：[libs/code/deepagents_code/integrations/sandbox_factory.py]() ## 沙箱后端接口 所有沙箱后端实现统一的 `SandboxBackend` 接口，定义以下核心能力： ### 文件系统操作 | 方法 | 功能 | |------|------| | `read_file` | 读取文件内容，支持分页 | | `write_file` | 写入文件内容 | | `list_files` | 列出目录内容 | | `mkdir` | 创建目录 | | `rm` | 删除文件或目录 | | `glob` | 文件模式匹配 | ### 命令执行 | 方法 | 功能 | |------|------| | `exec` | 在沙箱中执行命令 | | `kill` | 终止正在运行的进程 | | `grep` | 文件内容搜索 | ### 状态管理 | 方法 | 功能 | |------|------| | `save_snapshot` | 保存当前环境快照 | | `restore_snapshot` | 恢复环境到指定快照 | | `list_snapshots` | 列出可用快照 | ## 提供商实现 ### Daytona 沙箱 Daytona 提供基于容器的轻量级沙箱实现，适合快速启动和短期任务执行。 资料来源：[libs/partners/daytona/langchain_daytona/sandbox.py]() ### Modal 沙箱 Modal 沙箱利用云端函数能力，支持 GPU 加速和大内存工作负载，适合计算密集型任务。 资料来源：[libs/partners/modal/langchain_modal/sandbox.py]() ### Runloop 沙箱 Runloop 沙箱提供本地开发环境集成能力，适合需要访问本地工具链和开发资源的场景。 资料来源：[libs/partners/runloop/langchain_runloop/sandbox.py]() ## 配置管理 ### deepagents.toml 配置 沙箱环境通过 `deepagents.toml` 文件进行配置： ```toml [sandbox] provider = "daytona" # 沙箱提供商 image = "python:3.12" # 容器镜像 timeout = 3600 # 超时时间（秒） snapshot_name = "my-snapshot" # 快照名称（可选） ``` ### 环境变量 | 变量 | 说明 | 必需 | |------|------|------| | `LANGSMITH_API_KEY` | LangSmith 访问密钥 | 对于 LangSmith 沙箱 | | `DAYTONA_API_KEY` | Daytona API 密钥 | 对于 Daytona 沙箱 | | `MODAL_TOKEN_ID` | Modal Token ID | 对于 Modal 沙箱 | | `MODAL_TOKEN_SECRET` | Modal Token Secret | 对于 Modal 沙箱 | ## 部署集成 ### CLI 部署 使用 `deepagents deploy` 命令部署代理时，配置中的沙箱设置自动生效： ```bash deepagents deploy ``` 部署代理会使用 `deepagents.toml` 中定义的沙箱配置，在 LangSmith 平台启动隔离的执行环境。 资料来源：[examples/deploy-coding-agent/README.md]() ### 快照管理 deepagents-code 0.1.4 版本引入了 `--sandbox-snapshot-name` 参数，支持指定沙箱快照名称，便于恢复特定工作环境状态： ```bash deepagents-code run --sandbox-snapshot-name "my-dev-env" ``` ## 已知问题 ### Grep 操作崩溃 当沙箱容器执行失败时，`SandboxBackend.grep` 方法可能抛出 `ValueError` 异常。此问题已在 deepagents 0.6.4 版本中修复。 资料来源：[@langchain-ai/deepagents/issues/3441]() ### 文件消失导致的 Grep 崩溃 在文件系统遍历过程中，如果文件被删除或移动，`grep` 操作可能崩溃。该问题同样在 0.6.4 版本中修复。 资料来源：[deepagents==0.6.4 Release Notes]() ## 使用场景 | 场景 | 推荐沙箱 | 理由 | |------|----------|------| | 快速原型开发 | Daytona | 启动快、资源占用低 | | 大规模数据处理 | Modal | 支持 GPU、高内存 | | 本地工具链集成 | Runloop | 访问本地开发环境 | | 云端协作 | LangSmith | 托管服务、易于分享 | ## 最佳实践 ### 安全建议 - 避免在沙箱中处理敏感凭证，使用环境变量注入 - 定期清理不需要的快照以释放存储空间 - 使用只读模式处理不可信代码 ### 性能优化 - 选择合适的容器镜像大小，避免不必要的依赖安装 - 利用快照功能快速恢复常用工作环境 - 对于长时间运行任务，设置合理的超时时间 --- --- ## Doramagic 踩坑日志 项目：langchain-ai/deepagents 摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：feat(sdk): add regex support to the `grep` tool。 ## 1. 配置坑 · 来源证据：feat(sdk): add regex support to the `grep` tool - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(sdk): add regex support to the `grep` tool - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_835108c2241d479e882292911a15ba40 | https://github.com/langchain-ai/deepagents/issues/3547 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 安装坑 · 来源证据：`FilesystemMiddleware`'s `_handle_read_result` ignores `read_result.file_data["encoding"]` when routing files - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`FilesystemMiddleware`'s `_handle_read_result` ignores `read_result.file_data["encoding"]` when routing files - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_c1040f878b164a949793ba929d2d6463 | https://github.com/langchain-ai/deepagents/issues/3657 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 配置坑 · 来源证据：Add `RemoteBackend` as a backend alternative - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Add `RemoteBackend` as a backend alternative - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_5caff99ca831421092eb3042c17156a0 | https://github.com/langchain-ai/deepagents/issues/1877 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | README/documentation is current enough for a first validation pass. ## 5. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | last_activity_observed missing ## 6. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | no_demo; severity=medium ## 7. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | no_demo; severity=medium ## 8. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | issue_or_pr_quality=unknown ## 9. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1027384981 | https://github.com/langchain-ai/deepagents | release_recency=unknown