十分钟跑通你的第一个深度研究 Agent

《Deep Agents 实战笔记》第 2 篇 | 基于 deepagents (Python) 官方 Quickstart 原文：https://docs.langchain.com/oss/python/deepagents/quickstart

上一篇讲了 Deep Agents 为什么用文件系统和子代理这两个设计来解决问题。纸上得来终觉浅，这一篇我们直接跑通官方 Quickstart：一个能自主搜索、拆解任务、写出研究报告的深度研究 Agent。完整代码不到 40 行。

一、准备环境

pip install -U deepagents

然后配一个模型 API key（三选一即可）：

# 任选其一
export GOOGLE_API_KEY="..."      # Google
export OPENAI_API_KEY="..."      # OpenAI
export ANTHROPIC_API_KEY="..."   # Anthropic

Deep Agents 的模型接入沿用 LangChain 的 provider:model 字符串规范，理论上 100+ 提供商都能接。国内读者常用的 OpenRouter / Ollama 也直接支持，比如 openrouter:z-ai/glm-5.2 或 ollama:你的模型名，后面代码里替换即可。

二、给 Agent 一双"能上网的手"

Agent 本身没有任何联网能力，搜索要靠我们喂给它一个工具。如果你的模型自带搜索（Gemini / GPT / Claude 均有内置 web search），可以直接用内置搜索，零额外配置：

# Google 内置搜索（以 Gemini 为例）
internet_search = {"google_search": {}}

如果你的模型没有内置搜索（或你想统一控制），用 Tavily：

import os
from typing import Literal

