Deep Agents 02：子 Agent、虚拟文件系统与长期记忆

#1、本篇任务：让主管只看结论，让子 Agent 处理细节

技术调研会产生几十次搜索和大量文件。如果全部进入主管上下文，真正的目标会被噪音淹没。本课用两个子 Agent：researcher 收集证据，reviewer 检查结论；主管负责计划与最终合成。

#2、什么时候委派，什么时候直接调用工具

适合委派：子任务有多步；需要专门提示或工具；会产生大量中间结果；只需返回有限结论。不适合：一步查询；主管需要全部中间上下文；协调成本超过任务本身。

复制主管
  ├─ researcher：搜索 → /workspace/research/sources.json → 摘要
  └─ reviewer：读取 sources/analysis → unsupported_claims.json
主管读取两个结果 → final.md

#3、配置专门子 Agent

Python：

复制subagents = [
    {
        "name": "researcher",
        "description": "收集公开资料并返回带 URL 的证据；不做最终推荐。",
        "system_prompt": "来源写入 /workspace/research/；不得修改其他目录。",
        "tools": [search_web],
    },
    {
        "name": "reviewer",
        "description": "检查分析中的无证据断言和遗漏约束；只读。",
        "system_prompt": "返回 unsupported_claims 与 missing_constraints。",
        "tools": [],
    },
]
agent = create_deep_agent(model="openai:gpt-5.5", subagents=subagents)

TypeScript 的 subagents 使用 name/description/systemPrompt/tools 表达同一合同。对复杂子工作流，可把已编译 LangGraph 作为 subagent。

子 Agent 返回值最好结构化并限制长度；完整 tool trace 留在其上下文，主管只拿 status、summary、artifacts、citations、missing。

#4、虚拟文件系统与 Backend

Deep Agents 提供 ls/read_file/write_file/edit_file/glob/grep。工具操作虚拟路径，真实数据由 backend 决定：

生产部署不要使用直接访问宿主的 FilesystemBackend/LocalShellBackend。大文件也不适合进入 StateBackend checkpoint，应放对象存储或 sandbox artifact。

#5、设计目录和并发规则

复制/workspace/subtasks/{task_id}/   单个子任务可写
/artifacts/                       最终交付，经扫描后发布
/memories/                        长期记忆，受 namespace 与权限保护

两个子 Agent 不要同时编辑同一文件。各写独立目录，主管生成新汇总文件；必须共写时使用 version/etag 乐观锁。限制路径、文件数、大小、MIME 和总配额，拒绝 ..、绝对路径与符号链接逃逸。

#6、长期记忆怎样写才安全

短期 scratch 属于 thread；长期记忆跨 thread。最常见的是 user-scoped memory，例如语言和输出偏好；组织政策通常只读；共享 agent memory 若允许所有用户写，会成为持久 prompt injection 通道。

推荐“提议—校验—批准—版本化写入”：

复制MemoryProposal(scope=user, key=response_style, value=简洁中文, reason=用户明确要求)
  → PII/允许字段检查 → 用户或确定性规则批准 → 写 /memories/preferences.md

不要保存密钥、一次性任务文本、工具返回中的指令。提供查看、编辑、删除和导出能力，并处理并发更新。

#7、本篇测试

主管上下文不包含子 Agent 的全部搜索轨迹；两个子任务文件不互相覆盖；用户 A 无法读取 B 的 memory；共享政策路径不可写；路径逃逸和超大文件被拒绝；memory 并发更新产生版本冲突而非静默覆盖。

下一课把文件、shell 和长期任务放入隔离 sandbox，并完成生产安全设计。

官方阅读：Subagents、Backends、Memory。