将零代码应用迁移至 Managed Agents

本文介绍如何将应用实验室中通过 Bot API 调用的零代码应用迁移至 方舟 Managed Agents。内容覆盖迁移判断、配置映射、资源创建和结果验证，帮助你基于原零代码应用配置重建 Agent 和调用链路。

本文仅适用于已发布、通过 Bot API 调用的零代码应用。其中，单聊应用可以按本文步骤迁移；群聊应用需要先重新设计角色和编排方式，不能直接复用单聊迁移方案。

迁移的核心不是替换一个接口地址，而是把原应用中可复用的配置映射到 Agent，再创建新的 Environment 和 Session 运行资源。

场景说明#

在存量业务中，你可能已经在应用实验室中创建并发布零代码应用，再通过 Bot API 调用它，完成客服问答、运营助手或内部知识查询等任务。

已发布的存量零代码应用仍可继续通过 Bot API 调用。应用实验室后续会下线新建零代码应用入口，具体时间以后续公告为准；入口下线后，将无法再创建新的零代码应用。存量业务可以根据能力需求安排迁移，无需因新建入口下线立即切换调用链路。

随着业务复杂度提升，单次对话接口也会逐渐遇到边界：应用能力类型有限、上下文需要自己维护，复杂任务也缺少沙箱执行环境。

Managed Agents 将 Agent 运行所需的通用能力拆成平台资源。你定义 Agent 行为，选择 Environment 提供执行环境，再通过 Session 发送事件并订阅结果流。这样可以把“调用一个应用”升级为“托管一个可执行、可观测、可扩展的 Agent”。

本文会帮助你完成以下动作：

• 判断一个存量零代码应用适合迁移到 Managed Agents，还是应改用模型 API。
• 将零代码应用中可复用的配置映射为 Agent 配置。
• 创建 Agent 运行所需的 Environment 和 Session。
• 选择控制台或 API 路径重建 Agent。
• 记录 agent_id、environment_id 和 session_id，供业务服务后续调用。
• 用原零代码应用的真实问题集验证迁移后的回答结果和工具调用。

判断是否需要迁移#

先根据应用类型、调用方式和目标能力判断迁移优先级，再准备迁移材料。

判断迁移优先级时，同时对照原零代码应用能力和 Managed Agents 能力。两者并非一一对应，迁移前需要明确哪些配置可以复用，哪些能力需要重新设计。

准备迁移材料#

确认适合迁移到 Managed Agents 后，再准备以下信息和资源。不要在没有完成能力映射前直接创建 Agent，否则后续容易反复修改模型、工具和知识来源。

• 准备一个已发布、可通过 Bot API 调用的零代码应用，或导出该应用的名称、描述、推理接入点和系统提示词。
• 导出应用的能力配置。
• 准备 5 到 10 个真实问题，用于迁移后的回归测试。
• 开通方舟，并准备可调用 Managed Agents 的 API Key。
• 确认目标 Model ID。本文示例使用 doubao-seed-2-1-pro-260915，实际迁移时替换为你的 Model ID。
• 选择知识来源。原应用使用知识库插件时，确认知识内容适合整理为记忆存储中的静态参考资料，还是需要通过 MCP 或自定义工具接入原知识服务。

迁移时会用到以下核心对象：

迁移操作流程#

迁移操作分为控制台和 API 两条路径。先人工验证配置时，选择控制台路径。已经在业务代码中调用 Bot API 时，选择 API 路径。

整体执行顺序如下：

1. 梳理原零代码应用的配置和真实问题集。
2. 判断要继续维护应用、改用模型 API，还是迁移到 Managed Agents。
3. 按能力映射表重建 Agent 配置。
4. 根据运行需求创建或选择一个 Environment。
5. 创建 Session，并把一次输入消息发送为 user.message 事件。
6. 订阅事件流，检查 Agent 回复、工具调用和最终状态。
7. 对比原零代码应用和新 Agent 的输出，调整提示词、工具和知识来源。
8. 小流量切换业务调用，确认稳定后再扩大迁移范围。

路径一：通过控制台迁移#

如果你希望先用可视化方式验证迁移效果，使用 Managed Agents 控制台更合适。

1. 打开 Agents 页面，创建 Agent。
2. 将原应用的名称、描述和系统提示词填写到 Agent 的对应配置中。
3. 选择 Managed Agents 支持的模型，并按能力映射表重新配置工具、技能、MCP 和知识来源。
4. 创建 Environment，配置 Agent 运行所需的网络、依赖包、环境变量和产物存储。
5. 创建绑定 Agent 与 Environment 的 Session，使用原应用的典型问题完成回归测试。
6. 记录 agent_id 和 environment_id。业务服务使用这两个 ID 创建 Session，再通过 Session 事件接口发送消息和订阅事件。

