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.
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 the 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 the 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:
# 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()"
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
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.
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 requests for the AI model. This behavior means the AI model used by the agent effectively forgets any interactions from the rewind point up to the next request.
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.