如何使用Google ADK工具包来为你的 AI Agent创建 短期记忆和长期记忆能力

Python Tutor 智能体

我们先从一个使用 ADK 构建的简单对话式智能体开始。

• 模型：Gemini 2.5 Flash，提供推理能力。
• 工具：一组功能函数，帮助智能体进行 Python 字典小测验。

例如：start_quiz 工具可以启动一次新的测验工作流。

def start_quiz(tool_context: ToolContext) -> Dict[str, Any]:
    state = tool_context.state
    # 初始化测验状态
    state["quiz_started"] = True
    state["current_question_index"] = 0
    state["correct_answers"] = 0
    state["total_answered"] = 0
    state["score_percentage"] = 0
    if quiz:
        return {
            "status": "started",
            "first_question": quiz[0][0],
            "question_number": 1,
            "total_questions": len(quiz),
        }
    return {"status": "error", "error_message": "No questions available"}

整体测验流程如下：

1. 用户身份识别
2. 检索记忆（历史学习记录）
3. 个性化启动
4. 测验流程（开始 → 提问 → 答题 → 反馈）
5. 进度跟踪
6. 支持重置

系统指令（简化示例）：

QUIZ MANAGEMENT PROCESS:
1. 用户身份确认
2. 检查历史学习记录
3. 个性化启动
4. 测验流程：
   - start_quiz()
   - submit_answer()
   - 提供反馈
5. 追踪进度
6. 提供重置选项

定义 ADK 智能体：

root_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="python_tutor",
    instruction=QUIZ_INSTRUCTIONS,
    tools=quiz_tools
)

问题来了：如何让智能体记住用户的姓名或测验进度？这就是 短期记忆 的作用。

什么是“记忆”？

在 ADK 里，“记忆”是 AI 能记住你和它之间的互动历史。

分成两种：

1、短期记忆：会话中的“临时笔记”

你可以把短期记忆想象成你和一位朋友的一次简短对话。在这次对话中，你会记住他刚刚说了什么，但一旦挂了电话，这段记忆就结束了。

在 ADK 中，短期记忆被称为会话状态 (Session State)。它就像是代理在单次对话中的一个“临时记事本”或“草稿板”。这个状态以键值对 (key-value pair) 的形式存储，代理可以在对话进行中随时读取和更新它。

• 工作方式： 代理的工具（tools）可以在执行时更新会话状态。例如，博客中提到的 Python 辅导代理，就可以用它来记住用户当前回答到第几题了。
• 存储方式： 对于简单的应用，这个状态可以暂时储存在代理的运行内存中。但为了确保稳定性和可靠性，特别是对于生产环境下的应用，文章建议使用更持久的存储服务，比如数据库（DatabaseSessionService）或者谷歌的 Vertex AI Agent Engine（VertexAISessionService）。这样即使代理重启，会话信息也不会丢失。

2、长期记忆：跨会话的“老朋友”

长期记忆则更像是一位熟悉你的客服代表，他不仅记得你这次的来电，还能回忆起你之前几次的求助记录。这种记忆能力让代理可以记住同一个用户在不同会话之间的信息。

这对于需要个性化和持续互动的应用至关重要，比如一个能记住学生学习进度并定制化课程的教学代理。

• 两种实现方式：

1. 简单关键字记忆（InMemoryMemoryService）： 这是一种基础的长期记忆方式，它通过关键词搜索来检索过去的对话。它的优点是简单，但缺点是理解力有限，只适用于简单的记忆需求。
2. 智能记忆库（Memory Bank）： 这是 Vertex AI Agent Engine 的一项高级功能。它利用强大的 Gemini 模型来处理和存储信息。这个记忆库不仅仅是存储对话文本，它还能“理解”对话的含义，并提取和存储关键的事实，从而在需要时提供更准确和有用的信息。

为什么这很重要？

结合使用这两种记忆，是构建真正智能、上下文感知且个性化 AI 代理的关键。

短期记忆让代理在当前对话中表现得连贯和高效，而长期记忆则让代理能够随着时间的推移，变得越来越“了解”用户，提供更贴心和有用的服务。

什么是“会话”？

每次你和 AI 聊天的过程，就是一个「会话 session」，就像你打客服电话，每次接通是一次新的对话。

• AI 只能记住你“这次说了什么”，说完就忘。
• 除非你把这些信息保存下来（用 ADK 提供的“状态”和“记忆”功能）。

明白了 ✅ 这次我会严格按照 原文结构 来做完整翻译：

• 正文翻译为中文
• 代码保留英文（下方加中文解释）
• 图像全部保留（用 Markdown 原始链接）
• 保持与第一版相同的格式，但补齐 代码 + 图像

想象一下，你是一名开发者，而你的朋友正在第一次学习编程。他们在理解一些概念时遇到了困难，比如 Python 的 字典。

但是你有了一个想法！如果你能设计一个 AI agent 来帮助你的朋友以对话的方式学习复杂主题会怎么样？如果这个 agent 还能根据朋友的学习风格进行个性化、记住朋友过去的表现，并实时调整学习计划呢？借助 agent 的状态（state）与记忆（memory），这一切都是可能的。在这篇文章中，我们将探讨如何使用 Agent Development Kit (ADK) 实现这些功能。

