Session：跟踪个别对话

Supported in ADKPython v0.1.0Java v0.1.0

在前述介绍之后，让我们深入了解 Session。回想一下"对话线程"的概念。就像你不会每次发短信都从头开始一样，智能体也需要了解当前交互的上下文。Session 是 ADK 专门设计用于跟踪和管理这些单独对话线程的对象。

Session 对象

当用户开始与你的智能体交互时，SessionService 会创建一个 Session 对象（google.adk.sessions.Session）。该对象作为单个对话线程相关所有内容的容器。其主要属性如下：

• 标识 (id, appName, userId)： 对话的唯一标签。
• id：此特定对话线程的唯一标识符，对于后续检索至关重要。一个 SessionService 对象可以处理多个 Session。此字段标识我们正在引用哪个特定的 session 对象。例如，"test_id_modification"。
• app_name：标识此对话属于哪个智能体应用。例如，"id_modifier_workflow"。
• userId：将对话链接到特定用户。
• 历史 (events)： 此特定线程中发生的所有交互（Event 对象——用户消息、智能体响应、工具操作）的时间顺序序列。
• Session 状态 (state)： 存储仅与此特定持续对话相关的临时数据的地方。这充当智能体在交互过程中的草稿板。我们将在下一节详细介绍如何使用和管理 state。
• 活动跟踪 (lastUpdateTime)： 指示此对话线程中最后一次发生事件的时间戳。

示例：检查 Session 属性

PythonJava

 from google.adk.sessions import InMemorySessionService, Session

 # 创建一个简单的 session 以检查其属性
 temp_service = InMemorySessionService()
 example_session = await temp_service.create_session(
     app_name="my_app",
     user_id="example_user",
     state={"initial_key": "initial_value"} # 可以初始化 state
 )

 print(f"--- 检查 Session 属性 ---")
 print(f"ID (`id`):                {example_session.id}")
 print(f"应用名 (`app_name`): {example_session.app_name}")
 print(f"用户 ID (`user_id`):         {example_session.user_id}")
 print(f"状态 (`state`):           {example_session.state}") # 这里只显示初始状态
 print(f"事件 (`events`):         {example_session.events}") # 初始为空
 print(f"最后更新时间 (`last_update_time`): {example_session.last_update_time:.2f}")
 print(f"---------------------------------")

 # 清理（本例可选）
 temp_service = await temp_service.delete_session(app_name=example_session.app_name,
                             user_id=example_session.user_id, session_id=example_session.id)
 print("temp_service 的最终状态 - ", temp_service)

 import com.google.adk.sessions.InMemorySessionService;
 import com.google.adk.sessions.Session;
 import java.util.concurrent.ConcurrentMap;
 import java.util.concurrent.ConcurrentHashMap;

 String sessionId = "123";
 String appName = "example-app"; // 示例 app 名称
 String userId = "example-user"; // 示例用户 id
 ConcurrentMap<String, Object> initialState = new ConcurrentHashMap<>(Map.of("newKey", "newValue"));
 InMemorySessionService exampleSessionService = new InMemorySessionService();

 // 创建 Session
 Session exampleSession = exampleSessionService.createSession(
     appName, userId, initialState, Optional.of(sessionId)).blockingGet();
 System.out.println("Session 创建成功。");

 System.out.println("--- 检查 Session 属性 ---");
 System.out.printf("ID (`id`): %s%n", exampleSession.id());
 System.out.printf("应用名 (`appName`): %s%n", exampleSession.appName());
 System.out.printf("用户 ID (`userId`): %s%n", exampleSession.userId());
 System.out.printf("状态 (`state`): %s%n", exampleSession.state());
 System.out.println("------------------------------------");


 // 清理（本例可选）
 var unused = exampleSessionService.deleteSession(appName, userId, sessionId);

（注意： 上述 state 仅为初始状态。状态更新通过事件完成，详见 State 章节。）

使用 SessionService 管理会话

如上所示，你通常不会直接创建或管理 Session 对象，而是通过 SessionService。该服务作为会话生命周期的中央管理者。

其核心职责包括：

• 开启新对话： 当用户开始交互时，创建新的 Session 对象。
• 恢复已有对话： 通过 ID 检索特定 Session，让智能体可以从上次中断处继续。
• 保存进度： 将新的交互（Event 对象）追加到 session 历史。这也是 session state 更新的机制（详见 State 章节）。
• 列出对话： 查找特定用户和应用的活跃会话线程。
• 清理： 当对话结束或不再需要时，删除 Session 及其相关数据。

SessionService 实现

ADK 提供了多种 SessionService 实现，你可以选择最适合需求的存储后端：

