Skip to content

ADK 智能体 GoodMem 插件 (GoodMem)

Supported in ADKPython

GoodMem ADK 插件 将你的 ADK 智能体连接到 GoodMem（一种基于向量的语义记忆服务）。此集成使你的智能体拥有跨对话的持久、可搜索记忆，使其能够回忆过去的交互、用户偏好和上传的文档。

共有两种集成方式：

方式 描述
插件 (GoodmemPlugin) 隐式的、确定性的记忆，通过 ADK 回调在每一轮对话中实现。自动保存所有对话回合和文件附件。
工具 (GoodmemSaveTool, GoodmemFetchTool) 显式的、由智能体控制的记忆。智能体决定何时保存和检索信息。

使用场景

  • 智能体的持久化记忆：赋予你的智能体可以在跨对话中依赖的长期记忆。
  • 自动化的、多模态记忆管理：自动保存和检索对话中的信息，包括用户消息、智能体响应以及文件附件（PDF、DOCX 等）。
  • 永不从零开始：智能体可以回忆起你是谁、你们讨论过什么以及已经解决的方案——从而节省 Token 并避免重复劳动。

先决条件

  • 一个 GoodMem 实例（自托管或云端）
  • GoodMem API 密钥
  • Gemini API 密钥（用于使用 Gemini 自动创建嵌入）

安装

pip install goodmem-adk

在智能体中使用

import os
from google.adk.agents import LlmAgent
from google.adk.apps import App
from goodmem_adk import GoodmemPlugin

plugin = GoodmemPlugin(
    base_url=os.getenv("GOODMEM_BASE_URL"),  # 例如 "http://localhost:8080"
    api_key=os.getenv("GOODMEM_API_KEY"),
    top_k=5,  # 每轮检索的记忆条数
)

agent = LlmAgent(
    name="memory_agent",
    model="gemini-2.5-flash",
    instruction="你是一个具有持久记忆的得力助手。",
)

app = App(name="GoodmemPluginDemo", root_agent=agent, plugins=[plugin])

import os
from google.adk.agents import LlmAgent
from google.adk.apps import App
from goodmem_adk import GoodmemSaveTool, GoodmemFetchTool

save_tool = GoodmemSaveTool(
    base_url=os.getenv("GOODMEM_BASE_URL"),  # 例如 "http://localhost:8080"
    api_key=os.getenv("GOODMEM_API_KEY"),
)
fetch_tool = GoodmemFetchTool(
    base_url=os.getenv("GOODMEM_BASE_URL"),
    api_key=os.getenv("GOODMEM_API_KEY"),
    top_k=5,
)

agent = LlmAgent(
    name="memory_agent",
    model="gemini-2.5-flash",
    instruction="你是一个具有持久记忆的得力助手。",
    tools=[save_tool, fetch_tool],
)

app = App(name="GoodmemToolsDemo", root_agent=agent)

可用工具

插件回调

GoodmemPlugin 使用 ADK 回调来自动管理记忆：

回调 描述
on_user_message_callback 将用户消息和文件附件保存到记忆中
before_model_callback 检索相关记忆并将其注入到提示词中
after_model_callback 将智能体的响应保存到记忆中

这些回调是确定性的，在每次智能体交互期间运行，将所有通过智能体传递的信息保存到记忆中。智能体不需要决定何时保存或检索信息。

工具

当使用工具方式时，智能体可以访问：

工具 描述
goodmem_save 将文本内容和文件附件保存到持久记忆中
goodmem_fetch 使用语义相似度查询搜索记忆

这些工具由智能体按需调用，智能体可以根据对话上下文选择何时保存（可能带有重写）或检索信息。

配置

环境变量

变量 是否必填 描述
GOODMEM_BASE_URL 是 GoodMem 服务器 URL（不带 /v1 后缀）
GOODMEM_API_KEY 是 GoodMem 的 API 密钥
GOOGLE_API_KEY 是 用于自动创建 Gemini 嵌入器的 Gemini API 密钥
GOODMEM_EMBEDDER_ID 否 固定特定的嵌入器（必须存在）
GOODMEM_SPACE_ID 否 固定特定的记忆空间（必须存在）
GOODMEM_SPACE_NAME 否 覆盖默认空间名称（如果缺失则自动创建）

空间解析

如果没有配置空间，系统将为每个用户自动创建一个：

  • 插件：adk_chat_{user_id}
  • 工具：adk_tool_{user_id}

其他资源