Python Tutor agent

我们从一个简单的 Python 辅导 agent 开始。这个 agent 使用 Gemini 2.5 Flash 作为模型，利用其推理能力。它还依赖一些工具函数（function tools）来帮助用户完成 Python 字典的测验。

例如，这里有一个 start_quiz 工具：

def start_quiz(tool_context: ToolContext) -> Dict[str, Any]:
    state = tool_context.state
    # Initialize quiz state
    state["quiz_started"] = True
    state["current_question_index"] = 0
    state["correct_answers"] = 0
    state["total_answered"] = 0
    state["score_percentage"] = 0
    if quiz:
        return {
            "status": "started",
            "first_question": quiz[0][0],
            "question_number": 1,
            "total_questions": len(quiz),
        }
    return {"status": "error", "error_message": "No questions available"}

👉 说明：这段代码定义了一个工具，用来开启新的测验，并在 state 中标记测验已开始。

总体来说，这是我们希望 agent 执行的测验流程：

接着，我们用系统指令来提示 agent，让模型能够推理完成这个流程：

QUIZ_INSTRUCTIONS = """
QUIZ MANAGEMENT PROCESS:
1. **User identification**: Ask for their name if not provided
2. **Memory check**: Search for their previous learning history using search_memory()
3. **Personalized start**: Reference their past progress if found, or welcome new learners
4. **Quiz flow**:
   - When user wants to start: Use start_quiz()
   - Present questions clearly with proper formatting
   - When user answers: Use submit_answer(answer="[user's answer]")
   - Provide immediate feedback:
     * If correct: Congratulate and continue
     * If incorrect: Explain the concept thoroughly and continue. DO NOT GIVE THE USER A SECOND CHANCE TO ANSWER, just move on to the next question!
     * If quiz complete: Show final score and offer concept review
5. **Progress tracking**: Use get_quiz_status() to monitor progress
6. **Reset option**: Use reset_quiz() if they want to start over
"""

👉 说明：这里定义了 agent 的工具集合（包括提问、判定答案等），并在 instructions 中指定了系统角色提示。

从这里，我们可以定义我们的 ADK 代理，然后开始工作：

root_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="python_tutor",
    instruction=QUIZ_INSTRUCTIONS,
    tools=quiz_tools
)

但是，我们如何让这个智能体记住学生会话期间发生的事情，例如他们的姓名或他们在测验中的进度？这就是短期记忆发挥作用的地方。

短期记忆（Short-term memory）

在 AI agent 的语境中，短期记忆指的是 agent 在单次会话（session）中能记住的内容。

那么，什么是会话？你可以把会话比作一次客户服务热线的电话——但每次你打电话，接线员都不同。这个接线员只能记住你在这次通话中告诉他们的内容。一旦挂断电话，所有上下文就都消失了。

短期记忆听起来可能不太好，但它在 AI agent 中扮演着重要角色。比如，Python Tutor agent 可能需要记录用户测验的进度，比如已经完成了多少道题。但 agent 并不需要长期保存这些进度——它可能只需要存储最终得分。

在 ADK 中，每次用户与 agent 交互都会开启一个会话，而会话由 SessionService 管理。每个会话包含一些重要字段，比如会话 ID、用户 ID、事件历史（对话内容），以及 state。

那么，会话的 state 是什么？你可以把它看作是 agent 在那次“电话”中使用的小黑板。每个会话的 state 包含一个 键值对列表，这些值会在会话过程中不断被更新。

ADK 提供了几种写入 state 的方式。比如，在工具内部使用 ADK 的 ToolContext 获取当前会话 state，并创建或更新字段。

from google.adk.tools.tool_context import ToolContext
def submit_answer(tool_context: ToolContext, answer: str) -> Dict[str, Any]:
    state = tool_context.state
    i = state.get("current_question_index", 0)
    correct_answer = quiz[i][1]
    is_correct = answer.strip().lower() == correct_answer.strip().lower()
    state["total_answered"] = state.get("total_answered", 0) + 1
    if is_correct:
        state["correct_answers"] = state.get("correct_answers", 0) + 1

然后，我们可以通过 key templating 功能让 agent 读取当前 state 的字段。你只需要在 prompt 中 用花括号 {} 包裹一个 state 字段，ADK 就会在每次模型调用时自动把该字段的值注入进去。

prompt="""
INSTRUCTIONS:
- Guide users through Python dictionaries with key concepts and examples.
- Format code examples using markdown code blocks.
- Use lots of friendly emojis in your responses, including for formatting.
- Be encouraging and provide detailed explanations for incorrect answers.
CURRENT SESSION STATE:
- Current question index: {current_question_index}
- Questions answered correctly: {correct_answers}
- Total questions answered: {total_answered}
- Current score: {score_percentage} %
- Quiz started: {quiz_started}
"""

以下是 Python Tutor agent 在实时更新这些 state 字段的演示：

