Execution Runtime

Narrative view of Execution, Thread, Run, Checkpoint, and Interruption. For field-level detail see Models.

Why split intent from attempts

Agency separates:

what we meant to do (Execution),
the continuing conversation / graph timeline (Thread),
one shot at advancing that timeline (Run).

That split supports audit trails, retries, long pauses (HITL), and debugging without rewriting history.

Relationships

Execution  (user + agent + mission, overall status/result)
   │
   └── Thread*  (optional FK; ad-hoc threads may omit Execution)
          │
          ├── Run*
          │     └── Checkpoint*
          │            └── Interruption?  (HITL pause at a checkpoint)
          └── …

Statuses (see models for the full TextChoices set) include starting / running / success / interrupted / error, plus others such as cancelled, timeout, and on Run also pending / resuming.

Case: normal success

Execution
└── Thread
    └── Run #1 → SUCCESS

One attempt completed. Execution result is stored when Agent.execute finishes without __interrupt__.

Case: error / retry

Execution
└── Thread
    ├── Run #1 → ERROR
    └── Run #2 → SUCCESS

Each Run keeps its own error payload / outcome. A later Run is a new technical attempt on the same Thread (same thread_id), not an edit of Run #1.

Case: human-in-the-loop

Execution
└── Thread
    ├── Run #1 → INTERRUPTED
    └── Run #2 → SUCCESS

Run #1 remains interrupted. Resume creates Run #2 with Command(resume=…) from the answered Interruption. Tutorial: Human-in-the-Loop.

Design payoffs

Audit — each attempt is a row; interrupted attempts stay interrupted.
Observability — Monitor events and checkpoints attach to Runs.
Retries — new Run, same Thread; prior failures remain inspectable.
Debugging — inspect checkpoint / messages for a specific Run.
Long processes — HITL can wait hours; workers are not held open.

Inspection today

REST: GET /api/execution/<uuid>/ (nested threads / runs / interruptions).
No dedicated public REST for Thread or Run alone.
Django admin for deep inspection.