Team Checkpoint & Resume

A team that crashes on task 9 of 12 resumes at task 9 — not task 1

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:

from praisonaiagents import Agent, AgentTeam, Task

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.

   from praisonaiagents import Agent, AgentTeam, Task
   
   writer = Agent(name="Writer", instructions="Draft the section.", llm="gpt-4o")
   editor = Agent(name="Editor", instructions="Polish the draft.", llm="gpt-4o")
   
   team = AgentTeam(
       agents=[writer, editor],
       tasks=[
           Task(name="draft",  description="Write intro",   expected_output="200 words",  agent=writer),
           Task(name="polish", description="Edit for tone", expected_output="clean copy", agent=editor),
       ],
   )
   
   team.save_session_state("release-notes-run-1")   # durable, returns True on write

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.

   from praisonaiagents import Agent, AgentTeam, Task
   
   writer = Agent(name="Writer", instructions="Draft the section.", llm="gpt-4o")
   editor = Agent(name="Editor", instructions="Polish the draft.", llm="gpt-4o")
   
   team = AgentTeam(
       agents=[writer, editor],
       tasks=[
           Task(name="draft",  description="Write intro",   expected_output="200 words",  agent=writer),
           Task(name="polish", description="Edit for tone", expected_output="clean copy", agent=editor),
       ],
   )
   
   team.restore_session_state("release-notes-run-1")   # completed tasks come back done
   team.start()                                          # continues from the next 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

Related