为智能体重置会话¶

Supported in ADKPython v1.17.0Kotlin v0.3.0

ADK 会话重置功能允许你将一个会话恢复到先前的请求状态，使你能够撤消错误、探索替代路径或从已知的良好点重新启动流程。本文档概述了该功能、如何使用它以及其限制。

重置会话¶

当你重置会话时，你需要指定一个要撤销的用户请求或调用，系统将撤销该请求以及其后的请求。所以如果你有三个请求（A、B、C），而你想要回到请求 A 的状态，你需要指定 B，这样就会撤销请求 B 和 C 的更改。你可以通过在Runner实例上调用重置法来重置会话，指定用户、会话和调用 ID，如下所示：

PythonKotlin

# 创建 runner
runner = InMemoryRunner(
    agent=agent.root_agent,
    app_name=APP_NAME,
)

# 创建会话
session = await runner.session_service.create_session(
    app_name=APP_NAME, user_id=USER_ID
)
# 通过包装函数 "call_agent_async()" 调用智能体
await call_agent_async(
    runner, USER_ID, session.id, "set state color to red"
)
# ... 更多智能体调用 ...
events_list = await call_agent_async(
    runner, USER_ID, session.id, "update state color to blue"
)

# 获取调用 ID
rewind_invocation_id=events_list[1].invocation_id

# 回退调用（状态颜色：red）
await runner.rewind_async(
    user_id=USER_ID,
    session_id=session.id,
    rewind_before_invocation_id=rewind_invocation_id,
)

suspend fun rewindSession(rootAgent: BaseAgent) {
    val sessionService = InMemorySessionService()
    val runner =
        InMemoryRunner(agent = rootAgent, appName = APP_NAME, sessionService = sessionService)

    // Create a session. The service assigns the id, which is held on Session.key.
    val session = sessionService.createSession(SessionKey(APP_NAME, USER_ID, id = null))
    val sessionId = checkNotNull(session.key.id)

    // Call the agent
    callAgent(runner, sessionId, "set state color to red")
    // ... more agent calls ...
    val events = callAgent(runner, sessionId, "update state color to blue")

    // Get the invocation id of the request to undo
    val rewindInvocationId = events[1].invocationId ?: return

    // Rewind invocations (state color: red)
    runner.rewindAsync(
        userId = USER_ID,
        sessionId = sessionId,
        rewindBeforeInvocationId = rewindInvocationId,
    )
}

private suspend fun callAgent(
    runner: InMemoryRunner,
    sessionId: String,
    query: String,
): List<Event> =
    runner
        .runAsync(
            userId = USER_ID,
            sessionId = sessionId,
            newMessage = Content(role = Role.USER, parts = listOf(Part(text = query))),
        ).toList()

当你调用 rewind 方法时，所有 ADK 管理的会话级资源将被恢复到你在 调用 ID 中指定的请求之前的状态。但是，全局资源（例如应用级或用户级的状态和制品）不会被恢复。有关智能体会话重置的完整示例，请参阅 rewind_session 示例代码。有关重置功能限制的更多信息，请参阅限制。

工作原理¶

重置功能创建一个特殊的重置请求，将会话的状态和制品恢复到调用 ID 指定的重置点之前的状态。这种方法意味着所有请求，包括重置的请求，都保留在日志中以供后续调试、分析或审核。重置后，系统在为 AI 模型准备下一个请求时会忽略重置的请求。这种行为意味着智能体使用的 AI 模型有效地忘记了从重置点到下一个请求之间的任何交互。

限制¶

重置功能有一些限制，你在使用它与你的智能体工作流时应注意：

全局智能体资源： 应用级和用户级状态和制品不会被重置功能恢复。只有会话级状态和制品会被恢复。
外部依赖： 重置功能不管理外部依赖项。如果智能体中的工具与外部系统交互，你有责任处理这些系统的恢复到之前的状态。
原子性： 状态更新、制品更新和事件持久化不是在单个原子事务中执行的。因此，你应该避免重置活动会话或在重置期间并发操作会话制品以防止不一致。