本教程面向第一次接触方舟 Managed Agents 的开发者。你将先认识 Agent、Skill、Environment、Session 和 Event 五个核心对象，再以一个售后工单分诊场景跑通完整链路。

完成后，你会得到一个绑定了工单分诊 Skill 的 Agent，并能在同一个 Session 中连续发送两轮消息：第一轮提交故障现象，第二轮补充新的线索。Agent 会沿用上一轮的上下文继续判断，而不是重新开始。

先理解五个核心对象

对象	它负责什么	本教程中的对应实例
Agent	定义模型、系统指令、Tools 和 Skills，是可复用的智能体配置	售后工单分诊助手
Skill	把一类任务的知识、流程、约束和输出格式打包成可复用能力	工单分诊 SOP
Environment	定义 Session 使用的云端运行环境	一个隔离的 cloud 环境
Session	保存一次任务的上下文、状态和事件历史	某一张客户工单的处理过程
Event	向 Session 追加输入，或记录 Agent 回复、工具调用和状态变化	user.message、agent.message、session.status_idle

五者的关系可以概括为：Agent 决定「谁来做、会什么」，Environment 决定「在哪里做」，Session 承载「这一次具体任务」，Events 记录「任务如何一步步发生」。

其中最重要的一点是：Session 不是一次请求，而是一段可持续推进的任务上下文。每次调用 POST /sessions/{session_id}/events 都是在这个 Session 中追加一个新的回合，而不是重开一次模型调用。

你将跑通的场景

假设客服收到一张「升级客户端后无法登录」的工单。第一轮只有基础现象；Agent 按 Skill 输出初步分诊和需要补充的信息。随后客服拿到「账号刚迁移过，旧租户仍能登录」的新线索，并把它作为第二条消息发送到原 Session。Agent 应结合两轮信息更新判断和下一步动作。

本场景特意不接入 CRM、工单系统或知识库，目的是先看清 Managed Agents 的最小运行链路。跑通后，再把真实业务查询封装成 MCP Tool 即可。

准备环境

先设置 API 地址和 API Key。API Key 只应保存在本地环境变量或服务端密钥系统中，不要硬编码在代码中。

本地需安装 curl 7.76.0 或更高版本、zip 和 jq。运行以下命令确认版本：

创建并上传 Skill

Skill 是一个包含 SKILL.md 的目录。本教程创建的 Skill 不负责调用外部系统，而是把工单分诊的步骤、约束和输出格式固化下来。

先创建目录：

在 customer-support-triage/SKILL.md 中写入：

打包时保留顶层目录：

上传 Skill：

id 标识这项能力，latest_version 标识当前最新版本。Agent 绑定的是明确的 Skill 版本，因此更新 Skill 后需要把 Agent 配置更新到新版本，运行中的旧 Session 不会被悄悄改变。

创建 Agent 并绑定 Skill

创建 Agent 时，把刚上传的 Skill 放入 skills。系统指令只描述稳定角色和边界，具体的分诊流程交给 Skill 管理。

创建 Environment

Environment 是 Session 的运行基础设施。本场景不需要额外 Python 包，只创建一个最小 cloud 环境。

创建 Session

现在创建一张具体「工单」。请注意 agent 是对象，Agent ID 放在 agent.id 中。

ARK_SESSION_ID 是后续所有消息和事件查询的共同地址。只要任务仍然属于同一张工单，就应复用这个 Session。

先订阅 Events，再发送第一条消息

发送消息使用以下接口：

请求体中的 events 是事件数组，但一次请求只放一个 user.message，不要把多个用户回合打包在一起。

先定义一个单轮执行函数。它会建立 SSE 流，等待服务端返回 : ready，再发送消息并持续读取到会话终态：

发送第一条消息：

这个调用表示「把一条用户消息追加到已有 Session」，不是新建一次模型调用。SSE 就绪后，服务接收消息，Session 从 idle 进入 running，Agent 随后产生回复、工具调用和状态事件。

