DeepAgents：给大模型一间真正能干活的工作室

大模型刚开始会用工具时，我们很容易兴奋：它会搜索、会读文件、会调用 API，好像下一步就能变成稳定的数字同事。真正把它放进一段长任务里，问题很快冒出来：上下文越堆越乱，工具结果塞满窗口，任务做一半忘了目标，危险操作缺少审批，失败后还要从头再来。

DeepAgents 解决的不是“再包一层聊天机器人”，而是给 agent 准备一套能长期工作的基础设施。它把模型、工具、文件系统、子代理、记忆、检查点和人工介入拼成一个默认可用的 agent harness：你不必从零搭脚手架，也不必被默认行为锁死。

截至 2026-07-08，PyPI 上 deepagents 的稳定版本显示为 0.6.12，同时已经出现 0.7.0a6 这样的 alpha 版本。写生产依赖时别只写裸包名，建议明确锁定版本，并先在测试环境验证默认工具表、权限和中间件行为。

它到底补了什么

普通工具调用像是一张干净的办公桌：模型面前摆着几个按钮，按哪个全靠提示词。DeepAgents 更像是一间工作室：有白板写任务，有抽屉存资料，有隔间让同事并行研究，有门禁限制危险区域，还有摄像头记录每一步。

第一层：模型会说话

模型只负责生成文本。它能推理，但无法直接碰系统、数据库或文件。

第二层：模型会调用工具

LangChain 的 agent loop 让模型可以选择工具，拿结果，再继续生成下一步。

第三层：模型能长期工作

DeepAgents 把规划、文件、子代理、记忆、审批、持久化组合成默认工作流。

底座：运行时要可靠

LangGraph 提供流式输出、检查点、可恢复执行和 human-in-the-loop 等运行时能力。

核心画面：主代理、工具和子代理

DeepAgents 的主代理并不需要亲自把所有事情做完。它更像项目负责人：先看目标，再写任务清单，然后决定哪些事自己做，哪些事派给子代理。子代理拿到一个隔离的上下文窗口，专注做一个子任务，最后只把整理好的报告交回主代理。

这件事在长任务里很关键。假设你让 agent 调研一个技术方案：搜索材料会产生几十页网页内容，代码实验会产生日志，结论还要比较优缺点。如果所有东西都堆在一个上下文窗口里，模型迟早会被噪音淹没。子代理把“调研数据库方案”“验证 SDK 示例”“整理部署风险”拆出去，主代理只接收摘要和结论，主线就清爽得多。

快速开始：最小可用骨架

下面是一个研究型 agent 的最小形状。真实项目里，你会把搜索、数据库、代码执行、内部文档查询等能力封装成工具，再交给 DeepAgents 调度。

uv add deepagents tavily-python

import os
from typing import Literal

from deepagents import create_deep_agent
from tavily import TavilyClient

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])


def internet_search(
    query: str,
    max_results: int = 5,
    topic: Literal["general", "news", "finance"] = "general",
    include_raw_content: bool = False,
):
    """Run a web search."""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )


research_instructions = """You are an expert researcher.
Use internet_search to gather evidence, save large intermediate notes to files,
and write a concise final report with sources and tradeoffs.
"""

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[internet_search],
    system_prompt=research_instructions,
)

result = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "Research DeepAgents and explain when to use it.",
        }
    ]
})

print(result["messages"][-1].content)

这里真正值得注意的不是代码有多短，而是这几行背后默认带上了许多工程约定：agent 会有任务规划工具，会有文件系统工具，会在需要时把内容卸载到文件里，会通过 LangGraph 的运行时把过程串起来。

文件系统：agent 的草稿纸和资料柜

DeepAgents 提供虚拟文件系统，默认可以读写、编辑、搜索、列目录；在 sandbox backend 可用时，还可以执行 shell 命令。文件系统不是装饰，它是长任务的上下文管理器。

想象一次“写技术选型报告”的任务：搜索结果、PDF 摘要、性能测试输出、草稿结构都不应该反复塞进聊天记录。更好的做法是：

1. 搜索结果写入 /notes/search-results.md。
2. 关键证据整理到 /notes/evidence.md。
3. 报告草稿写到 /drafts/report.md。
4. 主代理只在需要时读取相关片段。

