Rewind sessions for agents¶
智能体的会话回退¶
The ADK session Rewind feature allows you to revert a session to a previous request state, enabling you to undo mistakes, explore alternative paths, or restart a process from a known good point. This document provides an overview of the feature, how to use it, and its limitations.
ADK 会话回退功能允许您将会话恢复到以前的请求状态,使您能够撤销错误、探索替代路径,或从已知的良好点重新启动过程。本文档提供了该功能的概述、如何使用它以及其限制。
Rewind a session¶
回退会话¶
When you rewind a session, you specify a user request, or invocation, that you want to undo, and the system undoes that request and requests after it. So if you have three requests (A, B, C) and you want to return to the state at request A, you specify B, which undoes changes from requests B and C. You rewind a session by using the rewind method on a Runner instance, specifying the user, session, and invocation id, as shown in the following code snippet:
当您回退会话时,您指定要撤销的用户请求或调用,系统会撤销该请求及其后的请求。因此,如果您有三个请求(A、B、C),并且想要返回请求 A 的状态,则指定 B,这将撤销来自请求 B 和 C 的更改。您可以通过使用Runner实例上的 rewind 方法来回退会话,指定用户、会话和调用 id,如以下代码片段所示:
# Create runner
# 创建运行程序
runner = InMemoryRunner(
agent=agent.root_agent,
app_name=APP_NAME,
)
# Create a session
# 创建会话
session = await runner.session_service.create_session(
app_name=APP_NAME, user_id=USER_ID
)
# call agent with wrapper function "call_agent_async()"
# 使用包装函数 "call_agent_async()" 调用智能体
await call_agent_async(
runner, USER_ID, session.id, "set state color to red"
)
# ... more agent calls ...
# ... 更多智能体调用 ...
events_list = await call_agent_async(
runner, USER_ID, session.id, "update state color to blue"
)
# get invocation id
# 获取调用 id
rewind_invocation_id=events_list[1].invocation_id
# rewind invocations (state color: red)
# 回退调用(状态颜色:红色)
await runner.rewind_async(
user_id=USER_ID,
session_id=session.id,
rewind_before_invocation_id=rewind_invocation_id,
)
When you call the rewind method, all ADK managed session-level resources are restored to the state they were in before the request you specified with the invocation id. However, global resources, such as app-level or user-level state and artifacts, are not restored. For a complete example of an agent session rewind, see the rewind_session sample code. For more information on the limitations of the Rewind feature, see Limitations.
当您调用回退方法时,所有 ADK 管理的会话级资源都会恢复到您用调用 id指定的请求之前的状态。但是,全局资源(如应用级或用户级状态和工件)不会恢复。有关智能体会话回退的完整示例,请参阅 rewind_session 示例代码。有关回退功能限制的更多信息,请参阅限制。
How it works¶
工作原理¶
The Rewind feature creates a special rewind request that restores the session's state and artifacts to their condition before the rewind point specified by an invocation id. This approach means that all requests, including rewound requests, are preserved in the log for later debugging, analysis, or auditing. After the rewind, the system ignores the rewound requests when it prepares the next request for the AI model. This behavior means that the AI model used by the agent effectively forgets any interactions from the rewind point up to the next request.
回退功能创建一个特殊的回退请求,将会话的状态和工件恢复到调用 id 指定的回退点之前的条件。这种方法意味着所有请求(包括回退的请求)都保留在日志中,以便以后进行调试、分析或审计。回退后,系统在为 AI 模型准备下一个请求时会忽略回退的请求。这种行为意味着智能体使用的 AI 模型实际上会忘记从回退点到下一个请求的任何交互。
Limitations¶
限制¶
The Rewind feature has some limitations that you should be aware of when using it with your agent workflow:
回退功能具有一些限制,您在使用它与智能体工作流时应该注意:
- Global agent resources: App-level and user-level state and artifacts are not restored by the rewind feature. Only session-level state and artifacts are restored. 全局智能体资源:应用级和用户级状态和工件不由回退功能恢复。仅会话级状态和工件会被恢复。
- External dependencies: The rewind feature does not manage external dependencies. If a tool in your agent interacts with external systems, it is your responsibility to handle the restoration of those systems to their prior state. 外部依赖项:回退功能不管理外部依赖项。如果智能体中的工具与外部系统交互,则您负责处理将这些系统恢复到其先前状态。
- Atomicity: State updates, artifact updates, and event persistence are not performed in a single atomic transaction. Therefore, you should avoid rewinding active sessions or concurrently manipulating session artifacts during a rewind to prevent inconsistencies. 原子性:状态更新、工件更新和事件持久化不是在单个原子事务中执行的。因此,您应该避免回退活动会话或在回退期间并发操作会话工件,以防止不一致。