连续任务与会话

一次推理返回一段动作。要让机器人持续完成任务，你的程序需要反复获取观测、请求动作，并报告实际执行情况。会话将这些轮次关联在一起，记录任务进度，也方便查询每次请求和执行反馈。

使用 本地控制台 时，RoboAPI 会管理这个循环。自行编写控制程序时，先完成 第一次 API 调用，再按下列流程加入会话。

创建会话 → 当前观测 → 模型动作 → 执行与回执 → 下一轮观测 → … → 关闭会话

以下路径都相对接入配置中的 Base URL，使用 Authorization: Bearer <API_KEY>。会话应始终使用同一服务地址与模型 ID；从该服务的 /models 列表选择 MODEL_ID。接入配置与请求格式见 云端 API。

1. 创建会话复制标题链接

发送 POST /sessions，指定任务使用的模型：

{"model":"MODEL_ID"}

响应示例：

{
  "id":"session_1",
  "model":"MODEL_ID",
  "status":"open",
  "next_turn":1,
  "last_request_id":null,
  "history":[],
  "messages":[]
}

保存 id 和 next_turn。后续请求用这两个值关联会话和轮次。

2. 请求当前轮次的动作复制标题链接

向 POST /chat/completions 提交当前图像、状态和指令，并在 metadata 中传入会话 ID 与轮次：

{
  "model":"MODEL_ID",
  "metadata":{"session_id":"session_1","turn":"1"},
  "messages":[{"role":"user","content":[
    {"type":"text","text":"{\"instruction\":\"Pick up the block\",\"state\":[-0.13,-0.46,0.49,0,1,0,0,1]}"},
    {"type":"image_url","image_url":{"url":"data:image/png;base64,<PNG_BYTES>"}}
  ]}]
}

turn 在请求中是字符串。用真实相机图片替换 <PNG_BYTES>，用机器人当前观测替换示例状态。状态与动作的含义见 观测与动作。

响应中的 execute_actions 工具调用包含动作块。保存完整的 choices[0].message、响应头 X-Request-ID 和 metadata.next_turn。下一轮需要原始 assistant 消息及其工具调用 ID，而不只是解析后的动作数组。

3. 报告执行结果并继续复制标题链接

你的控制程序负责校验和执行动作。每个动作块之后，生成与实际执行情况一致的工具回执：

{
  "role":"tool",
  "tool_call_id":"call_0123456789abcdef0123456789abcdef",
  "content":"{\"executed_steps\":1,\"status\":\"completed\"}"
}

这个示例表示只包含一步的动作块已全部派发，且该步执行周期已经结束。实际回执中的 tool_call_id 必须取自模型响应；executed_steps 填实际派发的步数。

执行回执记录控制程序做了什么，不代表机器人已物理到位，也不代表任务目标已经完成。

继续推理时，将 metadata.turn 更新为上一轮返回的 next_turn，并按顺序提交三条消息：

1. 上一轮原始的 assistant 消息。
2. 与该工具调用对应的 tool 执行回执。
3. 新采集的 user 观测，包含当前图像、状态和任务指令。

每次等待当前请求结束，再开始下一轮。不要根据上次预测的动作推算新的 state；应重新读取机器人状态。

4. 查询会话与轮次复制标题链接

保存会话 ID、轮次和 request ID，可以分别查看任务上下文、模型返回的动作和请求处理情况。

例如，查询第 1 轮：

curl "$PLATFORM_BASE_URL/sessions/$SESSION_ID/turns/1" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

PLATFORM_BASE_URL、PLATFORM_API_KEY 使用接入时的配置，SESSION_ID 使用创建会话返回的 id。查询结果中的 succeeded 表示推理请求成功，不能据此判断机器人任务完成。查询到历史动作后也不应自动再次执行。

5. 结束任务并关闭会话复制标题链接

结束任务时，先停止本地动作派发，再向 POST /sessions/{session_id}/close 提交原因和最后尚未报告的消息。

若最后一轮回执已经提交：

{"reason":"stopped","messages":[]}

若仍有尚未报告的动作块，messages 应依次包含该轮原始 assistant 消息及对应的 tool 回执。例如，没有执行任何一步就停止时，回执为 {"executed_steps":0,"status":"interrupted"}。

响应返回会话对象，status 为 closed。可以再通过 GET /sessions/{session_id} 查看关闭状态和最后的执行记录。停止机器人不应依赖关闭请求是否成功。

本地任务、运行与云端会话复制标题链接

使用 RoboAPI 时，这三个概念分别对应不同记录：

停止后重新启动相同指令，且未选择新任务时，默认继续当前本地任务，但会创建新的运行与云端会话。需要单独保存为新任务时，使用控制台的新任务入口，或通过本地 HTTP API 在启动请求中设置 new_task: true。MCP 的 robot_start_policy 不提供这个参数。

运行中从网页再次发送指令，即使文字相同，也会先停止，再创建新任务、运行和云端会话。HTTP/MCP 的活动指令更新则在下一轮推理生效：指令变更会切换本地任务记录，当前运行与云端会话继续。

RoboAPI 本地运行时要求复制标题链接

自行接入 RoboAPI 0.4.5 本地运行时时，模型服务还需要满足下列协议。运行时会校验响应，字段缺失或不匹配时以 invalid_response 结束运行。

初始化向导和控制台通过 GET /models 获取可用模型，使用所选条目的实际 ID。控制台中先 连接、选择模型，再 保存；获取列表本身不保存凭据或创建会话。连接配置与操作见安装指南。