从 Deep Agents 迁移到 Managed Deep Agents

把一个用 create_deep_agent 构建的 agent 转换为一个 Managed Deep Agents 项目。

Managed Deep Agents 运行你已经在针对其构建的同一个 Deep Agents harness，因此迁移一个现有 agent 是一项重新打包工作，而非重写。你的工具、中间件和子 agent 原样沿用。agent 入口改变，而系统提示、技能和记忆移入项目文件。

NOTE

Managed Deep Agents 处于公开 beta 阶段，仅在 US 区域的 LangSmith Cloud 上可用。

决定是否迁移

Managed Deep Agents 运行同一个 harness，因此 agent 本身的行为相同。工具、中间件和子 agent 像今天一样工作。迁移会在 agent 周围增加一层：Slack 及其他聊天界面、终端用户的 OAuth、计划运行、一个托管沙箱，以及持久记忆——这些从你构建和运维的服务变成项目文件中的声明。

当你想要那一层却不想运行它时，迁移一个 agent。当你需要拥有它时，留在 Deep Agents。

	Deep Agents	Managed Deep Agents
托管	在你自己的进程或容器中运行 agent，或把它部署为一个 LangSmith deployment。	LangSmith 在 Agent Server 上托管 agent。mda deploy 就是整个部署步骤。
文件系统与 shell	任何后端：agent 状态、本地磁盘、一个存储，或你用某个提供商预配的沙箱。	一个托管沙箱，在一个文件中声明。LangSmith 创建它、为它打快照，并在空闲时停止它。
跨对话的记忆	你运行存储并自行接线。	一棵共享的记忆树，通过添加一个文件启用。
终端用户的第三方访问	你为每个用户预配并存储凭据。	连接持有工作区机密并运行 OAuth，因此终端用户自己授权服务。
聊天界面	你编写集成。	渠道连接 Slack 及其他消息服务。
计划运行	你运行调度器。	计划运行托管 cron 作业。
agent 周围的代码	由你编写，包括自定义路由和应用代码。	仅 agent。对于自定义路由或应用代码，使用一个 LangSmith deployment。

两种情况下 harness 都相同，因此先在 Deep Agents 上构建，等 agent 准备好投产时再迁移，是一条正常的路径。参阅走向生产。

理解什么会改变

create_deep_agent 在你的进程中编译一个 agent，因此它把 backend、store 和 checkpointer 作为参数接收。define_deep_agent 返回的是一个定义，而托管运行时会编译它。这个定义是配置而非一个可运行的 agent：mda CLI 在 mda dev 和 mda deploy 时消费它，运行时在那时提供托管的部分。有关完整图景，参阅与 Deep Agents 的关系。

检查什么无法沿用

大多数 agent 除了入口文件之外无需改动即可迁移。四种情形需要先做决定：

• 自定义后端：手写的 BackendProtocol 实现没有等价物。运行时拥有后端，而托管沙箱是给 agent 一个文件系统和 shell 的唯一选择。
• 你自己的 store 或 checkpointer：线程、运行和持久化来自 Agent Server。一个依赖特定 store 实现的 agent 需要把那部分逻辑移入一个工具或中间件。
• 自定义应用代码和路由：Managed Deep Agents 托管 agent，而非任意 web 应用。对于自定义路由、高级身份验证或 agent 周围的应用代码，请改用 LangSmith deployment。
• Python 中的自定义状态 schema：define_deep_agent 不接受 state_schema，因此一个扩展 DeepAgentState 的 agent 无法原样迁移。TypeScript 的 defineDeepAgent 确实接受 stateSchema。

如果这些都不适用，agent 逻辑按所写的那样迁移。

Convert this codebase from a self-hosted Deep Agents agent into a Managed Deep Agents (MDA) project.

第 1 步：阅读指南

Fetch and follow https://www.bytesrouter.com/langsmith/python/managed-deep-agents-migrate as the source of truth for the parameter mapping and project layout.

步骤 2：添加 SDK

就地转换项目；不要运行 mda init，它只创建一个新目录。把 managed-deepagents 添加到现有的项目清单，固定到 mda --version 报告的版本，并保留所有现有依赖不动。

在 Python 中，如果清单设置了 build-backend = "hatchling.build"，还要添加 [tool.hatch.metadata] allow-direct-references = true。mda build 会把该需求重写为一个否则会被 Hatchling 在安装时拒绝的路径引用。

步骤 3：迁移配置

