第一部分：DeepAgent 极简入门

从最少的代码开始，逐步理解 DeepAgent 的核心概念。

在开始使用 DeepAgent 之前，需要配置运行环境。本框架依赖 uv（Python 包管理器）和 Node.js（MCP 服务运行器）。

安装 Node.js 和 uv

系统	安装命令
Windows	`powershell -ExecutionPolicy Bypass -c "irm https://gitee.com/wangnov/uv-custom/releases/download/0.10.2/uv-installer-custom.ps1 \| iex"`
macOS	`curl -LsSf https://gitee.com/wangnov/uv-custom/releases/download/0.10.2/uv-installer-custom.sh \| sh`
Linux	`curl -LsSf https://gitee.com/wangnov/uv-custom/releases/download/0.10.2/uv-installer-custom.sh \| sh`

以上为国内镜像版，规避网络问题

验证安装：

# 检查 uv 版本
uv --version

# 检查 node 版本
node --version

配置 LLM 凭证

在项目根目录创建 .env 文件，配置 LLM API 凭证：

# LLM 配置（必需）
IMAGE_MODEL="qwen-image-plus"  # 图像生成模型名称
QWEN_MODEL="qwen-plus" # 语言模型名称
QWEN_API="你的API密钥" # 需要在阿里百炼大模型平台注册免费领取额度
QWEN_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
BOCHA_API_KEY="你的Bocha搜索API密钥" # 需要在https://open.bochaai.com/ 注册免费领取额度

安装 Python 依赖

# 在项目目录内运行安装项目依赖
uv sync

1.1 构建 DeepAgent并添加Tool

Tool 是 Agent 的"手"，让它能够执行具体操作：

点击展开：完整代码示例

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent
from langchain.tools import tool
from dotenv import load_dotenv
import os

load_dotenv()

QWEN_MODEL = os.getenv("QWEN_MODEL")
QWEN_API = os.getenv("QWEN_API")
QWEN_URL = os.getenv("QWEN_URL")

# 1. 定义工具（模拟查询公司信息）
@tool
def get_company_profile(company_name: str) -> str:
    """获取公司基础信息（名称、成立时间、创始人、核心业务等）"""
    # 实际项目中，这里会调用数据库或 API
    return f"{company_name}成立于2019年，是一家专注于人工智能技术的创新公司..."

# 2. 创建模型
model = ChatOpenAI(
    model=QWEN_MODEL,
    api_key=QWEN_API,
    base_url=QWEN_URL,
    temperature=0,
)

# 3. 创建 Agent
agent = create_deep_agent(
    model=model,
    tools=[get_company_profile]  # ← 添加工具
)

# 4. 调用 Agent（Agent 会自动调用 tool）
result = agent.invoke({"messages": [("user", "请查询深空智能公司的信息")]})
print(result["messages"][-1].content)

1.2 添加 backend 和 store

为什么需要 backend 和 store？

组件	作用	类比
`backend`	提供文件操作能力，Skill 通过它读取 `skills/` 目录	像"文件系统"，让 Agent 能读取 Skill 文件
`store`	提供记忆，让 Agent 能够记住和学习 Skill	像"大脑"，存储 Skill 知识

如果要使用 Skill，必须配置 backend 和 store！

点击展开：完整代码示例

# 重新创建 Agent，添加 backend 和 store
from deepagents.backends import CompositeBackend, FilesystemBackend
from langgraph.store.memory import InMemoryStore
from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent
from langchain.tools import tool

from pathlib import Path
from dotenv import load_dotenv , find_dotenv
import os


load_dotenv()

QWEN_MODEL = os.getenv("QWEN_MODEL")
QWEN_API = os.getenv("QWEN_API")
QWEN_URL = os.getenv("QWEN_URL")

# 定义项目路径
root = Path(find_dotenv()).parent
print(" 项目根目录是："+str(root))

MEMORY_DIR = (root / "memories").as_posix()
SKILLS_DIR = (root / "skills").as_posix()
WORKSPACE_DIR = (root / "workspaces").as_posix()

USER_PREFER_DIR= "/memory/user_preferences.md"

print(" Memory 目录是："+MEMORY_DIR)
print(" Skill 目录是："+SKILLS_DIR)
print(" Workspace 目录是："+WORKSPACE_DIR)
print(" 用户偏好保存在："+USER_PREFER_DIR)


# 1. 定义工具
@tool
def get_company_profile(company_name: str) -> str:
    """获取公司基础信息"""
    return f"{company_name}成立于2019年，是一家专注于AI技术的创新公司..."

# 2. 创建模型
model = ChatOpenAI(
    model=QWEN_MODEL,
    api_key=QWEN_API,
    base_url=QWEN_URL,
    temperature=0,
)

# 3. 创建复合 Backend（支持多目录）
composite_backend = CompositeBackend(
    default=FilesystemBackend(root_dir=root, virtual_mode=True),
    routes={
        "/memories/": FilesystemBackend(root_dir=MEMORY_DIR, virtual_mode=True),
        "/skills/": FilesystemBackend(root_dir=SKILLS_DIR, virtual_mode=True),
        "/workplace/": FilesystemBackend(root_dir=WORKSPACE_DIR, virtual_mode=True)
    },
)
store = InMemoryStore()

# 4. 创建 Agent
agent = create_deep_agent(
    model=model,
    tools=[get_company_profile],
    memory=["/memory/user_preferences.md"],
    backend=composite_backend,
    store=store,
)

# 普通输出方法（非实时更新）
# result = agent.invoke({"messages": [("user", "请问你之前的memory中用户有什么偏好")]})
# print(result["messages"][-1].content)


