消息管理

分页查询指定会话的对话历史消息，按时间正序返回每一轮问答及其执行明细（思考、工具调用、工作流节点、回复内容等）。Agent、AgentLite 和 ChatFlow 类型应用支持（TextCompletion 无对话上下文）。

接口路径：POST /v1/openapi/chat/history

INFO

Agent、AgentLite 与 ChatFlow 共用同一接口路径，由 app_id 对应应用的类型分发。

请求头

参数名	必填	说明
Content-Type	是	`application/json`
Authorization	是	鉴权凭证，格式 `Bearer sk_xxx`

请求参数

json

{
    "app_id": "",            // 必填-应用ID
    "conversation_id": "",   // 必填-会话ID
    "page": 1,               // 页码，缺省 1
    "page_size": 10          // 每页条数，缺省 10
}

参数名	类型	必填	说明
app_id	string(uuid)	是	应用 ID
conversation_id	string(uuid)	是	会话 ID
page	int	否	页码，缺省 1
page_size	int	否	每页条数，缺省 10

返回数据

json

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "id": "01965de1-1920-7fe4-aa38-2e6836c46f22",   // 消息ID
            "query": "帮我分析这张报表",                        // 用户提问
            "files": [                                       // 用户上传的多模态附件
                {"type": "image", "url": "https://example.com/a.png"}
            ],
            "content": "根据报表数据，...",                    // AI 最终回复内容
            "thinking": "让我先看一下数据结构...",              // 深度思考内容（如有）
            "input": {"tone": "正式"},                        // 本轮变量参数
            "status": 1,                                     // 消息状态
            "total_tokens": 168,                             // 总 tokens
            "duration": 1500,                                // 总耗时（毫秒）
            "tool_calls": [                                  // 工具调用汇总（如有）
                {
                    "tool_call_id": "",
                    "tool_name": "web_search",
                    "tool_arguments": "{\"query\":\"报表\"}",
                    "tool_result": "搜索结果",
                    "status": 1,
                    "duration": 120
                }
            ],
            "items": [                                       // 消息明细条目（按 sort_order 排序）
                {
                    "item_type": 3,
                    "sort_order": 0,
                    "is_sub_agent": false,
                    "content": {"text": "根据报表数据，..."}
                }
            ],
            "created_at": "2025-04-22 22:22:34",             // 创建时间
            "is_favorited": false                            // 是否已收藏
        }
    ]
}

TIP

返回的 data 为消息数组（不含分页 total 包裹），按时间正序排列；每个元素代表一轮完整问答。

消息项字段

字段	类型	说明
id	string(uuid)	消息 ID
query	string	用户提问内容
files	array	用户上传的多模态附件，每项含 `type`（目前仅 `image`）与 `url`，无附件时省略
content	string	AI 最终回复内容
thinking	string	深度思考内容，无则省略
input	object	本轮变量参数
status	uint8	消息状态，见下表
total_tokens	int	本轮总 tokens
duration	int64	总耗时（毫秒）
tool_calls	array	工具调用汇总列表，无则省略
items	array	消息明细条目（思考 / 工具 / 回复分片等），按 `sort_order` 排序
created_at	string	创建时间，`YYYY-MM-DD HH:mm:ss`
is_favorited	bool	是否已收藏

消息状态（status）：

值	说明
1	成功
2	失败
3	取消
4	中断（等待人工输入）

tool_calls 字段

字段	类型	说明
tool_call_id	string	工具调用 ID
tool_name	string	工具名称
tool_arguments	string	工具入参（JSON 字符串）
tool_result	string	工具执行结果
status	uint8	状态：`1`-成功、`2`-失败
duration	int64	工具耗时（毫秒）

items 明细条目

items 还原一轮对话的完整执行过程，每个条目通过 item_type 区分类型。

字段	类型	说明
item_type	uint8	条目类型，见下表
sort_order	int	排序序号
is_sub_agent	bool	是否来自 Sub-Agent
agent_id	string	Sub-Agent 运行时的当前智能体 ID（如有）
parent_agent_id	string	父智能体 ID（如有）
root_agent_id	string	主智能体 ID（如有）
tool_call_id	string	工具调用 ID（`item_type=1` 时）
tool_name	string	工具名称（`item_type=1` 时）
tool_label	string	工具显示名称（`item_type=1` 时）
files	array	工具产生的工作空间文件（如有），每项含 `name` 与 `path`
status	uint8	条目状态
error	string	错误信息（如有）
duration	int64	总耗时（毫秒）
llm_duration	int64	LLM 耗时（毫秒）
tool_duration	int64	工具耗时（毫秒）
content	object	条目内容（结构随类型而定）

条目类型（item_type）：

值	说明
1	工具调用
2	思考消息
3	助手回复分片
4	错误消息
5	取消

消息管理 ​

请求头 ​

请求参数 ​

返回数据 ​

消息项字段 ​

tool_calls 字段 ​