找到 create_deep_agent（或 createDeepAgent）调用点，然后：

• 把它替换为项目根目录 agent.py（或 agent.ts）中的 define_deep_agent（或 defineDeepAgent），导出一个名为 agent 的变量。该定义调用必须位于那个文件中，而不是被重新导出到那里。
• 添加一个静态的 name，它是必需的。使用匹配 [a-zA-Z][a-zA-Z0-9_-]* 的字符串。
• 把 system_prompt 文本移到 agent 入口旁边的 instructions.md，并移除该参数。
• 把 skills 所引用的文件移到 skills/<name>/SKILL.md，并移除该参数。
• 用一个根目录 memory.py（或 memory.ts）替换 memory，导出一个名为 memory 的变量并设为 define_memory(scope="agent")，并移除该参数。如果 agent 不需要持久记忆就不放那个文件。警告用户这会挂载一棵空树，任何现有的记忆内容都必须移到 instructions.md 或某个技能中。
• 删除 backend、store 和 checkpointer。运行时拥有这三者。如果 agent 用过沙箱后端，改为添加一个 sandbox/ 声明，导出 define_sandbox(...)。托管沙箱是 Managed Deep Agents 提供的唯一后端。
• 保留 model、tools、middleware、subagents、permissions、cache 和 debug 原样，连同那些中断、响应格式和上下文 schema 参数也保持其现有名称。警告用户：一个声明了 sandbox/ 的项目会在清空 permissions 的情况下运行，因为一条文件系统权限规则会禁用沙箱的 execute 工具。
• 把工具和中间件模块留在它们已有的位置，并继续从 agent 入口导入它们。不要重构项目结构。

步骤 4：显式处理缺口

如果代码库在 Python 中传入 state_schema、构建了一个自定义 BackendProtocol，或把 agent 包裹在它自己的服务器路由或应用代码中，请停下并询问用户如何继续。Managed Deep Agents 不接受这些。不要臆造替代品。

步骤 5：验证

运行 mda build，然后 mda dev，确认 agent 能启动并回答一个测试消息。mda build 不会校验定义调用，因此一个遗留的托管参数只会在图加载时显现。报告任何无法迁移的东西。

映射参数

大部分接口原样迁移到 define_deep_agent，用相同的名称：model、tools、middleware、subagents、interrupt_on、response_format、context_schema、cache 和 debug。把工具和中间件模块留在它们已有的位置，并继续从 agent 入口导入它们。

define_deep_agent 增加一个必需参数。给 name 传入一个以字母开头、仅含字母、数字、下划线或连字符的静态字符串。Managed Deep Agents 把它用作 agent 的图 ID 和默认部署名。

其余的移到一个项目文件或变成运行时的职责：

create_deep_agent	它去哪里	备注
system_prompt	instructions.md	把文本移到文件里，然后移除该参数。参阅指令。
skills	skills/	每个技能一个目录，各带一个 SKILL.md。参阅技能。
memory	memory.py	导出 define_memory(scope="agent")。无持久记忆则省略该文件。参阅记忆。
backend	sandbox/	声明一个托管沙箱而非构造一个后端。参阅沙箱。
permissions	仍是一个参数	接受，并在项目声明沙箱时被清空。参阅权限。
store、checkpointer	托管运行时	两者都移除。
state_schema	无等价物	define_deep_agent 不接受它。

Deep Agents 后端是可插拔的，而托管运行时提供它自己的。一个声明了 sandbox/ 的项目会为 agent 文件系统和 shell 得到一个托管沙箱。没有声明的项目会得到线程范围的 agent 状态，连同用于指令、技能和记忆的只读 Context Hub 挂载。没有其他后端可选，因此一个依赖特定后端的 agent 会留在 Deep Agents。

迁移一个 agent

就地转换项目。现有的布局、模块结构和依赖保持原样：mda build 会把它所需的依赖合并进项目清单，而非替换它。

要先安装 mda CLI，参阅快速开始。

Add the SDK to the project

uv add managed-deepagents

把版本固定到与 CLI 相匹配，即 mda --version 报告的。

如果项目用 Hatchling 构建，在 pyproject.toml 中允许直接引用：

[tool.hatch.metadata]
allow-direct-references = true

mda build 会把 managed-deepagents 需求重写为对它所暂存运行时的路径引用，而 Hatchling 默认拒绝那个。没有该设置时，mda build 仍会成功，而 mda dev 会在安装项目期间失败，报 Dependency #N of field project.dependencies cannot be a direct reference。由 mda init 搭建的项目不声明构建后端，因此该设置只在转换一个现有项目时才会遇到。

