[{"data":1,"prerenderedAt":505},["ShallowReactive",2],{"content:\u002F2026\u002Fintroducing-deepagents":3,"surround:\u002F2026\u002Fintroducing-deepagents":499},{"id":4,"title":5,"body":6,"categories":457,"date":459,"description":460,"draft":461,"extension":462,"image":463,"meta":464,"navigation":466,"path":467,"permalink":463,"published":463,"readingTime":468,"recommend":463,"references":473,"seo":488,"sitemap":489,"stem":490,"tags":491,"type":497,"updated":459,"__hash__":498},"content\u002Fposts\u002F2026\u002Fintroducing-deepagents.md","DeepAgents：给大模型一间真正能干活的工作室",{"type":7,"value":8,"toc":444},"minimark",[9,13,16,29,44,48,51,151,178,182,185,188,195,199,202,214,224,227,231,234,237,263,266,306,310,313,319,326,336,339,343,346,354,357,361,364,375,381,388,391,394,408,416,426,429,432,435,441],[10,11,12],"p",{},"大模型刚开始会用工具时，我们很容易兴奋：它会搜索、会读文件、会调用 API，好像下一步就能变成稳定的数字同事。真正把它放进一段长任务里，问题很快冒出来：上下文越堆越乱，工具结果塞满窗口，任务做一半忘了目标，危险操作缺少审批，失败后还要从头再来。",[10,14,15],{},"DeepAgents 解决的不是“再包一层聊天机器人”，而是给 agent 准备一套能长期工作的基础设施。它把模型、工具、文件系统、子代理、记忆、检查点和人工介入拼成一个默认可用的 agent harness：你不必从零搭脚手架，也不必被默认行为锁死。",[17,18,21],"alert",{"title":19,"type":20},"一句话理解","info",[10,22,23,24,28],{},"DeepAgents 是 LangChain 生态里的开源 agent harness。它站在 ",[25,26,27],"code",{"code":27},"create_agent"," 之上、运行在 LangGraph 之上，把长任务需要的工程能力预先装好：会规划，会分工，会把中间材料写进文件，会压缩上下文，也能在关键动作前停下来等人确认。",[10,30,31,32,35,36,39,40,43],{},"截至 2026-07-08，PyPI 上 ",[25,33,34],{"code":34},"deepagents"," 的稳定版本显示为 ",[25,37,38],{"code":38},"0.6.12","，同时已经出现 ",[25,41,42],{"code":42},"0.7.0a6"," 这样的 alpha 版本。写生产依赖时别只写裸包名，建议明确锁定版本，并先在测试环境验证默认工具表、权限和中间件行为。",[45,46,47],"h2",{"id":47},"它到底补了什么",[10,49,50],{},"普通工具调用像是一张干净的办公桌：模型面前摆着几个按钮，按哪个全靠提示词。DeepAgents 更像是一间工作室：有白板写任务，有抽屉存资料，有隔间让同事并行研究，有门禁限制危险区域，还有摄像头记录每一步。",[52,53,54,70],"table",{},[55,56,57],"thead",{},[58,59,60,64,67],"tr",{},[61,62,63],"th",{},"能力",[61,65,66],{},"如果自己搭",[61,68,69],{},"DeepAgents 的默认思路",[71,72,73,89,100,114,129,140],"tbody",{},[58,74,75,79,82],{},[76,77,78],"td",{},"任务规划",[76,80,81],{},"让模型在自然语言里记计划，容易丢步骤",[76,83,84,85,88],{},"内置 ",[25,86,87],{"code":87},"write_todos","，把任务拆成可追踪状态",[58,90,91,94,97],{},[76,92,93],{},"文件上下文",[76,95,96],{},"工具输出塞回聊天窗口，越来越胀",[76,98,99],{},"提供虚拟文件系统，把长结果写入、读取、搜索",[58,101,102,105,108],{},[76,103,104],{},"分工",[76,106,107],{},"手写多 agent 编排和消息协议",[76,109,84,110,113],{},[25,111,112],{"code":112},"task"," 工具，子代理在隔离上下文里做子任务",[58,115,116,119,122],{},[76,117,118],{},"长记忆",[76,120,121],{},"每次都把项目规则重新塞进 prompt",[76,123,124,125,128],{},"支持 ",[25,126,127],{"code":127},"AGENTS.md"," 记忆和 skills 渐进加载",[58,130,131,134,137],{},[76,132,133],{},"运行安全",[76,135,136],{},"只靠提示词说“不要乱删”",[76,138,139],{},"用权限、sandbox、interrupt 和中间件约束真实能力",[58,141,142,145,148],{},[76,143,144],{},"可观测性",[76,146,147],{},"出错时只看到最后一句回答",[76,149,150],{},"依赖 LangGraph\u002FLangSmith 追踪步骤、工具调用和子代理",[152,153,154,157,160,163,166,169,172,175],"timeline",{},[10,155,156],{},"{第一层：模型会说话}",[10,158,159],{},"模型只负责生成文本。它能推理，但无法直接碰系统、数据库或文件。",[10,161,162],{},"{第二层：模型会调用工具}",[10,164,165],{},"LangChain 的 agent loop 让模型可以选择工具，拿结果，再继续生成下一步。",[10,167,168],{},"{第三层：模型能长期工作}",[10,170,171],{},"DeepAgents 把规划、文件、子代理、记忆、审批、持久化组合成默认工作流。",[10,173,174],{},"{底座：运行时要可靠}",[10,176,177],{},"LangGraph 提供流式输出、检查点、可恢复执行和 human-in-the-loop 等运行时能力。",[45,179,181],{"id":180},"核心画面主代理工具和子代理","核心画面：主代理、工具和子代理",[10,183,184],{},"DeepAgents 的主代理并不需要亲自把所有事情做完。它更像项目负责人：先看目标，再写任务清单，然后决定哪些事自己做，哪些事派给子代理。子代理拿到一个隔离的上下文窗口，专注做一个子任务，最后只把整理好的报告交回主代理。",[10,186,187],{},"这件事在长任务里很关键。假设你让 agent 调研一个技术方案：搜索材料会产生几十页网页内容，代码实验会产生日志，结论还要比较优缺点。如果所有东西都堆在一个上下文窗口里，模型迟早会被噪音淹没。子代理把“调研数据库方案”“验证 SDK 示例”“整理部署风险”拆出去，主代理只接收摘要和结论，主线就清爽得多。",[17,189,192],{"title":190,"type":191},"子代理不是魔法并行按钮","warning",[10,193,194],{},"子代理能隔离上下文、压缩结果，但它也会消耗模型调用和工具调用。真正好用的设计，是让子代理处理边界清晰、结果可验收的任务，而不是把每个小动作都外包出去。",[45,196,198],{"id":197},"快速开始最小可用骨架","快速开始：最小可用骨架",[10,200,201],{},"下面是一个研究型 agent 的最小形状。真实项目里，你会把搜索、数据库、代码执行、内部文档查询等能力封装成工具，再交给 DeepAgents 调度。",[203,204,211],"pre",{"className":205,"code":207,"filename":208,"language":209,"meta":210},[206],"language-bash","uv add deepagents tavily-python\n","安装","bash","icon=tabler:terminal",[25,212,207],{"__ignoreMap":213},"",[203,215,222],{"className":216,"code":218,"filename":219,"language":220,"meta":221},[217],"language-python","import os\nfrom typing import Literal\n\nfrom deepagents import create_deep_agent\nfrom tavily import TavilyClient\n\ntavily_client = TavilyClient(api_key=os.environ[\"TAVILY_API_KEY\"])\n\n\ndef internet_search(\n    query: str,\n    max_results: int = 5,\n    topic: Literal[\"general\", \"news\", \"finance\"] = \"general\",\n    include_raw_content: bool = False,\n):\n    \"\"\"Run a web search.\"\"\"\n    return tavily_client.search(\n        query,\n        max_results=max_results,\n        include_raw_content=include_raw_content,\n        topic=topic,\n    )\n\n\nresearch_instructions = \"\"\"You are an expert researcher.\nUse internet_search to gather evidence, save large intermediate notes to files,\nand write a concise final report with sources and tradeoffs.\n\"\"\"\n\nagent = create_deep_agent(\n    model=\"openai:gpt-5.5\",\n    tools=[internet_search],\n    system_prompt=research_instructions,\n)\n\nresult = agent.invoke({\n    \"messages\": [\n        {\n            \"role\": \"user\",\n            \"content\": \"Research DeepAgents and explain when to use it.\",\n        }\n    ]\n})\n\nprint(result[\"messages\"][-1].content)\n","agent.py","python","icon=tabler:brand-python wrap",[25,223,218],{"__ignoreMap":213},[10,225,226],{},"这里真正值得注意的不是代码有多短，而是这几行背后默认带上了许多工程约定：agent 会有任务规划工具，会有文件系统工具，会在需要时把内容卸载到文件里，会通过 LangGraph 的运行时把过程串起来。",[45,228,230],{"id":229},"文件系统agent-的草稿纸和资料柜","文件系统：agent 的草稿纸和资料柜",[10,232,233],{},"DeepAgents 提供虚拟文件系统，默认可以读写、编辑、搜索、列目录；在 sandbox backend 可用时，还可以执行 shell 命令。文件系统不是装饰，它是长任务的上下文管理器。",[10,235,236],{},"想象一次“写技术选型报告”的任务：搜索结果、PDF 摘要、性能测试输出、草稿结构都不应该反复塞进聊天记录。更好的做法是：",[238,239,240,248,254,260],"ol",{},[241,242,243,244,247],"li",{},"搜索结果写入 ",[25,245,246],{"code":246},"\u002Fnotes\u002Fsearch-results.md","。",[241,249,250,251,247],{},"关键证据整理到 ",[25,252,253],{"code":253},"\u002Fnotes\u002Fevidence.md",[241,255,256,257,247],{},"报告草稿写到 ",[25,258,259],{"code":259},"\u002Fdrafts\u002Freport.md",[241,261,262],{},"主代理只在需要时读取相关片段。",[10,264,265],{},"这样模型的上下文窗口像工作台，文件系统像资料柜。工作台保持整洁，资料柜保留细节。",[267,268,270,273,303],"folding",{"title":269},"一个实用的文件权限思路",[10,271,272],{},"生产环境不要让 agent 看到整台机器。更稳妥的配置是：",[274,275,276,279,285,292],"ul",{},[241,277,278],{},"允许读取项目的公开资料目录。",[241,280,281,282,247],{},"允许写入单独的工作目录，如 ",[25,283,284],{"code":284},"\u002Fworkspace\u002Fagent-output\u002F",[241,286,287,288,291],{},"拒绝读取 ",[25,289,290],{"code":290},".env","、密钥、用户隐私文件和部署配置。",[241,293,294,295,298,299,302],{},"对 ",[25,296,297],{"code":297},"edit_file","、",[25,300,301],{"code":301},"write_file","、外部 API 调用加 human-in-the-loop。",[10,304,305],{},"权限应该落在真实工具和 sandbox 边界上，而不是只写在系统提示词里。",[45,307,309],{"id":308},"记忆与-skills不要把所有知识一次性塞进去","记忆与 skills：不要把所有知识一次性塞进去",[10,311,312],{},"DeepAgents 把长期知识分成两类：memory 和 skills。",[10,314,315,316,318],{},"Memory 更像“上班第一分钟就要知道的规章制度”。例如项目编码规范、团队偏好、用户的长期偏好，可以放进 ",[25,317,127],{"code":127},"，启动时加载。",[10,320,321,322,325],{},"Skills 更像“需要时再拿出来的工具手册”。一个 skill 目录里可以有 ",[25,323,324],{"code":324},"SKILL.md","、脚本、模板、参考资料。DeepAgents 采用渐进披露：先让 agent 知道有哪些技能，等任务真正需要时再读完整内容。这能避免一启动就把上下文塞满。",[203,327,334],{"className":328,"code":330,"filename":331,"language":332,"meta":333},[329],"language-text","skills\u002F\n  report-writer\u002F\n    SKILL.md\n    templates\u002F\n      technical-report.md\n  sql-analyst\u002F\n    SKILL.md\n    references\u002F\n      warehouse-schema.md\n","目录示例","text","icon=tabler:folders",[25,335,330],{"__ignoreMap":213},[10,337,338],{},"这套设计对团队很有价值：把“我们总是怎么做这类任务”的经验固化成 skill，而不是每次在对话里临时补充。",[45,340,342],{"id":341},"human-in-the-loop让人类在关键门口站岗","Human-in-the-loop：让人类在关键门口站岗",[10,344,345],{},"真实系统里，agent 会犯错，也会误解目标。DeepAgents 支持在工具调用前中断，例如写文件、编辑文件、调用付费接口、发邮件、删资源之前先暂停。人可以批准、修改参数、拒绝，或者补充指导。",[203,347,352],{"className":348,"code":349,"filename":350,"language":220,"meta":351},[217],"from deepagents import create_deep_agent\nfrom langgraph.checkpoint.memory import MemorySaver\n\nagent = create_deep_agent(\n    model=\"openai:gpt-5.5\",\n    tools=[send_email, update_ticket],\n    interrupt_on={\n        \"send_email\": True,\n        \"update_ticket\": True,\n        \"edit_file\": True,\n    },\n    checkpointer=MemorySaver(),\n)\n","需要审批的工具","icon=tabler:shield-check",[25,353,349],{"__ignoreMap":213},[10,355,356],{},"这不是降低自动化程度，而是把自动化放在正确的轨道上：搜索、整理、草拟可以自动；发送、删除、付款、公开发布要过闸。",[45,358,360],{"id":359},"和-langchainlanggraph-的关系","和 LangChain、LangGraph 的关系",[10,362,363],{},"一个简单记法：",[274,365,366,369,372],{},[241,367,368],{},"LangChain 提供工具、模型、agent 的基础构件。",[241,370,371],{},"LangGraph 提供图运行时、检查点、流式输出、可恢复执行。",[241,373,374],{},"DeepAgents 是预装好的工作台，把长任务 agent 常用能力组合成默认 harness。",[10,376,377,378,380],{},"如果你只需要一个轻量工具调用机器人，",[25,379,27],{"code":27}," 可能更直接。如果你要完全自定义状态机、复杂节点路由和业务流程，直接写 LangGraph 更合适。如果你想快速得到“能计划、能分工、能管理文件和上下文”的通用 agent，DeepAgents 就是更省力的起点。",[17,382,385],{"title":383,"type":384},"什么时候值得用 DeepAgents？","question",[10,386,387],{},"当任务会跨越很多步骤、涉及大量中间资料、需要子任务分工、要保存草稿或产物、并且未来可能部署到生产环境时，DeepAgents 的默认 harness 很有价值。反过来，如果只是“问一句、调一个 API、回一句”，它可能显得太重。",[45,389,390],{"id":390},"生产环境要先想清楚的事",[10,392,393],{},"DeepAgents 的能力越强，越要把边界设计清楚。官方文档里反复强调的生产问题可以压缩成四个词：身份、范围、耐久、安全。",[238,395,396,399,402,405],{},[241,397,398],{},"身份：每次调用都要知道是谁在用，工具和记忆要能按用户隔离。",[241,400,401],{},"范围：thread_id 管对话历史，runtime context 管本次调用里的用户、密钥和特性开关。",[241,403,404],{},"耐久：长任务需要 checkpointer，失败、中断、人工审批后才能恢复。",[241,406,407],{},"安全：权限、sandbox、速率限制、重试、PII 处理和密钥管理要落到中间件或平台层。",[203,409,414],{"className":410,"code":411,"filename":412,"language":220,"meta":413},[217],"from dataclasses import dataclass\nfrom langchain_core.utils.uuid import uuid7\n\n\n@dataclass\nclass Context:\n    user_id: str\n\n\nconfig = {\"configurable\": {\"thread_id\": str(uuid7())}}\n\nagent.invoke(\n    {\"messages\": [{\"role\": \"user\", \"content\": \"Plan a 3-day trip to Tokyo\"}]},\n    config=config,\n    context=Context(user_id=\"user-123\"),\n)\n","生产调用的两个关键参数","icon=tabler:route",[25,415,411],{"__ignoreMap":213},[10,417,418,421,422,425],{},[25,419,420],{"code":420},"thread_id"," 让同一段对话能接着往下走；",[25,423,424],{"code":424},"context"," 让工具知道“这次是哪个用户、能访问什么、该用什么凭据”。这两个概念别混在一起。",[45,427,428],{"id":428},"我对它的判断",[10,430,431],{},"DeepAgents 最有意思的地方，不是它发明了某个全新的 agent 理论，而是它承认 agent 工程里那些“麻烦但绕不过去”的部分：上下文会爆，工具会错，任务会长，权限要管，过程要看，人类要能插手。",[10,433,434],{},"它把这些问题做成默认能力，给开发者一个可以马上开工的起点。你仍然需要设计工具、权限、数据边界和评估集；但你不必先花几周把 todo、文件、子代理、checkpoint、interrupt 这些基础设施全重写一遍。",[436,437],"link-card",{"description":438,"link":439,"title":440},"继续看核心能力、文件系统、子代理、上下文管理和生产建议。","https:\u002F\u002Fdocs.langchain.com\u002Foss\u002Fpython\u002Fdeepagents\u002Foverview","DeepAgents 官方概览",[10,442,443],{},"如果说早期 agent 像一个会点鼠标的实习生，DeepAgents 想提供的就是工位、任务板、资料柜、审批流和日志系统。模型还是模型，但它终于不再赤手空拳地面对复杂工作。",{"title":213,"searchDepth":445,"depth":445,"links":446},4,[447,449,450,451,452,453,454,455,456],{"id":47,"depth":448,"text":47},2,{"id":180,"depth":448,"text":181},{"id":197,"depth":448,"text":198},{"id":229,"depth":448,"text":230},{"id":308,"depth":448,"text":309},{"id":341,"depth":448,"text":342},{"id":359,"depth":448,"text":360},{"id":390,"depth":448,"text":390},{"id":428,"depth":448,"text":428},[458],"开发","2026-07-08 17:46:00","从 LangChain 体系里的 agent harness 视角，拆解 DeepAgents 如何把计划、工具、文件系统、子代理、记忆和人工审批组织成可落地的智能体工程。",false,"md",null,{"slots":465},{},true,"\u002F2026\u002Fintroducing-deepagents",{"text":469,"minutes":470,"time":471,"words":472},"14 min read",13.235,794100,2647,[474,476,479,482,485],{"title":475,"link":439},"Deep Agents overview",{"title":477,"link":478},"Deep Agents Quickstart","https:\u002F\u002Fdocs.langchain.com\u002Foss\u002Fpython\u002Fdeepagents\u002Fquickstart",{"title":480,"link":481},"DeepAgents GitHub","https:\u002F\u002Fgithub.com\u002Flangchain-ai\u002Fdeepagents",{"title":483,"link":484},"deepagents on PyPI","https:\u002F\u002Fpypi.org\u002Fproject\u002Fdeepagents\u002F",{"title":486,"link":487},"Going to production","https:\u002F\u002Fdocs.langchain.com\u002Foss\u002Fpython\u002Fdeepagents\u002Fgoing-to-production",{"title":5,"description":460},{"loc":467},"posts\u002F2026\u002Fintroducing-deepagents",[492,493,494,495,496],"AI","Agent","LangChain","LangGraph","DeepAgents","tech","KLY_OVP3OsPGJYjXqFqSyBn1oigAputDjOesb-d8598",[463,500],{"title":501,"path":502,"stem":503,"date":504,"type":497,"children":-1},"Loop Engineering：别再只会写 Prompt 了","\u002F2026\u002Floop-engineering","posts\u002F2026\u002Floop-engineering","2026-07-08 18:29:00",1783560682660]