对话上新消息的 SSE 流。

授权

Authorization

string

header

必填

通过 Authorization: Bearer <token> header 传用户 JWT 或 oag_ User API Key。两者都由 openapi-gateway 对 Auth service 验证。

JWT 与 API Key 都是 user-scoped：每个 key（以及每个 JWT）绑定到唯一 owner，所有路由都自动放开该 owner 名下的全部资源。跨租户访问由 handler 内的 owner-ACL 拦截 —— API 表面没有 per-route scope 词汇。

v1.1.0 已移除：历史 scope 词汇（agents:* / tasks:* / files:* / instances:*）以及 403 insufficient_scope 错误码已下线。已签发的 oag_ key 自动获得 owner 全权限，无需重建。之前显式传 scopes 调用 createAPIKey 的 SDK 客户端可以直接删除该参数。详见文末 changelog 迁移说明。

路径参数

agentId

string

必填

Maximum string length: 128

convId

string

必填

Maximum string length: 128

查询参数

since

integer<int64>

重放 cursor。匹配上次收到事件的 offset 字段 —— 客户端持久化此值、重连时传回来从此 resume，不会有缺口或重复（Last-Event-ID 语义；wire 拼写保留 since 与 v2 前的 SSE 客户端向后兼容）。

特殊值：

省略 / 0 —— 完整历史重放。
<offset> —— 严格在给定 offset 之后 resume。

与 task 变体不同，此流永不在终止信封上自关 —— 对话跨多回合保持开放、继续发 agent_reply 事件。跨重连范围持久化 since 避免网络抖动里丢回合。

必填范围: x >= 0

响应

通道消息信封的 SSE 流。

Server-Sent Events 流。

per-event JSON payload 格式（v3 envelope 字段 body / state / stop_reason / updated_at 当底层行经 v3 路径写入时有值；旧 v1 / v2 行缺这些字段——消费者请回退到 payload.text + type 判断终态）：

event: message
data: {
  "type": "agent_message_chunk",   // 见下
  "message_id": "msg-uuid",
  "offset": 5,                     // 单调 per-channel offset
  "in_reply_to": "msg-source-uuid",
  "publisher_id": "agent-identity",
  "payload": { ... },              // 不透明 per-type
  "body": "Hello, world",          // v3 累计文本（可选）
  "state": "streaming",            // v3 生命周期（可选）
  "stop_reason": "",               // v3 终态原因（仅在 state != streaming 时有值）
  "created_at": "2026-05-14T18:00:00.000Z",
  "updated_at": "2026-05-14T18:00:00.123Z"
}

Backfill 截断帧——服务端把回放窗口截断时只发一次（见 since=<offset> 语义）。客户端看到这帧后应从 latest_offset 继续：

event: backfill_truncated
data: {
  "since": 100,
  "latest_offset": 1500,
  "dropped_count": 1400
}

终止事件：

event: end
data: { "reason": "task_terminal" }    # 仅 task：agent_reply / agent_reply_error / agent.refuse / agent_busy 后自关

event: end
data: { "reason": "stream_closed" }    # MS 关闭上游流

event: end
data: { "reason": "channel_closed" }   # 仅 conversation：调用方（或对方）删除对话

end.reason 枚举：

reason	接入面	何时
`task_terminal`	task	终止回复自关 SSE
`stream_closed`	task + conversation	MS 关上游流
`channel_closed`	conversation	底层通道被删

常见消息 type 值：

type	含义
`chat_message`	调用方 prompt
`agent_thought_chunk`	智能体推理（增量）
`agent_message_chunk`	智能体回复 delta（增量）
`agent_reply_delta`	terminal-bound 流式 delta
`agent_reply`	终止成功回复
`agent_reply_error`	终止失败回复
`agent.input_required`	暂停等 `user.continue`
`agent.auth_required`	暂停等 `user.auth_grant`
`user.continue`	调用方 resume `input_required`
`user.auth_grant`	调用方 resume `auth_required`
`chat_cancel`	调用方发起的 cancel