DeepAgents 实战开发

一、项目概述与目标

🎯 项目定义

Deep Agents 是一个构建在 LangChain 及其 LangGraph 运行时 之上的高级智能体（Agent）框架。它并非 LangChain 的替代品，而是一个提供“开箱即用”能力的独立库，旨在简化复杂、多步骤智能体应用的开发。其核心设计是一个 “智能体套具（agent harness）”，通过预置的模块化组件、中间件和可插拔的后端系统，将开发者的重心从基础架构搭建转移到业务逻辑实现。

✨ 核心价值与设计理念

Deep Agents 的诞生是为了应对传统智能体开发中的常见挑战：

• 复杂性管理：擅长将庞杂、开放式任务（如“开发一个Web应用”、“撰写一篇研究报告”）自动分解为可执行的子步骤，并有序推进。
• 上下文过载：通过虚拟文件系统工具和灵活的后端，智能地将大量中间结果（如代码片段、研究数据）卸载到“外部存储”，有效避免大语言模型（LLM）上下文窗口的溢出。
• 安全与可控性：强调安全性第一，内置对人类在回路（Human-in-the-loop）审批的支持，并强烈建议在生产环境中使用沙箱后端来隔离代码执行，避免对主机系统造成风险。
• 持久化与记忆：支持配置跨会话的长期记忆，允许智能体记住用户偏好、项目知识，并在不同对话线程中保持状态连续性。

🧭 项目目标

本实战教程的核心目标是，引导开发者从零开始，掌握使用 Deep Agents 构建、配置和部署一个功能完整、安全可靠的智能体应用。具体而言，我们将实现以下目标：

1. 掌握核心架构：理解 Deep Agents 以可插拔文件系统后端和模块化中间件为基石的设计思想，熟悉其 SDK 与 CLI 两大使用界面。
2. 成功构建多功能智能体：能够创建一个具备任务规划与分解、上下文管理、子代理协同以及长期记忆等核心能力的智能体。
3. 实现安全部署：学会为生产环境正确配置沙箱后端（如 Modal、Runloop），并理解如何通过 CompositeBackend 实现数据的临时存储与持久化分离。
4. 应用于典型开发场景：能够将 Deep Agents 应用于实际开发任务，例如：
   • 数据分析代理：自动处理数据文件、进行分析、可视化并分享结果。
   • 研究协调系统：创建主代理与多个专业化子代理（如研究员、撰稿人）协同工作的流水线。
   • 编码助手：集成 ACP (Agent Client Protocol) 在开发环境中提供交互式帮助，或通过 CLI 执行项目指令。
5. 建立调试与运维能力：掌握使用 LangSmith 进行全链路追踪，利用流式输出实时观察智能体工作流，并确保应用的可观测性与稳定性。

总之，本教程旨在将 Deep Agents 从一个概念框架，转化为开发者手中能够安全、高效地解决现实世界复杂问题的实践工具。

二、核心架构与组件解析

Deep Agents 的核心架构可以理解为一个构建于 LangGraph 运行时之上的“智能体套具（Agent Harness）”。它并非 LangChain 的替代品，而是基于其基础构建块，通过一系列开箱即用的组件和抽象，极大地简化了构建、运行和管理复杂智能体的过程。

其架构设计围绕两大基石和两大界面展开：

• 基石：模块化中间件、可插拔的文件系统后端。
• 界面：Deep Agents SDK（用于编程构建）和 CLI（用于命令行交互）。

本章将深入解析这些核心组件，揭示它们如何协同工作，以实现上一章概述的各项关键能力。

2.1 Deep Agents SDK：核心组件详解

SDK 是构建智能体应用的核心库，create_deep_agent 是主要的工厂函数。其实质是通过组合以下高度模块化的组件来创建功能强大的智能体。

