跳到主要内容

快速开始指南

环境要求​

前置条件​

  • Python 3.8+
  • 一个支持工具调用的 LLM API 密钥（例如 Anthropic、OpenAI 等）
  • 基本的 Python 编程知识

模型选择​

DeepAgents 支持任何具备工具调用能力的模型。建议在实际项目中使用最新的模型以获得最佳性能：

  • Anthropic: Claude 3.5 Sonnet 或更新版本
  • OpenAI: GPT-4 或更新版本
  • Google: Gemini 系列
  • 其他支持工具调用的开源模型

安装步骤​

方式一：使用 pip（推荐）​

pip install deepagents

方式二：使用 uv（更快）​

uv init
uv add deepagents
uv sync

可选依赖​

根据你的使用场景，可能需要安装额外的依赖：

# 网络搜索支持
pip install deepagents tavily-python

# 深度研究支持
pip install deepagents arxiv

# 沙盒执行支持
pip install deepagents e2b-code-interpreter

配置 API 密钥​

所有 LLM 提供商都要求你设置 API 密钥作为环境变量。

使用 .env 文件​

在项目根目录创建 .env 文件：

ANTHROPIC_API_KEY="your-anthropic-key"
TAVILY_API_KEY="your-tavily-key"

然后在 Python 代码中加载：

from dotenv import load_dotenv
load_dotenv()

直接设置环境变量​

export ANTHROPIC_API_KEY="your-anthropic-key"
export TAVILY_API_KEY="your-tavily-key"

你的第一个 Agent​

最简单的例子​

创建一个文件 simple_agent.py：

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """获取指定城市的天气预报。"""
    return f"{city}的天气是晴天！"

agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="你是一个友好的天气助手。",
)

# 运行代理
result = agent.invoke(
    {"messages": [{"role": "user", "content": "北京的天气怎么样？"}]}
)

# 输出结果
print(result["messages"][-1].content)

运行代码：

python simple_agent.py

代码说明​

  1. 导入框架：导入 create_deep_agent 函数
  2. 定义工具：创建一个带有文档字符串的普通 Python 函数
    • 函数名自动成为工具名
    • 文档字符串用作工具描述
    • 类型注解用于参数验证
  3. 创建代理：通过 create_deep_agent() 创建代理实例
    • 传入可用工具列表
    • 设置系统提示词
  4. 执行代理：调用 invoke() 方法，传入完整的消息历史
  5. 处理结果：从返回的字典中提取最后一条消息

一个更实用的例子：研究代理​

创建一个 research_agent.py，演示文件系统和搜索能力：

import os
from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def search_web(query: str) -> str:
    """在互联网上搜索信息。"""
    response = tavily_client.search(query=query, max_results=5)
    results = response.get("results", [])
    formatted = "\n".join([f"- {r['title']}: {r['content']}" for r in results])
    return formatted or "未找到相关信息"

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[search_web],
    system_prompt="""你是一个研究助手。
    
你的职责是：
1. 根据用户的查询进行网络搜索
2. 整理和总结搜索结果
3. 如果需要，进行多次搜索以获得全面的信息
4. 提供可信度高的信息"""
)

# 执行研究任务
result = agent.invoke(
    {"messages": [{"role": "user", "content": "请研究最新的 AI 发展趋势"}]}
)

print(result["messages"][-1].content)

工作流程理解​

代理执行流程​

用户输入
    ↓
代理接收消息
    ↓
LLM 分析并调用工具
    ↓
工具执行并返回结果
    ↓
LLM 进一步分析（如需要）
    ↓
重复上述过程直到完成任务
    ↓
返回最终响应

消息格式​

DeepAgents 使用标准的消息格式：

messages = [
    {"role": "user", "content": "用户的问题"},
    {"role": "assistant", "content": "代理的响应"},
    # ... 更多消息
]

调试和日志​

启用 LangSmith 追踪​

为了更好地理解代理的行为，建议启用 LangSmith 追踪：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-key"
export LANGSMITH_PROJECT="your-project-name"

这样所有的 API 调用、工具执行和中间结果都被记录，便于调试。

添加日志输出​

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# 现在所有 deepagents 的调试信息会被打印

常见错误排查​

错误：ModuleNotFoundError: No module named 'deepagents'​

原因：deepagents 未安装

解决：

pip install deepagents

错误：API 密钥认证失败​

原因：

  • 环境变量未正确设置
  • 密钥已过期或无效
  • 密钥对应的账户已禁用

解决：

  • 检查环境变量名称是否正确
  • 在提供商控制台验证密钥
  • 生成新的密钥

工具未被调用​

原因：

  • 工具文档字符串不清晰
  • 系统提示词未正确引导模型使用工具
  • 模型认为无需使用工具

解决：

  • 改进工具的文档字符串
  • 在系统提示词中明确指出何时使用工具
  • 更新为更新的模型版本

下一步​

现在你已经掌握了基础知识，接下来可以：

  1. 深入学习模型配置：支持的模型和提供商
  2. 定制工具和功能：工具与自定义
  3. 使用子代理：子代理系统
  4. 集成技能系统：技能与扩展

完整示例项目模板​

my-deepagents-project/
├── .env                    # API 密钥配置
├── .env.example           # 密钥模板
├── requirements.txt       # 依赖列表
├── agent.py              # 主要代理逻辑
├── tools/                # 自定义工具目录
│   ├── __init__.py
│   ├── search.py        # 搜索工具
│   └── data.py          # 数据工具
├── skills/               # 技能库
│   └── research/
│       └── SKILL.md
└── README.md            # 项目文档

资源链接​