文档首页/ 智果（AgentArts）智能体平台/ API参考/ API/ Managed Agents/ Managed Agent对话管理接口/ 获取会话历史对话消息 - ShowChatHistory
更新时间：2026-11-09 GMT+08:00
查看PDF
分享

获取会话历史对话消息 - ShowChatHistory

功能介绍

该接口用于以 SSE 流式返回指定会话的历史消息。

适用场景：

加载会话历史记录、分页浏览历史消息。

接口约束：

需提供有效的 session_id。

调用方法

请参见如何调用API。

授权信息

当前API调用无需身份策略权限。

URI

GET /runtimes/{runtime_name}/invocations/v1/chat/history

表1 路径参数

参数

是否必选

参数类型

描述

runtime_name

是

String

参数解释：

Managed Agent对应的运行时名称。格式为managed-{Agent名称}

Agent名称获取方式：

  1. 进入AgentArts平台，在左侧导航栏选择“Managed Agents”。

  2. 在智能体列表中“智能体名称/ID”处获取智能体名称。

约束限制:

不涉及。

取值范围：

以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。

默认取值:

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

page_idx

否

Integer

参数解释：

分页查询页码，表示从第几页开始查询，从1开始，每页固定50条记录。

约束限制:不涉及。

取值范围：1 - 10000

默认取值:

1

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Hw-Agentarts-Session-Id

是

String

参数解释：

会话ID，每个会话的唯一标识符。用户可将会话ID设置为任意符合下述字符集要求的字符串，例如“123e4567e89b12d3a456426614174000”，无需在其他地方获取。

约束限制:

不涉及。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

默认取值:

不涉及。

X-Hw-Agentgateway-User-Id

否

String

参数解释：

本次智能体运行时调用对应的用户唯一ID，用于标识此次调用的用户身份，用户可自行设置用户ID，需符合取值范围的字符要求，例如“123e4567e89b12d3a456426614174000”，无需在其他地方获取。

约束限制:

不涉及。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过128个字符。

默认取值:

不涉及。

Authorization

是

String

参数解释：

本次智能体运行时调用对应的身份认证凭据。需要根据实际的智能体运行时的入站身份认证方式获取对应的身份认证凭据。

API Key认证、IAM认证及OAuth 2.0认证具体请参见认证鉴权。

约束限制:

不涉及。

取值范围：

不超过4096个字符。

默认取值:

不涉及。

X-Sdk-Content-Sha256

否

String

参数解释：

如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。

约束限制:

不涉及。

取值范围：

UNSIGNED-PAYLOAD：表示请求体不参与签名校验，适用于IAM认证场景下跳过请求体的SHA256校验

默认取值:

不涉及。

响应参数

状态码：200

响应体遵循SSE（Server-SentEvents）规范。一次完整的响应包含多个SSE事件，每条事件格式为id/event/data三行。历史事件按照从新到旧的顺序发送。

表4 SSE响应体参数

参数

参数类型

描述

id

String

参数解释：

本次历史查询对应的请求ID。

取值范围：

1 - 128个字符。

event

String

参数解释：

SSE事件名。

取值范围：

history.message：历史对话事件

data

表5 Object

参数解释：

事件payload，包含历史消息记录和分页信息。

取值范围：

不涉及。
表5 data

参数

参数类型

描述

message

表6~表13 Object

参数解释：

历史消息记录，结构随消息角色和事件类型不同而不同。

取值范围：

不涉及。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

total_pages

Integer

参数解释：

历史消息总页数。

取值范围：

1 - 10000

page_idx

Integer

参数解释：

当前页码（从1开始）。

取值范围：

1 - 10000

status

String

参数解释：

流结束标记。仅最后一条事件携带此字段。其他场景该字段为空。

取值范围：

done

event_type

String

参数解释：

事件类型，固定为history.message。

取值范围：

history.message

request_id

String

参数解释：

本次历史查询对应的请求ID。

取值范围：

1 - 128个字符。

message字段根据消息角色和事件类型不同，包含以下几种结构：

表6 message（用户消息，role为user时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:user）。

取值范围：

1-128个字符。

role

String

参数解释：

消息角色。固定为user。

取值范围：

user。

content

String