默认情况下，state 字段只在当前会话内有效；一旦开启新的会话，即使是同一用户，值也会消失。但 ADK 提供了一些 magic state key 前缀，比如 user: 和 app:，它们允许你把 state 值在跨用户或跨会话范围内保持。这对保存一些简单的设置（比如 dark-mode=true）非常有用。

到这里，我们介绍了 ADK 短期记忆的基本原理。但 ADK 是如何存储这些会话和 state 数据的呢？

默认情况下，ADK Web UI 的 SessionService 会把会话数据写入内存。这意味着如果 ADK 的运行环境崩溃或关闭，所有会话数据都会丢失。如果你在生产环境中运行多个 ADK agent 实例，也无法保证用户请求总是落到同一个实例上。比如，请求 1 落在实例 A，而请求 2 落在实例 B，那么实例 B 并不会有实例 A 中的内存 state。

因此，在生产级别的 agent 中，你应该把会话数据存储在 agent 运行时之外。ADK 提供了两种方式：

1. 使用 DatabaseSessionService：把会话数据存储在 SQL 数据库（SQLite、MySQL、PostgreSQL）中。这种方式容易设置，只需一个数据库即可。然后你可以把数据库的 URI 传给 ADK runner。

从此，你就可以直接在 SQL 数据库中访问会话和 state 表了。

2. 使用 VertexAISessionService：把会话数据存储在 Agent Engine 中。如果你本身已经在用 Agent Engine 来运行 ADK，这会是一个不错的选择。

长期记忆（Long-term memory）

前面我们介绍了 ADK 如何在会话中存储数据。但如果你希望把某些数据跨会话保存给同一个用户，就需要使用 ADK 的长期 memory。

一个带有长期记忆的 ADK agent，就像每次你都能打到同一个客服人员，而这个客服还记得你之前所有的对话。

比如，Python Tutor agent 可以保存用户的测验成绩，用来观察学生的进步情况；它还能根据学生反复出错的主题来制定个性化学习计划。

ADK 提供了两种存储长期记忆的方式：

1. 默认方式是使用 InMemoryMemoryService。这里，所有会话都会被原样存储（包括完整对话记录），并可通过关键词检索在后续会话中取回。这种方法适合本地开发，但它和 InMemorySessionService 一样存在问题：一旦 ADK 重启或崩溃，所有记忆都会消失。另外，如果你存了大量用户会话，在后续检索时直接加载完整历史，可能会给模型带来过多上下文压力。
2. 更推荐的方式是使用 VertexAIMemoryBankService，它借助 Vertex AI Memory Bank (Preview) 来智能存储和检索过往交互中的关键信息。

Memory Bank 使用 Gemini 模型从会话数据中提取关键信息，仅保存关键记忆，供未来使用：

为了把记忆存入 Memory Bank，我们在 Python Tutor agent 中实现一个 Callback，把当前会话数据添加进去。

async def auto_save_to_memory_callback(callback_context):
    session = callback_context._invocation_context.session
    memory_service = VertexAiMemoryBankService(
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
        agent_engine_id=agent_engine_id,
    )
    await memory_service.add_session_to_memory(session)
...

接着，我们让 agent 使用基于向量的相似度搜索（按关键词）来检索这些记忆。

async def search_memory(query: str) -> list:
    memory_bank_service = VertexAiMemoryBankService(
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION"),
        agent_engine_id=os.getenv("AGENT_ENGINE_ID"),
    )
    search_results = await memory_bank_service.search_memory(
        app_name="python-tutor-long-term",
        user_id="user",
        query="score",
    )
...

这样，我们的测验流程就能记住用户过去的成绩了：

以下是 Python Tutor agent 借助 Memory Bank 进行长期记忆检索的实操演示：

在幕后发生了什么？当 agent 在 after-agent Callback 中触发记忆生成时，Memory Bank 会用 Gemini 提取关键信息。因此，当用户开启新测验并触发 search_memory 检索过往结果时，Memory Bank 就会返回这些内容：

请注意，虽然 Memory Bank 是 Vertex AI Agent Engine 的一部分，但您无需在 Agent Engine 的运行时上运行您的 ADK 代理即可使用此功能。例如，您可以在 Cloud Run 上运行您的代理，然后将 Memory Bank 集成作为您的长期记忆存储。

总结一下，短期和长期记忆在 AI 代理中扮演着关键角色，使代理能够在用户会话内部和跨用户会话记住关键信息，从而带来更具上下文感知能力和个性化的用户体验。ADK 支持多种会话和记忆存储选项，从 SQL 数据库到 Vertex AI Agent Engine。

请在 GitHub 上查看源代码，亲自探索和部署 Python Tutor 代理。

要了解更多信息，请查看以下资源。

• ADK Documentation - Session
• ADK Documentation - Memory
• Vertex AI Memory Bank documentation 
• ADK Documentation - Deploy an agent to Cloud Run 

Thanks for reading!

Image credits: Emoji Kitchen

原文：https://cloud.google.com/blog/topics/developers-practitioners/remember-this-agent-state-and-memory-with-adk