对于 Deep Agents，一个比较完整、能走向生产的项目，至少要包含这 6 层：
1. 入口层：API / Web / CLI
2. Agent 编排层：主 agent + subagents
3. 能力层：tools + skills
4. 上下文层：文件系统 backend + memory
5. 运行时层：LangGraph 持久化、流式、线程状态
6. 治理层：日志、审批、安全隔离、评估

之所以这样拆，是因为 Deep Agents 本身就是一个“agent harness”，官方内置了任务规划、文件系统工具、子代理和长期记忆接入能力；前端层面也按 coordinator-worker 架构暴露主代理与子代理状态。

⸻

一、先定你要搭的“完整 Deep Agent 框架”

我建议你直接按这个目标来做：

一个主代理负责规划与汇总，若干子代理负责检索、分析、写作；工具负责真实执行；skills 负责复用 SOP 和领域规范；文件系统负责中间产物；memory 负责跨会话记忆。
这和 Deep Agents 官方能力边界是匹配的：规划靠内置 write_todos，上下文管理靠文件系统工具，复杂任务拆分靠 subagents，长期信息复用靠 memory，领域能力沉淀靠 skills。

⸻

二、推荐的总架构

可以直接按下面这个逻辑搭：

用户 / 前端
   ↓
FastAPI / CLI / WebSocket(SSE)
   ↓
Deep Agent App Service
   ↓
┌──────────────────────────────────────┐
│ Main Deep Agent (Coordinator)        │
│ - 任务理解                            │
│ - write_todos 规划                    │
│ - 调度工具 / skills / 子代理          │
│ - 汇总最终结果                        │
└──────────────────────────────────────┘
        ↓                ↓                 ↓
   Tools Runtime      Skills Runtime     Subagents
   - 搜索                - 合同审查 SOP      - Research Agent
   - 数据库              - 报告模板          - Analysis Agent
   - HTTP/API           - 会议纪要规范      - Writer Agent
   - 检索/RAG           - 行业知识          - QA Agent

        ↓
Virtual File System / Backends
- StateBackend
- FilesystemBackend
- StoreBackend
- CompositeBackend

        ↓
Memory / LangGraph Store
- 用户偏好
- 项目规范
- 历史任务结论
- 长期可复用事实

Deep Agents 官方说明里，文件系统 backend 支持 StateBackend、FilesystemBackend、StoreBackend、CompositeBackend 等；而且如果你要使用 skills 或 memory，需要在创建 agent 之前，把对应的 skill 或 memory 文件先放进 backend。 

⸻

三、项目目录怎么搭

我建议直接用这个目录：

deepagent_app/
├── app/
│   ├── main.py                       # FastAPI 入口
│   ├── config.py                     # 配置
│   ├── api/
│   │   ├── routes_agent.py           # /agent/run /agent/stream
│   │   └── routes_files.py           # 报告/文件读取
│   ├── agent/
│   │   ├── factory.py                # create_deep_agent
│   │   ├── prompts.py                # system prompt
│   │   ├── subagents.py              # 子代理定义
│   │   ├── skills_loader.py          # 技能装载
│   │   └── memory_loader.py          # 记忆初始化
│   ├── tools/
│   │   ├── search_tools.py           # 搜索工具
│   │   ├── rag_tools.py              # 知识库工具
│   │   ├── file_tools.py             # 自定义文件工具（可选）
│   │   ├── http_tools.py             # HTTP/API 调用
│   │   └── biz_tools.py              # 业务工具
│   ├── skills/
│   │   ├── report_writer/
│   │   │   ├── SKILL.md
│   │   │   ├── templates/
│   │   │   └── examples/
│   │   ├── contract_reviewer/
│   │   │   ├── SKILL.md
│   │   │   └── checklist.md
│   │   └── meeting_summarizer/
│   │       ├── SKILL.md
│   │       └── output_template.md
│   ├── memory/
│   │   ├── user_profile.json
│   │   ├── org_conventions.md
│   │   └── project_memory.md
│   ├── workspace/                    # agent 工作区
│   │   ├── threads/
│   │   ├── reports/
│   │   └── temp/
│   └── services/
│       ├── backend_service.py        # backend 选择
│       ├── tracing_service.py        # tracing/log
│       └── report_service.py         # 报告生成/导出
├── tests/
├── requirements.txt
└── README.md

这个目录的核心原则是：
agent、tools、skills、memory、workspace 分开。
因为 Deep Agents 里的 skills 本质是可复用能力包，memory 是长期信息，backend 是上下文承载层，混在一起后面会非常难维护。官方也明确把 skills、memory、backends 作为独立可配置对象来设计。 

⸻

四、每一层怎么设计

1）主 Agent 层

主 agent 只做四件事：
• 理解目标
• 写 todo 计划
• 决定调用 tool / skill / subagent
• 汇总最终结果

Deep Agents 自带 write_todos，就是为了让 agent 把复杂任务拆成离散步骤、跟踪进度并根据新信息调整计划。这个能力应该交给主 agent，不要分散到各个业务工具里。 

⸻

2）Subagents 层

