会话 (Conversations)

受众：构建聊天 UI、多轮 assistant、或者任何需要给同一智能体发 多条消息而不重建上下文的工作流的 SDK 用户。

如果你只需要单次 request/reply 或带 deadline 的单个长任务，请改看调用智能体。

1. 我该选哪个

┌────────────────────────────────────────────────────────────────────┐
│ 单条 prompt、单条回答、转身就走？                                  │
│       → POST /agents/{id}/invoke    (同步 / SSE / 异步)            │
│                                                                    │
│ 一个大背景任务、完成后自动关闭？                                   │
│       → POST /agents/{id}/tasks     (任务 API，带 deadline)        │
│                                                                    │
│ 开放式聊天 —— 多轮、同上下文、无固定终点？                         │
│       → POST /agents/{id}/conversations  (本指南)                  │
└────────────────────────────────────────────────────────────────────┘

任务和会话都骑在 Message Service 同一根底层消息通道上 —— 差别纯粹是网关层的 UX 选择：

属性	任务 (Task)	会话 (Conversation)
`single_shot`	`true` —— 通道在首次终止回复后自动关闭	`false` —— 多轮间保持开放
Deadline	create 时的 `deadlineMs`，过期 MS 自动关闭（最大 7 天）	无 —— Redis 自然 24h 未活动 TTL；活跃 SSE / `POST /messages` 续期
状态机	`pending` → `processing` → `completed` / `failed` / `cancelled`（ADR-0017）	朴素 `state` 字段：`open` 或 `closed`
生命周期终止	首次终止回复自动关通道；`POST .../cancel` 中断飞行中	`DELETE /conversations/{id}` 关闭；否则活到 TTL
`POST /messages` 语义	不适用 —— 初始消息就是 create body	非阻塞 202；回复通过 SSE / history 到达
Webhook 投递	有 —— `POST /tasks/{id}/webhooks`（见 Webhook 指南）	无 —— 通过 SSE / 轮询观察
SSE 自动关闭	终止信封（`agent_reply`、`agent_reply_error` 等）触发关闭 —— `event: end reason=task_terminal`	一直开到 `DELETE` 或客户端断开 —— 删除时 `event: end reason=channel_closed`
调用方回合预算	每次重试是独立任务（或 `POST /continue` 续传暂停）	每会话多轮；允许分层并发

经验法则：

聊天 UI → 会话
Cron 任务 / 后台进程 / 批处理报告 → 任务
一次性问答 → 阻塞 invoke（最简）

2. 生命周期（会话）

┌────────────────┐  POST .../conversations          ┌──────────────┐
│  (无通道)      │ ──────────────────────────────▶ │  state=open  │
└────────────────┘   201 + conv_id                  └──────┬───────┘
                                                            │
              ┌─────────────────────────────────────────────┤
              │                                             │
              │ POST .../messages         GET .../events    │
              │ (202, 异步)               (SSE, 实时)       │
              │ POST .../messages         GET .../messages  │
              │ (202, 异步)               (分页)            │
              │  ...                       ...              │
              │                                             │
              │ DELETE .../conversations/{id}               │
              ▼                                             ▼
        ┌─────────────────┐                       SSE: event: end reason=channel_closed
        │  state=closed   │ ◀────  CloseReason="canceled"
        └─────────────────┘
              │
              │ MS 宽限窗口（关闭后 5 分钟）
              ▼
        history 仍可通过 GET .../messages 读
              │
              │ TTL（Redis 默认 24h since last touch）
              ▼
        通道被驱逐；后续读 → 404

注：会话没有 chat_cancel 信封。没有单一飞行中的回合可中断 —— 如果想阻止智能体继续最近一轮，DELETE 整个会话（关闭通道）。智能体收到正常通道关闭信号并停止流式输出。

3. 五个会话端点

全部需要 Authorization: Bearer <JWT or oag_...>。oag_ key 是 user-scoped 的：任何 key 只要 owner 拥有底层会话，就能调用以下全部端点（鉴权模型见认证与 API Key —— v1.1.0 起 per-route scope 已下线）。

