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

默认 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 路径并验证执行顺序。