Appearance
上下文工程
Agent 的表现不只取决于模型，还取决于“在当前步骤看到什么”。Deep Agents 把上下文管理拆成 启动信息、运行时依赖、自动压缩、文件 offloading、subagent 隔离和长期 memory，避免把所有信息 都堆进一个 system prompt。
五种上下文
| 类型 | 典型内容 | 生命周期 | 主要入口 |
|---|---|---|---|
| 启动上下文 | system prompt、memory metadata、skills metadata | 每次 Agent run | system_prompt、memory、skills |
| 运行时上下文 | user id、tenant id、连接句柄、请求配置 | 当前 invoke/run | context schema 与 runtime context |
| 工作上下文 | messages、todos、当前文件与工具结果 | 当前 thread | LangGraph state、filesystem |
| 隔离上下文 | 某个 subagent 的详细轨迹 | 一次委派或独立 thread | task、AsyncSubAgent |
| 长期上下文 | 用户偏好、Agent 规则、跨 thread memory | Store 生命周期 | StoreBackend 与 namespace |
前端类比
可以把启动上下文类比为应用配置，运行时上下文类比为 request context，工作上下文类比为当前 页面 state，subagent 隔离类比为 Web Worker 的独立内存，长期 memory 类比为有租户命名空间的 持久存储。
Deep Agents 原生语义：这些信息最终以 system prompt、runtime context、LangGraph state、 文件或 subagent messages 的形式参与模型调用。它们不是一个统一对象，也不会自动获得相同的 持久化和访问控制。
压缩、Offloading 与隔离
三种机制解决的问题不同：
- Offloading 主动把原始材料写入文件，模型需要时再读取。
- Subagent isolation 让独立任务的详细工具轨迹不进入主 Agent。
- Summarization 在接近限制时压缩已有 messages，是最后一道预算管理而不是无损存储。
启动上下文要小而稳定
适合放入启动上下文的内容：
- Agent 的职责与不可变约束。
- 工具选择和输出格式的简短规则。
- 稳定的项目约定或用户偏好入口。
- Skills 的 name/description 目录。
不适合的内容：完整日志、整站文档、每次请求变化的凭据、大型检索结果。Memory 文件会被加载到 system prompt，应保持精炼；Skills 采用渐进披露，适合更长的按需说明。
Runtime context 不等于 prompt
Runtime context 适合传递 user id、tenant id、数据库连接或服务客户端。工具和 middleware 可以 读取它，但不需要把所有字段暴露给模型。敏感值应保留在工具实现或凭据代理中，只把模型完成任务 所需的最小语义加入 prompt。
一个安全顺序是：
- 应用认证用户并建立 typed context。
- Backend namespace 从已认证 context 派生。
- 工具在执行时再次校验 context 与目标资源。
- 模型只看到完成任务所需的非敏感描述。
文件 Offloading 模式
当工具返回大结果时，不要把全部内容直接返回 ToolMessage。可以让工具或 Agent：
- 将原始结果写到
/artifacts/search-001.json。 - 在消息里返回记录数、字段说明和文件路径。
- 使用
grep或read_file分段提取需要的证据。 - 最终报告只引用结论与来源，不复制全部原始数据。
文件不是永久真相来源。其生命周期和一致性由 backend 决定，关键 artifact 仍应进入受控持久存储。
何时使用 subagent 隔离
适合隔离的问题应有明确输入和输出，例如“比较三份官方文档并返回差异表”。不适合把共享业务 状态拆散到多个 subagent 后再期待模型自动合并。主 Agent 应负责：
- 提供最小任务说明和验收格式。
- 控制 subagent 的模型、工具和权限。
- 校验返回结果，而不是无条件信任。
- 决定哪些证据进入主上下文或文件。
上下文预算检查表
- 每个工具的 schema 是否精炼且不重复。
- 大结果是否有 artifact 路径和摘要。
- Memory 是否只保留稳定事实与偏好。
- Skill 是否通过 metadata 可准确触发。
- Subagent 是否能在独立上下文完成清晰任务。
- Summarization 后是否仍保留关键约束和来源。
- Trace 是否会记录不应进入观测平台的敏感数据。