建议至少拆成 3 个子代理：
• research_subagent：查资料、查知识库、收集事实
• analysis_subagent：比较、归纳、提炼风险点
• writer_subagent：按模板输出正式文档

Deep Agents 前端文档明确描述了它的 coordinator-worker 架构：主代理规划任务并委派给隔离运行的 specialized subagents。你做后端时，也建议按这个模型设计。 

⸻

3）Tools 层

tools 只负责“真正执行”：
• 搜索
• 调 API
• 查数据库
• 调 RAG
• 获取业务数据
• 写入外部系统

不要把领域规范、流程说明写在 tool 里，那些应该进 skill。
Deep Agents 官方把 tools 和 filesystems 用于执行与上下文管理，而 skills 则是 specialized workflows and domain knowledge。 

⸻

4）Skills 层

skills 用来沉淀 可复用 SOP。
适合做成 skills 的内容：
• 合同审查步骤
• 会议纪要模板
• 技术方案输出规范
• PPT 一页纸表达模板
• 行业领域术语与规则

官方文档把 skills 定义为 reusable agent capabilities，用于提供 specialized workflows and domain knowledge，并遵循 Agent Skills 规范。 

一个 skill 目录最少有一个 SKILL.md。
推荐写法：

report_writer

适用场景

用于生成技术方案、总结报告、会议纪要。

工作步骤

1. 先确认输入材料是否完整
2. 提取背景、目标、问题、建议
3. 若信息不足，先输出“待补充信息”
4. 按固定模板输出 Markdown

输出模板

• 背景
• 现状
• 核心问题
• 建议方案
• 风险
• 结论

注意事项

• 不夸大
• 不编造数据
• 结论与材料可追溯

这种设计的价值在于：主代理不必每次从零思考“怎么写报告”，而是命中 skill 后按这套规范来执行。Deep Agents 的 skill 机制就是为这个目的存在的。 

⸻

5）Memory 层

建议把 memory 分成两类：
• 用户记忆：偏好、输出格式、术语习惯
• 项目记忆：项目背景、长期规则、历史结论

Deep Agents 文档说明，若使用 skills 或 memory，要先把相应文件写入 backend 再创建 agent。也就是说，你的 memory 不是聊天里临时塞一句话，而应该作为工程的一部分被初始化。 

推荐你维护这些 memory 文件：

• user_profile.json
• org_conventions.md
• project_memory.md

示例：

{
  "user_name": "陈XX",
  "output_language": "zh-CN",
  "preferred_style": "结构化、业务化、可直接落地",
  "report_preference": "先结论后展开"
}

⸻

6）File / Backend 层

这是 Deep Agents 的核心。
官方明确说文件系统工具如 ls、read_file、write_file、edit_file 用来把大上下文卸载到内存或文件系统，避免上下文窗口溢出。

推荐这样选 backend：
• 开发期：StateBackend
线程级、轻量，适合调试。
• 单机部署：FilesystemBackend
直接落本地目录，方便看中间文件。
• 生产多会话：StoreBackend
跨线程持久化更合适。
• 混合场景：CompositeBackend
把技能、记忆、线程文件拆到不同后端。

实际推荐：
skills + memory 放持久层，临时任务文件放 thread workspace。

⸻

五、完整搭建顺序

第一步：初始化依赖

根据官方 quickstart，先安装 deepagents，再配模型 provider；Deep Agents 要求模型支持 tool calling。 

pip install deepagents langchain

如果你要接具体模型，再装对应 provider 包。

⸻

第二步：写 system prompt

app/agent/prompts.py

SYSTEM_PROMPT = """
你是一个企业级 Deep Agent 主代理。

你的职责：
1. 使用 write_todos 先规划任务
2. 根据任务判断是调用工具、调用 skill，还是委派给子代理
3. 长内容优先写入文件系统，不要把大段中间结果一直保留在消息中
4. 最终输出结构化结果，并给出产出文件路径

原则：
- 不编造事实
- 结论必须和工具结果或文件内容一致
- 遇到复杂子问题，优先委派给合适的子代理
"""

⸻

第三步：先准备 skills 和 memory 文件

在 app/skills//SKILL.md 和 app/memory/ 下先放好文件。
这一步不能省，因为官方明确要求：使用 skills 或 memory 时，要在创建 agent 前将它们写入 backend。 

⸻

第四步：定义 tools

app/tools/search_tools.py

from langchain.tools import tool

@tool
def search_internal_docs(query: str) -> str:
    """Search internal documents and return concise findings."""
    return f"[internal-docs] result for: {query}"

@tool
def query_project_data(project_name: str) -> str:
    """Query structured project data."""
    return f"project data for {project_name}"

⸻

第五步：定义 subagents

app/agent/subagents.py

RESEARCH_SUBAGENT_PROMPT = """
你是研究子代理，只负责检索、提取事实、整理来源，不负责最终结论。
"""

ANALYSIS_SUBAGENT_PROMPT = """
你是分析子代理，只负责比较、归纳、提炼问题与建议。
"""

WRITER_SUBAGENT_PROMPT = """
你是写作子代理，只负责依据现有材料输出结构化文档。
"""

⸻