参数解释：

用户输入文本。

取值范围：

0-1048576个字符。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1-128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0-2147483647。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。
表7 message（Agent回复消息，event_type为chat.final/chat.error/chat.interrupt_result时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:assistant）。

取值范围：

1-128个字符。

role

String

参数解释：

消息角色，固定为assistant。

取值范围：

assistant。

content

String

参数解释：

Agent回复文本（chat.delta合并后的完整内容）。

取值范围：

0-1048576个字符。

error

String

参数解释：

错误信息。仅在event_type为chat.error时会出现。

取值范围：

0-4096个字符。

event_type

String

参数解释：

关联的Agent事件类型。

取值范围：

  • chat.final：本轮对话成功结束。
  • chat.error：本轮对话异常结束。
  • chat.interrupt_result：用户中断。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1-128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0-2147483647。

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。

reasoning_content

String

参数解释：

推理过程文本（chat.reasoning合并后的完整内容）。

取值范围：

0-1048576个字符。
表8 message（工具调用消息，event_type为chat.tool_call时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:assistant）。

取值范围：

1 - 128个字符。

role

String

参数解释：

消息角色，固定为assistant。

取值范围：

assistant

event_type

String

参数解释：

事件类型。

取值范围：

chat.tool_call

content

String

参数解释：

消息内容（通常为空）。

取值范围：

0 - 128个字符。

tool_call

表9 object

参数解释：

工具调用详情，包含工具名称、调用ID、参数和展示名称。

取值范围：

不涉及。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1 - 128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0 - 2147483647

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。
表9 ToolCallInfo

参数

参数类型

描述

name

String

参数解释：

发起调用的工具名称。

取值范围：

read_file / write_file / edit_file / bash / list_files / glob / grep

tool_call_id

String

参数解释：

工具调用唯一ID，用于关联后续的tool_update / tool_result事件。

取值范围：

1 - 128个字符。

arguments

One of：

参数解释：

工具调用使用的所有参数，结构随工具不同而不同。

取值范围：

不涉及。

display_name

String

参数解释：

工具调用的可读展示名称，用于前端展示。

取值范围：

0 - 256个字符。
表10 message（工具结果消息，event_type为chat.tool_result时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:assistant）。

取值范围：

1 - 128个字符。

role

String

参数解释：

消息角色，固定为assistant。

取值范围：

assistant

event_type

String

参数解释：

事件类型。

取值范围：

chat.tool_result

content

String

参数解释：

消息内容（通常为空）。

取值范围：

0 - 128个字符。

tool_result

表11Object

参数解释：

工具执行结果对象。

取值范围：

不涉及。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1 - 128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0 - 2147483647

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。
表11 tool_result

参数

参数类型

描述

result

String

参数解释：

工具执行结果文本。

取值范围：

0-1024个字符。

tool_name

String

参数解释：

发起调用的工具名称。

取值范围：

read_file/write_file/edit_file/bash/list_files/glob/grep。

tool_call_id

String

参数解释：

工具调用ID。

取值范围：

1-128个字符。
表12 message（Agent反问消息，event_type为chat.ask_user_question时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:assistant）。

取值范围：

1 - 128个字符。

role

String

参数解释：

消息角色，固定为assistant。

取值范围：

assistant

event_type

String

参数解释：

事件类型。

取值范围：

chat.ask_user_question

questions

Array of 表33 object

参数解释：

结构化问题列表。

取值范围：

最小数量0，最大数量4。

source

String

参数解释：

中断来源。

取值范围：

permission_interrupt：工具权限审批

confirm_interrupt：控制类工具确认

ask_user_interrupt：LLM主动调用ask_user工具反问用户

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1 - 128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0 - 2147483647

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。
表13 message（Token用量消息，event_type为chat.usage_summary/chat.usage_metadata时）

参数

参数类型

描述

id

String

参数解释：

消息唯一标识（格式：{request_id}:assistant）。

取值范围：

1 - 128个字符。

role

String

参数解释：

消息角色，固定为assistant。

取值范围：

assistant

event_type

String

参数解释：

事件类型。

取值范围：

chat.usage_summary：本轮对话Token使用量统计

chat.usage_metadata：单次LLM调用Token使用量统计

