session-rewind-checkpoint

session-rewind-checkpoint

ADK 2.0 ships rewindable sessions — you can revert state to any prior invocation and re-run from there.

When to use

• Debugging: "what if the agent took a different turn at step 3?"
• A/B testing prompt variants from the same midpoint
• Recovering from a bad agent decision without losing earlier work
• User-facing "undo" feature in chat UIs

Template

from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner

session_service = InMemorySessionService()
runner = Runner(agent=root_agent, session_service=session_service)

# Run a few turns
session = await session_service.create_session(app_name="demo", user_id="u1")
await runner.run_async(session=session, input="Plan a trip to Tokyo")
await runner.run_async(session=session, input="Make it 5 days")
await runner.run_async(session=session, input="Add a day in Kyoto")

# List invocation checkpoints
for inv in session.invocations:
    print(inv.id, inv.created_at, inv.user_input[:50])

# Rewind to before the Kyoto add
target_id = session.invocations[-2].id
await session_service.rewind_session(session, to_invocation=target_id)

# Re-run with a different input from that checkpoint
await runner.run_async(session=session, input="Add a day in Osaka instead")

Persistent rewind (production)

For non-volatile rewind use a persistent session service:

from google.adk.sessions import VertexAiSessionService

session_service = VertexAiSessionService(
    project="my-project",
    location="us-central1",
)

Vertex stores all invocations; rewind works the same way.

Pairing with eval

# Replay a session with a tweaked agent to compare outputs
from copy import deepcopy
forked = deepcopy(session)
await session_service.rewind_session(forked, to_invocation=target_id)
forked_runner = Runner(agent=tweaked_agent, session_service=session_service)
await forked_runner.run_async(session=forked, input=user_input)
# Diff session.events vs forked.events

Validation

• session.invocations is non-empty before rewind
• to_invocation ID exists in the session history
• After rewind, len(session.events) reflects the truncated state
• Test that a re-run from checkpoint produces a fresh event stream (not appended to the old one)

See also

• session-migrate for moving a session between users / apps / storage backends