# 添加消息 - AddCoreSpaceMessages #### 功能介绍 该接口用于向 Session 批量追加消息。消息按数组顺序依次追加，请求体不超过2MB。 #### 调用方法 请参见[如何调用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:addCoreSpaceMessages | Write | memorySpace \* | g:ResourceTag/\ | - | - | | agentarts:memorySpace:addCoreSpaceMessages | Write | - | - agentarts:MemoryActorId - agentarts:MemorySessionId | - | - | #### URI POST /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字符。 **默认取值：** 不涉及。 | #### 请求参数 表2请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | messages | 是 | Array of [MessageInput] objects | **参数解释：** 消息数组（按顺序追加，最多 100 条）。 **取值范围：** 1-100个。 | | timestamp | 否 | Long | **参数解释：** 客户端调用 API 时间（毫秒时间戳，可选），禁止使用未来时间。 不传则使用服务端当前时间。 同一请求内的多条消息共享相同 message_time。 支持历史数据导入、离线同步、多 Agent 协作等场景。 **约束限制：** 不涉及。 **取值范围：** 1735689600000-4102444800000。 **默认取值：** 不涉及。 | | idempotency_key | 否 | String | **参数解释：** 批量操作的幂等键（防重试重复写）。 如果为空，则不校验； 如果不为空，则校验是否重复。 **约束限制：** 不涉及。 **取值范围：** 长度1-255字符。 **默认取值：** 不涉及。 | | is_force_extract | 否 | Boolean | **参数解释：** 是否强制触发记忆抽取。设为 true 时，无论计数器是否达到阈值， 都会立即触发一次记忆抽取（trigger_type=force）。 适用于会话结束、重要对话节点等需要及时抽取的场景。 **约束限制：** 不涉及。 **取值范围：** - true: 表示强制触发记忆抽取 - false: 表示按计数器规则触发抽取 **默认取值：** false。 | 表3MessageInput | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 否 | String | **参数解释：** 消息 ID，用于标识消息。如果为空则自动生成消息ID，如果非空则以此ID创建message（若冲突报错） **约束限制：** 同一个Session下id不可重复。 **取值范围：** 长度0-64字符。 **默认取值：** 不涉及。 | | role | 是 | String | **参数解释：** 消息角色，标识消息的发送者类型。 **约束限制：** 必填参数。 **取值范围：** - user: 用户，表示发送消息的用户 - assistant: 助手，表示AI助手 - tool: 工具，表示工具调用 - system: 系统，表示系统消息 **默认取值：** 不涉及。 | | parts | 是 | Array of [MessagePart] objects | **参数解释：** 消息内容数组，每条消息可包含多个 Part（文本、工具调用、图片等）必填参数。 **取值范围：** 不涉及。 | | actor_id | 否 | String | **参数解释：** 消息发送者的 Actor ID，用于标识消息的发送者。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | assistant_id | 否 | String | **参数解释：** 归属 Assistant ID。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | meta | 否 | String | **参数解释：** 扩展元数据，用于存储自定义的附加信息，如标题、标签等。 **约束限制：** 不涉及。 **取值范围：** 长度0-10000字符。 **默认取值：** 不涉及。 | | skip_extract | 否 | Boolean | **参数解释：** 本条消息是否跳过记忆抽取。 **约束限制：** 不涉及。 **取值范围：** - true: 跳过抽取，消息正常入库 - false: 参与抽取（默认） **默认取值：** false。 | 表4MessagePart | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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字符。 **默认取值：** 不涉及。 | 表5tool_call | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | id | 否 | String | **参数解释：** Session 内唯一 ID，标识一次工具调用。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | name | 否 | String | **参数解释：** 工具名称，表示要调用的工具。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | arguments | 否 | String | **参数解释：** 工具参数，JSON 格式的工具调用参数。 **约束限制：** 不涉及。 **取值范围：** 长度0-100000字符。 **默认取值：** 不涉及。 | 表6tool_result | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | tool_call_id | 否 | String | **参数解释：** 引用的 tool_call.id，用于关联对应的工具调用请求。 **约束限制：** 不涉及。 **取值范围：** 长度1-64字符。 **默认取值：** 不涉及。 | | content | 否 | String | **参数解释：** 工具执行的文本结果。 **约束限制：** 不涉及。 **取值范围：** 长度0-100000字符。 **默认取值：** 不涉及。 | | asset_ref | 否 | [AssetRef] object | **参数解释：** 消息中引用外部文件资源（OBS/S3 存储）的结构体，用于 MessagePart 的 FILE/IMAGE/AUDIO 类型，指向存储在对象存储中的实际文件。 **取值范围：** 不涉及。 | 表7AssetRef | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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字符。 **默认取值：** 不涉及。 | 表8data | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | kind | 否 | String | **参数解释：** 数据类型，标识结构化数据的用途。 **约束限制：** 不涉及。 **取值范围：** - summary: 摘要，表示对话摘要 - offload_index: 卸载索引，表示卸载的索引 - custom: 自定义，表示用户自定义数据类型 **默认取值：** 不涉及。 | | covers | 否 | Array of strings | **参数解释：** 被摘要/卸载的消息id，用于记录哪些消息被本数据条目覆盖。 **约束限制：** 不涉及。 **取值范围：** 0-100个。 **默认取值：** 不涉及。 | | content | 否 | String | **参数解释：** 结构化数据的内容文本。 **约束限制：** 不涉及。 **取值范围：** 长度0-100000字符。 **默认取值：** 不涉及。 | #### 响应参数 **状态码：201** 表9响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | messages | Array of [Message] objects | **参数解释：** 创建的消息列表（按追加顺序）。 **取值范围：** 0-100个。 | | count | Integer | **参数解释：** 成功追加的消息数量，表示本次请求中实际写入的消息数。 **取值范围：** 0-100。 | 表10Message | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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）。 | 表11MessagePart | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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字符。 | 表12tool_call | 参数 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** Session 内唯一 ID，标识一次工具调用。 **取值范围：** 长度1-64字符。 | | name | String | **参数解释：** 工具名称，表示要调用的工具。 **取值范围：** 长度1-64字符。 | | arguments | String | **参数解释：** 工具参数，JSON 格式的工具调用参数。 **取值范围：** 长度0-100000字符。 | 表13tool_result | 参数 | 参数类型 | 描述 | |:---|:---|:---| | tool_call_id | String | **参数解释：** 引用的 tool_call.id，用于关联对应的工具调用请求。 **取值范围：** 长度1-64字符。 | | content | String | **参数解释：** 工具执行的文本结果。 **取值范围：** 长度0-100000字符。 | | asset_ref | [AssetRef] object | **参数解释：** 消息中引用外部文件资源（OBS/S3 存储）的结构体，用于 MessagePart 的 FILE/IMAGE/AUDIO 类型，指向存储在对象存储中的实际文件。 **取值范围：** 不涉及。 | 表14AssetRef | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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字符。 | 表15data | 参数 | 参数类型 | 描述 | |:---|:---|:---| | kind | String | **参数解释：** 数据类型，标识结构化数据的用途。 **取值范围：** - summary: 摘要，表示对话摘要 - offload_index: 卸载索引，表示卸载的索引 - custom: 自定义，表示用户自定义数据类型 | | covers | Array of strings | **参数解释：** 被摘要/卸载的消息id，用于记录哪些消息被本数据条目覆盖。 **取值范围：** 0-100个。 | | content | String | **参数解释：** 结构化数据的内容文本。 **取值范围：** 长度0-100000字符。 | **状态码：400** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：401** 表17响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：403** 表18响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表19Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：409** 表20响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：413** 表21响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：429** 表22响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | | encoded_authorization_message | String | **参数解释：** 编码后的授权失败信息。 **取值范围：** 长度1-4096字符。 | | details | Array of [Error] objects | **参数解释：** 依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。 **取值范围：** 不涉及。 | 表23Error | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释：** 错误码，标识错误类型，格式为 AgentArts.XXXXXXXX。 **取值范围：** 长度18-18字符。 | | error_msg | String | **参数解释：** 错误消息，描述错误详情，供问题排查使用。 **取值范围：** 长度1-256字符。 | **状态码：500** 表24响应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 { "messages" : [ { "role" : "user", "parts" : [ { "type" : "text", "text" : "创建记忆消息" } ], "actor_id" : "user-12345", "assistant_id" : "assistant-abc", "meta" : "", "skip_extract" : false } ], "timestamp" : 1735789700000, "idempotency_key" : "batch-20250118-001", "is_force_extract" : false } ``` #### 响应示例 **状态码：201** 无 **状态码：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" } ``` **状态码：409** ``` { "error_code" : "AgentArts.01020006", "error_msg" : "Request conflict" } ``` **状态码：413** ``` { "error_code" : "AgentArts.01020007", "error_msg" : "Quantity exceeds limit" } ``` **状态码：429** ``` { "error_code" : "AgentArts.01020008", "error_msg" : "Too many requests" } ``` **状态码：500** ``` { "error_code" : "AgentArts.01020004", "error_msg" : "Internal service error" } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 批量追加成功 | | 400 | 请求参数错误（如消息数组为空、格式不合法） | | 401 | 认证失败 | | 403 | 权限不足 | | 409 | 幂等键冲突（重复请求） | | 413 | 消息数量超过限制（最多 100 条） | | 429 | 请求过于频繁 | | 500 | 内部服务错误 | #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-agentarts/ErrorCode.html)。