方法	路径	用途	Body	返回
`POST`	`/api/v1/agents/{agentId}/conversations`	创建一条新对话通道	`{ title?, metadata?: {...} }`	`201` + `Conversation`
`GET`	`/api/v1/agents/{agentId}/conversations`	列出调用方与该智能体的会话	—	`200` + `{ conversations, next_since }`
`GET`	`/api/v1/agents/{agentId}/conversations/{convId}`	取一个会话	—	`200` + `Conversation`
`DELETE`	`/api/v1/agents/{agentId}/conversations/{convId}`	关闭该会话	—	`204`
`POST`	`/api/v1/agents/{agentId}/conversations/{convId}/messages`	发送一个用户回合（非阻塞）	`{ message, idempotency_key? }`	`202` + `{ message_id, created_at }`
`GET`	`/api/v1/agents/{agentId}/conversations/{convId}/messages`	分页历史	`?since=<offset>&limit=<n>`	`200` + `{ messages, latest_offset }`
`GET`	`/api/v1/agents/{agentId}/conversations/{convId}/events`	SSE 实时流	`?since=<offset>`	SSE 流

授权不变量：调用方只能看到 / 修改自己的会话。会话的 metadata.caller_owner_id 在 create 时写入；每次读写调用都检查。所有权不匹配返回 403 forbidden（"conversation is not owned by caller"）。

4. `since` cursor（历史 + SSE）

since 是会话单调消息日志上的整数 offset。wire 把它当不透明值，但模型如下方便你推理：

offset:    1     2     3     4     5     6      latest_offset = 6
           │     │     │     │     │     │
        user.q1 agent agent agent user.q2 agent_reply.q2
                ^chunk ^chunk reply.q1

since=0（或省略）—— 从头开始。给晚到 SSE 客户端取完整 transcript 用。
since=N —— 从 offset N+1 续传。传入你成功观察到的最后一个 offset。

`GET /messages`

GET /api/v1/agents/agent_abc/conversations/conv_xyz/messages?since=4&limit=200
{
  "messages": [
    { "offset": 5, "type": "chat_message", "message_id": "m_...", ... },
    { "offset": 6, "type": "agent_reply",  "message_id": "m_...", ... }
  ],
  "latest_offset": 6
}

用上一页的 latest_offset 作为下一次 since。页大小：默认 200，最大 500（Message Service 上限）。

`GET /events`（SSE）

GET /api/v1/agents/agent_abc/conversations/conv_xyz/events?since=4

流先回放所有 offset > 4 的消息，然后保持连接接收新消息。每个 frame：

event: message
data: {"type":"agent_message_chunk","message_id":"m_...","offset":7,
       "in_reply_to":"m_q2","publisher_id":"agent:abc",
       "payload":{"text":"hello"},"created_at":"2026-05-14T18:00:00Z"}

offset 逐 frame：追踪最新一个，重连时作为 since=<latest> 传入。崩溃后重连的 SSE 客户端不要传 since=0 —— 那会重放全部历史，让你处理过的每个事件重复。
event: end（带 reason）在连接终止前发一次。可能的 reason：
- channel_closed —— 你（或同认证的对端）对这个会话调了 DELETE。
- stream_closed —— Message Service 关了上游流（罕见；通常是服务重启或会话 TTL 到了）。

会话上没有任务 SSE 的 task_terminal end reason 等价物 —— 开放式模型里没有终止 frame。连接只在关闭 / 断开时结束。

Keepalive

空闲期连接没流量。浏览器和某些 HTTP 代理会在 ~60s 后关闭 idle 连接。缓解：

把客户端放在不会杀 idle SSE 的代理后（大多数 CDN 原生处理 SSE）；或
socket 关闭就重连，把最新观察到的 offset 作为 since=<offset> 传入，避免漏事件。

5. 实例 —— 聊天循环（Node.js fetch + EventSource）

const BASE = "https://openapi.beeos.ai";
const headers = { Authorization: `Bearer ${process.env.BEEOS_API_KEY}` };

// 1. open a conversation
const created = await fetch(
  `${BASE}/api/v1/agents/agent_abc/conversations`,
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ title: "Customer support — order #12345" }),
  },
).then((r) => r.json());
const convId = created.data.id;

// 2. start streaming agent replies
const es = new EventSource(
  `${BASE}/api/v1/agents/agent_abc/conversations/${convId}/events`,
  { withCredentials: true } as any, // SDK passes the token via header
);

let latestOffset = 0;
es.addEventListener("message", (evt) => {
  const frame = JSON.parse(evt.data);
  latestOffset = frame.offset ?? latestOffset;
  if (frame.type === "agent_message_chunk") {
    process.stdout.write(frame.payload.text);
  } else if (frame.type === "agent_reply") {
    console.log("\n[turn complete]\n");
  }
});
es.addEventListener("end", (evt) => {
  const { reason } = JSON.parse(evt.data);
  console.log(`stream ended: ${reason}`);
  es.close();
});

