Session：跟踪个别对话¶

延续我们的介绍，让我们深入了解 Session。回想一下"对话线程"的概念。就像你不会从头开始每条短信一样，智能体需要来自持续交互的上下文。Session 是 ADK 对象，专门设计用于跟踪和管理这些个别对话线程。

`Session` 对象¶

当用户开始与你的智能体交互时，SessionService 创建一个 Session 对象（google.adk.sessions.Session）。该对象充当保存与一个特定聊天线程相关的所有内容的容器。以下是它的关键属性：

标识（id, app_name, user_id）： 对话的唯一标签。
- id：这个特定对话线程的唯一标识符，对于以后检索它至关重要。
- app_name：标识此对话属于哪个智能体应用程序。
- user_id：将对话链接到特定用户。
历史（events）： 在这个特定线程中发生的所有交互（Event 对象 - 用户消息、智能体响应、工具动作）的时间顺序序列。
会话数据（state）： 一个存储仅与这个特定、持续对话相关的临时数据的地方。这在交互过程中充当智能体的草稿板。我们将在下一节详细介绍如何使用和管理 state。
活动跟踪（last_update_time）： 表示上次向此对话线程添加事件的时间戳。

示例：检查 Session 属性¶

from google.adk.sessions import InMemorySessionService, Session

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

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.delete_session(app_name=example_session.app_name,
                            user_id=example_session.user_id, session_id=example_session.id)

（注意： 上面显示的状态只是初始状态。状态更新通过事件发生，将在 State 部分讨论。）

使用 `SessionService` 管理会话¶

你通常不直接创建或管理 Session 对象。相反，你使用 SessionService。这个服务充当负责你的对话会话整个生命周期的中央管理器。

其核心职责包括：

开始新对话： 当用户开始交互时创建新的 Session 对象。
恢复现有对话： 检索特定的 Session（使用其 ID），以便智能体可以从上次中断的地方继续。
保存进度： 将新的交互（Event 对象）追加到会话的历史记录中。这也是会话 state 更新的机制（更多内容在 State 部分）。
列出对话： 查找特定用户和应用程序的活动会话线程。
清理： 当对话结束或不再需要时，删除 Session 对象及其相关数据。

`SessionService` 实现¶

ADK 提供了不同的 SessionService 实现，使你能够选择最适合你需求的存储后端：

InMemorySessionService {: #inmemorysessionservice}
- 工作原理： 直接在应用程序内存中存储所有会话数据。
- 持久性： 无。如果应用程序重启，所有对话数据都会丢失。
- 要求： 无额外要求。
- 最适用于： 快速测试、本地开发、示例以及不需要长期持久性的场景。
```
from google.adk.sessions import InMemorySessionService
session_service = InMemorySessionService()
```
DatabaseSessionService {: #databasesessionservice}
- 工作原理： 连接到关系型数据库（例如 PostgreSQL、MySQL、SQLite）将会话数据持久化存储在表中。
- 持久性： 是。数据在应用程序重启后仍然存在。
- 要求： 配置好的数据库和 sqlalchemy 库（pip install google-adk[database]）。
- 最适用于： 需要可靠、持久存储且你自己管理的应用程序。
```
# 要求：pip install google-adk[database]
from google.adk.sessions import DatabaseSessionService
# 使用本地 SQLite 文件的示例：
db_url = "sqlite:///./my_agent_data.db"
session_service = DatabaseSessionService(db_url=db_url)
```

VertexAiSessionService {: #vertexaisessionservice}

工作原理： 通过 API 调用使用 Google Cloud 的 Vertex AI 基础设施进行会话管理。
持久性： 是。数据由 Google Cloud 可靠且可扩展地管理。
要求： Google Cloud 项目、适当的权限、必要的 SDK（pip install google-adk[vertexai]）以及 Reasoning Engine 资源名称/ID。
最适用于： 部署在 Google Cloud 上的可扩展生产应用程序，特别是当与其他 Vertex AI 功能集成时。

# 要求：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.create_session(app_name=REASONING_ENGINE_APP_NAME, ...)

选择正确的 SessionService 是定义你的智能体的对话历史和临时数据如何存储和持久化的关键。

Session 生命周期¶

Session lifecycle

以下是 Session 和 SessionService 在对话回合中如何共同运作的简化流程：

开始或恢复： 用户发送消息。你的应用程序的 Runner 使用 SessionService 要么 create_session（用于新聊天）要么 get_session（检索现有聊天）。
提供上下文： Runner 从服务获取适当的 Session 对象，为智能体提供访问其 state 和 events 的权限。
智能体处理： 智能体使用当前用户消息、其指令，以及可能的会话 state 和 events 历史来决定响应。
响应和状态更新： 智能体生成响应（并可能标记要在 state 中更新的数据）。Runner 将其打包为 Event。
保存交互： Runner 使用 Session 和新的 Event 调用 session_service.append_event(...)。服务将 Event 添加到历史记录中，并根据事件中的信息更新存储中会话的 state。会话的 last_update_time 也会更新。
准备下一次： 智能体的响应发送给用户。更新后的 Session 现在由 SessionService 存储，为下一回合做好准备（在步骤 1 重新开始循环，通常使用 get_session）。
结束对话： 当对话结束时，理想情况下你的应用程序调用 session_service.delete_session(...) 清理存储的会话数据。

这个循环突显了 SessionService 如何通过管理与每个 Session 对象相关的历史和状态来确保对话连续性。

Session：跟踪个别对话¶

Session 对象¶

示例：检查 Session 属性¶

使用 SessionService 管理会话¶

SessionService 实现¶

Session 生命周期¶

`Session` 对象¶

使用 `SessionService` 管理会话¶

`SessionService` 实现¶