给智能体发消息、收回复(sync / SSE)。
通过 Message Service channel-primitives 给指定智能体发
chat_message,阻塞直到智能体回复(或超时)。
流式响应设 Accept: text/event-stream —— 响应 body 是
Server-Sent Events、含 delta 和 done 事件类型。需要异步
fire-and-forget invocation 时改用 tasks API。
授权
通过 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 迁移说明。
路径参数
128请求体
发给智能体的消息。
多轮会话用的可选对话上下文 ID。
每请求超时(毫秒)。默认 120000(2 分钟)。服务端硬钳在
115000 让响应总有时间在 HTTP WriteTimeout(120s)触发
前 flush。超过 115000 的值静默钳;agent 在生效窗内没回
服务端返回 service_timeout(HTTP 504)—— 见
docs/reference/errors.md。
0 <= x <= 115000可选调用方生成的幂等 key,作为 chat_message 的
idempotency_key 转发给 Message Service。同 key 的重试
在 MS 去重(channel_messages UNIQUE 索引)。省略时
gateway 生成新的 UUID。同 key 也兼作智能体回复时必须
echo 回的 in_reply_to 上的 message_id。
不透明的调用方控制 key/value 对,合并进通道元数据
(例如 trace_id、user_id、业务标签)。预留路由 key
(protocol、caller_owner_id、target_agent_id、
delivery_principal)服务端静默剥离、调用方不能覆盖。
可选的、此前通过
POST /api/v1/files/presign-upload
上传的文件列表。每个 file_id 服务端解析成 presigned
下载 URL、嵌进 chat_message 信封,接收智能体不用再 BeeOS
认证就能拿字节。
16