---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - managed-deep-agents
  - architecture
topic: Managed Deep Agents Python 架构与项目模型
sources:
  - https://docs.langchain.com/langsmith/python/managed-deep-agents
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-overview
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-project-structure
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-agent-definition
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-instructions
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-skills
last_verified: 2026-08-11
---
# Managed Deep Agents：架构与项目模型

## 定位

Managed Deep Agents（MDA）把 agent 定义为一个普通 Python 项目目录。开发者提供业务逻辑，平台提供 Deep Agents harness 与 LangSmith 托管基础设施。

它由三层组成：

1. **业务逻辑**：instructions、tools、skills 和项目代码。
2. **Agent harness**：Deep Agents 提供规划、工具、文件系统、记忆与子代理等运行能力。
3. **托管基础设施**：Agent Server、sandbox、Context Hub、evals、channels、schedules、deployment 和 observability。

当前文档明确标记为公开 Beta，并且只在 LangSmith Cloud 美国区提供。生产选型必须把区域、稳定性承诺和 API 变化风险纳入评估。

## 项目发现约定

```text
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 形态当成长期稳定契约。

## 关联

- [[Study/langchain/03-Managed-Deep-Agents/Python/02-扩展能力与安全边界|扩展能力与安全边界]]
- [[Study/langchain/03-Managed-Deep-Agents/Python/03-渠道调度与评估|渠道、调度与评估]]
- [[Study/langchain/03-Managed-Deep-Agents/Python/04-本地开发部署与CLI|本地开发、部署与 CLI]]