Skip to main content
如果你已经基于模型推理 API 自建了智能体循环——自己维护消息历史、自己执行工具、自己处理失败重试——本指南说明如何把这套系统迁移到托管智能体，把运行时交给平台，只保留真正属于你的部分。
迁移不要求任何 SDK 兼容层：托管智能体就是一组 HTTP + SSE 接口，用 curl 或任意 HTTP 客户端即可调用。以下示例的 API Key 从环境变量 KIMI_API_KEY 读取；未设置 API_BASE_URL 时，请求地址默认使用 https://api.moonshot.cn。

​
什么变了

自建 Harness 时，运行时的一切都由你的代码负责。迁移后，这些职责交给平台托管： 迁移的本质是：把「怎么运行」交给平台，把「是什么任务」留在你的配置和代码里。

​
迁移步骤

1

把系统提示词、工具定义、技能搬进 Agent 配置

把原来代码里的系统提示词、工具 schema 等「怎么干」的内容，收敛为一个持久化的 Agent 配置对象。智能体创建一次即可跨会话按 ID 引用，每次更新生成不可变的新版本。
原来「循环内硬编码」的内容对应关系：
  • 系统提示词 → 智能体的 system 字段；
  • 原来在客户端执行的业务工具 → 先通过 MCP 工具接入，或暂时保留在自建流程中；
  • 原来手写的工具函数（搜索、读写文件、跑命令）→ 智能体默认获得云沙箱的内置工具（文件读写、代码执行、搜索等），无需声明，删掉你的实现；
  • 成体系的领域经验（提示词 + 脚本 + 模板）→ 打包为 技能 挂载。
智能体字段与版本机制详见 创建与管理智能体。
2

删除自建的智能体循环与消息历史存储

这是迁移中「删代码」的一步。以下组件可以整体移除：
  • 「调模型 → 解析工具调用 → 执行 → 回填结果 → 再调模型」的主循环；
  • 消息历史的拼接、截断与持久化存储；
  • 崩溃恢复、断线续跑、超时重试的兜底逻辑。
上下文压缩、历史管理、中断恢复都由平台承担，你不再需要在每次请求时回传完整消息列表。
3

改为创建会话、订阅事件流、发送事件

原来「调用一次模型推理 API」的交互，换成「创建会话 → 订阅事件流 → 发送事件」三步。AGENT_ID 为 Step 1 创建响应中的 id，SESSION_ID 为创建会话响应中的 id，ENVIRONMENT_ID 为执行环境的 ID：
建议先订阅事件流再发送消息，避免漏掉二者之间产生的事件。事件流支持断线续读：重连时携带 Last-Event-ID 请求头即可从断点继续，详见 事件流。
会话的创建、状态与生命周期详见 会话。

​
不用迁移什么

以下能力由平台承担，迁移时不需要在你的系统中重建：
  • 会话历史持久化：事件历史在服务端持久化，可随时完整拉取，无需自建消息存储；
  • 断线恢复：事件流断线后按游标续读；平台故障后执行自动接管并恢复，恢复后行为与中断前一致；
  • 超时重试：执行层的重试、调度与上下文压缩由平台负责，客户端只需处理自身请求的错误码。
如果你更想继续自建智能体循环、精细控制每一轮模型调用，请使用 模型推理 API；托管智能体适合把长程任务的运行时整体托管出去的场景。

​
下一步

智能体

把系统提示词与工具定义收敛为版本化的 Agent 配置。

会话

创建会话、发送事件，替代自建的智能体循环。

事件流

订阅事件、断线续读与完整事件类型说明。