核心组件	关键能力 (对应“概述”章节)	核心作用与实现
模型	- 任务规划与分解 - 子代理协同	默认模型 为 claude-sonnet-4-5-20250929。 支持通过 model 参数灵活切换任何兼容的模型标识符（如openai:gpt-5）或 LangChain 模型对象，为任务选择合适的推理引擎。
系统提示	- 任务规划与执行	通过 system_prompt 参数定义智能体的身份、任务范围和核心行为准则。清晰、具体的提示是驱动智能体正确工作的“指挥棒”。
工具	三大类内置工具直接实现核心能力	支持集成自定义工具，且本身提供了强大的内置工具箱： • 🛠️ 规划工具 (write_todos等)：实现任务分解与追踪。 • 💾 文件系统工具 (ls, read_file**,** write_file**,** edit_file**,** glob**,** grep**)**：实现上下文卸载与管理。 • ➡️ 子代理生成工具 (task)：实现模块化任务委托与子代理协同。
中间件	- 任务规划与分解 - 上下文管理 - 子代理协同	模块化的处理管道，用于管理智能体执行的工作流。默认包含： • TodoListMiddleware: 管理待办列表，实现任务规划。 • FilesystemMiddleware: 处理所有文件系统工具调用，是上下文管理核心。 • SubAgentMiddleware: 协调子代理的创建和调用，实现协同。 • SummarizationMiddleware: 总结历史消息以控制上下文长度。 此外，开发者可以添加自定义中间件以扩展功能。
子代理	- 子代理协同 - 上下文隔离	通过 subagents 参数，主智能体内部可创建具有特定角色、系统提示和工具集的专门子代理。这实现了： • 上下文隔离：主代理专注于高层协调，不受子任务中间细节干扰。 • 任务委派：支持嵌套结构，可构建复杂的工作流。
后端	实现上下文管理和安全隔离的基石	提供可插拔的文件系统后端，处理所有文件系统工具操作。智能体操作的“虚拟文件系统”环境完全由后端定义。 可选的StateBackend（默认）：数据存储在 LangGraph agent state 中，仅在线程内持久，作为“临时草稿纸”使用。 可选的****StoreBackend：将数据持久化到 LangGraph BaseStore（如 Redis、Postgres），实现跨线程持久存储，是长期记忆的基础。 CompositeBackend**（混合路由）：允许将不同虚拟路径路由到不同后端，例如，默认路径 (/) 使用 StateBackend 存储中间结果，而 /memories/ 路径使用 StoreBackend 实现持久化记忆。 沙箱后端：为 execute 工具和文件系统提供安全的隔离执行环境（支持 Modal、Runloop、Daytona 等），是实现安全隔离**的关键。
长期记忆	- 长期记忆（跨会话持久化）	主要通过文件系统实现。 • 持久化策略：通过 CompositeBackend 将特定路径（如 /memories/）路由到 StoreBackend，信息即可在跨线程对话中持久保存，用于存储用户偏好、项目知识等。 • 启动预加载：通过 memory 参数，智能体可以在启动时自动加载指定路径（如一个 AGENTS.md 文件）的内容作为上下文，提供静态指导信息。
人机交互	- 安全隔离（Human-in-the-loop 审批）	通过配置 interrupt_on 等参数，可以在执行特定敏感工具调用（如文件写入、命令执行）前暂停，等待人工审批（Approve）、编辑或拒绝。这是提升生产环境安全控制的核心机制。
技能	-	通过 skills 参数，可以加载封装了特定任务流程、工具和提示的自定义技能（Skill），这些技能可按需激活。

2.2 Deep Agents CLI：终端交互界面

Deep Agents CLI 是一个基于上述 SDK 构建的开源命令行工具，专门用于终端交互式任务，尤其是编码场景。它并非一个独立的架构，而是 SDK 能力的终端封装与便捷入口。

• 技术根基：CLI 完全继承并利用了 SDK 的所有核心架构组件，如相同的后端、记忆、技能和文件操作能力。
• 核心价值：为非开发者或快速原型验证提供了一个“零代码”开箱即用的交互界面。用户通过简单的命令行对话，即可驱动一个具备复杂规划、工具调用和记忆能力的智能体。
• 补充能力：CLI 本身围绕终端交互增加了配置文件管理 (~/.deepagents/)、管道操作 (-q 参数) 等便利功能，但其底层的执行引擎、上下文管理和安全模型均与 SDK 保持一致。

总结而言，Deep Agents 的核心架构是一个以“文件系统后端”和“模块化中间件”为基石、围绕“LangGraph 运行时”构建的执行容器。开发者通过 SDK 编程，自由组合模型、工具、子代理、后端等“积木”来定制复杂的智能体应用；而终端用户则通过 CLI，直接获得一个具备了所有底层强大能力的交互助手。 正是这种清晰的分层设计，使得它能优雅地支撑从数据分析代理、研究协调系统到编码助手等各种典型场景。

三、开发环境搭建

成功使用 Deep Agents 进行开发的首要步骤是正确配置一个“装上就能跑”的本地或云端环境。本章将为您提供一份清晰、逐步的操作指南，涵盖从核心依赖安装到环境验证的完整流程。

1. 环境准备概要

开始前，请确保您已准备好以下基础组件：

• Python 3.9+ 运行环境：这是运行 Deep Agents CLI 和 SDK 的唯一必需前提。
• 模型供应商 API 密钥：例如 ANTHROPIC_API_KEY（默认模型 claude-sonnet-4-5-20250929）或 OPENAI_API_KEY。
• 网络访问权限：用于连接所选模型 API 及可能的沙箱服务。

后续步骤将从“无”到“有”，逐步构建一个功能完整的 Deep Agents 开发与测试环境。

2. 核心第一步：安装 Python 环境与 Deep Agents 库

一切始于 Python 环境和核心库的安装。

# 1. 安装 deepagents 核心库及其基础依赖（包括 LangChain 与 LangGraph）
pip install deepagents

# 2. （可选）根据项目需要安装额外工具包
# 例如，若需集成搜索功能
pip install tavily-python
# 或，若需集成 Slack 通知
pip install slack-sdk

此命令会自动处理所有必需的底层运行时（如 LangChain、LangGraph）依赖。安装完毕后，可通过以下命令快速验证：

