接入四步总览与 SDK 速查

接入四步总览与 SDK 速查

本节摘要:第 9 章面向「自研 Agent 用代码接入记忆」的场景,官方提供 Python 与 TypeScript 两套 SDK,把接入收敛成四步:召回、捕获、工具暴露、错误降级。本节先给四步法全景与 SDK 核心 API 速查,建立「这四步是什么、为什么是这四步」的整体认知。后续四节分别深入每一步。本质上,SDK 四步就是把第 8 章代理层帮你做的事,用代码自己做一遍——换来对每一格上下文的完全控制,代价是要自己处理污染、切片与降级。

一、四步法全景

接入记忆的四步,正好对应一次对话的「前-中-后」+ 「兜底」:

四步法全景
  用户提问
    ↓
  ① 召回:从记忆系统取相关内容,注入上下文
    ↓
  ② 捕获:对话过程中,把该沉淀的回写
    ↓ (同时)
  ③ 工具暴露:把知识(Wiki/CodeGraph)作为工具供模型调用
    ↓
  LLM 推理 + 答复
    ↓
  ④ 错误降级:以上任何一步失败,Agent 仍能正常工作
​

关键概念:SDK 四步与代理层八步是「同一件事的两种实现」——代理层帮你做了(零改造但失控),SDK 你自己做(可控但要写代码)。所以理解了第 8 章,第 9 章的每一步都能在代理层找到对应,只是现在由你用代码显式完成。

二、为什么是这四步

这四步不是随意分的,每步解决一个不可或缺的问题:

四者缺一不可——少召回等于没记忆,少捕获等于记忆不生长,少工具等于没知识,少降级等于记忆故障连累 Agent。这就是为什么官方 SDK 把这四步作为「接入清单」——它是接入记忆的最小完备集。

三、SDK 核心 API 速查

Python 与 TypeScript 两套 SDK 的核心 API,概念上一致:

SDK 核心 API(概念性,以 Python 风格示意)
  # 初始化客户端
  client = MemoryCoreClient(endpoint="http://localhost:8420", key="...")
  
  # ① 召回:取相关记忆
  memories = client.recall(query="用户问题", team_id=..., agent_id=...)
  
  # ② 捕获:回写对话
  client.capture(conversation=..., team_id=..., agent_id=...)
  
  # ③ 工具暴露:注册知识工具(供模型调用)
  tools = client.list_tools(team_id=...)  # 发现可用工具
  result = client.call_tool(tool_name="code_impact", params=...)  # 调用
  
  # 错误处理:四步都用 try/降级包裹
​

⚠️ 注意:以上是概念性示意,真实 API 名称与签名以本地 SDK 源码为准。SDK 提供 Python 与 TypeScript 两套,功能对等,选你 Agent 用的语言即可。后续章节会给出更接近真实的代码片段,但仍以概念说明为主——实际编码务必对照本地 SDK。

四、SDK 接入的最小骨架

把四步合起来,一个最小可用的接入骨架(概念性):

# 概念性骨架(Python 风格,真实 API 以本地 SDK 为准)
from memory_core import MemoryCoreClient

client = MemoryCoreClient(endpoint="...", key="...")

async def chat(user_message, session_ctx):
    # ① 召回(降级包裹)
    try:
        memories = await client.recall(query=user_message, **session_ctx)
        prompt = inject_memories(user_message, memories)
    except Exception:
        prompt = user_message  # 降级:无记忆也能答

    # ③ 工具暴露(把知识工具告知模型)
    tools = await client.list_tools(**session_ctx)

    # 推理
    reply = await llm.complete(prompt, tools=tools)

    # ② 捕获(降级包裹,失败不影响答复)
    try:
        await client.capture(conversation=(user_message, reply), **session_ctx)
    except Exception:
        pass  # 降级:回写失败不拖垮对话

    return reply
​

这个骨架体现了四步法的协作:召回在推理前、捕获在推理后、工具暴露伴随推理、降级包裹每一步。后续四节会展开每一步的细节。

五、SDK 与代理层的选型

什么时候用 SDK,什么时候用代理层?核心看「Agent 能不能改」:

💡 技巧:SDK 的收益是「完全控制」——召回什么、注入到哪、捕获什么、何时降级,全由你定。代价是「要自己处理细节」(下一节讲的注入两区块、第 4 节讲的工程坑)。如果你不需要这种精细控制,代理层的「省心」更合适;如果你要做严肃的产品级 Agent,SDK 的「可控」更值得。

本节要点回顾

1. 四步对应八步:SDK 召回/捕获/工具/降级,对应代理层 injection/extract/toolize/各步降级——同一件事两种实现。
2. 四步不可或缺:召回(有记忆)+ 捕获(记忆生长)+ 工具(有知识)+ 降级(故障不崩),最小完备集。
3. 核心 API:recall/capture/list_tools/call_tool,Python 与 TypeScript 对等。
4. 最小骨架:召回在推理前、捕获在后、工具伴随、降级包裹每步——第 9 章后续展开。
5. 选型:成熟 Agent 用代理层(不能改源码),自研 Agent 用 SDK(要完全控制)。

四步全景清楚了,下一节深入第一步——召回,讲清注入的两区块(prepend/append)布局及其命中 KV cache 的原理。