文档首页/ 智果（AgentArts）智能体平台/ API参考/ API/ 记忆库/ 消息管理/ 添加消息 - AddCoreSpaceMessages
更新时间：2026-11-09 GMT+08:00
查看PDF
分享

添加消息 - AddCoreSpaceMessages

功能介绍

该接口用于向 Session 批量追加消息。消息按数组顺序依次追加，请求体不超过2MB。

调用方法

请参见如何调用API。

授权信息

账号根用户具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备如下身份策略权限，更多的权限说明请参见权限和授权项。

授权项

访问级别

资源类型（*为必须）

条件键

别名

依赖的授权项

agentarts:memorySpace:addCoreSpaceMessages

Write

memorySpace *

g:ResourceTag/<tag-key>

-

-

-

  • 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。
表3 MessageInput

参数

是否必选

参数类型

描述

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。
表4 MessagePart

参数

是否必选

参数类型

描述

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字符。

默认取值：

不涉及。
表5 tool_call

参数

是否必选

参数类型

描述

id

否

String

参数解释：

Session 内唯一 ID，标识一次工具调用。

约束限制：

不涉及。

取值范围：

长度1-64字符。

默认取值：

不涉及。

name

否

String

参数解释：

工具名称，表示要调用的工具。

约束限制：

不涉及。

取值范围：

长度1-64字符。

默认取值：

不涉及。

arguments

否

String

参数解释：

工具参数，JSON 格式的工具调用参数。

约束限制：

不涉及。

取值范围：

长度0-100000字符。

默认取值：

不涉及。
表6 tool_result

参数

是否必选

参数类型

描述

tool_call_id

否

String

参数解释：

引用的 tool_call.id，用于关联对应的工具调用请求。

约束限制：

不涉及。

取值范围：

长度1-64字符。

默认取值：

不涉及。

content

否

String

参数解释：

工具执行的文本结果。

约束限制：

不涉及。

取值范围：

长度0-100000字符。

默认取值：

不涉及。

asset_ref

否

AssetRef object

参数解释：

消息中引用外部文件资源（OBS/S3 存储）的结构体，用于 MessagePart 的 FILE/IMAGE/AUDIO 类型，指向存储在对象存储中的实际文件。

取值范围：

不涉及。
表7 AssetRef

参数

是否必选

参数类型

描述

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字符。

默认取值：

不涉及。
表8 data

参数

是否必选

参数类型

描述

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。
表10 Message

参数

参数类型

描述

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）。
表11 MessagePart

参数

参数类型

描述

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字符。
表12 tool_call

参数

参数类型

描述

id

String

参数解释：

Session 内唯一 ID，标识一次工具调用。

取值范围：

长度1-64字符。

name

String

参数解释：

工具名称，表示要调用的工具。

取值范围：

长度1-64字符。

arguments

String

参数解释：

工具参数，JSON 格式的工具调用参数。

取值范围：

长度0-100000字符。
表13 tool_result

参数

参数类型

描述

tool_call_id

String

参数解释：

引用的 tool_call.id，用于关联对应的工具调用请求。

取值范围：

长度1-64字符。

content

String

参数解释：

工具执行的文本结果。

取值范围：

长度0-100000字符。

asset_ref

AssetRef object

参数解释：

消息中引用外部文件资源（OBS/S3 存储）的结构体，用于 MessagePart 的 FILE/IMAGE/AUDIO 类型，指向存储在对象存储中的实际文件。

取值范围：

不涉及。
表14 AssetRef

参数

参数类型

描述

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字符。
表15 data

参数

参数类型

描述

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

参数解释：

依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。

取值范围：

不涉及。
表19 Error

参数

参数类型

描述

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

参数解释：

依赖的下游服务错误信息列表，包含导致当前请求失败的下游服务错误详情。

取值范围：

不涉及。
表23 Error

参数

参数类型

描述

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

内部服务错误

错误码

请参见错误码。

父主题： 消息管理

相关文档