> ## Documentation Index > Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 构建深度研究智能体 > 构建一个具有子智能体委派能力的多步骤网络研究智能体 ## 概述 本指南演示如何使用[深度智能体](/oss/python/deepagents)从零开始构建一个多步骤网络研究智能体。该智能体将研究问题分解为聚焦的任务，将其委派给专门的子智能体，并将发现综合为一份全面的报告。 你构建的智能体将： 1. 使用待办列表规划研究 2. 将聚焦的研究任务委派给具有隔离上下文的子智能体 3. 在收集信息时评估搜索结果并规划下一步 4. 将发现综合为带有适当引用的最终报告 生成的子智能体将使用 Tavily 进行网络搜索，获取完整的网页内容进行分析。 ### 关键概念 本教程涵盖： * 用于并行、上下文隔离研究的[子智能体](/oss/python/deepagents/subagents) * 用于网络搜索的自定义[工具](/oss/python/langchain/tools) * 使用[内置规划工具](/oss/python/deepagents/harness#planning-capabilities)进行多步骤规划 ## 前置条件 以下服务的 API 密钥： * Anthropic (Claude) 或 Google (Gemini) * [Tavily](https://www.tavily.com/) 用于网络搜索（可选 - 免费额度足够） * [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-deepagents-deep-research) 用于追踪（可选） ## 设置 ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} mkdir deep-research-agent cd deep-research-agent ``` ```bash pip wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} pip install deepagents tavily-python httpx markdownify langchain-anthropic langchain-core ``` ```bash uv wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv init uv add deepagents tavily-python httpx markdownify langchain-anthropic langchain-core uv sync ``` ```bash pip wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} pip install deepagents tavily-python httpx markdownify langchain-google-genai langchain-core ``` ```bash uv wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} uv init uv add deepagents tavily-python httpx markdownify langchain-google-genai langchain-core uv sync ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export ANTHROPIC_API_KEY="your_anthropic_api_key" export TAVILY_API_KEY="your_tavily_api_key" export LANGSMITH_API_KEY="your_langsmith_api_key" # 可选 ``` ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} export GOOGLE_API_KEY="your_google_api_key" export TAVILY_API_KEY="your_tavily_api_key" export LANGSMITH_API_KEY="your_langsmith_api_key" # 可选 ``` ## 构建智能体 在项目目录中创建 `agent.py`： 添加自定义搜索工具。`tavily_search` 工具使用 Tavily 进行 URL 发现，然后获取完整的网页内容，这样智能体可以分析完整的来源而不是摘要。 ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} import os from typing import Annotated, Literal import httpx from langchain.tools import InjectedToolArg, tool from markdownify import markdownify from tavily import TavilyClient tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"]) def fetch_webpage_content(url: str, timeout: float = 10.0) -> str: """Fetch webpage and convert HTML to markdown.""" headers = { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" } try: response = httpx.get(url, headers=headers, timeout=timeout) response.raise_for_status() return markdownify(response.text) except Exception as e: return f"Error fetching {url}: {e!s}" @tool(parse_docstring=True) def tavily_search( query: str, max_results: Annotated[int, InjectedToolArg] = 1, topic: Annotated[ Literal["general", "news", "finance"], InjectedToolArg ] = "general", ) -> str: """Search the web for information on a given query. Uses Tavily to discover relevant URLs, then fetches and returns full webpage content as markdown. Args: query: Search query to execute max_results: Maximum number of results to return (default: 1) topic: Topic filter - 'general', 'news', or 'finance' (default: 'general') Returns: Formatted search results with full webpage content """ search_results = tavily_client.search( query, max_results=max_results, topic=topic, ) result_texts = [] for result in search_results.get("results", []): url = result["url"] title = result["title"] content = fetch_webpage_content(url) result_texts.append(f"## {title}\n**URL:** {url}\n\n{content}\n---") return f"Found {len(result_texts)} result(s) for '{query}':\n\n" + "\n".join( result_texts ) ``` 将编排工作流和子智能体提示词模板添加到 `agent.py`： ```python expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} RESEARCH_WORKFLOW_INSTRUCTIONS = """# Research Workflow Follow this workflow for all research requests: 1. **Plan**: Create a todo list with write_todos to break down the research into focused tasks 2. **Save the request**: Use write_file() to save the user's research question to `/research_request.md` 3. **Research**: Delegate research tasks to sub-agents using the task() tool - ALWAYS use sub-agents for research, never conduct research yourself 4. **Synthesize**: Review all sub-agent findings and consolidate citations (each unique URL gets one number across all findings) 5. **Write Report**: Write a comprehensive final report to `/final_report.md` (see Report Writing Guidelines below) 6. **Verify**: Read `/research_request.md` and confirm you've addressed all aspects with proper citations and structure ## Research Planning Guidelines - Batch similar research tasks into a single TODO to minimize overhead - For simple fact-finding questions, use 1 sub-agent - For comparisons or multi-faceted topics, delegate to multiple parallel sub-agents - Each sub-agent should research one specific aspect and return findings ## Report Writing Guidelines When writing the final report to `/final_report.md`, follow these structure patterns: **For comparisons:** 1. Introduction 2. Overview of topic A 3. Overview of topic B 4. Detailed comparison 5. Conclusion **For lists/rankings:** Simply list items with details - no introduction needed: 1. Item 1 with explanation 2. Item 2 with explanation 3. Item 3 with explanation **For summaries/overviews:** 1. Overview of topic 2. Key concept 1 3. Key concept 2 4. Key concept 3 5. Conclusion **General guidelines:** - Use clear section headings (## for sections, ### for subsections) - Write in paragraph form by default - be text-heavy, not just bullet points - Do NOT use self-referential language ("I found...", "I researched...") - Write as a professional report without meta-commentary - Each section should be comprehensive and detailed - Use bullet points only when listing is more appropriate than prose **Citation format:** - Cite sources inline using [1], [2], [3] format - Assign each unique URL a single citation number across ALL sub-agent findings - End report with ### Sources section listing each numbered source - Number sources sequentially without gaps (1,2,3,4...) - Format: [1] Source Title: URL (each on separate line for proper list rendering) - Example: Some important finding [1]. Another key insight [2]. ### Sources [1] AI Research Paper: https://example.com/paper [2] Industry Analysis: https://example.com/analysis """ ``` ```python expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} RESEARCHER_INSTRUCTIONS = """You are a research assistant conducting research on the user's input topic. For context, today's date is {date}. Your job is to use tools to gather information about the user's input topic. You can use the tavily_search tool to find resources that can help answer the research question. You can call it in series or in parallel, your research is conducted in a tool-calling loop. You have access to the tavily_search tool for conducting web searches. Think like a human researcher with limited time. Follow these steps: 1. **Read the question carefully** - What specific information does the user need? 2. **Start with broader searches** - Use broad, comprehensive queries first 3. **After each search, pause and assess** - Do I have enough to answer? What's still missing? 4. **Execute narrower searches as you gather information** - Fill in the gaps 5. **Stop when you can answer confidently** - Don't keep searching for perfection **Tool Call Budgets** (Prevent excessive searching): - **Simple queries**: Use 2-3 search tool calls maximum - **Complex queries**: Use up to 5 search tool calls maximum - **Always stop**: After 5 search tool calls if you cannot find the right sources **Stop Immediately When**: - You can answer the user's question comprehensively - You have 3+ relevant examples/sources for the question - Your last 2 searches returned similar information After each search, assess results before continuing: What key information did I find? What's missing? Do I have enough to answer? Should I search more or provide my answer? When providing your findings back to the orchestrator: 1. **Structure your response**: Organize findings with clear headings and detailed explanations 2. **Cite sources inline**: Use [1], [2], [3] format when referencing information from your searches 3. **Include Sources section**: End with ### Sources listing each numbered source with title and URL Example: ## Key Findings Context engineering is a critical technique for AI agents [1]. Studies show that proper context management can improve performance by 40% [2]. ### Sources [1] Context Engineering Guide: https://example.com/context-guide [2] AI Performance Study: https://example.com/study The orchestrator will consolidate citations from all sub-agents into the final report. """ ``` ```python expandable wrap theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} SUBAGENT_DELEGATION_INSTRUCTIONS = """# Sub-Agent Research Coordination Your role is to coordinate research by delegating tasks from your TODO list to specialized research sub-agents. ## Delegation Strategy **DEFAULT: Start with 1 sub-agent** for most queries: - "What is quantum computing?" -> 1 sub-agent (general overview) - "List the top 10 coffee shops in San Francisco" -> 1 sub-agent - "Summarize the history of the internet" -> 1 sub-agent - "Research context engineering for AI agents" -> 1 sub-agent (covers all aspects) **ONLY parallelize when the query EXPLICITLY requires comparison or has clearly independent aspects:** **Explicit comparisons** -> 1 sub-agent per element: - "Compare OpenAI vs Anthropic vs DeepMind AI safety approaches" -> 3 parallel sub-agents - "Compare Python vs JavaScript for web development" -> 2 parallel sub-agents **Clearly separated aspects** -> 1 sub-agent per aspect (use sparingly): - "Research renewable energy adoption in Europe, Asia, and North America" -> 3 parallel sub-agents (geographic separation) - Only use this pattern when aspects cannot be covered efficiently by a single comprehensive search ## Key Principles - **Bias towards single sub-agent**: One comprehensive research task is more token-efficient than multiple narrow ones - **Avoid premature decomposition**: Don't break "research X" into "research X overview", "research X techniques", "research X applications" - just use 1 sub-agent for all of X - **Parallelize only for clear comparisons**: Use multiple sub-agents when comparing distinct entities or geographically separated data ## Parallel Execution Limits - Use at most {max_concurrent_research_units} parallel sub-agents per iteration - Make multiple task() calls in a single response to enable parallel execution - Each sub-agent returns findings independently ## Research Limits - Stop after {max_researcher_iterations} delegation rounds if you haven't found adequate sources - Stop when you have sufficient information to answer comprehensively - Bias towards focused research over exhaustive exploration""" ``` 将模型初始化和智能体创建添加到 `agent.py`。选择你的提供商： ```python Google theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="google_genai:gemini-3.1-pro-preview", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python OpenAI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="openai:gpt-5.4", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python Anthropic theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="anthropic:claude-sonnet-4-6", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python OpenRouter theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="openrouter:anthropic/claude-sonnet-4-6", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python Fireworks theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="fireworks:accounts/fireworks/models/qwen3p5-397b-a17b", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python Baseten theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="baseten:zai-org/GLM-5", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python Ollama theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from deepagents import create_deep_agent from langchain.chat_models import init_chat_model max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = init_chat_model(model="ollama:devstral-2", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from datetime import datetime from langchain_google_genai import ChatGoogleGenerativeAI from deepagents import create_deep_agent max_concurrent_research_units = 3 max_researcher_iterations = 3 current_date = datetime.now().strftime("%Y-%m-%d") INSTRUCTIONS = ( RESEARCH_WORKFLOW_INSTRUCTIONS + "\n\n" + "=" * 80 + "\n\n" + SUBAGENT_DELEGATION_INSTRUCTIONS.format( max_concurrent_research_units=max_concurrent_research_units, max_researcher_iterations=max_researcher_iterations, ) ) research_sub_agent = { "name": "research-agent", "description": "Delegate research to the sub-agent. Give one topic at a time.", "system_prompt": RESEARCHER_INSTRUCTIONS.format(date=current_date), "tools": [tavily_search], } model = ChatGoogleGenerativeAI(model="gemini-3-pro-preview", temperature=0.0) agent = create_deep_agent( model=model, tools=[tavily_search], system_prompt=INSTRUCTIONS, subagents=[research_sub_agent], ) ``` ## 运行智能体 你可以同步运行智能体（即等待完整结果然后打印），也可以在更新到来时进行流式输出。 将相应标签页中的代码添加到 `agent.py` 底部： ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.messages import HumanMessage if __name__ == "__main__": result = agent.invoke( { "messages": [ HumanMessage( content="What are the main differences between RAG and fine-tuning for LLM applications?" ) ] } ) for msg in result.get("messages", []): if hasattr(msg, "content") and msg.content: print(msg.content) ``` ```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} from langchain.messages import HumanMessage from langgraph.types import Overwrite if __name__ == "__main__": for chunk in agent.stream( { "messages": [ HumanMessage(content="Compare Python vs JavaScript for web development") ] }, stream_mode="updates", ): for node, update in chunk.items(): if not update or not (messages := update.get("messages")): continue msg_list = messages.value if isinstance(messages, Overwrite) else messages for msg in msg_list: if hasattr(msg, "content") and msg.content: print(msg.content) ``` 从项目根目录运行智能体： ```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}} python agent.py ``` 如果你在运行前设置了 `LANGSMITH_API_KEY` 环境变量，可以在 [LangSmith](/langsmith/home) 中查看智能体的追踪信息，以调试和监控多步骤行为。 ## 完整代码 在 GitHub 上查看完整的[深度研究示例](https://github.com/langchain-ai/deepagents/tree/main/examples/deep_research)。 ## 下一步 现在你已经构建了智能体，可以通过更改智能体文件中的提示词常量来自定义它，以调整工作流程、委派策略或研究者行为。 你还可以调整委派限制以允许更多的并行子智能体或委派轮次。 有关本教程中概念的更多信息，请查看以下资源： * [子智能体](/oss/python/deepagents/subagents)：了解如何使用不同的工具和提示词配置子智能体 * [自定义](/oss/python/deepagents/customization)：自定义模型、工具、系统提示词和规划行为 * [LangSmith](/langsmith/home)：追踪研究运行并调试多步骤行为 * [深度研究课程](https://academy.langchain.com/courses/deep-research-with-langgraph)：使用 LangGraph 进行深度研究的完整课程 ***
[连接这些文档](/use-these-docs)到 Claude、VSCode 等工具，通过 MCP 获取实时答案。 [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/deep-research.mdx)或[提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。