帮你快速理解、总结文档立即下载
文档中心>腾讯云数据库 AI 服务>Memory 应用指南>开发者参考>V3 版本>Python SDK>SDK 简介

SDK 简介

最近更新时间：2026-07-28 10:20:02

我的收藏

本页目录：

SDK 概述

云数据库 Agent Memory（TencentDB Agent Memory）Python SDK 为 Memory V3 API 提供了完整的 Python 语言封装。SDK 版本 0.2.0，支持同步和异步两种调用方式，覆盖数据面 L0–L3 四层记忆、Skill 管理和元数据管理三大场景。

获取与安装

获取 SDK 包

前往 Python SDK V3 下载页面 获取最新版本的 .whl 安装包：
tencentdb_agent_memory_sdk_python-0.2.0-py3-none-any.whl

安装

下载 .whl 文件后，在本地执行以下命令完成安装：
pip install tencentdb_agent_memory_sdk_python-0.2.0-py3-none-any.whl
安装成功后，即可在项目中导入 SDK：
from tencentdb_agent_memory.v3 import MemoryClient

客户端组成

V3 SDK 包含三个客户端，分别面向不同的使用场景：
客户端
导入路径
用途
方法数
MemoryClient
tencentdb_agent_memory.v3
L0–L3 数据面读写
18
SkillClient
tencentdb_agent_memory.v3
Skill 全生命周期管理
14
MetadataClient
tencentdb_agent_memory.v3
管理面：用户/团队/Agent/Task/资产/ACL/Knowledge 等资源
59
每个客户端均提供同步版和异步版（Async 前缀），方法签名完全一致。

与 HTTP API 的差异说明

Python SDK 在 HTTP API 基础上进行了以下封装优化，与直接调用 HTTP API 有以下关键差异：
维度
HTTP API
Python SDK
归属信息
每次请求手动传递 team_id/agent_id/user_id
构造时传入，SDK 自动携带到每次请求
session 切换
每次请求手动设置 session_id
with_isolation() 动态切换，或调用时传递 session_id 参数。注意：调用时传 None 不会清除构造值，跨 session 需用 with_isolation(session_id=None)
scenario/ls
file_path 参数
path_prefix 参数
scenario/rm
file_paths 数组
path 单路径字符串
scenario/write
无 summary 字段
额外支持 summary 摘要字段
delete_conversation
仅 message_ids
支持 message_ids 或 session_id（至少一项）
delete_atomic
atomic_ids 数组
ids 数组（参数名不同）
错误处理
ApiResponseEnvelope.code
code != 0 抛出 TDAMError 异常
scenario/read
file_path 参数
path 参数

使用前提

1. 已创建 Memory 实例，获取实例 ID（如 tdai-mem-xxxxxxxx）
2. 已获取 API Key（密钥格式：sk-...）
3. 已明确团队 ID、Agent ID 和用户 ID 等归属信息

快速开始

from tencentdb_agent_memory.v3 import MemoryClient

# 初始化（team_id / agent_id / user_id 必填）
client = 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",  # 可选，不传则读接口跨 session 聚合；写接口需至少一处提供
)

# 写入对话
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()

异步版本

import asyncio
from tencentdb_agent_memory.v3 import AsyncMemoryClient

async def main():
    client = AsyncMemoryClient(
        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",
    )
    result = await client.query_conversation(limit=10)
    print(result)
    await client.close()

asyncio.run(main())

上下文管理器（推荐）

# 同步
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)

# 异步
async with AsyncMemoryClient(
    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 = await client.query_conversation(limit=20)

异常处理

SDK 提供两种异常类型：
异常类
说明
TDAMError
服务端返回的业务错误（code != 0），包含 code、message、request_id、details 属性
ParamError
客户端参数校验失败
from tencentdb_agent_memory.v3 import MemoryClient
from tencentdb_agent_memory import TDAMError, ParamError

try:
    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，会追加到返回字典中，方便问题排查。

中国站