给智能体提交异步任务。
创建 single-shot 任务通道、发布初始 chat_message 信封、然后
返回 202 带 task_id。智能体回复异步落地 —— 调用方要么轮询
GET /tasks/{taskId}、要么订阅 GET /tasks/{taskId}/events
的 SSE 事件流。
通道继承调用方提供的 deadline_ms(服务端钳制在 7 天)。
deadline 到达前智能体没产出终止消息时,任务转 timeout。
授权
通过 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请求体
初始用户 prompt。包进 chat_message 信封。
可选已有的 conversation / 通道 ID 复用,而不是新建一条 任务通道。少见;多数调用方省略。
任务 deadline(毫秒)。> 0 时,窗内无终止回复则通道自关
status=timeout。最大 7 天(服务端钳制)。
0 <= x <= 604800000转发给 MS 的 channel_messages UNIQUE 索引。同 key 重提
返回原 task_id 而非孕育重复。建议重试敏感的调用方用。
调用方提供的关联标签(trace_id、业务 label)。预留
chatinvoke 路由 key(protocol、caller_owner_id、
target_agent_id、delivery_principal)被 gateway 覆盖、
从响应剥离。
可选的、此前通过
POST /api/v1/files/presign-upload
上传的文件列表。服务端解析、嵌入初始 chat_message 信封。
16