# 获取会话历史对话消息 - ShowChatHistory #### 功能介绍 该接口用于以 SSE 流式返回指定会话的历史消息。 **适用场景：** 加载会话历史记录、分页浏览历史消息。 **接口约束：** 需提供有效的 session_id。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 当前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个字符。 **默认取值**: 不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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认证具体请参见[认证鉴权](https://support.huaweicloud.com/api-agentarts/agentarts_07_0005.html)。 **约束限制**: 不涉及。 **取值范围**： 不超过4096个字符。 **默认取值**: 不涉及。 | | X-Sdk-Content-Sha256 | 否 | String | **参数解释**： 如果智能体运行时的入站认证类型为IAM认证时，需要指定该Header头为UNSIGNED-PAYLOAD。 **约束限制**: 不涉及。 **取值范围**： UNSIGNED-PAYLOAD：表示请求体不参与签名校验，适用于IAM认证场景下跳过请求体的SHA256校验 **默认取值**: 不涉及。 | #### 响应参数 **状态码：200** 响应体遵循SSE（Server-SentEvents）规范。一次完整的响应包含多个SSE事件，每条事件格式为id/event/data三行。历史事件按照从新到旧的顺序发送。 表4SSE响应体参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释**： 本次历史查询对应的请求ID。 **取值范围**： 1 - 128个字符。 | | event | String | **参数解释**： SSE事件名。 **取值范围**： history.message：历史对话事件 | | data | [表5] Object | **参数解释**： 事件payload，包含历史消息记录和分页信息。 **取值范围**： 不涉及。 | 表5data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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字段根据消息角色和事件类型不同，包含以下几种结构： 表6message（用户消息，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个字符。 | 表7message（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个字符。 | 表8message（工具调用消息，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个字符。 | 表9ToolCallInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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： - [表15](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table1822710207399) object - [表16](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table66951427123917) object - [表17](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table18506728103915) object - [表18](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table4248229163916) object - [表19](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table6671301391) object - [表20](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table1781193010399) object - [表21](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table19560123118391) object | **参数解释**： 工具调用使用的所有参数，结构随工具不同而不同。 **取值范围**： 不涉及。 | | display_name | String | **参数解释**： 工具调用的可读展示名称，用于前端展示。 **取值范围**： 0 - 256个字符。 | 表10message（工具结果消息，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 | [表11]Object | **参数解释**： 工具执行结果对象。 **取值范围**： 不涉及。 | | request_id | String | **参数解释**： 本次对话对应的请求ID。 **取值范围**： 1 - 128个字符。 | | timestamp | Integer | **参数解释**： 消息时间戳（Unix时间戳，精确到秒）。 **取值范围**： 0 - 2147483647 | | session_id | String | **参数解释**： 会话ID。 **取值范围**： 由英文字母，数字，"-"，"_"组成，不超过64个字符。 | 表11tool_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个字符。 | 表12message（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](https://support.huaweicloud.com/api-agentarts/InvokeChat.html#InvokeChat__zh-cn_topic_0000002808859239_table166711938153611) 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个字符。 | 表13message（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个字符。 | 表14UsageSummary | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 | 服务器内部错误。 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。