# 检查 SDK 包版本
python -c "import deepagents; print(deepagents.__version__)"  # 或您偏好的方式

# 验证 CLI 是否可调用（需单独安装 CLI，见后续步骤）

3. 核心第二步：配置密钥与后端环境变量

安装库后，必须通过环境变量配置智能体运行所需的关键凭证。

3.1 配置 LLM 运行密钥

智能体的“大脑”需要连接到大型语言模型服务。

# 使用 Anthropic Claude 模型（默认，推荐）
export ANTHROPIC_API_KEY="sk-ant-..."

# 或，使用 OpenAI 模型
export OPENAI_API_KEY="sk-..."

# 您也可以在 Python 代码中动态设置
import os
os.environ["ANTHROPIC_API_KEY"] = "your-api-key"

3.2 （生产环境强烈推荐）配置沙箱后端

为了智能体能安全地执行代码或文件操作，必须配置一个隔离的沙箱环境。切勿在生产或共享环境中跳过此步而使用本地非隔离环境。

# 根据您选择的沙箱提供商设置对应的密钥
# 例如使用 Runloop 沙箱
export RUNLOOP_API_KEY="your-runloop-key"

4. 核心第三步：准备可选运行时与后端服务

根据您计划使用的功能，可能还需准备以下持久化或可观测性服务。

4.1 配置持久化存储（用于长期记忆）

若需实现跨会话的长期记忆（如存储用户偏好、项目知识），需要配置一个 BaseStore 兼容的存储后端（开发阶段可选）。

4.2 （强烈推荐）配置 LangSmith 用于追踪与调试

LangSmith 能提供完整的执行链路追踪，是开发和调试智能体的利器。

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="your-langsmith-key"
# 可选：为 Deep Agents 的执行单独设立一个项目，便于追踪
export DEEPAGENTS_LANGSMITH_PROJECT="my-deep-agent-execution"

5. 开发环境验证：创建一个最小可运行的代理实例

环境配置完成后，应通过一个最简单的脚本验证一切工作正常。

# verification.py
import uuid
from langgraph.checkpoint.memory import MemorySaver
from deepagents import create_deep_agent

# 1. 创建一个检查点管理器（支持中断恢复等功能）
checkpointer = MemorySaver()

# 2. 使用最小配置创建一个 Deep Agent
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5", # 使用已配置的模型
    checkpointer=checkpointer,
)

# 3. 指定一个线程ID并尝试运行
thread_id = str(uuid.uuid4())
config = {"configurable": {"thread_id": thread_id}}

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "Hello, reply with 'Environment OK!'"}]},
        config=config
    )
    print("Agent Response:", result["messages"][-1].content)
    print("✅ 开发环境验证通过！")
except Exception as e:
    print("❌ 环境验证失败，错误信息:", e)

运行此脚本 python verification.py，若成功获得 Agent 的回复，则证明核心 SDK 环境、模型连接均正常。

6. CLI 工具的安装与快速启动（可选）

除了编程式 SDK，Deep Agents 也提供了便捷的命令行工具，适合快速交互与测试。

# 使用 uv 包管理器全局安装 CLI 工具（推荐）
uv tool install deepagents-cli
# 安装后，可以直接运行
deepagents

# 或者，不进行全局安装，使用 uvx 直接运行
uvx deepagents-cli

首次运行 CLI 时，它会自动读取 ~/.deepagents/ 下的配置，并继承您已设置的环境变量。您可以在 CLI 中直接与智能体对话，开始您的开发任务。

至此，一个具备核心功能、安全可用的 Deep Agents 开发环境已搭建完毕。您可以在此基础上，根据后续章节的指引，进行项目级配置、集成自定义工具或部署到生产环境。

四、项目级配置与实战示例

掌握了 Deep Agents 的核心架构，并完成开发环境搭建后，本章将专注于项目级的配置组合与实战代码示例。我们将从最简单的助手开始，逐步构建包含持久化记忆、安全沙箱、多代理协作和人工审批的复杂项目，展示如何将理论组件转化为实际应用。

4.1 基石：一个基础的世界查询助手

一切从 create_deep_agent 开始。即使不配置任何复杂的后端或中间件，你也能快速创建一个具备特定功能的助手。

场景：创建一个具备自定义查询工具（如天气查询）的简单对话代理。

# 前置：已安装 deepagents (pip install deepagents)
from deepagents import create_deep_agent

# 1. 定义一个自定义工具
def get_weather(city: str) -> str:
    """查询指定城市的天气"""
    # 这里可以是调用真实天气API的代码
    return f"It‘s always sunny in {city}!"

# 2. 配置并创建代理
agent = create_deep_agent(
    tools=[get_weather],  # 注入自定义工具
    system_prompt="你是一个有用的、能查询天气的助手。",
)

# 3. 运行代理
result = agent.invoke(
    {"messages": [{"role": "user", "content": "旧金山的天气怎么样？"}]}
)
print(result["messages"][-1].content)

