# 查询后台任务详情

`GET` `/api/session/backgroundTasks/detail`

查询当前登录用户指定会话下某个后台任务的完整执行详情。当前支持子智能体（SUBAGENT），executionParts 默认返回最近10个执行步骤的可见思考、正文、工具调用参数与结果；同一步内容不拆分或截断。可传nextBeforeStep至beforeStep读取更早10步。同时保留任务计划、最近工具步骤等摘要字段。任务结束后仍可查询该次运行，不跳转至后续运行。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | integer | 是 | 父会话ID |
| taskType | string | 是 | 后台任务类型，可选值：SUBAGENT |
| taskId | string | 是 | 后台任务ID，取自后台任务列表的taskId |
| beforeStep | integer | 否 | 更早步骤的排他游标，传上一页nextBeforeStep；不传则查询最新10步，不能为负数 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | BackgroundTaskDetailVO | 响应数据 |
|     taskType | string | 后台任务类型，可选值：SUBAGENT（子智能体） |
|     taskId | string | 后台任务ID |
|     status | string | 任务状态，可选值：CREATED、PROCESSING、SUSPENDED、COMPLETED、FAILED、CANCELLED |
|     statusReason | string | 任务失败或取消的中文原因说明；其他状态为空 |
|     currentStep | integer | 当前执行步骤数 |
|     startedAt | integer | 开始执行时间，Unix毫秒时间戳 |
|     completedAt | integer | 结束时间，Unix毫秒时间戳，未结束时为空 |
|     lastActivityAt | integer | 最近一次活动时间，Unix毫秒时间戳 |
|     subagent | SubagentDetailVO | 子智能体详情，仅 taskType=SUBAGENT 时返回 |
|         plan | array | 任务计划 |
|             content | string | 计划项说明 |
|             status | string | 状态，可选值：pending、in_progress、completed、cancelled |
|         recentSteps | array | 最近工具步骤 |
|             stepId | string | 步骤ID |
|             toolName | string | 工具名称 |
|             title | string | 工具执行标题 |
|             status | string | 状态，可选值：PENDING、RUNNING、COMPLETED、FAILED |
|             arguments | string | 工具参数 JSON，超长内容已截断 |
|             errorMessage | string | 失败原因摘要 |
|             startedAt | integer | 开始时间，Unix毫秒时间戳 |
|             endedAt | integer | 结束时间，Unix毫秒时间戳，执行中为空 |
|         toolStats | array | 累计工具调用统计 |
|             toolName | string | 工具名称 |
|             total | integer | 累计调用次数 |
|             failed | integer | 失败次数 |
|         totalToolCalls | integer | 累计工具调用次数 |
|         executionParts | array | 本页最近10个步骤的完整可见消息片段，按创建顺序排列；包含思考、工具调用参数与结果、正文，不截断内容 |
|             partId | integer | 部件ID |
|             messageId | integer | 所属消息ID |
|             partType | string | 部件类型，可选值：TEXT（文本）、TOOL（工具调用）、REASONING（推理思考）。SUMMARY（上下文压缩摘要）类型部件已被本接口过滤，不会返回 |
|             content | string | 部件内容（JSON字符串，需解析后使用，内部结构根据partType不同而不同）。

**partType=TEXT 时的字段：**
- text：文本内容（必填，String）
- synthetic：是否为合成文本，即系统生成的提示信息，仅供UI展示、不回灌LLM（可选，Boolean，默认false）
- startTime：文本生成开始时间，首chunk到达时刻（可选，DateTime）
- endTime：文本生成结束时间（可选，DateTime）

**partType=TOOL 时的字段：**
- callId：工具调用唯一标识（必填，String）
- toolName：工具名称（必填，String）
- status：执行状态（必填，String），可选值：PENDING（等待执行）、RUNNING（执行中）、COMPLETED（执行成功）、FAILED（执行失败）
- title：工具调用的展示标题（可选，String）
- arguments：工具调用参数，JSON格式字符串（可选，String）
- output：工具执行输出结果（可选，String）
- errorMessage：执行失败时的错误信息（可选，String）
- generatingStartTime：LLM首次探测到工具名的时刻，早于参数生成完成（可选，DateTime）
- startTime：工具执行开始时间（可选，DateTime）
- endTime：工具执行结束时间（可选，DateTime）
- hidden：是否UI静默工具（可选，Boolean）。本接口已过滤hidden=true的部件，此值恒为false

**partType=REASONING 时的字段：**
- text：推理思考文本内容（必填，String）
- startTime：推理开始时间（可选，DateTime）
- endTime：推理结束时间（可选，DateTime） |
|             promptTokens | integer | 本次LLM调用的prompt token数 |
|             completionTokens | integer | 本次LLM调用的补全token数 |
|             totalTokens | integer | 本次LLM调用的总token数 |
|             cachedTokens | integer | 缓存命中的prompt token数 |
|             reasoningTokens | integer | 推理消耗的completion token数 |
|             stepIndex | integer | 所属Agent循环步骤号（从1开始；0表示COMPACT摘要或存量数据未知） |
|             startTime | string | 部件开始时间（TEXT/REASONING为首chunk到达，TOOL为开始执行） |
|             endTime | string | 部件结束时间，为空表示进行中 |
|             modelResponseId | string | 模型响应ID |
|             gmtCreate | string | 创建时间 |
|         nextBeforeStep | integer | 下一页步骤游标，作为beforeStep传入；为空表示已加载全部记录 |
|         executionId | string | 执行代次标识；变化时应丢弃此前已加载的分页记录 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |