# 查询消息列表 - ListCoreSpaceMessages #### 功能介绍 该接口用于分页获取 Session 中的消息，默认按消息序号升序排序，不包含消息详情。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-agentarts/agentarts_07_0003.html)。 #### 授权信息 账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见[权限和授权项](https://support.huaweicloud.com/api-agentarts/Permission.html)。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | agentarts:memorySpace:listCoreSpaceMessages | List | memorySpace \* | g:ResourceTag/\ | - | - | | agentarts:memorySpace:listCoreSpaceMessages | List | - | - agentarts:MemoryActorId - agentarts:MemorySessionId | - | - | #### URI GET /v1/core/spaces/{space_id}/sessions/{session_id}/messages 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | space_id | 是 | String | **参数解释：** Space ID是记忆空间的唯一标识，可通过"创建Space"获取。 **约束限制：** 不涉及。 **取值范围：** UUID格式。示例：123e4567-e89b-12d3-a456-426614174001。 **默认取值：** 不涉及。 | | session_id | 是 | String | **参数解释：** Session ID：会话的唯一标识，可通过"创建Session"接口生成或由调用方指定。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | limit | 否 | Integer | **参数解释：** 每页数量（单位：条），用于限制分页查询时每页返回的最大记录数。 **约束限制：** 不涉及。 **取值范围：** 1-100。 **默认取值：** 20。 | | offset | 否 | Integer | **参数解释：** 偏移量（单位：条），用于指定分页查询时的起始位置，从0开始计算。 **约束限制：** 不涉及。 **取值范围：** 0-2147483647。 **默认取值：** 0。 | | order | 否 | String | **参数解释：** 排序方向，控制消息列表的排列顺序。 **约束限制：** 不涉及。 **取值范围：** - asc: 升序排列 - desc: 降序排列 **默认取值：** asc。 | | sort_by | 否 | String | **参数解释：** 排序字段，选择按哪个字段进行排序。 **约束限制：** 不涉及。 **取值范围：** - seq: 按消息序号排序（默认），服务端分配的递增序号 - message_time: 按消息业务时间排序，消息实际发生的时间 **默认取值：** seq。 | | cursor | 否 | String | **参数解释：** 游标分页 token，首次请求需要包含参数名称，可以不传值，后续传入上次响应的 next_cursor 进行翻页。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 无 #### 响应参数 **状态码：200** 表3响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | items | Array of [Message] objects | **参数解释：** 消息列表，包含当前页的所有消息记录。 **取值范围：** 0-100个。 | | limit | Integer | **参数解释：** 每页返回的记录数量（单位：条），用于分页查询。 **取值范围：** 1-100。 | | offset | Integer | **参数解释：** 偏移量（单位：条），用于分页查询时指定起始位置，从0开始。 **取值范围：** 0-2147483647。 | | total | Integer | **参数解释：** 符合条件的记录总数（单位：条），用于计算总页数。 **取值范围：** 0-2147483647。 | | next_cursor | String | **参数解释：** 下一页游标（编码后的 opaque token）。 客户端原样传入下次请求的 cursor 参数即可翻页。 为空表示没有更多数据。 **取值范围：** 1-256。 | | has_more | Boolean | **参数解释：** 是否还有更多数据 **取值范围：** - true: 表示还有更多数据 - false: 表示没有更多数据 | 表4Message | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 消息 ID，可通过"添加消息"接口获取。 **取值范围：** 长度1-64字符。 | | session_id | String | **参数解释：** 所属 Session ID，标识该消息所属的会话，可通过"创建Session"接口获取。 **取值范围：** 长度36-36字符。 | | seq | Long | **参数解释：** Session 内自增序号，用于保证消息的顺序性。 **取值范围：** 1-2147483647。 | | actor_id | String | **参数解释：** 消息发送者的 Actor ID，用于标识消息的发送者，实现 Actor 级别的消息隔离。 **取值范围：** 长度1-64字符。 | | assistant_id | String | **参数解释：** 归属 Assistant ID，标识该消息所属的 AI 助手。 **取值范围：** 长度1-64字符。 | | role | String | **参数解释：** 消息角色，标识消息的发送者类型。 **取值范围：** - user: 用户，表示发送消息的用户 - assistant: 助手，表示 AI 助手生成的消息 - tool: 工具，表示工具调用消息 - system: 系统，表示系统消息 | | parts | Array of [MessagePart] objects | **参数解释：** 消息内容数组，每条消息可包含多个 Part（文本、工具调用、图片等）。 **取值范围：** 1-5个。 | | idempotency_key | String | **参数解释：** 幂等键，用于防止重试导致的重复写入。如果为空则不校验，如果不为空则校验是否重复。 **取值范围：** 长度1-255字符。 | | meta | Object | **参数解释：** 扩展元数据，用于存储自定义的附加信息，如客户端版本等。 **取值范围：** 不涉及。 | | skip_extract | Boolean | **参数解释：** 本条消息是否跳过记忆抽取。 **取值范围：** - true: 跳过抽取，不参与记忆抽取 - false: 参与抽取（默认） | | message_time | Long | **参数解释：** 消息实际发生时间（毫秒时间戳）。用于记录消息的业务发生时间。 **取值范围：** 946684800000-4102444800000。 | | created_at | String | **参数解释：** 服务器创建时间，由系统自动生成。 **取值范围：** 格式为 ISO 8601（YYYY-MM-DDTHH:mm:ssZ）。 | 表5MessagePart | 参数 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** Part 类型，标识消息内容的类型。 **取值范围：** - text: 文本，表示文本内容 - tool_call: 工具调用，表示工具调用 - tool_result: 工具结果，表示工具执行结果 - file: 文件，表示文件引用 - image: 图片，表示图片引用 - audio: 音频，表示音频引用 - data: 数据，表示结构化数据 | | text | String | **参数解释：** 文本内容，当 type=text 时填写。 **取值范围：** 长度0-100000字符。 | | tool_call | [tool_call] object | **参数解释：** 工具调用，当 type=tool_call 时使用。用于记录调用外部工具的请求信息。 **取值范围：** 不涉及。 | | tool_result | [tool_result] object | **参数解释：** 工具执行结果，当 type=tool_result 时使用。用于记录工具调用返回的结果信息。 **取值范围：** 不涉及。 | | asset_ref | [AssetRef] object | **参数解释：** 资源引用，当 type 为 file/image/audio 时使用。用于关联存储资源。 **取值范围：** 不涉及。 | | data | [data] object | **参数解释：** 结构化数据，当 type=data 时使用。用于记录摘要、卸载索引等非文本数据。 **取值范围：** 不涉及。 | | meta | String | **参数解释：** 扩展元数据，用于存储自定义的附加信息。 **取值范围：** 长度0-10000字符。 | 表6tool_call | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** Session 内唯一 ID，标识一次工具调用。 **取值范围：** 长度1-64字符。 | | name | String | **参数解释：** 工具名称，表示要调用的工具。 **取值范围：** 长度1-64字符。 | | arguments | String | **参数解释：** 工具参数，JSON 格式的工具调用参数。 **取值范围：** 长度0-100000字符。 | 表7tool_result | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tool_call_id | String | **参数解释：** 引用的 tool_call.id，用于关联对应的工具调用请求。 **取值范围：** 长度1-64字符。 | | content | String | **参数解释：** 工具执行的文本结果。 **取值范围：** 长度0-100000字符。 | | asset_ref | [AssetRef] object | **参数解释：** 消息中引用外部文件资源（OBS/S3 存储）的结构体，用于 MessagePart 的 FILE/IMAGE/AUDIO 类型，指向存储在对象存储中的实际文件。 **取值范围：** 不涉及。 | 表8AssetRef | 参数 | 参数类型 | 描述 | |:---|:---|:---| | asset_id | String | **参数解释：** 资源 ID，唯一标识一个存储资源，只能包含字母、数字、连字符和下划线。 **取值范围：** 长度1-255字符。 | | uri | String | **参数解释：** OBS/S3 路径，用于定位存储的资源文件。 **取值范围：** 长度1-2048字符。 | | mime | String | **参数解释：** MIME 类型，标识资源的媒体格式。 **取值范围：** 长度1-128字符。 | | size | Long | **参数解释：** 文件大小（字节）。 **取值范围：** 0-1073741824。 | | sha256 | String | **参数解释：** SHA256 校验值，64位十六进制字符串。 **取值范围：** 长度64-64字符。 | 表9data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | kind | String | **参数解释：** 数据类型，标识结构化数据的用途。 **取值范围：** - summary: 摘要，表示对话摘要 - offload_index: 卸载索引，表示卸载的索引 - custom: 自定义，表示用户自定义数据类型 | | covers | Array of strings | **参数解释：** 被摘要/卸载的消息id，用于记录哪些消息被本数据条目覆盖。 **取值范围：** 0-100个。 | | content | String | **参数解释：** 结构化数据的内容文本。 **取值范围：** 长度0-100000字符。 | **状态码：400** 表10响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：401** 表11响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：403** 表12响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表13Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：429** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表15Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：500** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | #### 请求示例 ``` /v1/core/spaces/123e4567-e89b-12d3-a456-426614174000/sessions/123e4567-e89b-12d3-a456-426614174001/messages ``` #### 响应示例 **状态码：200** 无 **状态码：400** ``` { "error_code" : "AgentArts.01020001", "error_msg" : "Invalid request parameters" } ``` **状态码：401** ``` { "error_code" : "AgentArts.01020002", "error_msg" : "Authentication failed" } ``` **状态码：403** ``` { "error_code" : "AgentArts.01020003", "error_msg" : "Insufficient permissions" } ``` **状态码：429** ``` { "error_code" : "AgentArts.01020008", "error_msg" : "Too many requests" } ``` **状态码：500** ``` { "error_code" : "AgentArts.01020004", "error_msg" : "Internal service error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 成功获取消息列表 | | 400 | 请求参数错误（如 sort_by 非法值） | | 401 | 认证失败 | | 403 | 权限不足 | | 429 | 请求过于频繁 | | 500 | 内部服务错误 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。