这个最简单的示例揭示了 Deep Agents 项目的基本模式：定义工具 -> 配置代理 -> 执行任务。系统提示 (system_prompt) 定义了代理的角色，而 tools 参数赋予了它执行特定任务的能力。

4.2 核心配置：实现跨会话的长期记忆

对于真实项目，让代理记住过去的互动至关重要。这通过 CompositeBackend 结合 StoreBackend 实现。

场景：配置一个代理，使其能够将用户偏好和项目知识持久化存储，并在后续对话中调用。

from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
from langgraph.checkpoint.memory import MemorySaver

# 1. 创建复合后端：将 /memories/ 路径映射到持久化存储，其他路径使用临时存储
def make_backend(runtime):
    return CompositeBackend(
        default=StateBackend(runtime),           # 默认：线程内临时存储（如草稿）
        routes={"/memories/": StoreBackend(runtime)}  # 特定路径：持久化存储
    )

# 2. 创建代理，注入记忆使用指南
checkpointer = MemorySaver()
agent = create_deep_agent(
    store=InMemoryStore(),  # 开发环境使用内存存储；生产环境可省略（LangSmith部署自动提供）
    backend=make_backend,    # 使用复合后端
    checkpointer=checkpointer, # 必须配合checkpointer以实现状态恢复
    system_prompt="""你有一个文件 `/memories/instructions.txt`，里面包含了用户的额外指令和偏好。
    在每次对话开始时，记得用 `read_file` 工具先阅读它。
    当用户提供新的反馈或信息时，使用 `edit_file` 工具更新这个文件，以便未来记住。"""
)

# 3. 使用示例：跨两次“会话”记住信息
# 第一次交互，让代理保存信息
config_1 = {"configurable": {"thread_id": "project_notes_session_1"}}
agent.invoke(
    {"messages": [{"role": "user", "content": "我们正在使用React和TypeScript构建一个仪表板项目。请把这条笔记保存好。"}]},
    config=config_1
)

# 第二次交互（模拟未来某个时间），代理应能回忆起来
config_2 = {"configurable": {"thread_id": "project_notes_session_2"}}
result = agent.invoke(
    {"messages": [{"role": "user", "content": "我们当前项目用的是什么前端框架？"}]},
    config=config_2
)
# 代理会通过读取 /memories/instructions.txt 来回答

🔑 关键点：

• 路由机制：CompositeBackend 允许你为不同的虚拟文件路径指定不同的存储后端。这是实现“临时工作区”与“长期记忆库”分离的核心。
• 路径即记忆：通过将 /memories/ 甚至更细分的路径（如 /memories/user_preferences.txt）路由到 StoreBackend，所有写入这些路径的文件内容都将被持久化。
• 生产环境：在本地开发时可以使用 InMemoryStore，但在生产部署到 LangSmith 时，平台会自动提供持久化存储，你通常无需手动配置 store 参数。

4.3 复杂协作：构建子代理协调系统

对于需要多领域专家协作的任务，Deep Agents 的子代理 (subagents) 系统是理想选择。

场景：创建一个研究协调员，它将研究任务委托给专门的“研究员”子代理，并将写作任务委托给“作家”子代理。

from deepagents import create_deep_agent

# 假设已定义了一个网络搜索工具
def web_search_tool(query: str) -> str:
    # 集成 Tavily 或其他搜索API
    return f"关于 '{query}' 的模拟搜索结果..."

agent = create_deep_agent(
    system_prompt="你是一个项目协调员。你的工作是理解用户请求，并使用 `task()` 工具将任务分解并委托给最合适的专家子代理。保持你自身上下文的简洁。",
    subagents=[
        {
            "name": "research-specialist",
            "description": "深入研究特定主题，擅长使用网络搜索工具查找和分析信息。",
            "system_prompt": "你是一名细致的研究员。针对给定的主题进行研究，并提供一份2-3句话的简洁摘要。不要返回原始数据或冗长引文。",
            "tools": [web_search_tool]
        },
        {
            "name": "technical-writer",
            "description": "将复杂信息转化为结构清晰、易于理解的技术报告或文档。",
            "system_prompt": "你是一名技术文档作者。你将接收来自研究员的信息，并将其组织成结构化的报告。"
        }
    ],
)

# 使用流式执行，观察主代理与子代理的协作过程
for namespace, chunk in agent.stream(
    {"messages": [{"role": "user", "content": "请撰写一篇关于‘强化学习在机器人控制中的最新进展’的简短报告。’"}]},
    stream_mode="updates",  # 实时获取更新
):
    print(f"[{namespace}]: {chunk}")  # 将看到主代理规划和子代理执行的过程

✅ 最佳实践：

• 清晰的描述：为子代理提供具体、明确的 name 和 description，这有助于主代理准确选择。
• 上下文隔离：子代理拥有独立的系统提示和工具集，这避免了所有工具和上下文都堆叠在主代理的提示词中，能有效管理上下文长度。
• 输出控制：在子代理的系统提示中要求其输出简洁摘要，防止其返回大量原始数据污染主代理的上下文。