第六步：创建 backend 并预加载 skills/memory

app/services/backend_service.py

思路如下：

# 伪代码结构
backend = FilesystemBackend(root_dir="./app/workspace")

# 将 app/skills 下的文件写入 backend 的 skills 区域
# 将 app/memory 下的文件写入 backend 的 memory 区域
# 然后再把 backend 传给 create_deep_agent

因为 Deep Agents 的 backend 就是上下文承载层，skills 和 memory 依赖它存储与读取。 

⸻

第七步：创建主 agent

app/agent/factory.py

from deepagents import create_deep_agent
from app.agent.prompts import SYSTEM_PROMPT
from app.tools.search_tools import search_internal_docs, query_project_data

def build_agent(backend):
    agent = create_deep_agent(
        model="openai:gpt-5.3-codex",
        tools=[search_internal_docs, query_project_data],
        system_prompt=SYSTEM_PROMPT,
        # backend=backend,
        # subagents=[...],
        # memory=...,
        # skills=...
    )
    return agent

你这里真正要做的是把 backend、subagents、skills、memory 都接进来。
官方 customization 文档说明，这些就是 Deep Agents 的主要可定制点。 

⸻

第八步：加 API 层

app/main.py

from fastapi import FastAPI
from app.agent.factory import build_agent
from app.services.backend_service import get_backend

app = FastAPI()

backend = get_backend()
agent = build_agent(backend)

@app.post("/agent/run")
async def run_agent(payload: dict):
    result = agent.invoke({
        "messages": [
            {"role": "user", "content": payload["query"]}
        ]
    })
    return {"result": result}

后面再加 /agent/stream，做流式输出即可。Deep Agents 官方强调它建立在 LangGraph 运行时之上，适合做持久化与流式执行。 

⸻

六、最推荐的“完整项目落地模式”

如果你是要做真正可用的项目，我建议直接用下面这套职责分配：

主代理

负责：
• 任务分解
• 选择 skill
• 决定是否调用子代理
• 汇总结论

子代理 A：Research

负责：
• 搜索
• 检索知识库
• 读上传文件
• 写事实摘要到 workspace

子代理 B：Analysis

负责：
• 做对比
• 找风险点
• 归纳可执行建议

子代理 C：Writer

负责：
• 套用 report_writer / meeting_summarizer skill
• 输出 markdown / html / pdf 草稿

Skills

负责：
• 提供稳定 SOP、模板、行业规则

Tools

负责：
• 与外界系统真正交互

Memory

负责：
• 记住长期信息，不把长期规则写死在 prompt 里

Filesystem

负责：
• 中间产物、报告草稿、对比表、检索摘要

这套方式最符合 Deep Agents 的 harness 思路：
主代理协调，子代理隔离执行，skills 提供方法，tools 提供动作，files 承担上下文，memory 保持长期一致性。 

⸻

七、你这个项目里最值得先做的 3 个 skill

结合你的使用场景，我建议先从这 3 个 skill 起：

1. report_writer

适合：
• 技术方案
• 汇报材料
• 会议纪要
• 商业计划书摘要

2. contract_reviewer

适合：
• 找乙方不利条款
• 风险条款清单
• 修改建议输出

3. tech_solution_architect

适合：
• 技术架构说明
• 模块拆分
• 部署方案
• 估算与风险说明

因为这些任务都高度重复，特别适合做成可复用 skill，而不是每次重新写 prompt。官方 skills 文档就是鼓励这样沉淀 specialized workflows。 

⸻

八、上线前一定要补的工程项

1）Tracing

要能看到：
• todo 变化
• 调了哪些 tools
• 哪个 skill 被用到了
• 哪个子代理在执行

2）审批

高风险动作必须人工确认。

3）隔离

执行 shell / 外部写操作时不要直接跑宿主机。

4）产物规范

所有报告都落到 workspace/reports/，并带任务 ID。

这些虽然不是你问的“框架主体”，但没有它们，这个项目很难稳定跑向生产。Deep Agents 本身就是为复杂长任务设计的，治理层不能省。 

⸻

九、最简实施路线

你现在可以按这个顺序真开工：
1. 建目录
2. 先写 2 个 tools
3. 写 1 个 report_writer skill
4. 准备 2 个 memory 文件
5. 选 FilesystemBackend 跑本地版
6. create_deep_agent 接入主 agent
7. 再补 research / analysis / writer 三个 subagents
8. 接 FastAPI
9. 最后补 tracing、streaming、审批

⸻

十、一句话定稿

完整的 Deep Agent 项目，不是只写一个 create_deep_agent() 就结束，而是要把主代理、子代理、tools、skills、memory、backend/filesystem 作为独立层来设计：主代理负责规划和调度，tools 负责执行，skills 负责 SOP 复用，memory 负责长期信息，文件系统负责中间产物和上下文卸载。这样搭出来的项目，才是真正可扩展的 Deep Agent 框架。 

我可以下一条直接给你一份 可运行的项目脚手架代码，包括：
• factory.py
• subagents.py
• tools.py
• SKILL.md 示例
• memory 初始化
• FastAPI 接口
• 本地 FilesystemBackend 版本。