跳转至

Deep Agents

Abstract

Deep Agents 是构建复杂 Agent 的 higher-level agent harness。 它基于 LangChain 的 Agent building blocks，并使用 LangGraph runtime 提供 durable execution、streaming、human-in-the-loop 等能力。

可以把 Deep Agents 理解为：在常规 tool calling loop 之上，预置了任务规划、虚拟文件系统、子 Agent、长期记忆、上下文管理和更强的工程化默认行为。它适合复杂、多步骤、需要较长上下文和任务分解的 Agent。

和 LangChain / LangGraph 的关系

  • LangChain：提供模型、工具和 Agent loop 的核心抽象。
  • LangGraph：提供底层编排 runtime，例如状态图、持久执行、streaming、interrupt。
  • Deep Agents：基于 LangChain 和 LangGraph 的 agent harness，内置规划、文件系统、subagents、memory 和权限等能力。
  • LangSmith：用于 tracing、debugging、evaluation 和 deployment。

如果只是简单的 LLM + tools，优先使用 LangChain create_agent。如果需要自己设计复杂状态机，使用 LangGraph。若想直接使用现成的复杂 Agent harness，可以考虑 Deep Agents。

创建 Deep Agent

安装示例：

pip install -qU deepagents langchain-openai

最小示例：

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    model="openai:gpt-5.4",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Deep Agents 支持多种模型 provider，例如 OpenAI、Anthropic、Google Gemini、OpenRouter、Fireworks、Baseten、Ollama 等。模型配置方式和 LangChain 的 provider integration 体系保持一致。

适合场景

Deep Agents 适合这些场景：

  • 任务复杂，需要规划和分解。
  • 需要管理大量上下文，避免全部塞进模型上下文窗口。
  • 需要文件系统工具读写中间产物。
  • 需要通过 sandbox 执行 shell command、测试、构建或代码任务。
  • 需要派生 specialized subagents，把子任务上下文隔离出去。
  • 需要跨 conversation / thread 持久化 memory。
  • 需要用 permission rules 控制 Agent 能读写哪些文件。
  • 需要 human approval 保护敏感操作。
  • 需要在不同模型 provider 之间切换。

如果任务比较简单，例如问答、单次工具调用、轻量信息抽取，LangChain Agent 通常更直接。

核心能力

Planning and Task Decomposition

Deep Agents 内置 write_todos 工具，让 Agent 可以把复杂任务拆成多个步骤，记录进度，并在新信息出现时调整计划。

这类能力适合长任务：例如调研、代码修改、数据分析、文档整理、跨系统操作等。Agent 不再只是一轮一轮反应，而是可以显式维护任务计划。

Context Management

Deep Agents 通过文件系统工具管理上下文，例如：

  • ls
  • read_file
  • write_file
  • edit_file

这些工具让 Agent 可以把大量中间结果、工具输出、草稿和上下文写入虚拟文件系统，而不是全部保存在 messages 中。这样可以减少 context window 压力。

同时，Deep Agents 支持自动 summarization，在上下文变长时压缩旧消息，让长会话保持可用。

Shell Execution

使用 sandbox backend 时，Deep Agents 可以获得 execute 工具，用来运行 shell command，例如测试、构建、git 操作或系统任务。

Sandbox 的价值是隔离执行环境，避免 Agent 直接影响宿主系统。适合 coding agent、自动化运维、数据处理等需要执行命令的场景。

Pluggable Filesystem Backends

Deep Agents 的虚拟文件系统支持可插拔 backend。可以根据场景选择：

  • in-memory state
  • local disk
  • LangGraph store
  • sandbox backend
  • 自定义 backend
  • 多 backend 的 composite routing

这意味着文件系统既可以只是一次会话内的临时工作区，也可以接入持久化存储或隔离沙箱。

Subagent Spawning

Deep Agents 内置 task 工具，用来派生 specialized subagents。主 Agent 可以把某个子任务交给 subagent，让它在独立上下文中深入处理，最后把结果返回主 Agent。

Subagents 的好处是隔离上下文：主 Agent 不需要把所有细节都塞进自己的消息历史里。

Long-Term Memory

Deep Agents 可以接入 LangGraph Memory Store，实现跨 thread / conversation 的长期记忆。Agent 可以保存和检索用户偏好、历史事实、任务状态或应用级知识。

短期记忆解决当前会话；长期记忆解决跨会话复用。

Filesystem Permissions

Deep Agents 支持声明式 permission rules，用来控制 Agent 能读写哪些文件和目录。Subagents 可以继承或覆盖父 Agent 的权限规则。

权限控制对于 coding agent 或文件操作型 Agent 很重要，可以降低误删、误改或越权读取的风险。

Human-in-the-loop

Deep Agents 可以利用 LangGraph interrupt 能力，对敏感工具操作要求人工审批。比如执行 shell、写文件、调用生产 API、发送消息等操作，都可以在执行前暂停并等待确认。

Skills

Deep Agents 可以通过 skills 扩展 Agent 能力。Skill 可以包含专门的工作流、领域知识、自定义 instructions 或工具使用方式，适合把可复用经验沉淀成模块。

Smart Defaults

Deep Agents 自带较强的默认系统提示，指导模型如何计划、验证工作、使用工具和管理上下文。默认行为可以定制或替换。

Deep Agents 仓库组成

deepagents 仓库主要包含：

  • Deep Agents SDK：构建复杂 Agent 的 Python package。
  • Deep Agents CLI：基于 SDK 的终端 coding agent。
  • ACP integration：通过 Agent Client Protocol 在 Zed 等编辑器中使用 deep agents。

小结

Deep Agents 的定位是面向复杂任务的 Agent harness。它不是替代 LangChain 或 LangGraph，而是在它们之上提供一套更完整的默认能力：规划、上下文工程、虚拟文件系统、subagents、长期记忆、权限和 human-in-the-loop。对于简单 Agent，create_agent 更轻；对于需要长任务和强工程控制的 Agent，Deep Agents 更合适。