入门阶段重点关注三类事件：

事件	含义	应用中的典型展示
agent.tool_use	Agent 正在调用工具	展示工具名称和进行中状态
agent.message	Agent 产生了可展示的回复	渲染文本或交付物
session.status_idle 且 stop_reason.type=end_turn	当前回合正常结束，Session 可接收下一条消息	收起过程事件，展示最终回复和继续输入框

session.status_idle 表示 Session 当前暂停处理，但不一定表示正常完成。应继续检查 stop_reason.type：

end_turn：本轮正常结束。

requires_action：客户端需要根据 stop_reason.event_ids 处理需要确认或需要回传的工具事件。

retries_exhausted：自动重试已耗尽，需要根据 session.error 排查原因。

不要只以收到第一条 agent.message 作为完成信号，因为 Agent 后续仍可能继续调用工具或补充回复。run_session_turn 会执行上述判断；SSE 意外断开时，函数会先建立替代流，再分页补查历史事件并按事件 ID 去重。

在同一 Session 继续发送消息

现在模拟客服拿到新线索。不要创建新 Session，继续使用 run_session_turn 向原来的 ARK_SESSION_ID 追加 user.message。函数会为新一轮重新建立 SSE 流，并在确认 : ready 后发送消息：

函数收到新的 session.status_idle 且 stop_reason.type=end_turn 后返回。这一次 Agent 应能识别「上一轮」指什么，并把租户迁移线索与最初的登录故障合并分析。

这就是 Session 的核心价值：

同一个 Session 保留任务上下文、事件历史和运行状态；

每个 POST /events 只推进一个用户回合；

上一轮以 session.status_idle 且 stop_reason.type=end_turn 结束后，再发送下一轮；

如果创建新 Session，新的任务不会自动继承这张工单的上下文。

Session 发消息时最容易出错的地方

现象	常见原因	正确处理
后续消息没有继承上文	每一轮都创建了新 Session	业务任务未结束时复用同一个 session_id
消息请求被拒绝	上一轮仍在运行，或 Session 正在等待客户端处理工具事件	等待 session.status_idle，并确认 stop_reason.type=end_turn 后再发送下一条消息
一次请求里塞了多轮对话	一个 Events 请求包含多个 user.message	每次请求只发送一个 user.message
页面过早显示「已完成」	收到 agent.message 或任意 session.status_idle 就结束监听	同时检查 session.status_idle 和 stop_reason.type=end_turn
重连后出现重复事件	SSE 重连后重复消费历史事件	按事件 id 去重，并保存最后已处理位置
API Key 泄漏	浏览器直接调用 Managed Agents API	由业务后端保管 Key、发送消息和消费 SSE

把它嵌入自己的业务

在真实应用中，建议由业务后端维护「业务对象 ID 到 Session ID」的映射。例如一张工单、一个研究任务或一个代码修复任务，各对应一个 Session。前端只把用户输入交给业务后端；业务后端再追加 user.message、消费 SSE，并把标准化的进度推给前端。

前端可以把 agent.tool_use 展示为可折叠的执行过程，把最后的 agent.message 展示为正式结果，并在收到 session.status_idle 且 stop_reason.type=end_turn 后恢复输入框。这样用户既能看到 Agent 正在做什么，也能在同一任务中继续补充要求。

你刚才完成了什么

你已经完成了 Managed Agents 的最小闭环：把组织流程写成 Skill，绑定到 Agent，创建 Environment 和 Session，通过 Events 发送消息，再以 session.status_idle 和 stop_reason.type=end_turn 判断一轮正常结束。更重要的是，你没有把第二条要求当成一项新任务，而是复用了原 Session，让 Agent 基于已有上下文继续工作。

下一步可以选择一个方向扩展：

把 CRM、工单或知识库接成 MCP Tool；

给 Session 挂载文件或 Memory；

把 Events 映射成产品中的过程状态；

为高风险工具增加用户确认和幂等控制。

火山方舟