---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langchain
  - managed-deep-agents
  - security
topic: Managed Deep Agents Python 扩展能力与安全边界
sources:
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-tools
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-mcp-connectors
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-middleware
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-memory
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-sandboxes
  - https://docs.langchain.com/langsmith/python/managed-deep-agents-identity
last_verified: 2026-08-11
---
# Managed Deep Agents：扩展能力与安全边界

## Authored tools

- 私有 API、数据库访问和业务逻辑应实现为项目内 LangChain tools，从 `agent.py` 显式导入并加入 `tools`。
- 工具名必须清晰且唯一，避免与其他项目工具或 MCP 工具碰撞。
- 敏感操作使用 `interrupt_on` 暂停，让人类批准、编辑或拒绝；文件系统再叠加 `permissions`。
- 本地运行时中断由 Studio 展示；已部署运行通过 LangGraph Server 的 `Command(resume=...)` 恢复。
- 当前 Beta 文档仍以 CLI 为主，面向自有应用的完整 programmatic invocation 尚未正式文档化。
- durable thread state 由托管 checkpointer 提供，无需自行配置。

## MCP connectors

MCP connector 从远端 MCP server 加载工具，模块必须位于 `connectors/` 的直接子层并导出 `connector`。

- 支持 Streamable HTTP 和 legacy SSE；不支持 stdio MCP server。
- 默认暴露服务器全部工具，生产环境应优先使用 `include_tools` allowlist。
- `exclude_tools` 在 allowlist 之后应用，同一工具不能同时出现在两者中。
- 默认给工具加 `{server}__` 前缀，降低跨服务器重名风险。
- HTTP 可以配置自动 SSE fallback；每个 server 可配置超时和 SSE reconnect。
- `throw_on_load_error` 默认 `true`，即加载失败时 fail closed，而不是静默使用残缺工具集。
- 凭据从环境变量进入 headers，禁止硬编码到 connector 文件。

MCP connector 提供远端工具；authored tool 提供项目内逻辑；channel 负责接收外部消息并触发运行，三者不是同一抽象。

## Middleware

Middleware 适合 PII 处理、调用限额、重试、fallback、动态模型选择、审计与工具调用监控。

- 托管 runtime 仍拥有 backend、store、checkpointer、memory、skills 和 system prompt；middleware 不应试图接管这些职责。
- 列表顺序就是执行组合顺序，应显式设计顺序依赖。
- MDA 使用 `ainvoke` 和 `astream`，自定义 middleware 必须实现 async hooks。
- 每次运行的 user/org ID、feature flags、request metadata 应放 runtime context，不应默认进入模型 prompt。

## Durable memory

MDA 默认只有 thread/session 级对话状态。跨线程 durable memory 必须通过 `memory.py` 显式启用。

启用 `scope="agent"` 后，deployment 获得一个由所有调用者共享的 `/memories/agent/` 读写树：

- `/memories/agent/AGENTS.md` 是每次运行都加载的 hot memory，必须短小。
- 其他文件是按需读取的 cold memory，适合详细研究、流程和决策记录。
- agent 只能在该树内实现持久写入，其他路径的写入不等于 durable memory。

### 最高风险边界

共享 memory 可被每一个调用者影响，也会被后续调用者读取。它必须被视为不可信输入，不能授予权限、改变审批规则或替代 agent definition。禁止存储个人/客户私有数据、凭据、Token 和秘密。调用者之间不应互相影响时，不要启用 deployment-wide shared memory。

## Sandbox

- `sandbox/` 存在时启用，删除该目录即退出 sandbox 能力。
- 默认 `thread` scope：每个 durable thread 一个 sandbox，并在同一线程多次运行间复用。
- `agent` scope：同一进程的多个线程共享文件，只有明确需要共享状态时才能使用。
- `idle_ttl_seconds` 控制空闲回收，`default_timeout` 限制每条命令；template 与 snapshot 只能选择一种创建来源。
- 删除 deployment 会清理关联的 managed sandboxes。

隔离环境不是授权模型。仍需通过 instructions、tool permissions、network policy、timeout 和 HITL 约束 agent 行为。

## Identity

| 目标 | 方案 | 边界 |
|---|---|---|
| SDK、脚本和服务调用 | LangSmith workspace API key（默认） | 只回答“能否调用”，不会自动隔离最终用户线程 |
| 登录用户的私有会话 | Supabase JWT | 根据调用者身份建立 thread ownership |

默认 API-key 模式使用 `x-api-key`。任何持有 workspace key 的人都可访问 deployment，因此不能把它等同于 end-user isolation。

Supabase 模式由 MDA 根据项目 JWKS 验证 Bearer token。客户端只保留 Supabase publishable key，不得把 LangSmith API key 发给浏览器。已有 deployment 后补 Supabase 不会给历史 thread 自动补 owner metadata，必须规划迁移并验证跨用户访问返回 403。

## 上线检查

- MCP 工具使用 allowlist、合理超时，并决定加载失败是否允许降级。
- 外部副作用工具实现幂等并使用 HITL；filesystem 同时应用 path permission。
- Memory 明确调用者隔离模型；不把共享 memory 当可信指令。
- Sandbox 使用 thread scope，除非业务证明必须跨线程共享。
- Identity 测试 401、同用户访问、跨用户 403 和历史 thread 迁移。
- Middleware 全部走 async 路径并验证执行顺序。