usage

表14 object

参数解释：

整轮对话累计的Token用量和费用汇总。

取值范围：

不涉及。

request_id

String

参数解释：

本次对话对应的请求ID。

取值范围：

1 - 128个字符。

timestamp

Integer

参数解释：

消息时间戳（Unix时间戳，精确到秒）。

取值范围：

0 - 2147483647

session_id

String

参数解释：

会话ID。

取值范围：

由英文字母，数字，“-”，“_”组成，不超过64个字符。
表14 UsageSummary

参数

参数类型

描述

input_tokens

Integer

参数解释：

本轮所有LLM调用的输入Token累计总数。

取值范围：

0-1000000。

output_tokens

Integer

参数解释：

本轮所有LLM调用的输出Token累计总数。

取值范围：

0-1000000。

total_tokens

Integer

参数解释：

本轮所有LLM调用的总Token累计总数（input + output）。

取值范围：

0-1000000。

cache_tokens

Integer

参数解释：

本轮缓存命中的Token累计总数。

取值范围：

0-1000000。

cache_hit_rate

String

参数解释：

缓存命中率（百分比字符串），等于cache_tokens / input_tokens，如"98.2%"。

取值范围：

0-10个字符，包含数字，“.”，由“%”结尾。

状态码：401

表15 响应Body参数

参数

参数类型

描述

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

状态码：404

表16 响应Body参数

参数

参数类型

描述

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

状态码：500

表17 响应Body参数

参数

参数类型

描述

code

Integer

参数解释:

异常错误码。

取值范围:

不涉及。

message

String

参数解释：

错误详细信息。

取值范围：

长度为 1 - 512 个字符。

请求示例

查询会话历史记录, gateway_domain为运行时的访问域名，可以在智能体运行时的运行时详情页面中获取

GET https://{gateway_domain}/runtimes/{runtime_name}/invocations/v1/chat/history

响应示例

状态码：200

event: web.response
data: {"accepted": true, "session_id": "sess-001"}

id: req-001
event: history.message
data: { "message": {"id": "req-001:assistant", "role": "assistant", "content": "", "event_type": "chat.usage_summary", "request_id": "req-001", "timestamp": 1728460803, "session_id": "sess-001", "usage": {"input_tokens": 5200, "output_tokens": 80, "total_tokens": 5280, "cache_tokens": 4500, "cache_hit_rate": "86.5%", "total_cost": 0.012}}, "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

id: req-001
event: history.message
data: {"message": {"id": "req-001:assistant", "role": "assistant", "content": "这是 auth.py 文件的内容。login 函数使用了 MD5 哈希，建议改为 bcrypt。", "event_type": "chat.final", "request_id": "req-001", "timestamp": 1728460803, "session_id": "sess-001", "mode": "agent"}, "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

id: req-001
event: history.message
data: {"message": {"id": "req-001:assistant", "role": "assistant", "content": "", "event_type": "chat.tool_result", "request_id": "req-001", "timestamp": 1728460801, "session_id": "sess-001", "tool_result": {"result": "def login(username, password):\n    ...", "tool_name": "read_file", "tool_call_id": "call-001"}, "tool_call_id": "call-001"}, "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

id: req-001
event: history.message
data: {"message": {"id": "req-001:assistant", "role": "assistant", "content": "", "event_type": "chat.tool_call", "request_id": "req-001", "timestamp": 1728460801, "session_id": "sess-001", "tool_call": {"name": "read_file", "tool_call_id": "call-001", "arguments": {"file_path": "/src/auth.py"}, "display_name": "读取 auth.py"}}, "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

id: req-001
event: history.message
data: {"message": {"id": "req-001:user", "role": "user", "content": "帮我查看 auth.py 文件", "request_id": "req-001", "timestamp": 1728460800, "session_id": "sess-001", "mode": "agent"}, "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

id: req-001
event: history.message
data: {"status": "done", "session_id": "sess-001", "total_pages": 1, "page_idx": 1}

状态码

状态码

描述

200

SSE 历史消息流

401

未授权（认证令牌缺失、无效或已过期）。

404

运行时资源不存在。

500

服务器内部错误。

错误码

请参见错误码。

相关文档