Skip to main content
A team resumes where it stopped — completed tasks stay done, in-flight work continues, no re-runs. Every code example below imports the same top-level classes:

​
Quick Start

1

Save state during a run

Call save_session_state with a session id you can rebuild later. The durable write happens even with memory=False.
2

Resume after a crash

Rebuild the same team with the same tasks, restore with the same session id, then start(). Completed tasks come back marked done, so the run picks up at the first not-done task.

​
How It Works

A team writes a durable checkpoint to the SessionStore, then reads it back on restore and re-applies per-task status before the run continues.

​
What the checkpoint carries

The payload records enough to skip completed work, not just the shared variables.

​
Task-set fingerprint

Task keys inside a team are positional (0, 1, 2, …), not stable ids, so a checkpoint from a different team would restore by index and put task 3’s output onto a different task 3 — a resume that looks successful and is silently wrong. The fingerprint hashes each task, in sorted order, over:
  • task id
  • task.name
  • the full task.description (not truncated — a late-in-string edit must still change the fingerprint)
  • task.agent.name (or display_name)
  • task.expected_output
On mismatch, the shared state is still restored — it is keyed by name and safe — but task outputs are refused. A warning is logged naming the session id, and restore_session_state() still returns True because the shared state came back. This asymmetry matters for callers: a True return does not guarantee task outputs were re-applied.

​
JSON-safe serialisation

A single non-portable value (datetime, set, bytes, a custom object) inside a dict or list result would fail the JSON write and lose the whole checkpoint, so each field degrades on its own instead:
  • A TaskOutput result is reduced to its .raw text before writing.
  • A dict / list result carrying a nested non-JSON value falls back to its str(...) form.
  • A variables dict that isn’t JSON-safe falls back to {}.
  • The rest of the checkpoint is written intact.
On restore, a checkpointed result string is rebuilt into a minimal TaskOutput(description=..., raw=..., agent=..., output_format="RAW"), so consumers reading prev_task.result.raw (workflow dependency context, routing decisions) keep working. If you inspect a checkpoint file by hand, expect result to be stored as a string when it originated from a TaskOutput.

​
Best Practices

The same string must be used to save and restore. Pick an id you can reconstruct after a crash — a run name, a job id — not a random value generated in-process.
A mismatched fingerprint refuses task outputs. The run won’t crash — it will re-do the work from the start — but you lose the skip-on-resume benefit. Keep the task set identical to the one that saved the checkpoint.
A variables dict that isn’t JSON-safe falls back to {} on save. Keep task variables to plain JSON types so they survive the round-trip.
A checkpoint task with no matching task in the current team is skipped. A partial mismatch cannot half-restore, so a resume can never look successful while silently running the wrong work.
The CLI wraps this same API. See YAML / Team Session Continuity — it calls save_session_state / restore_session_state under the hood.

YAML / Team Session Continuity

CLI-level --continue — uses this API under the hood.

Workflow Checkpoint & Resume

A different feature: markdown workflows via WorkflowManager, not AgentTeam.

Session Persistence

The underlying SessionStore that holds the durable payload.

save_session_state Reference

Auto-generated SDK reference for the save API.