路径二：通过 API 迁移#

如果你已经在业务代码中调用 Bot API，建议用 API 方式完成迁移。新的调用链路不是把 Bot ID 替换为 Agent ID，而是从一次 POST /bots/chat/completions 调用，改为先创建 Agent 和 Environment，再创建 Session、发送事件并订阅事件流。

API 迁移时，三个 ID 的传递关系如下：

1
2agent_id + environment_id -> 创建 session -> session_id
session_id + user.message -> 触发 Agent 执行 -> Session 事件流

创建 Agent 后，记录返回的 agent_id。创建 Environment 后，记录返回的 environment_id。创建 Session 后，记录返回的 session_id。业务服务后续发送消息和订阅事件，都围绕 session_id 执行。

你可以直接复用 快速入门（代码） 中的端到端示例：

• 创建 Agent：参考 1. 创建 Agent。
• 创建环境：参考 2. 创建环境。
• 创建 Session：参考 3. 开启会话。
• 发送消息并接收流式响应：参考 4. 发送消息并流式接收响应。

验证迁移结果#

迁移后，用原应用的真实用例验证以下结果：

• Agent 能按原系统提示词完成基础问答。
• 开启联网能力后，事件流中能看到 web_search 或 web_fetch 相关工具调用。
• 需要读写文件或运行脚本时，事件流中能看到 bash、read、write 等工具调用。
• 需要知识库能力时，答案能使用记忆存储、MCP 或自定义工具提供的信息。
• 业务侧收到完整的 agent.message，随后收到 stop_reason.type = "end_turn" 的 session.status_idle。

期望看到的事件轨迹如下：

1
2
3
4
5
6user.message           发送原零代码应用回归问题
agent.message_delta    Agent 开始生成回复
agent.tool_use         调用 web_search、web_fetch、bash、read 或 write
agent.tool_result      返回工具执行结果
agent.message          输出完整回复
session.status_idle    stop_reason.type = end_turn

如果 session.status_idle 的 stop_reason.type 为 requires_action，表示 Session 正在等待工具确认或结果，并不表示迁移用例已经执行完成。先处理对应的阻塞事件，再继续等待最终回复。

如果事件流里没有出现预期工具调用，先检查 Agent 的工具配置，再检查系统提示词中是否明确说明了何时调用工具。

常见问题#

新建零代码应用入口下线时间#

当前尚未公布新建零代码应用入口的下线时间，具体时间以后续公告为准。入口下线后将无法再创建新的零代码应用，已发布的存量应用仍可继续通过 Bot API 调用。

继续使用现有零代码应用#

可以。已发布的存量零代码应用仍可继续通过 Bot API 调用。对于简单问答，特别是客服、车载助手等多轮对话场景，建议迁移到 Managed Agents，通过 Memory 读写持续使用用户偏好和历史信息；需要自行控制调用链时，可以改用模型 API。

迁移后的计费#

Managed Agents 与 Bot API 使用同一套方舟账号和 API Key 体系。Managed Agents 会按 Agent 运行过程中的模型 token、Agent 运行时长和工具调用次数计费，详情参见 Managed Agents 计费。

迁移知识库插件#

记忆存储不等同于带检索和重排能力的知识库。应用中的少量静态参考内容可以整理到记忆存储；已有外部知识服务可以通过 MCP 或自定义工具接入。需要保留检索、重排或来源引用能力时，不要直接使用记忆存储替代原知识库插件。

迁移联网搜索能力#

在 Managed Agents 中，联网搜索是 Agent 可主动调用的工具。迁移时，你需要在 Agent 工具集中启用 web_search 和 web_fetch，并在系统提示词中说明何时联网、如何使用搜索结果、是否需要标注来源。原联网内容插件中的内容源、问题改写、引用条数和来源展示配置不会自动迁移，需要逐项重新验证。

相关文档#

• 通过 快速入门（控制台） 创建和调试 Agent。
• 通过 快速入门（代码） 将 Agent 接入业务代码。
• 通过 Tools 配置内置工具集。
• 通过 持久化记忆 为 Agent 挂载长期记忆。
• 通过 编排 Multi Agent 将复杂任务按职责委派给多个 Agent。