4.4 安全实战：数据分析代理与沙箱执行

涉及代码执行或系统操作的项目，安全是首要考虑。我们必须使用沙箱后端。

场景：构建一个数据分析代理，能读取CSV文件、进行Python分析、生成图表，并可以将结果分享到Slack。

import uuid
import os
from langgraph.checkpoint.memory import MemorySaver
from deepagents import create_deep_agent
from deepagents.backends.sandboxes.modal import ModalSandbox
from slack_sdk import WebClient

# 1. 配置安全的沙箱后端（以Modal为例）
# 确保已设置 RUNLOOP_API_KEY 环境变量
backend = ModalSandbox(sandbox=modal_sandbox)  # ‘modal_sandbox‘ 需根据Modal配置初始化

# 2. 自定义工具：发送结果到Slack
def slack_send_message(channel: str, text: str) -> str:
    client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])
    response = client.chat_postMessage(channel=channel, text=text)
    return f"消息已成功发送到频道 #{channel}"

# 3. 创建代理
checkpointer = MemorySaver()
agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5",
    tools=[slack_send_message],  # 代理可以调用Slack工具
    backend=backend,             # 所有文件操作和代码执行都在隔离沙箱中进行
    checkpointer=checkpointer,
    system_prompt="你是一个数据分析专家。你可以读取数据文件（如CSV），使用Python进行统计分析并生成可视化图表。完成后，你可以将分析摘要分享到协作频道。"
)

# 4. 运行代理（假设sales.csv已存在于沙箱工作区）
thread_id = str(uuid.uuid4())
config = {"configurable": {"thread_id": thread_id}}
result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "请分析沙箱中 ‘sales.csv‘ 文件的月度销售数据，生成一个趋势折线图，并将主要发现总结后发送到Slack的 #data-insights 频道。"
            }
        ]
    },
    config=config
)

⚠️ 关键安全警告：

• 生产环境必须使用沙箱：LocalShellBackend 仅在完全受控的开发环境中用于测试。任何生产或共享环境必须配置 ModalSandbox**、**RunloopSandbox 或 DaytonaSandbox 等隔离后端。

4.5 可控流程：集成人在回路审批

对于删除文件、发送外部消息等高风险操作，可以引入人工审批环节。

from deepagents import create_deep_agent
from langgraph.checkpoint.memory import MemorySaver

def delete_file(path: str) -> str:
    import os
    os.remove(path)
    return f“已删除文件：{path}”

def send_email(to: str, subject: str, body: str) -> str:
    # 模拟发送邮件逻辑
    return f“主题为‘{subject}’的邮件已发送给 {to}”

checkpointer = MemorySaver()  # 必须配置检查点，否则中断后无法恢复
agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[delete_file, send_email],
    interrupt_on={
        "delete_file": True,  # 对该工具的调用将暂停，提供【Approve, Edit, Reject】选项
        "send_email": {
            "allowed_decisions": ["approve", "reject"]  # 仅允许批准或拒绝，不可编辑内容
        },
    },
    checkpointer=checkpointer
)

# 当代理调用 ‘delete_file‘ 或 ‘send_email‘ 时，执行会暂停，等待人工在控制台或UI上做出决策。

4.6 项目级配置速查表

以下表格总结了不同项目场景下的核心配置项，帮助你在实战中快速组合所需功能：

场景目标	核心配置项	说明与示例
基础功能代理	tools, system_prompt	注入自定义能力，定义角色。tools=[custom_tool]
切换模型	model	指定模型提供商。model=“openai:gpt-4o”
持久化记忆	backend=CompositeBackend, store	混合路由。routes={“/memories/”: StoreBackend(runtime)}
安全代码执行	backend=ModalSandbox	生产环境代码执行隔离。backend=ModalSandbox(…)
人工审批控制	interrupt_on, checkpointer	高风险工具调用前暂停。interrupt_on={“tool_name”: True}
加载领域知识	skills	注入技能目录。skills=[“./project_skills/”]
多专家协作	subagents	定义子代理列表。subagents=[{name: ‘expert‘, …}]
实时监控调试	agent.stream()	流式获取执行更新。stream_mode=“updates”

通过以上示例，你已经看到如何将 Deep Agents 的各个模块——从基础工具、记忆存储到安全沙箱和多代理协作——组合起来，解决从简单到复杂的实际项目需求。这些配置模式是构建可靠、可控、可扩展的智能体应用的基石。

五、常见开发场景最佳实践

本章旨在将前四章的核心概念、配置方法与示例代码，转化为可直接套用于具体项目场景的实战指南。以下总结了在不同开发场景下应用 Deep Agents 框架的最佳实践，确保你的智能体应用既安全高效，又易于维护。

1. 任务规划与子代理管理实践

当面对需要分解、多角色协作的复杂任务时，清晰的任务描述与职责隔离是核心。