这样模型的上下文窗口像工作台，文件系统像资料柜。工作台保持整洁，资料柜保留细节。

记忆与 skills：不要把所有知识一次性塞进去

DeepAgents 把长期知识分成两类：memory 和 skills。

Memory 更像“上班第一分钟就要知道的规章制度”。例如项目编码规范、团队偏好、用户的长期偏好，可以放进 AGENTS.md，启动时加载。

Skills 更像“需要时再拿出来的工具手册”。一个 skill 目录里可以有 SKILL.md、脚本、模板、参考资料。DeepAgents 采用渐进披露：先让 agent 知道有哪些技能，等任务真正需要时再读完整内容。这能避免一启动就把上下文塞满。

skills/
  report-writer/
    SKILL.md
    templates/
      technical-report.md
  sql-analyst/
    SKILL.md
    references/
      warehouse-schema.md

这套设计对团队很有价值：把“我们总是怎么做这类任务”的经验固化成 skill，而不是每次在对话里临时补充。

Human-in-the-loop：让人类在关键门口站岗

真实系统里，agent 会犯错，也会误解目标。DeepAgents 支持在工具调用前中断，例如写文件、编辑文件、调用付费接口、发邮件、删资源之前先暂停。人可以批准、修改参数、拒绝，或者补充指导。

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[send_email, update_ticket],
    interrupt_on={
        "send_email": True,
        "update_ticket": True,
        "edit_file": True,
    },
    checkpointer=MemorySaver(),
)

这不是降低自动化程度，而是把自动化放在正确的轨道上：搜索、整理、草拟可以自动；发送、删除、付款、公开发布要过闸。

和 LangChain、LangGraph 的关系

一个简单记法：

• LangChain 提供工具、模型、agent 的基础构件。
• LangGraph 提供图运行时、检查点、流式输出、可恢复执行。
• DeepAgents 是预装好的工作台，把长任务 agent 常用能力组合成默认 harness。

如果你只需要一个轻量工具调用机器人，create_agent 可能更直接。如果你要完全自定义状态机、复杂节点路由和业务流程，直接写 LangGraph 更合适。如果你想快速得到“能计划、能分工、能管理文件和上下文”的通用 agent，DeepAgents 就是更省力的起点。

生产环境要先想清楚的事

DeepAgents 的能力越强，越要把边界设计清楚。官方文档里反复强调的生产问题可以压缩成四个词：身份、范围、耐久、安全。

1. 身份：每次调用都要知道是谁在用，工具和记忆要能按用户隔离。
2. 范围：thread_id 管对话历史，runtime context 管本次调用里的用户、密钥和特性开关。
3. 耐久：长任务需要 checkpointer，失败、中断、人工审批后才能恢复。
4. 安全：权限、sandbox、速率限制、重试、PII 处理和密钥管理要落到中间件或平台层。

from dataclasses import dataclass
from langchain_core.utils.uuid import uuid7


@dataclass
class Context:
    user_id: str


config = {"configurable": {"thread_id": str(uuid7())}}

agent.invoke(
    {"messages": [{"role": "user", "content": "Plan a 3-day trip to Tokyo"}]},
    config=config,
    context=Context(user_id="user-123"),
)

thread_id 让同一段对话能接着往下走；context 让工具知道“这次是哪个用户、能访问什么、该用什么凭据”。这两个概念别混在一起。

我对它的判断

DeepAgents 最有意思的地方，不是它发明了某个全新的 agent 理论，而是它承认 agent 工程里那些“麻烦但绕不过去”的部分：上下文会爆，工具会错，任务会长，权限要管，过程要看，人类要能插手。

它把这些问题做成默认能力，给开发者一个可以马上开工的起点。你仍然需要设计工具、权限、数据边界和评估集；但你不必先花几周把 todo、文件、子代理、checkpoint、interrupt 这些基础设施全重写一遍。

如果说早期 agent 像一个会点鼠标的实习生，DeepAgents 想提供的就是工位、任务板、资料柜、审批流和日志系统。模型还是模型，但它终于不再赤手空拳地面对复杂工作。