切换主题
聊天与任务
使用 USER 或 APP_ADMIN 业务身份。所有 Run、事件、确认与会话按应用、用户和租户所有权校验。POST chat 显式使用 Accept，JSON 返回 202，SSE 返回 200 流。
同次创建请求保留 Idempotency-Key，同键同正文复用 Run，同键不同正文冲突。会话只能有一个活动任务。confirm 正文只提交确认标识与决策，不能替换参数。取消不撤销已经到达业务系统的副作用。
POST /v1/apps/{app}/chat
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| Idempotency-Key | header | 否 | string；— |
请求正文
Content-Type：application/json；正文必填。
类型：ChatRequest。—
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | text/event-stream | string |
| 202 | application/json | Run |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
GET /v1/apps/{app}/runs/
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | Run |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
GET /v1/apps/{app}/runs/{runId}/events
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
| Last-Event-ID | header | 否 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | 数组：AgentEvent |
| 200 | text/event-stream | string |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
POST /v1/apps/{app}/runs/{runId}/cancel
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | Run |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
POST /v1/apps/{app}/runs/{runId}/confirm
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
请求正文
Content-Type：application/json；正文必填。
类型：Confirmation。—
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | Confirmation |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
GET /v1/apps/{app}/conversations/
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| conversationId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | object |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 410 | application/json | Error |
| 412 | application/json | Error |
| 413 | application/json | Error |
| 429 | application/json | Error |
| 500 | application/json | Error |
| 502 | application/json | Error |
| 503 | application/json | Error |
会话属于发起主体；同一会话同时只有一个活动 Run。失败、超时与取消的用户消息保留在会话中并携带 status 与 errorCode，但不进入后续模型历史。删除仅移除会话正文，Run、事件、审计与幂等证据保留；带已删除会话号的 chat 返回 404。
PATCH /v1/apps/{app}/conversations/
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；pattern: "^[a-z][a-z0-9-]{0,63}$" |
| conversationId | path | 是 | string；— |
请求正文
Content-Type：application/json；正文必填。
类型：ConversationRename。—
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | ConversationRename |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
会话属于发起主体；同一会话同时只有一个活动 Run。失败、超时与取消的用户消息保留在会话中并携带 status 与 errorCode，但不进入后续模型历史。删除仅移除会话正文，Run、事件、审计与幂等证据保留；带已删除会话号的 chat 返回 404。
DELETE /v1/apps/{app}/conversations/
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；pattern: "^[a-z][a-z0-9-]{0,63}$" |
| conversationId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | ConversationDeletion |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
会话属于发起主体；同一会话同时只有一个活动 Run。失败、超时与取消的用户消息保留在会话中并携带 status 与 errorCode，但不进入后续模型历史。删除仅移除会话正文，Run、事件、审计与幂等证据保留；带已删除会话号的 chat 返回 404。
GET /v1/apps/{app}/runs
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | 数组：Run |
| 其他错误 | application/json | Error |
GET /v1/apps/{app}/runs/{runId}/tool-executions
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | 数组：ToolExecution |
GET /v1/apps/{app}/runs/{runId}/model-invocations
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
| limit | query | 否 | integer；default: 50；minimum: 1；maximum: 100 |
| offset | query | 否 | integer；default: 0；minimum: 0；maximum: 1000000 |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | ModelInvocationPage |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 412 | application/json | Error |
GET /v1/apps/{app}/runs/{runId}/citations/{citationId}/preview
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；— |
| runId | path | 是 | string；— |
| citationId | path | 是 | string；pattern: "^cite_[a-zA-Z0-9_-]{1,123}$" |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | CitationPreview |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
| 409 | application/json | Error |
| 412 | application/json | Error |
GET /v1/apps/{app}/runs/{runId}/trace
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；pattern: "^[a-z][a-z0-9-]{0,63}$" |
| runId | path | 是 | string；— |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | RunTrace |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
| 404 | application/json | Error |
GET /v1/apps/{app}/conversations
参数
| 名称 | 位置 | 必填 | 类型与约束 |
|---|---|---|---|
| app | path | 是 | string；pattern: "^[a-z][a-z0-9-]{0,63}$" |
| limit | query | 否 | integer；default: 50；minimum: 1；maximum: 200 |
| offset | query | 否 | integer；default: 0；minimum: 0；maximum: 1000000 |
响应
| HTTP | 响应类型 | 数据结构 |
|---|---|---|
| 200 | application/json | ConversationPage |
| 400 | application/json | Error |
| 401 | application/json | Error |
| 403 | application/json | Error |
会话属于发起主体；同一会话同时只有一个活动 Run。失败、超时与取消的用户消息保留在会话中并携带 status 与 errorCode，但不进入后续模型历史。删除仅移除会话正文，Run、事件、审计与幂等证据保留；带已删除会话号的 chat 返回 404。