把项目已经声明的每个依赖都保持原样。工具和中间件继续导入它们一直导入的东西。

Rewrite the agent entry

使用上面的表格转换调用点，放在项目根目录一个名为 agent.py 的文件中：

from deepagents import create_deep_agent

from tools.search import internet_search

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[internet_search],
    system_prompt=SYSTEM_PROMPT,
    skills=["/skills/research/"],
    checkpointer=checkpointer,  # yours to construct and wire
)

from managed_deepagents import define_deep_agent

from tools.search import internet_search

agent = define_deep_agent(
    name="research-assistant",
    model="openai:gpt-5.5",
    tools=[internet_search],
)

入口必须导出一个名为 agent 的变量，而定义调用本身必须位于这个文件中。一个把定义从另一个模块重新导出的根入口会失败，且错误会指向 name 而非真正的问题。

否则一个 src/ 布局没问题。把各个包留在它们所在之处，并从根入口导入它们。

Move the prompt, skills, and memory into files

把系统提示放进项目根目录的 instructions.md。在 skills/ 下为每个技能各建一个目录，带一个 SKILL.md。

如果 agent 需要跨线程持久化的记忆，在一个导出名为 memory 变量的根文件中声明它：

from managed_deepagents import define_memory

memory = define_memory(scope="agent")

持久记忆是选择加入的，没有那个文件的项目不挂载任何记忆。作用域是唯一的旋钮："agent" 挂载一棵该部署的每个调用者都共享的树。要控制 agent 在那里保留什么，把一条记忆策略写进 instructions.md。参阅指引要记住什么。

WARNING

define_memory 挂载一棵空的记忆树。旧 memory 参数所指文件中的内容不会迁移，因此在删除那些文件之前，把 agent 仍需要任何东西移到 instructions.md 或某个技能中。

Declare a sandbox

一个传入过沙箱 backend 的 agent 改为需要一个托管沙箱声明。创建该目录并声明它：

from managed_deepagents import define_sandbox

sandbox = define_sandbox(
    idle_ttl_seconds=600,
    default_timeout=600,
)

WARNING

声明一个沙箱会清空 permissions。一条文件系统权限规则会禁用沙箱的 execute 工具，因此运行时丢弃规则而非 shell。请改为通过你赋予它的工具来限制一个沙箱化的 agent。

要预配一个快照，添加 sandbox/setup.sh。对于一个没有沙箱后端的 agent，跳过此步。参阅沙箱。

Declare identity

（可选）要为每个调用者提供私有的线程和下游凭据，添加一个根身份声明：

from managed_deepagents import auth, define_identity

identity = define_identity(auth=auth.langsmith_api_key())

没有那个文件时，部署以无托管身份验证运行，mda dev 将其报告为 Identity none。参阅身份。

Set credentials and ignore the build output

把模型和工具的 API 密钥放进项目根目录的一个 .env 文件。你在 shell 中导出的一个值不会被读取。对于共享的工作区机密和 OAuth，请改用连接。

把构建目录添加到 .gitignore：

.env
.env.*
.mda/

mda build 会把整个项目根目录复制到 .mda/build，而 mda deploy 上传它。任何紧挨着 agent 入口的东西都会随 agent 一起被打包，因此把部署不需要的东西移出项目根目录。

Compile, then run

编译而不部署：

mda build

然后本地启动它：

mda dev

NOTE

mda build 不会检查定义调用，因此即使一个托管参数仍在，它也会以 0 退出。一个遗留的参数会在图在 mda dev 下加载时显现。

参阅本地开发。

Deploy

上传项目并让 LangSmith 构建并托管它：

mda deploy

参阅部署。

TIP

是新建一个 agent 而非迁移一个？脚手架整个项目，包括上面那些身份、沙箱、.env 和 .gitignore 文件：

mda init research-assistant

安装渠道决定编写语言：npm 包脚手架 TypeScript，PyPI 包脚手架 Python。该命令创建一个新目录且不就地运行，因此它适合一个全新项目而非迁移。参阅快速开始。

另请参阅

• 与 Deep Agents 的关系：为何两个入口点不同。
• Agent 定义：完整的参数参考。
• 项目结构：每个文件放在哪里。
• 走向生产：Deep Agents 的部署选项。

---