客户端介绍
MemoryClient 是 V3 数据面同步客户端，用于初始化与 Memory 服务的连接并绑定身份归属信息，提供 L0–L3 四层记忆数据的完整读写能力。导入
from tencentdb_agent_memory.v3 import MemoryClient
构造参数
参数名 | 类型 | 必填 | 描述说明 |
endpoint | str | 是 | Memory 服务接入地址 |
api_key | str | 是 | API Key，格式 sk-... |
service_id | str | 否 | 实例 ID，如 tdai-mem-xxxxxxxx。使用自定义传输通道构造时可省略 |
team_id | str | 是 | 团队 ID |
agent_id | str | 是 | Agent ID（全局唯一） |
user_id | str | 是 | 用户 ID |
session_id | str | 否 | 默认会话 ID，传入后在 L0/L1 调用中按此 session 收敛；不传则跨 session 聚合 |
task_id | str | 否 | 默认 Task ID |
timeout | float | 否 | 请求超时时间（秒），默认 30 |
verify | bool | 否 | 是否验证 SSL 证书，默认 False |
stub | Stub | 否 | 自定义网络传输通道，用于测试场景（如注入 mock） |
使用示例
from tencentdb_agent_memory.v3 import MemoryClientclient = 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",session_id="agent-main:sess-001",task_id="task-2026q3",timeout=30,verify=False,)# 写入对话result = client.add_conversation(messages=[{"role": "user", "content": "帮我查一下上周的会议纪要"},{"role": "assistant", "content": "好的，根据记忆..."},],)print(result) # {'accepted_ids': [...], 'accepted_versions': [...], 'total_count': 2}# 查询记忆memories = client.query_conversation(limit=20)print(f"共 {memories['total']} 条消息")for msg in memories['messages']:print(f"[{msg['role']}] {msg['content']}")# 使用完毕后关闭client.close()
上下文管理器（推荐）
使用
with 语句自动管理连接的创建和销毁：with 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.query_conversation(limit=20)# 退出 with 块时自动调用 close()
with_isolation 动态切会话
SDK 提供
with_isolation() 方法返回共享同一网络连接的新客户端副本，可在运行时动态调整隔离参数，适用于"跨 Agent / 跨 session"调用场景：# 切换到另一个 session 或 agentalt_client = client.with_isolation(session_id="agent-main:sess-002",# agent_id="agt-another", # 也可切换 agent)result = alt_client.query_conversation(limit=20)# 跨全部 session 聚合查询global_client = client.with_isolation(session_id=None)all_messages = global_client.query_conversation(limit=1)print(f"全部会话共 {all_messages['total']} 条消息")
说明：
调用时传
None 不会清除构造值，跨 session 查询请使用 with_isolation(session_id=None)。close 销毁
client.close()
关闭客户端连接，释放底层
httpx.Client 资源。建议在程序退出前调用，或使用上下文管理器自动管理。异常处理
SDK 提供两种异常类型：
异常类 | 说明 |
TDAMError | 服务端返回的业务错误（ code != 0），包含 code、message、request_id、details 属性 |
ParamError | 客户端参数校验失败 |
from tencentdb_agent_memory.v3 import MemoryClientfrom tencentdb_agent_memory import TDAMError, ParamErrortry:result = client.query_conversation(limit=9999)except TDAMError as e:print(f"业务错误: code={e.code}, message={e.message}, request_id={e.request_id}")except ParamError as e:print(f"参数错误: {e}")
响应格式
所有方法均返回
Dict[str, Any]，为 ApiResponseEnvelope 的 data 字段内容。当
code == 0 时直接返回 data 字典；当 code != 0 时抛出 TDAMError 异常。额外字段
trace_id：如果服务端响应头中包含 x-trace-id，会追加到返回字典中，方便问题排查。
