学习笔记 · Obsidian
Managed Deep Agents：架构与项目模型
定位
Managed Deep Agents（MDA）把 agent 定义为一个普通 Python 项目目录。开发者提供业务逻辑，平台提供 Deep Agents harness 与 LangSmith 托管基础设施。
它由三层组成：
- 业务逻辑：instructions、tools、skills 和项目代码。
- Agent harness：Deep Agents 提供规划、工具、文件系统、记忆与子代理等运行能力。
- 托管基础设施：Agent Server、sandbox、Context Hub、evals、channels、schedules、deployment 和 observability。
当前文档明确标记为公开 Beta，并且只在 LangSmith Cloud 美国区提供。生产选型必须把区域、稳定性承诺和 API 变化风险纳入评估。
项目发现约定
my-agent/
├── agent.py
├── instructions.md
├── skills/<name>/SKILL.md
├── tools/
├── middleware/
├── connectors/*.py
├── channels/*.py
├── schedules/*.py
├── sandbox/__init__.py
├── identity.py
├── memory.py
├── pyproject.toml
├── .env
└── evals/- 唯一必需文件是项目根目录的
agent.py。 - 一个项目只允许一个 agent entry；
agent.py必须导出名为agent的对象。 instructions.md与skills/**属于 managed context，部署时同步到 Context Hub。tools/、middleware/和普通本地模块属于应用代码，随编译产物部署。identity.py、memory.py、sandbox/__init__.py以及connectors/、channels/、schedules/的直接子模块属于约定式托管配置。.env只参与本地加载和部署 secret 路由，不进入构建归档。evals/是 Harbor 工作区，不进入 agent 部署包。
Agent definition 的职责
define_deep_agent 负责配置核心运行能力：
| 参数 | 责任 |
|---|---|
name | agent 名、默认 assistant ID 与默认 deployment 名 |
model | provider:model 或配置过的 LangChain chat model 实例 |
tools | 项目内 authored tools |
middleware | 模型调用、工具调用和生命周期的横切行为 |
subagents | 专用子代理及其模型、prompt、tools |
permissions | 内建文件工具的路径访问规则 |
interrupt_on | 敏感工具调用前的人类审批 |
response_format | 结构化输出 schema |
name 必须以字母开头，仅包含字母、数字、下划线或连字符。部署名可以由 CLI 覆盖，不需要修改 agent 定义。
系统 prompt、skills、memory、sandbox、identity、channels 与 schedules 应放在约定文件中，不应全部挤入 agent.py。
Instructions、Skills、Memory 的区别
| 能力 | 加载方式 | 是否允许 agent 修改 | 适用内容 |
|---|---|---|---|
| Instructions | 每次运行始终加载 | 否 | 角色、行为、约束、工具使用原则 |
| Skills | 先暴露名称和描述，命中任务后渐进加载 | 否 | 可复用、任务特定的流程与资源 |
| Memory | 显式启用后按热/冷分层读取 | 是 | 运行中学习并跨线程保留的共享知识 |
Skills 目录必须包含带 name、description frontmatter 的 SKILL.md，也可以引用 scripts、references 和 templates。部署会把 UTF-8 skill 文件同步到 Context Hub；后续部署以本地项目为准并移除已不存在的已部署 skill 文件。
设计原则
- 把 agent definition 保持为组合根，把业务工具、横切 middleware 和托管能力声明分离。
- Instructions 只放始终有效的规则；大段任务流程放 Skills，避免每次运行都消耗上下文。
- 对公共 Beta 的版本和行为建立回归测试，不把当前 CLI/API 形态当成长期稳定契约。