• 子代理定义力求明确：为主代理配置 subagents 时，务必提供具体、无歧义的名称和描述。这直接决定了主代理能否准确选择。
  • ✅ 正确的做法：{“name”: “data-analyst”, “description”: “Loads and analyzes CSV or JSON datasets, computes statistics, and identifies trends.”}
  • ❌ 错误的设计：{“name”: “helper”, “description”: “does data things”}
• 在系统提示中委派任务：主代理的 system_prompt 应明确指示其使用 task() 工具将专业性工作委托给子代理，以保持自身核心上下文的清洁。
• 约束子代理输出：在子代理的 system_prompt 中，要求其返回简洁的摘要而非原始数据。例如，“请将研究结果总结为不超过500词的概要”，这能有效防止大量中间结果污染上下文。
• 主-子协作模式：建立“协调 -> 执行 -> 汇总”的工作流。主代理像项目经理，负责任务规划与指令下达；专门的子代理（如研究员、写作者、代码工程师）执行具体任务并返回精炼结果。

2. 文件系统与上下文管理实践

Deep Agents 的核心能力之一是将海量上下文卸载到虚拟文件系统。根据数据生命周期选择正确的后端至关重要。

后端选择决策指南

后端类型	适用场景	数据生命周期	关键注意事项
StateBackend	默认后端。用于单次对话中的中间结果、草稿、临时计算。	单线程/会话内。大型输出会被自动分片并提供 read_chunk 工具。	会话结束或线程改变后数据丢失。
FilesystemBackend	受控开发环境。需要代理直接读写项目本地文件时使用。	持久化到本地磁盘。	无安全隔离！必须设置 root_dir 为绝对路径，并谨慎评估风险。可启用 virtual_mode=True 进行路径规范化。
StoreBackend	跨会话持久化。用于实现长期记忆，如用户偏好、项目知识库。	跨线程/跨会话持久。	需要在 runtime 中提供一个 BaseStore 实现（如PostgresStore、InMemoryStore 用于开发）。生产部署到 LangSmith 时，平台会自动提供。
沙箱后端	任何涉及代码执行的生产环境。提供安全隔离的执行环境。	沙箱实例生命周期内。	生产强制使用。支持 Modal、Runloop、Daytona 等。可按需销毁或复用沙箱实例以优化成本与速度。

• 复合后端是黄金标准：使用 CompositeBackend 为不同路径的数据指定存储策略，例如将临时工作文件路由到 StateBackend，而将长期记忆路由到 StoreBackend。

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),  # 临时工作区
    routes={
        "/memories/": StoreBackend(rt),  # 长期记忆
        "/workspace/cache/": FilesystemBackend(rt, root_dir="/tmp/agent_cache")
    }
)

• 路由规则：更具体的路径前缀会覆盖更通用的路径。例如，/memories/projects/ 的配置会优先于 /memories/ 的配置。

3. 长期记忆配置实践

记忆是智能体持续学习和个性化的基础，结构化和可引导的存储是关键。

1. 配置路由：务必使用 CompositeBackend，将记忆存储路径（如 /memories/）明确路由到 StoreBackend。
2. 清晰的目录结构：使用描述性的文件路径来组织记忆，使其易于管理和检索。
   • /memories/user_preferences.json
   • /memories/project_xyz/development_guidelines.md
   • /memories/research/llm_benchmarks_2024.md
3. 引导代理使用记忆：在代理的初始 system_prompt 中包含引导其与记忆交互的指令。例如：

“在每次对话开始时，请务必检查 /memories/user_context.md 文件以了解当前用户和项目背景。如果用户提供了新的重要信息或反馈，请使用 edit_file 或 write_file 工具将其记录到该文件中。”

1. 生产环境存储：本地开发可先使用 InMemoryStore 进行原型设计。在实际部署到 LangSmith 或自托管环境时，切换到 PostgresStore 或 RedisStore 等持久化后端。

4. 人在回路（Human-in-the-Loop）安全审批实践

对于文件删除、代码执行、邮件或消息发送等敏感操作，强制审批流程是最后的防线。

• 配置敏感工具中断：在创建代理时使用 interrupt_on 参数，为高风险工具配置触发中断。可以针对不同工具设置不同级别的审批选项。

agent = create_deep_agent(
    tools=[delete_file, execute_code, send_email],
    interpolrupt_on={
        "delete_file": True, # 默认：可审批、编辑参数或拒绝
        "execute_code": {"allowed_decisions": ["approve", "reject"]}, # 仅允许通过或拒绝
        "send_email": {"allowed_decisions": ["approve"]} # 仅允许通过
    },
    checkpointer=MemorySaver() # 必须配合检查点使用
)

• 检查点是必需的：必须配置 checkpointer（如 MemorySaver）并提供一个唯一的 thread_id。只有这样，图执行才能在人工干预后从暂停点正确恢复。
• 风险分级策略：根据操作的破坏性或影响范围，将工具划分为高、中、低风险，并为其定制不同的中断策略。

5. 前端流式展示与状态管理实践

为 Deep Agent 构建用户界面时，实时反馈与状态同步能极大提升用户体验。