1. InMemorySessionService

   • 工作方式： 直接将所有 session 数据存储在应用内存中。
   • 持久性： 无。应用重启后所有对话数据都会丢失。
   • 依赖： 无需额外配置。
   • 适用场景： 快速开发、本地测试、示例，以及不需要长期持久化的场景。
   PythonJava

    from google.adk.sessions import InMemorySessionService
    session_service = InMemorySessionService()
   

    import com.google.adk.sessions.InMemorySessionService;
    InMemorySessionService exampleSessionService = new InMemorySessionService();
   

2. VertexAiSessionService

   • 工作方式： 通过 API 调用使用 Google Cloud Vertex AI 基础设施进行会话管理。
   • 持久性： 是。数据通过 Vertex AI Agent Engine 可靠且可扩展地管理。
   • 要求：
     • 一个 Google Cloud 项目 (pip install vertexai)
     • 可通过此步骤配置的 Google Cloud 存储桶。
     • 可通过此教程设置的 Reasoning Engine 资源名称/ID。
     • 如果你没有 Google Cloud 项目但想免费试用 VertexAiSessionService，请参阅如何免费试用会话和记忆。
   • 最佳用途： 部署在 Google Cloud 上的可扩展生产应用，特别是与其它 Vertex AI 功能集成时。
   PythonJava

   # 依赖：pip install google-adk[vertexai]
   # 以及 GCP 配置和认证
   from google.adk.sessions import VertexAiSessionService
   
   PROJECT_ID = "your-gcp-project-id"
   LOCATION = "us-central1"
   # 与该服务配合使用的 app_name 应为 Reasoning Engine ID 或名称
   REASONING_ENGINE_APP_NAME = "projects/your-gcp-project-id/locations/us-central1/reasoningEngines/your-engine-id"
   
   session_service = VertexAiSessionService(project=PROJECT_ID, location=LOCATION)
   # 调用服务方法时使用 REASONING_ENGINE_APP_NAME，例如：
   # session_service = await session_service.create_session(app_name=REASONING_ENGINE_APP_NAME, ...)
   

   // 请参考上方依赖要求，并在 bashrc 文件中导出以下环境变量：
   // export GOOGLE_CLOUD_PROJECT=my_gcp_project
   // export GOOGLE_CLOUD_LOCATION=us-central1
   // export GOOGLE_API_KEY=my_api_key
   
   import com.google.adk.sessions.VertexAiSessionService;
   import java.util.UUID;
   
   String sessionId = UUID.randomUUID().toString();
   String reasoningEngineAppName = "123456789";
   String userId = "u_123"; // 示例用户 id
   ConcurrentMap<String, Object> initialState = new
       ConcurrentHashMap<>(); // 本例无需初始 state
   
   VertexAiSessionService sessionService = new VertexAiSessionService();
   Session mySession =
       sessionService
           .createSession(reasoningEngineAppName, userId, initialState, Optional.of(sessionId))
           .blockingGet();
   

3. DatabaseSessionService

   Supported in ADKPython v0.1.0
   • 工作方式： 连接到关系型数据库（如 PostgreSQL、MySQL、SQLite），将 session 数据持久化存储在表中。
   • 持久性： 有。数据可在应用重启后保留。
   • 依赖： 已配置的数据库。
   • 适用场景： 需要你自行管理的可靠持久存储的应用。

   from google.adk.sessions import DatabaseSessionService
   # 使用本地 SQLite 文件的示例：
   db_url = "sqlite:///./my_agent_data.db"
   session_service = DatabaseSessionService(db_url=db_url)
   

选择合适的 SessionService 是决定智能体对话历史和临时数据如何存储与持久化的关键。

Session 生命周期

以下是 Session 与 SessionService 在一次对话轮次中协作的简化流程：

1. 开始或恢复： 你的应用程序需要使用 SessionService 来要么 create_session（用于新聊天），要么使用现有的 session id。
2. 提供上下文： Runner 从适当的服务方法获取相应的 Session 对象，为智能体提供对相应 Session 的 state 和 events 的访问权限。
3. 智能体处理： 用户用查询提示智能体。智能体分析查询以及可能的 session state 和 events 历史来确定响应。
4. 响应和状态更新： 智能体生成响应（并可能标记要在 state 中更新的数据）。Runner 将其打包为 Event。
5. 保存交互： Runner 调用 sessionService.append_event(session, event)，将 session 和新的 event 作为参数。服务将 Event 添加到历史记录中，并根据事件中的信息更新存储中的 session state。session 的 last_update_time 也会得到更新。
6. 准备下一次： 智能体的响应发送给用户。更新后的 Session 现在由 SessionService 存储，准备进行下一轮（这通常会在当前会话中继续对话，从步骤 1 重新开始循环）。
7. 结束对话： 当对话结束时，你的应用程序调用 sessionService.delete_session(...) 来清理存储的会话数据（如果不再需要的话）。

此循环突出显示了 SessionService 如何通过管理每个 Session 对象的历史和状态，确保对话的连续性。