#流式输出方法（实时更新）
inputs = {"messages": [("user", "请问你之前的memory中用户有什么偏好")]}

for msg, metadata in agent.stream(inputs, stream_mode="messages"):
    if msg.content and not isinstance(msg.content, list):
        print(msg.content, end="", flush=True)

与 FunctionCall 的区别：在 DeepAgent 中，工具的注册和使用方式更自动化，Agent 会自动决定何时调用工具。

1.3 添加 Skill

Skill 是 Agent 的"大脑"，告诉它遇到某类任务该怎么做。

Skill vs Tool：

Tool：做具体操作（查询公司信息、写入文件）

Skill：提供操作指南（"当需要分析公司时，按以下步骤..."）

Skill 的结构：

一个完整的 Skill 由以下部分组成：

必需文件：SKILL.md —— 告诉 Agent 遇到这类任务该怎么做
可选目录：references/ —— 存放参考资料，如使用指南、模板文档等

创建 Skill 目录：

mkdir -p skills/analyze-company/references
touch skills/analyze-company/SKILL.md

SKILL.md 示例：

---
name: analyze-company
description: 分析公司的基础信息。当用户需要了解某家公司时使用。
---

# 公司分析技能

当需要分析公司时，请按以下步骤进行：

1. 使用 `get_company_profile` 工具获取公司信息
2. 分析公司业务和发展状况
3. 给出总结建议

创建带 Skill 的 Agent：

点击展开：完整代码示例

from deepagents.backends import CompositeBackend, FilesystemBackend
from langgraph.store.memory import InMemoryStore
from pathlib import Path
from dotenv import load_dotenv , find_dotenv

from pathlib import Path
import os
from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent
from langchain.tools import tool

load_dotenv()

QWEN_MODEL = os.getenv("QWEN_MODEL")
QWEN_API = os.getenv("QWEN_API")
QWEN_URL = os.getenv("QWEN_URL")

# 0. 定义项目路径
root = Path(find_dotenv()).parent
print(" 项目根目录是："+str(root))

MEMORY_DIR = (root / "memories").as_posix()
SKILLS_DIR = (root / "skills").as_posix()
WORKSPACE_DIR = (root / "workspaces").as_posix()

USER_PREFER_DIR= "/memory/user_preferences.md"

print(" Memory 目录是："+MEMORY_DIR)
print(" Skill 目录是："+SKILLS_DIR)
print(" Workspace 目录是："+WORKSPACE_DIR)
print(" 用户偏好保存在："+USER_PREFER_DIR)


# 1. 定义工具
@tool
def get_company_profile(company_name: str) -> str:
    """获取公司基础信息"""
    return f"{company_name}成立于2019年，是一家专注于AI技术的创新公司..."

# 2. 创建模型
model = ChatOpenAI(
    model=QWEN_MODEL,
    api_key=QWEN_API,
    base_url=QWEN_URL,
    temperature=0,
)

# 3. 创建复合 Backend（支持多目录）
composite_backend = CompositeBackend(
    default=FilesystemBackend(root_dir=root, virtual_mode=True),
    routes={
        "/memories/": FilesystemBackend(root_dir=MEMORY_DIR, virtual_mode=True),
        "/skills/": FilesystemBackend(root_dir=SKILLS_DIR, virtual_mode=True),
        "/workplace/": FilesystemBackend(root_dir=WORKSPACE_DIR, virtual_mode=True)
    },
)
store = InMemoryStore()

# 4. 创建 Agent（传入 Skill 文件路径）
agent = create_deep_agent(
    model=model,
    tools=[get_company_profile],
    skills=["/skills/analyze-company/SKILL.md"],  # ← Skill 文件路径
    memory=["/memories/user_preferences.md"],
    backend=composite_backend,
    store=store,
)

# 5. 调用 Agent
inputs = {"messages": [("user", "请读取一下你的analyze-company的SKILL")]}

for msg, metadata in agent.stream(inputs, stream_mode="messages"):
    if msg.content and not isinstance(msg.content, list):
        print(msg.content, end="", flush=True)

1.4 添加 SubAgent

SubAgent 是专业化的子代理，处理特定任务：

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent
from dotenv import load_dotenv
import os

load_dotenv()

QWEN_MODEL = os.getenv("QWEN_MODEL")
QWEN_API = os.getenv("QWEN_API")
QWEN_URL = os.getenv("QWEN_URL")

# 创建模型
model = ChatOpenAI(
    model=QWEN_MODEL,
    api_key=QWEN_API,
    base_url=QWEN_URL,
    temperature=0,
)

# 1. 创建子 Agent（专业写手）
writer_agent = {
    "model": model,
    "name": "writer-agent",
    "description": "用于撰写文字",
    "system_prompt": "你是一个专业作家，负责根据材料撰写报告"
}

# 2. 创建主 Agent（包含子 Agent）
agent = create_deep_agent(
    model=model,
    subagents=[writer_agent],  # ← 传入子 Agent 列表
)

# 3. 调用 Agent（会自动分派任务给子 Agent）
result = agent.invoke({"messages": [("user", "直接回答我，不要调用任何工具,你有什么subagent？")]})
print(result["messages"][-1].content)

SubAgent 的优势：

专业化：每个 SubAgent 专注特定领域
隔离性：复杂任务不会污染主 Agent 的上下文
可复用：SubAgent 可以被多次调用

1.1 构建 DeepAgent并添加Tool​

1.2 添加 backend 和 store​

1.3 添加 Skill​

1.4 添加 SubAgent​

1.1 构建 DeepAgent并添加Tool

1.2 添加 backend 和 store

1.3 添加 Skill

1.4 添加 SubAgent