• 使用 useStream Hook：在 React 应用中，利用 @langchain/langgraph-sdk/react 中的 useStream Hook。它能自动追踪和管理子代理的生命周期状态（待处理、运行中、完成、错误），并清晰地分离主代理与子代理的对话流。

const stream = useStream({
  assistantId: "your-deep-agent-id",
  apiUrl: " http://your-backend:2024 ",
  filterSubagentMessages: true, // 关键：分离子代理消息流
});

• 启用子图流式传输：在调用 stream.submit() 时，设置 { streamSubgraphs: true }，以实时获取子代理创建和执行的更新。
• 类型安全与状态恢复：
  • 利用 Python 后端代码的类型注解（如 Pydantic 模型），可以在前端获得更好的类型提示。
  • 利用检查点机制，当用户刷新页面时，可以从 thread_id 恢复之前的对话状态，包括所有子代理的执行历史。

6. 高级定制与集成实践

框架提供了足够的扩展点，但定制时需遵循既定模式并注意并发安全。

• 自定义工具：根据业务需求创建专用工具（如集成 JIRA、发送 Slack 通知、查询内部数据库）。遵循 LangChain 工具的定义规范。
• 中间件使用守则：自定义中间件可用于日志记录、性能监控或修改消息流。但核心原则是：不要在中间件自身的属性中保存或修改状态，因为这可能在并行调用时导致竞争条件。所有状态变化都应通过操作图的 state 来实现。
• 参考官方示例模式：在实现复杂代理时，反复参考文档中的“Deep agent example”和“Research coordinator”等完整示例，它们展示了工具、子代理、系统提示和状态管理的标准组合方式。

7. CLI 工具高效使用实践

Deep Agents CLI 是一个强大的交互式终端伴侣，正确的配置和命令能提升效率。

• 环境与追踪：确保 OPENAI_API_KEY 或 ANTHROPIC_API_KEY 已设置。通过配置 LANGSMITH_TRACING=true 来启用 LangSmith 追踪，这是调试复杂任务不可或缺的。
• 自动化与管道：
  • 使用 -q (–quiet) 参数获取干净的结果输出，便于传递给其他命令行工具进行处理。
  • 使用 --no-stream 参数让 CLI 缓冲完整响应后再一次性输出。
• 教学模式与记忆：CLI 代理会将从你那里学到的项目惯例和偏好，自动保存到 ~/.deepagents/<agent_name>/memories/ 目录中。这意味着你可以通过对话“教会”代理你的工作风格，并在未来的会话中复用这些记忆。
• 安全执行：始终使用 --sandbox modal（或 runloop、daytona）参数来执行代码，确保安全隔离。对于自动化的受信任任务，可以配合 --auto-approve 使用。
• 配置管理：通过 ~/.deepagents/config.toml 文件可以自定义和扩展模型供应商配置，实现灵活的模型切换和管理。

这些实践提炼自各场景的核心要求，旨在帮助你将 Deep Agents 从概念和配置快速转化为稳健、可扩展的生产级应用。结合前文提供的代码模板和配置片段，你可以根据具体需求选择和组合这些模式。

六、调试与部署指导

基于前五章的准备，您已经掌握了从架构认知到实战应用的全部技能。本章将进入项目周期的最后关键环节——调试与运维，确保您的 Deep Agent 能够稳定、可控地运行在生产环境中，并具备完善的观测与问题定位能力。

🐛 高效调试：洞悉智能体工作流

当复杂的多步任务或子代理协作出现意料之外的行为时，高效的调试工具至关重要。Deep Agents 提供了多层次、可视化的调试手段。

1. 利用流式输出实时观察进程

Deep Agents 内置了基于 LangGraph 的流式功能，允许您像查看日志一样，实时观察代理的思考、决策与执行过程。

• 核心价值：实时追踪主代理与子代理的完整生命周期，包括任务分发、工具调用、中间结果和最终响应，是理解复杂工作流不可或缺的工具。
• SDK 中使用：在调用代理时使用 stream 方法并指定 stream_mode=“updates”，可以逐步获取执行更新，这对审查代理内部状态非常有帮助。

for namespace, chunk in agent.stream(
    input, stream_mode="updates"
):
    print(f"{namespace}: {chunk}")  # 观察不同命名空间（如子代理）的输出

• 前端集成：在构建 Web 应用时，可以使用 React 的 useStream Hook，并通过设置 streamSubgraphs: true 参数，在前端 UI 中清晰地分离并展示主代理与各级子代理的实时状态和消息流。

2. 配置 LangSmith 实现全链路追踪

LangSmith 是调试和监控 LangChain 应用的事实标准，为 Deep Agents 提供强大的可观测性。

• 关键作用：记录从用户输入到最终输出的完整调用链，包括每一次 LLM 调用、工具调用的输入输出、耗时和成本，是进行根因分析和性能优化的核心。

