TencentDB Agent Memory · 第 9 章 SDK 接入开发:四步法

TencentDB Agent Memory · 第 9 章 SDK 接入开发:四步法

章节摘要:第 8 章讲了代理层如何让成熟 Coding Agent「零改造」接入记忆,本章面向另一种场景——你在自己写 Agent,想用代码直接接入记忆系统。官方提供 Python 与 TypeScript 两套 SDK,把接入收敛成四步:召回(从记忆系统取相关内容注入上下文)、捕获(把对话回写给记忆系统沉淀)、工具暴露(把知识能力作为工具供模型调用)、错误降级(记忆系统不可用时 Agent 仍能正常工作)。其中召回又分两个注入区块:prepend 区放动态 L1、append 区放稳定的 persona+scene+工具指南,这样的布局能让稳定部分命中模型的 KV cache。本章带你用双语言代码把四步跑通,并重点讲三个工程坑——召回内容污染用户消息时如何还原、写入位置如何切片避免重复、sanitize 如何清洗敏感字段。读完本章你能用几十行代码让自己的 Agent 拥有长期记忆,并知道在出错时如何优雅降级。

学习目标

阅读完本章,你应当能够:

1. 用 Python 或 TypeScript SDK 写出接入记忆的最小可用 Agent
2. 说清召回注入的 prepend / append 两区块各自放什么、为什么这样布局
3. 解释捕获回写的时机与对象(回写什么、不回写什么)
4. 复述三个工程坑(消息污染还原、写入位置切片、sanitize 清洗)的成因与对策
5. 应用错误降级三原则,确保记忆系统故障时 Agent 不宕机

核心概念速览

一句话金句:SDK 四步法的本质是「把代理层帮你做的事,用代码自己做一遍」——换来的是对每一格上下文的完全控制,代价是要自己处理污染、切片与降级。

子章节导航

01 接入四步总览与 SDK 速查

给出四步法全景与 SDK 的核心 API 速查表,讲清召回 / 捕获 / 工具暴露 / 错误降级四者的协作关系与调用顺序。

02 召回:注入两区块 prepend / append

深入召回实现:prepend 区为何放动态 L1、append 区为何放稳定 persona+scene+工具指南,以及这样的布局如何命中 KV cache。

03 捕获:工具暴露与对话回写

讲清捕获的两个动作——把 Wiki/CodeGraph 作为工具暴露给模型调用、把对话回写给记忆系统沉淀,以及回写的时机与对象选择。

04 工程坑:召回污染还原与 sanitize 清洗

本章硬核节:讲清三个高频坑——召回内容污染用户消息如何还原、写入位置如何切片避免重复写、sanitize 如何清洗敏感字段。

05 错误降级三原则与性能建议

讲清降级三原则(gather 用 return_exceptions、关键路径 try-catch、工具返回错误串而非抛异常)与性能建议(召回<200ms、注入大小控制、session 粒度)。

子章节之间的逻辑关系

本章四节对应四步法,第五节是横切的降级与性能,其中第四节是全书最实用的「避坑指南」之一:

┌──────────┐   ┌──────────┐   ┌──────────┐
│ 01 总览   │──▶│ 02 召回   │──▶│ 03 捕获   │
│ 四步速查  │   │ 两区块注入│   │ 工具+回写 │
└──────────┘   └──────────┘   └──────────┘
                                     │
                                     ▼
                            ┌────────────────┐
                            │ 04 工程坑 ★     │   (避坑:污染/切片/sanitize)
                            └────────────────┘
                                     │
                                     ▼
                            ┌────────────────┐
                            │ 05 降级与性能   │   (兜底:return_exceptions等)
                            └────────────────┘
​

铺垫说明:本章是「代码接入」视角,与第 8 章「代理接入」构成对子。同样的四件事,代理层帮你做了(代价是失去对上下文的精细控制),SDK 要你自己写(收益是每一格上下文都由你掌控)。第 04 节的工程坑是代理层内部同样要处理、但对你透明的那些问题——读完本章你会更理解代理层替你挡了多少刀。

前置知识与后续延伸

前置知识:

• 第 2 章的控制流旅程(SDK 四步是它的代码视角)
• 第 4 章的四层记忆(召回的 L1 与 persona/scene 来自分层)
• 第 7 章的 /v3/tools/call(工具暴露的对象就是 Wiki/CodeGraph)
• 熟悉 Python 或 TypeScript 其一,了解异步编程(gather / try-catch)

本章为后续章节奠定的基础:

• 四步法是第 10 章五框架接入中「自研 Agent / 通用 OpenAI 兼容」路径的实现基础
• 工程坑与降级原则是第 11 章场景实战的稳定性保障
• 性能建议(召回<200ms、注入大小控制)是第 12 章生产级运行的实操依据