方法介绍
add_conversation` 用于向 Memory 实例追加一批原始对话消息（L0）。功能说明如下：
会话归属：
session_id 用于将写入的消息归属到指定会话，支持以下两种方式指定：作用域归属：消息归属的团队/Agent/用户/任务由构造
MemoryClient 时传入的 team_id / agent_id / user_id / task_id 决定，抽取出的记忆会沉淀到对应作用域下。写入数量：
messages 单次最少 1 条、最多 100 条。后台处理：消息受理后，系统在后台自动执行记忆抽取，逐步沉淀为 L1 原子记忆、L2 场景记忆和 L3 核心记忆；沉淀结果不在本方法返回值中，可通过对应层级的查询或检索方法观测。
导入
from tencentdb_agent_memory.v3 import MemoryClient
方法签名
def add_conversation(self,messages: List[Dict[str, Any]],*,session_id: Optional[str] = None,) -> Dict[str, Any]
使用示例
from tencentdb_agent_memory.v3 import MemoryClientwith MemoryClient(endpoint="https://memory.tdai.tencentyun.com",api_key="sk-xxxxxxxxxxxxxxxx",service_id="tdai-mem-xxxxxxxx",team_id="team-abc123",agent_id="agt-xyz789",user_id="usr-456",) as client:result = client.add_conversation(messages=[ # 必填，消息列表，1-100 条{"role": "user", "content": "帮我查一下上周的会议纪要"},{"role": "assistant", "content": "好的，根据记忆，上周你参加了..."},],session_id="agent-main:sess-001", # 可选，覆盖构造时的 session_id)print(result)
请求参数
参数名 | 类型 | 必填 | 描述说明 |
messages | List[Dict] | 是 | 消息列表，单次 1–100 条 |
session_id | str | 是 | 消息归属的会话 ID。 初始化客户端时设置默认值： MemoryClient(..., session_id="your-session-id")，后续所有写入自动归属该会话。调用时单独指定： client.add_conversation(messages, session_id="your-session-id")，适用于同一客户端需向不同会话写入的场景。说明： 若两种方式同时使用，调用时指定的值优先。若初始化时未设置、调用时也未传入，SDK 将抛出 ValueError，以防止消息因缺少会话标识而被错误写入公共空间。 |
messages[] 子结构
参数名 | 类型 | 必填 | 描述说明 |
role | str | 是 | 消息角色，取值： user、assistant。 |
content | str | 是 | 消息内容，长度限制：[1, 8192]，即单条上限 8 KB。 |
timestamp | str | 否 | 消息时间戳。 格式：ISO 8601（例如 2026-07-22T10:00:00Z）。缺省取服务端接收时刻。 |
响应示例
{"accepted_ids": ["msg-aaaa", "msg-bbbb"],"accepted_versions": ["v1", "v1"],"total_count": 2}
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1
响应参数说明
参数名 | 类型 | 参数含义 |
accepted_ids | List[str] | 受理成功的消息 id 列表 |
accepted_versions | List[str] | 与 accepted_ids 一一对应的版本号，新建消息固定为 v1 |
total_count | int | 实际受理的消息数量 |
错误码
错误码 | 触发场景 | 处理建议 |
400 | messages 为空或超过 100 条 | 检查消息列表长度 |
401 | API Key 无效或过期 | 检查 api_key 配置 |
422 | 构造参数缺失 team_id / agent_id / user_id | 确保构造时传入必填归属参数 |
500 | 服务内部错误 | 可有限重试 |
