TencentDB Agent Memory Python SDK 实战：用 v2/v3 双客户端接入团队级 Agent 记忆体系

TencentDB Agent Memory Python SDK 实战用 v2/v3 双客户端接入团队级 Agent 记忆体系【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory本文是tencentdb-agent-memory-sdk-pythonPython 模块名tencentdb_agent_memory的完整使用指南。该 SDK 是TencentDB Agent Memory一个面向 AI Agent 的团队级记忆中心的官方 Python 客户端提供同步MemoryClient与异步AsyncMemoryClient两套接口覆盖 L0 对话、L1 原子记忆、L2 场景文件、L3 核心记忆、Offload 上下文压缩以及 v3 严格隔离数据面、管理面Metadata / Knowledge与 Skill 资产管理。读完本文你将掌握从安装、分层调用到隔离模型选型与错误处理的全部实战技能。一、SDK 概览与包布局先明确几个关键标识避免在安装与导入时混淆维度值发行名PyPItencentdb-agent-memory-sdk-python导入路径tencentdb_agent_memory当前版本0.2.0见 pyproject.tomlPython 版本要求3.9运行时依赖httpx0.24.0自带异步支持LicenseMIT包内版本布局与 tencentcloud-sdk-python 子模块拆版本风格一致见 tencentdb_agent_memory/init.py默认导出指向 v2from tencentdb_agent_memory import MemoryClient拿到的是 v2 客户端老代码升级 SDK 后零修改即可继续工作v3 需显式导入from tencentdb_agent_memory.v3 import MemoryClient切换到 v3 严格 isolation 版本构造时team_id/agent_id/user_id全部必填路径走/v3管理面客户端from tencentdb_agent_memory.v3 import MetadataClient/AsyncMetadataClient封装 v3 管理面接口Skill 客户端from tencentdb_agent_memory.v3 import SkillClient/AsyncSkillClient封装/v3/skill/*。SDK 源码结构清晰核心文件均在sdk/memory-core/python/tencentdb_agent_memory/下v2/client.pyv2 数据面、v3/client.pyv3 数据面、v3/metadata_client.py管理面、v3/skill_client.py技能面、_http.py/_v3_http.pyHTTP 传输层、cos.py对象存储工件读取、errors.py错误类型。中文版文档与 Agent 接入指南可参阅 README_CN.md 与 AGENT_GUIDE.python.zh-CN.md。二、安装与构建打包2.1 安装从 PyPI 安装发布后pip install tencentdb-agent-memory-sdk-python或安装本地构建出的 wheelpip install ./tencentdb_agent_memory_sdk_python-0.1.0-py3-none-any.whl2.2 自行构建项目使用hatchling作为构建后端见 pyproject.toml。构建 wheelpython -m build # → dist/tencentdb_agent_memory_sdk_python-0.1.0-py3-none-any.whl或只构建 wheel不拉取构建依赖pip wheel . --no-deps -w dist/pyproject.toml还声明了开发依赖组devpytest、pytest-asyncio、respx、build、python-dotenv需要时用pip install -e .[dev]安装。值得注意[tool.hatch.build.targets.wheel]只打包tencentdb_agent_memory一个包SDK 唯一的运行时依赖是httpx因此整体体积与依赖面都很轻。三、快速开始同步 MemoryClientv2 数据面3.1 构造参数MemoryClient的构造签名见 v2/client.py参数类型默认值说明endpointstr记忆服务 Base URL如http://127.0.0.1:8420api_keystrBearer Token通过Authorization头发送service_idstrNone必填记忆实例 ID通过x-tdai-service-id头发送timeoutfloat30请求超时秒verifyboolFalse是否校验 TLS 证书v2 默认关闭stubStubNone注入自定义传输层便于测试注意未注入stub时必须提供service_id否则抛出ValueError。3.2 最小可用示例from tencentdb_agent_memory import MemoryClient client MemoryClient( endpointhttp://127.0.0.1:8420, api_keyyour-api-key, service_idyour-memory-space-id, ) # L0: append a conversation result client.add_conversation( session_idsess-1, messages[ {role: user, content: Hello}, {role: assistant, content: Hi!}, ], ) print(result[accepted_ids]) # L1: search structured memories hits client.search_atomic(queryuser preferences, limit5) print(hits[items]) # L1: update a memory note client.update_atomic(idnote-xxx, contentupdated content, backgroundcontext) # L2: list scenario files scenarios client.list_scenarios(path_prefix) print(scenarios[entries]) # L2: read a scenario file file client.read_scenario(工作.md) print(file[content]) # L2: update a scenario file (must already exist) client.write_scenario(工作.md, # Updated content, summarynew summary) # L3: read core memory (persona) core client.read_core() print(core[content]) # L3: write core memory client.write_core(# User Profile\n...) # Offload v2: send tool pairs for server-side L1 async processing (fire-and-forget) client.offload_ingest( session_idagent_sess_123, tool_pairs[ {tool_name: search, tool_call_id: call_1, params: {q: ...}, result: ..., timestamp: ...}, ], ) # Offload v2: server-side context compaction (sync wait for result) compacted client.offload_compact( session_idagent_sess_123, messages[...], ratio0.7, context_window128000, ) print(compacted[messages], compacted[report]) # Read memory pipeline artifacts (e.g. persona.md, scene_blocks/*.md) raw client.read_file(scene_blocks/工作.md)3.3 底层传输原理所有方法最终都经由 _http.py 中的HttpStub发出POST请求关键机制有三点鉴权头请求固定携带Authorization: Bearer {api_key}、x-tdai-service-id: {service_id}与Content-Type: application/json响应 envelope 解包服务端返回{code, message, data}包裹结构code 0时只把data返回给调用方code ! 0时抛出TDAMError链路追踪若响应头带有x-trace-id会被合并进返回 dict键名trace_id便于与网关侧日志串接排查。另一个值得注意的细节是团队记忆 4 ID 隔离字段v2 的每个方法都接受可选的team_id/agent_id/user_id/task_id源码中_id_fields辅助函数负责剔除None后注入请求体。服务端resolveIsolation优先取 body 字段缺失时回退到x-tdai-*header——这为后续 v3 的严格隔离语义做了铺垫。四、分层 API 全解L0–L3 与 OffloadSDK 完整暴露了 v2 数据面的 14 条分层 API 与 3 条 Offload API。分层语义对应 Agent 记忆的加工深度L0 Conversation对话原始层追加、查询、搜索、删除会话消息是记忆体系的原始输入L1 Atomic结构化原子记忆把对话蒸馏成一条条可检索的原子记忆偏好、事实、决策等支持type过滤与全文检索L2 Scenario场景文件以 Markdown 文件组织场景化记忆如工作.md读写需显式指定路径L3 Core核心记忆 / Persona面向 agent 人格与长期画像的核心记忆通常由管线自动生成也可手动覆写Offload服务端卸载把 L1 异步抽取、上下文压缩、任务流程图查询下沉到服务端执行。4.1 API 方法总表下表完整列出各方法与其对应端点同步/异步客户端 API 面一致LayerMethodEndpointL0add_conversation()POST /v2/conversation/addL0query_conversation()POST /v2/conversation/queryL0search_conversation()POST /v2/conversation/searchL0delete_conversation()POST /v2/conversation/deleteL1update_atomic()POST /v2/atomic/updateL1query_atomic()POST /v2/atomic/queryL1search_atomic()POST /v2/atomic/searchL1delete_atomic()POST /v2/atomic/deleteL2list_scenarios()POST /v2/scenario/lsL2read_scenario()POST /v2/scenario/readL2write_scenario()POST /v2/scenario/writeL2rm_scenario()POST /v2/scenario/rmL3read_core()POST /v2/core/readL3write_core()POST /v2/core/writeOffloadoffload_ingest()POST /v2/offload/ingestOffloadoffload_compact()POST /v2/offload/compactOffloadoffload_query_mmd()POST /v2/offload/query-mmd4.2 各层方法参数细节L0 对话query_conversation支持session_id、limit/offset分页与time_start/time_end时间窗过滤search_conversation额外接受query关键词delete_conversation的message_ids与session_id二选一源码中二者均为可选但至少要提供一个才会产生有效删除动作。L1 原子记忆search_atomic(query, limit, type, ...)按语义/关键词检索query_atomic(type, limit, offset, time_start, time_end)按类型与时间窗枚举update_atomic(id, content, background)的background用于携带更新时的上下文信息供服务端判断改写策略delete_atomic(ids)接受 ID 列表批量删除。L2 场景文件read_scenario返回{content, created_at, updated_at}文件不存在时content为Nonewrite_scenario要求目标文件已存在必须先创建再更新可附带summary供场景索引使用rm_scenario删除指定路径文件。L3 核心记忆read_core返回{content, created_at, updated_at}若核心记忆尚未生成则content为Nonewrite_core(content)直接覆写。Offload服务端卸载offload_ingest(session_id, tool_pairs, promptNone, recent_messagesNone)上报工具调用对以触发服务端 L1 异步处理可 fire-and-forget忽略返回值。tool_pairs每项含tool_name、tool_call_id、params、result、timestamp可选duration_msprompt携带最新 user message 用于 L1.5 任务判断recent_messagesrolecontent辅助 L1 提取上下文offload_compact(session_id, messages, ratio, total_tokens, context_windowNone, message_tokensNone)对完整对话执行服务端压缩同步等待结果返回{messages, report}。ratio为当前 token 使用比例已用 / context_windowtotal_tokens需包含 system prompt、tool schemas 等不在 messages 中的隐性开销服务端据此计算 fixed overhead 并校准估算若提供message_tokens列表则可跳过服务端逐条估算提升性能offload_query_mmd(session_id, limitNone)查询会话的任务流程图MMD 文件返回{mmds, current_mmd}mmds每项含filename、content、versionlimit1时走快速路径只返回当前活跃 MMD。五、read_file直接读取记忆管线工件除分层 API 外SDK 还提供client.read_file(path)直接读取记忆管线产物例如根目录的persona.md或scene_blocks/*.mdscene_blocks/工作.md这类相对路径。它是存储无关的公开接口当前底层使用 COS 对象存储但对调用方透明。其实现见 cos.py分四步向平台POST /v2/cos/secret获取 STS 临时凭证含CosUrl、TmpSecretId、TmpSecretKey、TmpToken、ExpirationTime、PathPrefix凭证按过期时间缓存StsCredentialManager线程安全地自动刷新并保留 120 秒缓冲提前过期同时合并并发刷新请求使用 STS 凭证对 COS V5 GET 请求做签名hmac 签名以字符串返回文件内容。read_file首次调用时惰性初始化StsCredentialManager与MemoryFileReader复用同一个传输层的 endpoint / api_key / service_id因此不会给纯分层调用带来额外开销。读取失败404、鉴权失败等统一抛TDAMError。六、异步客户端 AsyncMemoryClient在 asyncio 应用FastAPI、异步 Agent 框架等中使用AsyncMemoryClient获得同样的 API 面所有方法均为协程并支持异步上下文管理器import asyncio from tencentdb_agent_memory import AsyncMemoryClient async def main(): async with AsyncMemoryClient( endpointhttp://127.0.0.1:8420, api_keyyour-api-key, service_idyour-memory-space-id, ) as client: result await client.search_atomic(querypreferences) print(result[items]) asyncio.run(main())异步客户端底层使用httpx.AsyncClient见 _http.py 的AsyncHttpStubenvelope 解包、错误抛升与x-trace-id传播逻辑与同步版完全一致close()/__aexit__会同时关闭传输层与 COS 读取器。七、v3 严格隔离客户端团队级数据治理的正确姿势当记忆需要按 团队 → Agent → 用户 严格隔离时应切换到 v3 客户端v3/client.py。7.1 与 v2 的核心差异维度v2v3构造要求仅service_id必填team_id/agent_id/user_id全部必填缺一立刻抛ParamErrorsession_id写入可选add_conversation写入必填构造或调用二选一缺失抛ValueErrorsession_id读取可选可选缺省时按(team, agent, user)跨 session 聚合agent 维度全量视图HTTP 路径/v2/.../v3/...TLS 校验verify默认False默认True且构造时严格校验 endpoint / api_key / service_id / timeout附加能力—新增count_*统计接口conversation / atomic / scenario / corev3 强制teamagentuser的原因源码注释明确避免服务端把无 session 的写入静默合并到默认 bucket导致不同调用方数据串扰。add_conversation缺 session_id 时的ValueError提示也直接给出了规避方案——写入必须显式带session_id而读取可以省略以做跨 session 聚合治理面板的 layer-counts、跨会话 L0/L1 列表等场景正是这种语义。7.2 典型用法from tencentdb_agent_memory.v3 import MemoryClient client MemoryClient( endpointhttps://memory.tencentyun.com, api_keysk-..., service_idmem-..., team_idt1, agent_ida1, user_idu1, session_ids1, # 可选不传时 L0/L1 查询走跨 session 聚合 ) client.add_conversation(messages[{role: user, content: hi}]) client.read_scenario(notes/2026Q2.md) # L2 不消费 session_id # 跨 session 拉某 agent 的全部 L0 对话总数 client.with_isolation(session_idNone).query_conversation(limit1)7.3 with_isolation按需切换隔离上下文with_isolation(team_idNone, agent_idNone, user_idNone, session_id..., task_id...)返回一个共享同一传输层的克隆客户端用于在不重建连接的前提下切换隔离字段传session_idNone或task_idNone显式清除已绑定的值省略参数则保留当前值。这非常适合多会话 Agent 在同一进程内复用连接、逐会话处理记忆的场景。v3 的 L2/L3 是teamagent级 profile 聚合天然不消费session_id此外 v3 客户端未暴露offload/read_file等非 L0–L3 接口需要时应继续使用 v2 客户端。八、MetadataClientv3 管理面元数据治理与 Knowledge 注册8.1 管理面 vs 数据面MetadataClient/AsyncMetadataClientv3/metadata_client.py封装的是网关 v3管理面接口。与数据面MemoryClient最大的不同不需要 isolation 四元组鉴权走 Bearer x-tdai-service-idteam_id等业务字段放在请求 body 中可选user_key通过x-tdai-user-key头传递user/create、user/delete等 system_admin 接口需要。其覆盖范围/v3/meta/*公开接口54 条与 Panel Control 的META_ACTIONS对齐含user-key/*涵盖 User、UserKey、Team、TeamMember、Agent、Task、TaskAgent、ParticipationLog、Asset、AgentFixedAsset、ACL、Authverify_auth、ConfigParamget_instance_quota/get/set_user_config等域/v3/knowledge/*Knowledge 实体 CRUD5 条非 meta 前缀保留兼容。方法命名直接反映语义create_user/get_user/delete_users/list_users、create_team/get_team/update_team/delete_teams/list_teams、add_team_member/remove_team_member、create_agent/archive_agent、link_task_agent/unlink_task_agent、grant_acl/revoke_acl/check_acl、verify_auth(user_key)、get_instance_quota()等并统一支持pagination参数。8.2 Knowledge 注册与管理from tencentdb_agent_memory.v3 import MetadataClient meta MetadataClient( endpointhttp://127.0.0.1:8420, api_keyverify-token, # gateway Bearer (KERNEL_AUTH_TOKEN) service_idknowledge-debug, # x-tdai-service-id # user_key..., # optional; only for system_admin endpoints ) # Register a wiki knowledge source k meta.create_knowledge({ knowledge_id: wiki-docs, type: wiki, service_url: http://127.0.0.1:8421/v3, # Knowledge Service>from tencentdb_agent_memory.v3 import SkillClient skills SkillClient( endpointhttps://memory.tencentyun.com, api_keysk-..., service_idmem-abc, team_idt1, agent_idagent-coder, user_idu1, ) created skills.create(namepy-tips, content---\nname: py-tips\n---\n# tips\n) skills.list()文件类操作使用encode_utf8(path, content, mime_typeNone, is_executableNone)/encode_base64(...)静态辅助函数构造SkillResourcePayload。SDK 同时导出一份SKILL_ERROR_CODE错误码映射便于精确处理业务错误错误码常量含义40001BAD_REQUEST请求参数非法40301NOT_OWNER非技能所有者40302TEAM_MISMATCH团队不匹配40401NOT_FOUND技能/资源不存在40901VERSION_STALE版本过期可依据details.current_version重试41002VERSION_EXPIRED版本已失效可依据details.latest_version升级41301RESOURCE_TOO_LARGE资源过大42201NAME_DUPLICATE名称重复42202PATCH_NOT_UNIQUEpatch 不唯一42203FRONTMATTER_INVALIDfrontmatter 非法50301QUEUE_UNAVAILABLE/STORAGE_NOT_FOUND队列/存储不可用50302LLM_UNAVAILABLELLM 不可用50303COS_REQUIRED需要 COS 支持十、错误处理TDAMError 与 ParamError10.1 TDAMError所有返回非零code的 API 响应都会抛出TDAMError定义见 errors.py其字段包括code服务端业务错误码message错误描述request_id请求 ID优先取响应头x-qcloud-transaction-id其次 envelope 内request_id便于与服务端日志串联detailsenvelope 中携带的data负载dict 类型——/v3/skill/*的版本类错误40901 / 41002会通过它返回current_version/latest_version方便调用方干净地重试或升级。from tencentdb_agent_memory import TDAMError try: client.read_core() except TDAMError as e: print(fcode{e.code} message{e.message} request_id{e.request_id})底层逻辑位于 _http.py响应体code ! 0时抛错code 0时解包data并合并x-trace-id。v3 专用传输层 _v3_http.py 更进一步构造时对endpoint必须是合法 http/https URL、api_key、service_id、timeout正数做严格校验缺一即抛ParamError响应解析时兼容 HTTP 错误状态码与非 JSON 响应。10.2 ParamErrorParamError用于调用方参数非法本地即抛出不发起请求例如v3MemoryClient构造缺team_id/agent_id/user_id、service_id缺失、delete_conversation既无message_ids也无session_id、extract缺隔离字段、管理面请求体非 dict 等。顶层导出TDAMError与ParamError两个错误类型见 tencentdb_agent_memory/init.py业务代码按需捕获。十一、总结tencentdb-agent-memory-sdk-python用一套轻薄仅依赖httpx的封装把 TencentDB Agent Memory 的团队级记忆能力完整暴露给 Python 开发者v2 数据面默认导出L0 对话 → L1 原子记忆 → L2 场景文件 → L3 核心记忆 → Offload 服务端卸载同步/异步双客户端 API 面一致老代码零迁移v3 数据面显式导入构造即强约束team/agent/user隔离四元组写入强制session_id、读取支持跨 session 聚合并新增count_*统计接口适合治理严格的多租户/多 Agent 场景管理面 MetadataClient54 条/v3/meta/* 5 条/v3/knowledge/*覆盖用户、团队、成员、Agent、任务、资产、ACL、配额与 Knowledge 元数据注册Skill 客户端版本化的技能资产 CRUD 与错误码语义化工程细节Bearer x-tdai-service-id鉴权、响应 envelope 解包、x-trace-id链路透传、COS 工件直读STS 凭证自动刷新、TDAMError/ParamError双错误体系。接入路径建议单 Agent 快速试用走 v2 默认导出多团队/多 Agent 治理优先 v3 with_isolation知识库元数据与技能资产管理则直接使用MetadataClient与SkillClient。相关源码均可在本仓库 sdk/memory-core/python 目录下继续深挖中英文文档与 Agent 接入指南也在同目录中。【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考