当前位置：首页 > ai >正文

Deep Agents：用于复杂任务自动化的 AI 代理框架

ai 2025/8/14 6:44:56

前言

说起AI智能体，大家可能都不陌生。用大语言模型调用工具，让它循环执行任务，这是最简单的智能体架构。但是问题来了，这种简单的架构往往很"浅"，碰到复杂的、需要长期规划的任务就歇菜了。

不过最近有几个厉害的应用，比如"Deep Research"、“Manus”，还有"Claude Code"，它们都成功突破了这个限制。怎么做到的？答案是组合拳：规划工具、子智能体、文件系统，还有详细的提示词。

今天要介绍的deepagents就是把这套组合拳封装成了一个通用的Python包，让大家也能轻松搭建自己的"深度智能体"。

说句实话，这个项目主要受到Claude Code的启发。一开始就是想搞明白Claude Code为什么这么通用，然后把它做得更通用一些。

快速上手

安装

pip install deepagents

来个例子

先来看看怎么创建一个研究型智能体（记得先装pip install tavily-python）：

import os
from typing import Literalfrom tavily import TavilyClient
from deepagents import create_deep_agenttavily_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,)# 给智能体设定角色和能力
research_instructions = """你是一个专业的研究员。你的任务是进行深入调研，然后写出高质量的研究报告。你可以使用以下工具：## `internet_search`用这个工具可以针对特定查询进行网络搜索。你可以指定结果数量、主题类型，以及是否包含原始内容。
"""# 创建智能体
agent = create_deep_agent([internet_search],research_instructions,
)# 开始使用
result = agent.invoke({"messages": [{"role": "user", "content": "langgraph是什么？"}]})

是不是很简单？这里创建的智能体其实就是一个LangGraph图，所以你可以像操作其他LangGraph智能体一样使用它（支持流式输出、人机交互、记忆功能、可视化调试等）。

深度定制你的智能体

create_deep_agent函数有三个核心参数，让你可以打造专属的深度智能体。

工具集（必填）

第一个参数是tools，传入一个工具列表。可以是普通函数，也可以是LangChain的@tool装饰器对象。主智能体和所有子智能体都能使用这些工具。

指令（必填）

第二个参数是instructions，这会成为智能体提示词的一部分。不过别担心，框架本身已经内置了一套系统提示词，你的指令会和它组合使用。

子智能体（可选）

通过subagents关键字参数，你可以定义自定义的子智能体。为什么需要子智能体？下面会详细说明。

subagents是一个字典列表，每个字典要包含：

class SubAgent(TypedDict):name: str          # 子智能体的名称description: str   # 描述信息，主智能体会看到prompt: str        # 子智能体专用的提示词tools: NotRequired[list[str]]  # 可用的工具列表

使用例子：

research_sub_agent = {"name": "research-agent","description": "专门用来深度研究复杂问题","prompt": sub_research_prompt,
}
subagents = [research_sub_agent]
agent = create_deep_agent(tools,prompt,subagents=subagents
)

自定义模型（可选）

默认情况下，deepagents使用的是"claude-sonnet-4-20250514"。你也可以传入任何LangChain支持的模型。

比如想用Ollama的模型：

from deepagents import create_deep_agent# 需要先安装：pip install langchain langchain-ollamamodel = init_chat_model(model="ollama:gpt-oss:20b",  
)
agent = create_deep_agent(tools=tools,instructions=instructions,model=model,
)

深度智能体的核心组件

下面这些组件是deepagents内置的，正是它们让智能体能够处理复杂任务。

系统提示词

框架内置了一套详细的系统提示词。这套提示词主要参考了一些尝试复制Claude Code系统提示词的工作，但做得更通用一些。

这套提示词详细说明了如何使用内置的规划工具、文件系统工具和子智能体。没有这套提示词，智能体根本不可能有现在这么好的表现。好的提示词对于创建"深度"智能体来说，重要性怎么强调都不过分。

规划工具

内置了一个简单但有效的规划工具，灵感来自Claude Code的TodoWrite工具。这个工具本身不执行任何操作，它的作用是让智能体制定计划，然后把计划保留在上下文中，帮助智能体保持正确的执行轨迹。

文件系统工具

提供了四个内置的文件系统工具：ls、edit_file、read_file、write_file。

这些工具不是真的在操作文件系统，而是通过LangGraph的State对象模拟的。这意味着你可以在同一台机器上运行多个智能体，不用担心它们会互相干扰。

目前的"文件系统"只支持一级目录（没有子目录）。

你可以通过LangGraph状态对象的files键来传入和获取文件：

agent = create_deep_agent(...)result = agent.invoke({"messages": ...,# 通过这个键传入文件# "files": {"foo.txt": "foo", ...}
})# 处理完后获取文件
result["files"]

子智能体

框架内置了子智能体调用能力（同样基于Claude Code的设计）。

默认情况下，每个智能体都有一个general-purpose子智能体，它使用和主智能体相同的指令和工具。你也可以定义自定义子智能体，给它们专门的指令和工具。

子智能体的好处主要有两个：

上下文隔离：避免污染主智能体的上下文
专门指令：针对特定任务使用专门的提示词

配合MCP使用

deepagents还可以和MCP工具配合使用，通过Langchain MCP Adapter库实现。

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from deepagents import create_deep_agentasync def main():# 获取MCP工具mcp_client = MultiServerMCPClient(...)mcp_tools = await mcp_client.get_tools()# 创建智能体agent = create_deep_agent(tools=mcp_tools, ...)# 流式执行async for chunk in agent.astream({"messages": [{"role": "user", "content": "langgraph是什么？"}]},stream_mode="values"):if "messages" in chunk:chunk["messages"][-1].pretty_print()asyncio.run(main())