// 3. send turns whenever the user types
async function send(userMsg: string) {
  const r = await fetch(
    `${BASE}/api/v1/agents/agent_abc/conversations/${convId}/messages`,
    {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ message: userMsg }),
    },
  );
  if (r.status !== 202) throw new Error(`send failed: ${r.status}`);
  // 202 — reply arrives via the SSE stream above.
}

await send("Hi, where's my order?");
// later...
await send("Can you also cancel item 2?");

6. 并发、幂等、附件

多个飞行中回合

会话 API 显式允许在智能体回复上一回合前排队多回合。回复按智能体产出顺序到达；每个 agent_reply 的 in_reply_to 字段回指最初的用户 message_id，所以即使回合交错，客户端也能关联。

幂等

在 POST /messages 上传 idempotency_key。Message Service 在 (channel_id, idempotency_key) 上去重。网络重试同样 key 返回已存在的 message_id 不重发 —— 可安全接入自动重试。省略时网关生成新 UUID，所以不同 fetch 尝试的重试被当作不同消息。

附件

会话接受附件的方式与 invoke 和 tasks 一致 —— 通过 POST /api/v1/files/presign-upload 上传，然后把返回的 file_id 包到下一个 POST /messages body：

{
  "message": "Here is the screenshot",
  "attachments": [{ "file_id": "file_abc" }]
}

网关把每个 file_id 解析成一个预签 download URL 嵌入 chat 信封，让智能体带外取字节。完整流程见调用智能体 § 附件。

7. 删除语义

DELETE /api/v1/agents/{agentId}/conversations/{convId}
204 No Content

发生了什么：

通道以 reason=canceled 关闭。
/events 上的任何 SSE 连接收到最后一个 event: end\ndata: {"reason":"channel_closed"}\n\n，流终止。
会话现在是 state=closed —— 后续 POST /messages 返回 409 conflict （"channel closed"）。
历史在关闭后 5 分钟的 MS 宽限窗口内仍可通过 GET /messages 读；之后通道被驱逐，读返回 404 agent_not_found （"conversation not found"）。

如果想无限期保留 transcript，在调 DELETE 之前取出所有消息 —— 网关不是长期归档，只是 Message Service 受 TTL 约束的日志。

8. 错误

完整集合见错误参考。此 API 上你最可能撞到的：

HTTP	`code`	原因
`400`	`invalid_param`	`convId` 空，或 `conv_id` 属于和 URL 路径不同的智能体
`400`	`invalid_param`	`conv_id refers to a non-conversation channel` —— 你在会话端点上用了任务 ID
`403`	`forbidden`	该会话不是你的
`404`	`agent_not_found`	会话不存在或已掉出 MS TTL
`409`	`conflict`	通道已关闭（如 `DELETE` 后 `POST /messages`）
`413`	`payload_too_large`	消息 body > 1 MiB —— 拆成多回合或用附件装大 blob
`503`	`agent_unavailable`	`MESSAGE_SERVICE_URL` 未配置、MS 挂了，或智能体离线（仅 `POST /messages`；list / get / SSE 在历史日志上仍工作）

9. 另请参阅

调用智能体 —— 三种单回合调用模式
流式（SSE） —— /events 端点的 wire framing、 since 语义、重连 / keepalive 完整参考
Webhook —— 任务 API 的 push 通知（会话无等价物）
错误参考 —— 会话端点可能发出的每个 code
认证与 API Key —— 凭证格式与 owner-ACL 鉴权模型
OpenAPI 契约： backend/openapi/beeos-platform-v1.yaml （在 paths 里搜 conversations:）

​1. 我该选哪个

​2. 生命周期（会话）

​3. 五个会话端点

​4. since cursor（历史 + SSE）

​GET /messages

​GET /events（SSE）

​Keepalive

​5. 实例 —— 聊天循环（Node.js fetch + EventSource）

​6. 并发、幂等、附件

​多个飞行中回合

​幂等

​附件

​7. 删除语义

​8. 错误

​9. 另请参阅

1. 我该选哪个

2. 生命周期（会话）

3. 五个会话端点

4. `since` cursor（历史 + SSE）

`GET /messages`

`GET /events`（SSE）

Keepalive

5. 实例 —— 聊天循环（Node.js fetch + EventSource）

6. 并发、幂等、附件

多个飞行中回合

幂等

附件

7. 删除语义

8. 错误

9. 另请参阅