Shahin Saadati
b39decfcfe
* Add Kotlin to the session rewind page The page was single-language: one bare Python fence, no tab structure, and a badge div listing Python only. Kotlin has had Runner.rewindAsync with matching semantics, so the code block is converted into a Python/Kotlin tab group with the Python content kept verbatim. Semantics were checked against the implementation rather than inferred from the method name, since the page makes specific promises. Two hold: AbstractRunner.rewindAsync appends a synthetic user event carrying reversing state and artifact deltas, so rewound requests stay in the log as the "How it works" section describes; and keys prefixed app: or user: are skipped when the delta is computed, which is exactly the "Global agent resources" limitation. Worth knowing for anyone reading the interface: Runner.rewindAsync has a default implementation that throws NotImplementedError. AbstractRunner overrides it and InMemoryRunner extends AbstractRunner, so the documented path works, but a custom Runner built straight on the interface would not. Runner.close was on the same backlog row and is left out: it is a lifecycle concern with nothing to do with rewinding. * Badge the rewind page with the version rewindAsync shipped in The badge said Kotlin v0.8.0, the version adk-docs compiles against, rather than the introducing release. Checking the tags, rewindAsync is absent at v0.1.0 and v0.2.0 and first appears in AbstractRunner at v0.3.0 - so the backlog row that recorded it as a v0.1.0 member was wrong as well.
3.9 KiB
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:
=== "Python"
```python
# 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,
)
```
=== "Kotlin"
```kotlin
--8<-- "examples/kotlin/snippets/sessions/RewindExample.kt:rewind_session"
```
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.