• 配置步骤：

  a. 启用基础追踪：设置环境变量以连接 LangSmith。

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

  b. 分离追踪项目（推荐）：为 Deep Agent 的执行单独设立项目，便于与主应用的其他 LangChain 调用区分管理。

  export DEEPAGENTS_LANGSMITH_PROJECT="my-deep-agent-execution" # 可选：您的主应用使用另一个项目 export LANGSMITH_PROJECT="my-app-core" `
  

• 使用效果：配置后，所有通过 CLI 或 SDK 执行的 Agent 操作都会在 LangSmith 仪表板中生成详细的追踪轨迹，您可以直观地查看任务分解、工具执行顺序以及任何错误发生的位置。

3. 通过 ACP 进行交互式开发调试

Agent Client Protocol (ACP) 允许您将 Deep Agent 暴露为一个标准服务器，并使用支持 ACP 的编辑器（如 Zed、VS Code、Neovim）进行连接和交互。

• 场景：非常适合在开发阶段进行集成调试。您可以在熟悉的编辑器环境中直接与 Agent 对话，测试工具调用，并实时观察其响应，无缝融入开发工作流。

• 快速开始：

  1. 安装 ACP 包：pip install deepagents-acp
  2. 创建一个启动 ACP 服务器的脚本（通常通过 stdio 通信），即可在编辑器中连接并开始调试会话。

• 调试工具	核心能力	最佳适用场景
  流式输出 (Streaming)	实时观察执行步骤、子代理状态流	开发中验证工作流逻辑；前端展示进度
  LangSmith 追踪	全链路记录、性能分析、根因诊断	生产问题排查、性能优化、成本审计
  ACP 协议	与编辑器集成的交互式对话调试	开发过程中的快速测试与迭代

🚀 安全部署：为生产环境保驾护航

将 Deep Agent 投入生产，安全性和可靠性是首要考量。以下是部署的关键指导原则。

1. 强制使用沙箱后端隔离执行环境

最重要的安全准则：绝不要在生产或任何共享环境中使用 LocalShellBackend，因为它允许 Agent 在主机上直接执行任意命令，带来严重的安全风险。

• 生产级选择：必须使用沙箱后端，它为代码执行提供完全隔离的安全环境。支持的选项包括 Modal、Runloop、Daytona 等。

• 集成模式：

  1. 工具模式（推荐）：您的 Agent 运行在自己的安全服务器上，当需要执行代码时，通过调用相应沙箱提供商的工具，在远程隔离环境中执行。这是最灵活和常见的方式。

  from deepagents.backends import ModalSandbox
  # 假设 modal_sandbox 已配置
  backend = ModalSandbox(sandbox=modal_sandbox)
  agent = create_deep_agent(backend=backend, ...)
  

  2. 容器化模式：将整个 Deep Agent 应用打包进容器，并在沙箱环境中运行。环境更一致，但需要额外处理通信机制。

2. 配置持久化存储实现长期记忆

为了使 Agent 在不同会话间记住关键信息（如用户偏好、项目上下文），必须配置跨线程的持久化记忆。

标准配置模式：使用 CompositeBackend，将用于记忆的特定路径（如 /memories/）路由到 StoreBackend，其他临时路径使用 StateBackend。

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend 
composite_backend = lambda rt: CompositeBackend(    
    default=StateBackend(rt),  # 默认临时存储    
    routes={"/memories/": StoreBackend(runtime=rt)}  # 记忆持久化 
) 
agent = create_deep_agent(backend=composite_backend, ...) 

生产存储：在本地开发时，可以使用 InMemoryStore。对于生产环境，需要为 StoreBackend 提供持久的 BaseStore 实现，如 PostgresStore 或 RedisStore。如果选择部署到 LangSmith Deployment，平台将自动为您管理持久化存储，无需手动配置 store 参数。

3. 生产环境下的 CLI 使用规范

Deep Agents CLI 同样可以用于生产脚本或自动化任务，但需遵循安全实践。

• 执行安全：始终通过 --sandbox 参数（如 --sandbox modal）指定沙箱，确保代码在隔离环境中运行。

• 自动化审批：对于受信任的、定义明确的自动化任务，可以使用 --auto-approve 参数跳过人工审批步骤。

• 配置与效率：Agent 的配置和记忆存储在 ~/.deepagents/<agent_name>/ 下。通过 --agent 指定配置，并使用 --sandbox-id 重用现有沙箱实例以加速后续执行。

4. 考虑使用 LangSmith 简化部署运维

对于希望减少基础设施复杂度的团队，LangSmith Deployment 提供了一站式解决方案。

• 核心优势：它将 Deep Agent 应用的托管、可观测性、访问控制弹性伸缩整合在一起，提供开箱即用的生产就绪能力。

• 推荐场景：当您希望专注于 Agent 业务逻辑开发，而非底层运维时，这是高效的部署选择。

从利用流式输出和 LangSmith 进行精细化调试，到为生产环境严格配置沙箱与持久化记忆，本指南为您提供了确保 Deep Agent 应用稳健运行的全套方案。正确实施这些调试与部署实践，