> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# runs • AI Agent SDK

> Durable, recoverable run-ledger module for PraisonAI Agents.

# runs

<Badge color="blue">AI Agent</Badge>

Durable, recoverable run-ledger module for PraisonAI Agents.

Provides a first-class ledger so long-running / async agent runs survive a
gateway restart: every run is recorded with a stable `run_id`, a
:class:`RunStatus`, a progress summary and a terminal outcome. On restart,
orphaned runs are reconciled so the gateway can notify the originating user.

Layering:

* Thin protocol + data shapes (:mod:`~praisonaiagents.runs.protocols`) are
  always available and carry no heavy imports.
* A zero-dependency SQLite default store
  (:class:`~praisonaiagents.runs.sqlite_ledger.SQLiteRunLedger`) is lazily
  loaded so importing this package stays cheap.

Usage::

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.runs import SQLiteRunLedger, RunRecord, RunStatus

ledger = SQLiteRunLedger()                       # ~/.praisonai/runs/ledger.db
ledger.upsert(RunRecord(run_id="r1", channel="#ops",
                        status=RunStatus.RUNNING))
# ...gateway restarts...
for lost in ledger.recover_orphans():            # reconcile on boot
    notify_origin(lost)
```

## Import

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import runs
```