尧图网页设计 
Deep Research Agent 实战用 deepagents 构建具备战略思考能力的多子代理深度研究系统【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本指南以 examples/deep_research 示例为骨架完整讲解如何在deepagents框架之上搭建一个可运行、可扩展的深度研究Deep ResearchAgent它通过tavily_search工具完成URL 发现 全文抓取通过think_tool在每轮检索后进行战略反思并通过编排者 研究子代理的分工结构实现并行研究与统一归稿。读完本文你将掌握环境搭建、两种运行方式Jupyter Notebook 与 LangGraph Server、三套提示词指令集的设计思路以及如何替换模型、指令与自定义工具。一、示例总览从搜索工具到研究系统深度研究Deep Research与普通搜索问答的本质区别在于它需要规划 → 多路检索 → 反思补漏 → 综合成文的完整工作流而不是单次搜索-回答循环。examples/deep_research正是演示了如何用deepagents包把这一工作流组织成一个可部署的 LangGraph Agent。该示例的核心设计是编排者 研究子代理双层结构编排者Orchestrator负责理解用户问题、拆解 TODO、把研究任务委托给子代理、汇总各子代理的发现并撰写最终报告研究子代理Research Sub-Agent只专注于某一具体方面的联网检索使用tavily_search与think_tool两个工具在搜索 → 反思 → 再搜索的循环中收敛答案。从代码结构看示例由以下文件组成文件作用agent.py组装 Agent 的独立脚本拼接指令、创建研究子代理、实例化模型并调用create_deep_agentresearch_agent/prompts.py三套提示词指令集工作流 / 子代理协调 / 研究者指令research_agent/tools.py两个自定义工具tavily_search与think_tool的实现research_agent.ipynb逐步讲解搭建过程的交互式 Notebooklanggraph.jsonLangGraph 平台配置声明research图与.env环境变量文件utils.pyNotebook 专用用 Rich 格式化展示消息与提示词pyproject.toml依赖声明与 uv 工程配置从 graph.py 中create_deep_agent的签名可以看到deepagents的 Agent 默认自带ls、read_file、write_file、edit_file、glob、grep等文件工具、execute执行工具与task子代理调用工具示例通过tools、system_prompt、subagents三个参数在原生能力之上叠加研究专用能力这正是任务特定工具 任务特定指令 任务特定子代理的扩展范式。二、环境准备安装与 API Key 配置2.1 前置要求uv 包管理器示例依赖uv进行依赖管理与运行pyproject.toml中requires-python 3.11并锁定了uv.lock。若尚未安装 uv先执行官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | sh随后进入示例目录cd examples/deep_research2.2 安装依赖uv syncuv sync会依据 pyproject.toml 创建虚拟环境并安装全部依赖其中核心依赖包括deepagents0.6.12Agent 框架本体langchain-anthropic1.5.4,2.0.0与langchain-google-genai4.2.7Claude 与 Gemini 的模型接入tavily-python0.7.26Tavily 搜索 API 客户端httpx0.28.1与markdownify1.2.2网页全文抓取与 HTML→Markdown 转换jupyter、ipykernelNotebook 运行环境langgraph-cli[inmem]0.4.30本地 LangGraph 服务器 CLI。注意 pyproject.toml 中还通过[tool.uv] override-dependencies对nbconvert与protobuf做了安全修复版本的强制覆盖对应 CVE 公告使用uv sync时会自动应用。2.3 配置环境变量运行前需要在环境中设置以下 API Keyexport ANTHROPIC_API_KEYyour_anthropic_api_key_here # Claude 模型必需 export GOOGLE_API_KEYyour_google_api_key_here # Gemini 模型必需 export TAVILY_API_KEYyour_tavily_api_key_here # 联网搜索必需Tavily 提供 generous 免费额度 export LANGSMITH_API_KEYyour_langsmith_api_key_here # LangSmith 可观测性免费注册其中TAVILY_API_KEY由 tools.py 中TavilyClient()读取客户端默认从TAVILY_API_KEY环境变量取密钥LANGSMITH_API_KEY用于链路追踪与调试。此外langgraph.json 中声明了env: .env说明使用 LangGraph Server 时也会读取项目根目录下的.env文件Notebook 首个 Cell 同样通过load_dotenv(.env, overrideTrue)加载它。三、两种运行方式示例提供了两种运行方式分别适合交互探索与 Web 界面部署。3.1 Option 1Jupyter Notebook逐步拆解uv run jupyter notebook research_agent.ipynbNotebook 按照理解原生工具 → 提供任务特定工具 → 提供任务特定指令 → 提供任务特定子代理四个步骤逐步组装 Agent并使用 utils.py 中的format_messages、show_prompt以 Rich Panel 形式可视化每一轮消息与提示词format_message_content同时兼容 Anthropic 的content列表格式与 OpenAI 的tool_calls字段格式非常适合学习与研究。3.2 Option 2LangGraph Server本地 Web 服务langgraph dev该命令由langgraph-cli提供读取 langgraph.json 中的配置——声明依赖[.]、注册名为research的图指向./agent.py:agent即 agent.py 中通过create_deep_agent创建的编译图对象。启动后 LangGraph 会自动打开浏览器进入 Studio 界面可直接提交搜索查询并观察 Agent 的逐步执行。也可以将该服务接入专门为 deepagents 设计的 Web UIgit clone对应 UI 项目后yarn install yarn dev再按其说明将 UI 连接到本地 LangGraph Server以获得更友好的聊天界面与文件状态可视化。提示langgraph dev需要langgraph-cli[inmem]已安装uv sync已包含agent.py中的create_deep_agent(...)在模块导入时即构建图因此langgraph.json可以无参直接引用agent。四、三套提示词指令集提示工程的具体实践深度研究的效果很大程度取决于提示词设计。prompts.py 定义了三套互补而非重复默认中间件指令的指令集可在不修改deepagents框架的前提下按需调整指令集目的RESEARCH_WORKFLOW_INSTRUCTIONS定义 5 步研究工作流保存请求 → 用 TODO 规划 → 委托子代理 → 综合 → 响应包含按查询类型分批相似任务、控制并行规模的规划准则SUBAGENT_DELEGATION_INSTRUCTIONS给出具体委托策略与示例简单查询用 1 个子代理对比型查询每个要素 1 个多面研究按方面拆分设定并行上限max 3与迭代轮数上限max 3RESEARCHER_INSTRUCTIONS指导单个研究子代理进行聚焦式联网检索简单查询 2–3 次、复杂查询最多 5 次搜索的硬性预算强调每次搜索后用think_tool做战略反思并给出停止条件4.1 研究工作流指令RESEARCH_WORKFLOW_INSTRUCTIONS该指令为编排者规定了完整的执行流程Plan用write_todos创建 TODO 列表把研究拆成聚焦任务Save the request用write_file()将用户研究问题保存到/research_request.mdResearch用task()工具把研究任务委托给子代理——始终使用子代理进行研究编排者不亲自检索Synthesize汇总所有子代理发现统一编号引用每个唯一 URL 全局只有一个编号Write Report将综合报告写入/final_report.md遵循下述报告写作准则Verify重读/research_request.md确认所有方面都已覆盖且引用与结构正确。同时给出研究规划准则把相似任务合并进单个 TODO 以降低开销简单事实性问题只用 1 个子代理对比或多面主题则并行委托多个子代理每个子代理专注一个方面并返回发现。4.2 报告写作准则指令对最终报告的结构模式与格式做了明确约定保证输出质量稳定对比类引言 → A 主题概述 → B 主题概述 → 详细对比 → 结论清单/排名类直接逐项列出并附说明无需引言摘要/综述类主题概述 → 关键概念 1/2/3 → 结论通用准则使用清晰的##/###标题层级默认段落式行文重文本而非堆砌 bullet避免自我指涉语言如I found...以专业报告口吻输出不加元评论每个小节内容详实仅当列表比散文更合适时才用 bullet引用格式正文内联[1]、[2]、[3]编号每个唯一 URL 在所有子代理发现中只分配一个编号文末以### Sources列出全部编号来源编号连续无空缺每行一条格式为[1] 标题: URL。4.3 子代理委托指令SUBAGENT_DELEGATION_INSTRUCTIONS委托策略的核心原则是默认 1 个子代理、仅在明确必要时并行默认 1 个子代理通用概述类什么是量子计算、旧金山 Top 10 咖啡店、互联网历史、AI Agent 的上下文工程研究都用 1 个子代理覆盖全部方面明确对比 → 每个要素 1 个对比 OpenAI vs Anthropic vs DeepMind 的 AI 安全方法用 3 个并行子代理对比 Python vs JavaScript用 2 个明显独立方面 → 每个方面 1 个慎用研究欧洲、亚洲、北美可再生能源应用按地理拆 3 路仅当单次综合搜索无法高效覆盖时才使用该模式。关键原则包括倾向单子代理一次全面研究比多次窄研究更省 token避免过早分解不要把研究 X拆成X 概述/技术/应用三路只为明确对比并行化。执行限制方面每轮最多{max_concurrent_research_units}个并行子代理示例中为 3在单次响应中多次调用task()以启用并行每轮最多{max_researcher_iterations}轮委托示例中为 3达到足够信息即停倾向聚焦研究而非穷举。4.4 研究者指令RESEARCHER_INSTRUCTIONS该指令通过.format(datecurrent_date)注入当前日期见 agent.py为子代理定义行为边界像有经验的人类研究者一样思考先精读问题 → 从宽泛查询开始 → 每轮搜索后暂停评估信息是否足够还缺什么→ 逐步收窄补漏 → 能自信回答就停止硬性工具调用预算简单查询最多 2–3 次搜索复杂查询最多 5 次5 次后仍找不到合适来源必须停止立即停止条件能全面回答用户问题已有 3 个以上相关示例/来源最近 2 次搜索返回相似信息展示思考每次搜索后用think_tool分析我找到了什么关键信息还缺什么是否足以全面回答继续搜还是给出答案最终回复格式结构化呈现发现清晰标题 详细解释、内联[1][2][3]引用、文末### Sources列出带标题与 URL 的编号来源编排者将汇总所有子代理的引用进最终报告。五、自定义工具检索与反思的底层实现示例在deepagents原生工具文件操作、execute、task之上新增两个研究专用工具实现位于 tools.py。5.1tavily_search把 Tavily 当 URL 发现引擎该工具的设计定位是纯 URL 发现引擎Tavily 只负责检索出相关 URL随后工具自行抓取完整网页内容并转为 Markdown 返回不做任何摘要从而把全部信息保留给 Agent 分析。tool(parse_docstringTrue) def tavily_search( query: str, max_results: Annotated[int, InjectedToolArg] 1, topic: Annotated[Literal[general, news, finance], InjectedToolArg] general, ) - str:参数说明参数类型默认值说明querystr必填要执行的搜索查询max_resultsint1返回结果条数上限InjectedToolArg由运行时注入模型不直接控制topicLiteral[general, news, finance]generalTavily 搜索主题过滤可选通用/新闻/财经工作流程tools.py为调用tavily_client.search(query, max_results..., topic...)发现候选 URL对每条结果调用fetch_webpage_content(url)抓取全文以## 标题 / **URL:** ... / 正文的格式拼接最终返回 Found N result(s) for query: ...的完整内容块。其中fetch_webpage_contenttools.py使用httpx.get默认 10 秒超时并携带真实浏览器 User-AgentChrome 91以规避 403 拒绝随后用markdownify将 HTML 转为干净 Markdown。任何抓取异常都会被捕获并作为错误文本返回不会中断 Agent 执行。5.2think_tool检索之间的战略反思think_tool是有意识的暂停机制让 Agent 在两次搜索之间停下系统化地评估进度、识别缺口、规划下一步从而改善决策质量、便于审计其推理过程。tool(parse_docstringTrue) def think_tool(reflection: str) - str: Tool for strategic reflection on research progress and decision-making. ... return fReflection recorded: {reflection}其 docstring 明确建议的使用时机收到搜索结果后我找到了哪些关键信息、决定下一步前信息是否足以全面回答、评估研究缺口时还缺什么具体信息、结束研究前现在能否给出完整答案。反思应覆盖四要素当前发现分析 → 缺口评估 → 质量评价证据/示例是否充分→ 战略决策继续搜索还是作答。工具本身只返回确认信息思考内容随对话上下文保留供编排者审计。5.3 接入自定义工具与 MCP在 agent.py 中这两个工具同时传入tools[tavily_search, think_tool]编排者可用与子代理的tools字段研究子代理可用。从create_deep_agent的签名文档graph.py可知tools参数是叠加式的——永远不会移除内建工具如需屏蔽内建工具需通过HarnessProfile的excluded_tools或自定义FilesystemMiddleware。同理示例也支持通过 MCP 服务器接入更多自有工具详细用法见 deepagents 包的 MCP 文档。六、自定义模型Claude 与 Gemini 自由切换默认情况下示例使用claude-sonnet-4-5-20250929见 agent.py。create_deep_agent的model参数接受provider:model字符串或任意已初始化的 LangChain 模型对象graph.py因此可非常方便地切换from langchain.chat_models import init_chat_model from deepagents import create_deep_agent # 使用 Claudetemperature 固定 0保证可复现性 model init_chat_model(modelanthropic:claude-sonnet-4-5-20250929, temperature0.0) # 使用 Gemini from langchain_google_genai import ChatGoogleGenerativeAI model ChatGoogleGenerativeAI(modelgemini-3-pro-preview) agent create_deep_agent( modelmodel, )agent.py 中同样保留了 Gemini 3 的构造示例ChatGoogleGenerativeAI(modelgemini-3-pro-preview, temperature0.0)注释掉了与 Claude 4.5 的默认配置。选择时注意tavily_search与think_tool均为纯工具调用不依赖特定模型的工具调用格式因此两种模型均可正常工作换模型时只需保证对应提供商依赖已安装langchain-anthropic/langchain-google-genai。七、源码级组装agent.py 如何把一切拼起来agent.py 是理解整套系统的关键入口其组装逻辑可拆为四步第一步拼接编排者指令INSTRUCTIONS ( RESEARCH_WORKFLOW_INSTRUCTIONS \n\n * 80 \n\n SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_unitsmax_concurrent_research_units, max_researcher_iterationsmax_researcher_iterations, ) )工作流指令与委托指令用 80 个分隔拼合并行上限3与迭代上限3作为格式化参数注入委托指令模板形成编排者全权负责流程与调度、研究者只做检索的职责分离。第二步定义研究子代理research_sub_agent { name: research-agent, description: Delegate research to the sub-agent researcher. Only give this researcher one topic at a time., system_prompt: RESEARCHER_INSTRUCTIONS.format(datecurrent_date), tools: [tavily_search, think_tool], }对照 subagents.py 中SubAgent的类型定义name与description用于主代理决策何时委托system_prompt附加到子代理提示词tools未指定时继承主代理工具。示例显式只给研究子代理搜索与反思工具确保其专注检索。子代理默认modeisolated——只看到被委托的任务拥有隔离上下文避免主代理的完整对话历史稀释其注意力。第三步实例化模型默认init_chat_model(modelanthropic:claude-sonnet-4-5-20250929, temperature0.0)。第四步组装 Agentagent create_deep_agent( modelmodel, tools[tavily_search, think_tool], system_promptINSTRUCTIONS, subagents[research_sub_agent], )system_prompt作为调用者编写的指令USER段被放在系统提示词最前graph.py随后拼接框架的BASE/SUFFIX段subagents触发SubAgentMiddleware注入task工具graph.py。最终图对象agent被 langgraph.json 以research: ./agent.py:agent注册可直接被langgraph dev加载。八、完整执行链路与验证从 Notebookresearch_agent.ipynb到服务端整个系统的执行链路可以归纳为用户查询 → 编排者Claude/Gemini → write_todos 拆解 TODO → write_file 保存 /research_request.md → task() 委托 research-agent每轮最多 3 个并行 → tavily_searchURL 发现 全文抓取转 Markdown → think_tool反思够了吗缺什么下一步 → 返回带 [n] 引用的发现 → 汇总去重编号引用 → 写入 /final_report.md按报告写作准则 → 重读 /research_request.md 校验覆盖度验证要点子代理的停止条件预算内收敛、编排者的报告结构对比/清单/综述模板与引用编号一致性都可以在 prompts.py 中逐条找到依据工具行为可在 tools.py 中直接阅读实现组装与部署配置见 agent.py 与 langgraph.json。九、扩展建议与注意事项接入更多 MCP 工具create_deep_agent的tools为叠加式可在不破坏内建工具的前提下加入数据库查询、API 调用等 MCP 工具拓宽研究素材来源调优并行与预算max_concurrent_research_units与max_researcher_iterations在 agent.py 中集中定义需注意与模型上下文窗口、API 速率限制的匹配提示词即产品需求三套指令尤其是报告写作准则是输出质量的直接决定因素按业务场景技术综述、竞品对比、文献调研调整结构模板即可复用整个框架依赖安全pyproject.toml已通过override-dependencies覆盖两个已知 CVE 版本升级依赖时请保留此类覆盖环境变量Notebook 与 LangGraph Server 都会读取.envload_dotenv与langgraph.json的env: .env建议将密钥集中放入该文件并确保其不入版本库。通过以上设计examples/deep_research展示了一条完整的框架原生能力 任务特定工具 任务特定指令 任务特定子代理的 Agent 构建路径——它既是可立即运行的深度研究系统也是理解 deepagents 提示词工程与多子代理协作范式的极佳样例。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Deep Research Agent 实战：用 deepagents 构建具备战略思考能力的多子代理深度研究系统
Deep Research Agent 实战用 deepagents 构建具备战略思考能力的多子代理深度研究系统【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本指南以 examples/deep_research 示例为骨架完整讲解如何在deepagents框架之上搭建一个可运行、可扩展的深度研究Deep ResearchAgent它通过tavily_search工具完成URL 发现 全文抓取通过think_tool在每轮检索后进行战略反思并通过编排者 研究子代理的分工结构实现并行研究与统一归稿。读完本文你将掌握环境搭建、两种运行方式Jupyter Notebook 与 LangGraph Server、三套提示词指令集的设计思路以及如何替换模型、指令与自定义工具。一、示例总览从搜索工具到研究系统深度研究Deep Research与普通搜索问答的本质区别在于它需要规划 → 多路检索 → 反思补漏 → 综合成文的完整工作流而不是单次搜索-回答循环。examples/deep_research正是演示了如何用deepagents包把这一工作流组织成一个可部署的 LangGraph Agent。该示例的核心设计是编排者 研究子代理双层结构编排者Orchestrator负责理解用户问题、拆解 TODO、把研究任务委托给子代理、汇总各子代理的发现并撰写最终报告研究子代理Research Sub-Agent只专注于某一具体方面的联网检索使用tavily_search与think_tool两个工具在搜索 → 反思 → 再搜索的循环中收敛答案。从代码结构看示例由以下文件组成文件作用agent.py组装 Agent 的独立脚本拼接指令、创建研究子代理、实例化模型并调用create_deep_agentresearch_agent/prompts.py三套提示词指令集工作流 / 子代理协调 / 研究者指令research_agent/tools.py两个自定义工具tavily_search与think_tool的实现research_agent.ipynb逐步讲解搭建过程的交互式 Notebooklanggraph.jsonLangGraph 平台配置声明research图与.env环境变量文件utils.pyNotebook 专用用 Rich 格式化展示消息与提示词pyproject.toml依赖声明与 uv 工程配置从 graph.py 中create_deep_agent的签名可以看到deepagents的 Agent 默认自带ls、read_file、write_file、edit_file、glob、grep等文件工具、execute执行工具与task子代理调用工具示例通过tools、system_prompt、subagents三个参数在原生能力之上叠加研究专用能力这正是任务特定工具 任务特定指令 任务特定子代理的扩展范式。二、环境准备安装与 API Key 配置2.1 前置要求uv 包管理器示例依赖uv进行依赖管理与运行pyproject.toml中requires-python 3.11并锁定了uv.lock。若尚未安装 uv先执行官方安装脚本curl -LsSf https://astral.sh/uv/install.sh | sh随后进入示例目录cd examples/deep_research2.2 安装依赖uv syncuv sync会依据 pyproject.toml 创建虚拟环境并安装全部依赖其中核心依赖包括deepagents0.6.12Agent 框架本体langchain-anthropic1.5.4,2.0.0与langchain-google-genai4.2.7Claude 与 Gemini 的模型接入tavily-python0.7.26Tavily 搜索 API 客户端httpx0.28.1与markdownify1.2.2网页全文抓取与 HTML→Markdown 转换jupyter、ipykernelNotebook 运行环境langgraph-cli[inmem]0.4.30本地 LangGraph 服务器 CLI。注意 pyproject.toml 中还通过[tool.uv] override-dependencies对nbconvert与protobuf做了安全修复版本的强制覆盖对应 CVE 公告使用uv sync时会自动应用。2.3 配置环境变量运行前需要在环境中设置以下 API Keyexport ANTHROPIC_API_KEYyour_anthropic_api_key_here # Claude 模型必需 export GOOGLE_API_KEYyour_google_api_key_here # Gemini 模型必需 export TAVILY_API_KEYyour_tavily_api_key_here # 联网搜索必需Tavily 提供 generous 免费额度 export LANGSMITH_API_KEYyour_langsmith_api_key_here # LangSmith 可观测性免费注册其中TAVILY_API_KEY由 tools.py 中TavilyClient()读取客户端默认从TAVILY_API_KEY环境变量取密钥LANGSMITH_API_KEY用于链路追踪与调试。此外langgraph.json 中声明了env: .env说明使用 LangGraph Server 时也会读取项目根目录下的.env文件Notebook 首个 Cell 同样通过load_dotenv(.env, overrideTrue)加载它。三、两种运行方式示例提供了两种运行方式分别适合交互探索与 Web 界面部署。3.1 Option 1Jupyter Notebook逐步拆解uv run jupyter notebook research_agent.ipynbNotebook 按照理解原生工具 → 提供任务特定工具 → 提供任务特定指令 → 提供任务特定子代理四个步骤逐步组装 Agent并使用 utils.py 中的format_messages、show_prompt以 Rich Panel 形式可视化每一轮消息与提示词format_message_content同时兼容 Anthropic 的content列表格式与 OpenAI 的tool_calls字段格式非常适合学习与研究。3.2 Option 2LangGraph Server本地 Web 服务langgraph dev该命令由langgraph-cli提供读取 langgraph.json 中的配置——声明依赖[.]、注册名为research的图指向./agent.py:agent即 agent.py 中通过create_deep_agent创建的编译图对象。启动后 LangGraph 会自动打开浏览器进入 Studio 界面可直接提交搜索查询并观察 Agent 的逐步执行。也可以将该服务接入专门为 deepagents 设计的 Web UIgit clone对应 UI 项目后yarn install yarn dev再按其说明将 UI 连接到本地 LangGraph Server以获得更友好的聊天界面与文件状态可视化。提示langgraph dev需要langgraph-cli[inmem]已安装uv sync已包含agent.py中的create_deep_agent(...)在模块导入时即构建图因此langgraph.json可以无参直接引用agent。四、三套提示词指令集提示工程的具体实践深度研究的效果很大程度取决于提示词设计。prompts.py 定义了三套互补而非重复默认中间件指令的指令集可在不修改deepagents框架的前提下按需调整指令集目的RESEARCH_WORKFLOW_INSTRUCTIONS定义 5 步研究工作流保存请求 → 用 TODO 规划 → 委托子代理 → 综合 → 响应包含按查询类型分批相似任务、控制并行规模的规划准则SUBAGENT_DELEGATION_INSTRUCTIONS给出具体委托策略与示例简单查询用 1 个子代理对比型查询每个要素 1 个多面研究按方面拆分设定并行上限max 3与迭代轮数上限max 3RESEARCHER_INSTRUCTIONS指导单个研究子代理进行聚焦式联网检索简单查询 2–3 次、复杂查询最多 5 次搜索的硬性预算强调每次搜索后用think_tool做战略反思并给出停止条件4.1 研究工作流指令RESEARCH_WORKFLOW_INSTRUCTIONS该指令为编排者规定了完整的执行流程Plan用write_todos创建 TODO 列表把研究拆成聚焦任务Save the request用write_file()将用户研究问题保存到/research_request.mdResearch用task()工具把研究任务委托给子代理——始终使用子代理进行研究编排者不亲自检索Synthesize汇总所有子代理发现统一编号引用每个唯一 URL 全局只有一个编号Write Report将综合报告写入/final_report.md遵循下述报告写作准则Verify重读/research_request.md确认所有方面都已覆盖且引用与结构正确。同时给出研究规划准则把相似任务合并进单个 TODO 以降低开销简单事实性问题只用 1 个子代理对比或多面主题则并行委托多个子代理每个子代理专注一个方面并返回发现。4.2 报告写作准则指令对最终报告的结构模式与格式做了明确约定保证输出质量稳定对比类引言 → A 主题概述 → B 主题概述 → 详细对比 → 结论清单/排名类直接逐项列出并附说明无需引言摘要/综述类主题概述 → 关键概念 1/2/3 → 结论通用准则使用清晰的##/###标题层级默认段落式行文重文本而非堆砌 bullet避免自我指涉语言如I found...以专业报告口吻输出不加元评论每个小节内容详实仅当列表比散文更合适时才用 bullet引用格式正文内联[1]、[2]、[3]编号每个唯一 URL 在所有子代理发现中只分配一个编号文末以### Sources列出全部编号来源编号连续无空缺每行一条格式为[1] 标题: URL。4.3 子代理委托指令SUBAGENT_DELEGATION_INSTRUCTIONS委托策略的核心原则是默认 1 个子代理、仅在明确必要时并行默认 1 个子代理通用概述类什么是量子计算、旧金山 Top 10 咖啡店、互联网历史、AI Agent 的上下文工程研究都用 1 个子代理覆盖全部方面明确对比 → 每个要素 1 个对比 OpenAI vs Anthropic vs DeepMind 的 AI 安全方法用 3 个并行子代理对比 Python vs JavaScript用 2 个明显独立方面 → 每个方面 1 个慎用研究欧洲、亚洲、北美可再生能源应用按地理拆 3 路仅当单次综合搜索无法高效覆盖时才使用该模式。关键原则包括倾向单子代理一次全面研究比多次窄研究更省 token避免过早分解不要把研究 X拆成X 概述/技术/应用三路只为明确对比并行化。执行限制方面每轮最多{max_concurrent_research_units}个并行子代理示例中为 3在单次响应中多次调用task()以启用并行每轮最多{max_researcher_iterations}轮委托示例中为 3达到足够信息即停倾向聚焦研究而非穷举。4.4 研究者指令RESEARCHER_INSTRUCTIONS该指令通过.format(datecurrent_date)注入当前日期见 agent.py为子代理定义行为边界像有经验的人类研究者一样思考先精读问题 → 从宽泛查询开始 → 每轮搜索后暂停评估信息是否足够还缺什么→ 逐步收窄补漏 → 能自信回答就停止硬性工具调用预算简单查询最多 2–3 次搜索复杂查询最多 5 次5 次后仍找不到合适来源必须停止立即停止条件能全面回答用户问题已有 3 个以上相关示例/来源最近 2 次搜索返回相似信息展示思考每次搜索后用think_tool分析我找到了什么关键信息还缺什么是否足以全面回答继续搜还是给出答案最终回复格式结构化呈现发现清晰标题 详细解释、内联[1][2][3]引用、文末### Sources列出带标题与 URL 的编号来源编排者将汇总所有子代理的引用进最终报告。五、自定义工具检索与反思的底层实现示例在deepagents原生工具文件操作、execute、task之上新增两个研究专用工具实现位于 tools.py。5.1tavily_search把 Tavily 当 URL 发现引擎该工具的设计定位是纯 URL 发现引擎Tavily 只负责检索出相关 URL随后工具自行抓取完整网页内容并转为 Markdown 返回不做任何摘要从而把全部信息保留给 Agent 分析。tool(parse_docstringTrue) def tavily_search( query: str, max_results: Annotated[int, InjectedToolArg] 1, topic: Annotated[Literal[general, news, finance], InjectedToolArg] general, ) - str:参数说明参数类型默认值说明querystr必填要执行的搜索查询max_resultsint1返回结果条数上限InjectedToolArg由运行时注入模型不直接控制topicLiteral[general, news, finance]generalTavily 搜索主题过滤可选通用/新闻/财经工作流程tools.py为调用tavily_client.search(query, max_results..., topic...)发现候选 URL对每条结果调用fetch_webpage_content(url)抓取全文以## 标题 / **URL:** ... / 正文的格式拼接最终返回 Found N result(s) for query: ...的完整内容块。其中fetch_webpage_contenttools.py使用httpx.get默认 10 秒超时并携带真实浏览器 User-AgentChrome 91以规避 403 拒绝随后用markdownify将 HTML 转为干净 Markdown。任何抓取异常都会被捕获并作为错误文本返回不会中断 Agent 执行。5.2think_tool检索之间的战略反思think_tool是有意识的暂停机制让 Agent 在两次搜索之间停下系统化地评估进度、识别缺口、规划下一步从而改善决策质量、便于审计其推理过程。tool(parse_docstringTrue) def think_tool(reflection: str) - str: Tool for strategic reflection on research progress and decision-making. ... return fReflection recorded: {reflection}其 docstring 明确建议的使用时机收到搜索结果后我找到了哪些关键信息、决定下一步前信息是否足以全面回答、评估研究缺口时还缺什么具体信息、结束研究前现在能否给出完整答案。反思应覆盖四要素当前发现分析 → 缺口评估 → 质量评价证据/示例是否充分→ 战略决策继续搜索还是作答。工具本身只返回确认信息思考内容随对话上下文保留供编排者审计。5.3 接入自定义工具与 MCP在 agent.py 中这两个工具同时传入tools[tavily_search, think_tool]编排者可用与子代理的tools字段研究子代理可用。从create_deep_agent的签名文档graph.py可知tools参数是叠加式的——永远不会移除内建工具如需屏蔽内建工具需通过HarnessProfile的excluded_tools或自定义FilesystemMiddleware。同理示例也支持通过 MCP 服务器接入更多自有工具详细用法见 deepagents 包的 MCP 文档。六、自定义模型Claude 与 Gemini 自由切换默认情况下示例使用claude-sonnet-4-5-20250929见 agent.py。create_deep_agent的model参数接受provider:model字符串或任意已初始化的 LangChain 模型对象graph.py因此可非常方便地切换from langchain.chat_models import init_chat_model from deepagents import create_deep_agent # 使用 Claudetemperature 固定 0保证可复现性 model init_chat_model(modelanthropic:claude-sonnet-4-5-20250929, temperature0.0) # 使用 Gemini from langchain_google_genai import ChatGoogleGenerativeAI model ChatGoogleGenerativeAI(modelgemini-3-pro-preview) agent create_deep_agent( modelmodel, )agent.py 中同样保留了 Gemini 3 的构造示例ChatGoogleGenerativeAI(modelgemini-3-pro-preview, temperature0.0)注释掉了与 Claude 4.5 的默认配置。选择时注意tavily_search与think_tool均为纯工具调用不依赖特定模型的工具调用格式因此两种模型均可正常工作换模型时只需保证对应提供商依赖已安装langchain-anthropic/langchain-google-genai。七、源码级组装agent.py 如何把一切拼起来agent.py 是理解整套系统的关键入口其组装逻辑可拆为四步第一步拼接编排者指令INSTRUCTIONS ( RESEARCH_WORKFLOW_INSTRUCTIONS \n\n * 80 \n\n SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_unitsmax_concurrent_research_units, max_researcher_iterationsmax_researcher_iterations, ) )工作流指令与委托指令用 80 个分隔拼合并行上限3与迭代上限3作为格式化参数注入委托指令模板形成编排者全权负责流程与调度、研究者只做检索的职责分离。第二步定义研究子代理research_sub_agent { name: research-agent, description: Delegate research to the sub-agent researcher. Only give this researcher one topic at a time., system_prompt: RESEARCHER_INSTRUCTIONS.format(datecurrent_date), tools: [tavily_search, think_tool], }对照 subagents.py 中SubAgent的类型定义name与description用于主代理决策何时委托system_prompt附加到子代理提示词tools未指定时继承主代理工具。示例显式只给研究子代理搜索与反思工具确保其专注检索。子代理默认modeisolated——只看到被委托的任务拥有隔离上下文避免主代理的完整对话历史稀释其注意力。第三步实例化模型默认init_chat_model(modelanthropic:claude-sonnet-4-5-20250929, temperature0.0)。第四步组装 Agentagent create_deep_agent( modelmodel, tools[tavily_search, think_tool], system_promptINSTRUCTIONS, subagents[research_sub_agent], )system_prompt作为调用者编写的指令USER段被放在系统提示词最前graph.py随后拼接框架的BASE/SUFFIX段subagents触发SubAgentMiddleware注入task工具graph.py。最终图对象agent被 langgraph.json 以research: ./agent.py:agent注册可直接被langgraph dev加载。八、完整执行链路与验证从 Notebookresearch_agent.ipynb到服务端整个系统的执行链路可以归纳为用户查询 → 编排者Claude/Gemini → write_todos 拆解 TODO → write_file 保存 /research_request.md → task() 委托 research-agent每轮最多 3 个并行 → tavily_searchURL 发现 全文抓取转 Markdown → think_tool反思够了吗缺什么下一步 → 返回带 [n] 引用的发现 → 汇总去重编号引用 → 写入 /final_report.md按报告写作准则 → 重读 /research_request.md 校验覆盖度验证要点子代理的停止条件预算内收敛、编排者的报告结构对比/清单/综述模板与引用编号一致性都可以在 prompts.py 中逐条找到依据工具行为可在 tools.py 中直接阅读实现组装与部署配置见 agent.py 与 langgraph.json。九、扩展建议与注意事项接入更多 MCP 工具create_deep_agent的tools为叠加式可在不破坏内建工具的前提下加入数据库查询、API 调用等 MCP 工具拓宽研究素材来源调优并行与预算max_concurrent_research_units与max_researcher_iterations在 agent.py 中集中定义需注意与模型上下文窗口、API 速率限制的匹配提示词即产品需求三套指令尤其是报告写作准则是输出质量的直接决定因素按业务场景技术综述、竞品对比、文献调研调整结构模板即可复用整个框架依赖安全pyproject.toml已通过override-dependencies覆盖两个已知 CVE 版本升级依赖时请保留此类覆盖环境变量Notebook 与 LangGraph Server 都会读取.envload_dotenv与langgraph.json的env: .env建议将密钥集中放入该文件并确保其不入版本库。通过以上设计examples/deep_research展示了一条完整的框架原生能力 任务特定工具 任务特定指令 任务特定子代理的 Agent 构建路径——它既是可立即运行的深度研究系统也是理解 deepagents 提示词工程与多子代理协作范式的极佳样例。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考