from tavily import TavilyClient
from deepagents import create_deep_agent

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,
):
    """执行一次网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

注意这个普通 Python 函数的三要素：类型标注的参数签名 + docstring。Deep Agents 会自动把它包装成模型可调用的工具，docstring 就是模型决定"什么时候调它、怎么调"的唯一依据。搜索类工具建议保留 include_raw_content 参数——后面你会看到它的妙用。

三、创建 Deep Agent：只需要三个参数

# 引导代理成为专家研究者的系统提示词
research_instructions = """You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## `internet_search`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
"""

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",   # 换成你的 provider:model
    tools=[internet_search],
    system_prompt=research_instructions,
)

create_deep_agent 的必填参数只有三个：模型、工具、系统提示词。但真正的"深度"来自你没传的那些东西——你没配文件系统，它有；你没定义子代理，它有；你没写总结压缩逻辑，它也有。这些都是 harness 默认内置的。

四、跑起来

result = agent.invoke({"messages": [{"role": "user", "content": "What is langgraph?"}]})

# 打印最终报告
print(result["messages"][-1].content)

一个看起来平平无奇的问题 "What is langgraph?"，背后会发生什么？用一张时序图还原 Agent 的真实执行过程：

sequenceDiagram
    participant U as 用户
    participant M as 主代理<br/>（监督者）
    participant T as internet_search
    participant FS as 虚拟文件系统
    participant SA as 子代理

    U->>M: What is langgraph?
    M->>T: 搜索 "LangGraph"
    T-->>M: 结果摘要
    M->>T: 追问细节（架构 / 应用场景...）
    T-->>M: 更多结果
    Note over M,FS: 结果过大时<br/>write_file 落盘，上下文只留摘要
    M->>SA: task: 深入研究某个子问题<br/>（独立上下文 + 同样的工具）
    SA->>T: 自主多轮搜索
    SA->>FS: 写入研究笔记
    SA-->>M: 研究结果摘要
    M->>U: 综合所有发现，输出完整报告

正在渲染图表…

官方对这段执行的概括是四步：

开展研究：调用 internet_search 收集信息；
管理上下文：用 write_file / read_file 把大型搜索结果卸载到文件系统；
按需生成子代理：把复杂的子问题委派给专门子代理；
综合成报告：汇总各项发现，输出连贯回答。

实际执行时它到底拆了几步、派了几个子代理，取决于问题的复杂度和模型自己的判断——这正是"deep"的含义：没有固定的 Agent 工作流，只有目标和工具，怎么拆解由它自己决定。

五、强烈建议：打开 LangSmith 追踪

裸看 result["messages"] 只能看到最终答案，看不到过程。强烈建议第一步就配好 LangSmith（免费额度够用）：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

配好后再跑一次，在 smith.langchain.com 里你能看到完整的执行树：每一次 LLM 调用的输入输出、每一次工具调用的参数与结果、子代理委派的层级结构。调试 Deep Agent 的第一原则：先看 trace，再猜问题。

六、两个立刻可以试的增强

跑通之后，可以马上试两个官方提供的增强：

1. 任务规划（todo list）：让复杂任务先列计划再执行，执行过程全程可追踪（v0.7 起为可选启用）：

from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[internet_search],
    system_prompt=research_instructions,
    middleware=[TodoListMiddleware()],
)

2. 流式输出：invoke 换成 stream，实时看到每一步工具调用和 token 生成，长任务的体验会好非常多（第 9 篇细讲）。

七、本篇踩坑点

docstring 不要省：搜索工具没有 docstring 或写得含糊，模型调用质量会断崖式下跌；
模型字符串写错不报错但很怪：provider:model 格式不对时有些 provider 会静默降级，遇到行为诡异先检查模型字符串；
第一次运行会觉得"慢"：深度研究本身就是多轮 LLM 调用 + 多轮搜索，这是特性不是 bug——但正因为慢，上下文管理才重要，这正是后面几篇的主题。

下一篇，我们拆开 harness 看内部构造：规划、文件系统、子代理、记忆、技能这五张牌各自怎么打。

参考资料与可运行代码：

官方 Quickstart：https://docs.langchain.com/oss/python/deepagents/quickstart
完整示例仓库：https://github.com/langchain-ai/deepagents/tree/main/examples

《Deep Agents 实战笔记》第 2 篇 | 基于 deepagents (Python) 官方 Quickstart 原文：https://docs.langchain.com/oss/python/deepagents/quickstart

一、准备环境

pip install -U deepagents

然后配一个模型 API key（三选一即可）：

# 任选其一
export GOOGLE_API_KEY="..."      # Google
export OPENAI_API_KEY="..."      # OpenAI
export ANTHROPIC_API_KEY="..."   # Anthropic

二、给 Agent 一双"能上网的手"

# Google 内置搜索（以 Gemini 为例）
internet_search = {"google_search": {}}

如果你的模型没有内置搜索（或你想统一控制），用 Tavily：

import os
from typing import Literal

from tavily import TavilyClient
from deepagents import create_deep_agent

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,
):
    """执行一次网络搜索"""
    return tavily_client.search(
        query,
        max_results=max_results,
        include_raw_content=include_raw_content,
        topic=topic,
    )

三、创建 Deep Agent：只需要三个参数

# 引导代理成为专家研究者的系统提示词
research_instructions = """You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## `internet_search`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
"""

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",   # 换成你的 provider:model
    tools=[internet_search],
    system_prompt=research_instructions,
)

四、跑起来

result = agent.invoke({"messages": [{"role": "user", "content": "What is langgraph?"}]})

# 打印最终报告
print(result["messages"][-1].content)

一个看起来平平无奇的问题 "What is langgraph?"，背后会发生什么？用一张时序图还原 Agent 的真实执行过程：

sequenceDiagram
    participant U as 用户
    participant M as 主代理<br/>（监督者）
    participant T as internet_search
    participant FS as 虚拟文件系统
    participant SA as 子代理

    U->>M: What is langgraph?
    M->>T: 搜索 "LangGraph"
    T-->>M: 结果摘要
    M->>T: 追问细节（架构 / 应用场景...）
    T-->>M: 更多结果
    Note over M,FS: 结果过大时<br/>write_file 落盘，上下文只留摘要
    M->>SA: task: 深入研究某个子问题<br/>（独立上下文 + 同样的工具）
    SA->>T: 自主多轮搜索
    SA->>FS: 写入研究笔记
    SA-->>M: 研究结果摘要
    M->>U: 综合所有发现，输出完整报告

正在渲染图表…

官方对这段执行的概括是四步：

开展研究：调用 internet_search 收集信息；
管理上下文：用 write_file / read_file 把大型搜索结果卸载到文件系统；
按需生成子代理：把复杂的子问题委派给专门子代理；
综合成报告：汇总各项发现，输出连贯回答。

五、强烈建议：打开 LangSmith 追踪

裸看 result["messages"] 只能看到最终答案，看不到过程。强烈建议第一步就配好 LangSmith（免费额度够用）：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

六、两个立刻可以试的增强

跑通之后，可以马上试两个官方提供的增强：

1. 任务规划（todo list）：让复杂任务先列计划再执行，执行过程全程可追踪（v0.7 起为可选启用）：

from langchain.agents.middleware import TodoListMiddleware

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[internet_search],
    system_prompt=research_instructions,
    middleware=[TodoListMiddleware()],
)

2. 流式输出：invoke 换成 stream，实时看到每一步工具调用和 token 生成，长任务的体验会好非常多（第 9 篇细讲）。

七、本篇踩坑点

docstring 不要省：搜索工具没有 docstring 或写得含糊，模型调用质量会断崖式下跌；
模型字符串写错不报错但很怪：provider:model 格式不对时有些 provider 会静默降级，遇到行为诡异先检查模型字符串；
第一次运行会觉得"慢"：深度研究本身就是多轮 LLM 调用 + 多轮搜索，这是特性不是 bug——但正因为慢，上下文管理才重要，这正是后面几篇的主题。

下一篇，我们拆开 harness 看内部构造：规划、文件系统、子代理、记忆、技能这五张牌各自怎么打。

参考资料与可运行代码：

官方 Quickstart：https://docs.langchain.com/oss/python/deepagents/quickstart
完整示例仓库：https://github.com/langchain-ai/deepagents/tree/main/examples

一、准备环境

二、给 Agent 一双"能上网的手"

三、创建 Deep Agent：只需要三个参数

四、跑起来

五、强烈建议：打开 LangSmith 追踪

六、两个立刻可以试的增强

七、本篇踩坑点

Related Articles

Deep Agents 实战笔记：从跑通到上线的 13 篇路线图

走向生产：容错、部署与可观测性

实战二：Agentic RAG——当检索遇上深度智能体

一、准备环境

二、给 Agent 一双"能上网的手"

三、创建 Deep Agent：只需要三个参数

四、跑起来

五、强烈建议：打开 LangSmith 追踪

六、两个立刻可以试的增强

七、本篇踩坑点

Related Articles

Deep Agents 实战笔记：从跑通到上线的 13 篇路线图

走向生产：容错、部署与可观测性

实战二：Agentic RAG——当检索遇上深度智能体