> ## Documentation Index > Fetch the complete documentation index at: https://docs-omnicoreagent.omnirexfloralabs.com/llms.txt > Use this file to discover all available pages before exploring further. # BackgroundAgentManager > Background tasks and runs: every method, run status and overlap policy # BackgroundAgentManager ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} from omnicoreagent import BackgroundAgentManager manager = BackgroundAgentManager() # tasks kept in memory manager = BackgroundAgentManager(task_store="sql") # SQLite, or DATABASE_URL; needs omnicoreagent[postgres] ``` The guide is [Background agents](/docs/core-concepts/background-agents). ## Run statuses A run is `queued`, then `claimed` by a worker, `running`, and `retrying` between attempts. It **ends** in a terminal status, or **pauses** in a waiting one until `resume_run`; `run_now(wait=True)` and `wait_for_run` return at either. | Status | | | ------------------- | ------ | | `queued` | active | | `claimed` | active | | `running` | active | | `retrying` | active | | `completed` | ends | | `failed` | ends | | `cancelled` | ends | | `timeout` | ends | | `skipped` | ends | | `awaiting_approval` | waits | | `awaiting_budget` | waits | ## Overlap policies What a task does when it is due while one of its runs is still active (`overlap_policy`; the default is `skip_if_running`): | Policy | | ----------------- | | `skip_if_running` | | `queue_next` | | `cancel_previous` | | `allow_parallel` | ## Methods ### `cancel_run` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def cancel_run(run_id: str) -> None: ... ``` Cancel a queued, running or waiting run. ### `delete_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def delete_task(task_id: str, delete_runs: bool = False) -> None: ... ``` Delete a task; `delete_runs` deletes its runs too. ### `get_agent` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_agent(agent_id: str) -> BackgroundAgentSpec | None: ... ``` The registered agent's spec, or None. ### `get_manager_status` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_manager_status() -> dict[str, Any]: ... ``` Agents, tasks, active runs and run counts by status, for this manager's store. ### `get_run` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_run(run_id: str) -> BackgroundRun | None: ... ``` The run: its status, attempts count, timings, result preview and error. ### `get_run_events` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_run_events(run_id: str) -> list[dict[str, Any]]: ... ``` The run's lifecycle events (queued, claimed, started, completed, ...), in order. ### `get_run_workspace` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_run_workspace(run_id: str) -> dict[str, Any]: ... ``` Return the durable workspace location and visible files for a run. ### `get_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_task(task_id: str) -> BackgroundTaskSpec | None: ... ``` The task, or None. ### `get_task_status` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def get_task_status(task_id: str) -> dict[str, Any]: ... ``` A task with its schedule state, active runs and a count of its runs by status. ### `initialize` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def initialize() -> None: ... ``` Prepare the task store. `start` and the first use call it for you. ### `list_agents` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def list_agents() -> list[BackgroundAgentSpec]: ... ``` Every registered agent's spec. ### `list_attempts` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def list_attempts(run_id: str) -> list[BackgroundAttempt]: ... ``` Every attempt of a run, with how each ended. ### `list_runs` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def list_runs(task_id: str | None = None, status: str | RunStatus | None = None) -> list[BackgroundRun]: ... ``` Runs, optionally one task's, optionally in one status. ### `list_tasks` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def list_tasks(agent_id: str | None = None) -> list[BackgroundTaskSpec]: ... ``` Every task, or one agent's. ### `pause_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def pause_task(task_id: str) -> None: ... ``` Stop scheduling a task; runs already queued or running continue. ### `recover_expired_runs` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def recover_expired_runs() -> None: ... ``` Take back runs whose worker stopped renewing its lease (a process that died), so they retry or fail. ### `register_agent` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def register_agent(agent_id: str, agent: Any, replace: bool = False) -> BackgroundAgentSpec: ... ``` Register an agent under `agent_id` so tasks can run it; `replace` swaps an existing one. ### `register_agent_spec` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def register_agent_spec(spec: BackgroundAgentSpec | dict[str, Any], replace: bool = False) -> BackgroundAgentSpec: ... ``` Register an agent from a spec (its model, tools and settings) that the store keeps, so a new process can rebuild it. ### `register_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def register_task(spec: BackgroundTaskSpec | dict[str, Any] | None = None, *, task_id: str | None = None, agent_id: str | None = None, query: str | None = None, schedule: ScheduleSpec | dict[str, Any] | None = None, enabled: bool = True, timeout_seconds: int | None = None, retry_policy: dict[str, Any] | None = None, overlap_policy: OverlapPolicy | str | None = None, session_policy: dict[str, Any] | None = None, workspace_policy: dict[str, Any] | None = None, metadata: dict[str, Any] | None = None, replace: bool = False) -> BackgroundTaskSpec: ... ``` Create a task: which agent runs which query, on what schedule (manual, once, interval or cron), with its timeout, retries, overlap, session and workspace policies. `replace` overwrites an existing one. ### `resume_run` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def resume_run(run_id: str) -> BackgroundRun: ... ``` Queue a run that was waiting for approval, once the approvals are decided (`agent.resolve_approval`). Its next attempt continues the same durable run instead of starting over. ### `resume_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def resume_task(task_id: str) -> None: ... ``` Schedule a paused task again. ### `run_now` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def run_now(task_id: str, query: str | None = None, wait: bool = False, timeout_seconds: float | None = None) -> BackgroundRun: ... ``` Queue one run of a task now, optionally with another `query`. With `wait`, return when it ends (or at `timeout_seconds`). Under the task's overlap policy, a run can come back `skipped` (another run holds the task) instead of `queued`. ### `run_until_terminal` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def run_until_terminal(run_id: str, timeout_seconds: float | None = None, poll_interval_seconds: float = 0.05) -> BackgroundRun: ... ``` Execute a queued run in this process and return it when it ends, or at `timeout_seconds`. ### `shutdown` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def shutdown() -> None: ... ``` Stop the worker loop and cancel the runs it is executing; their attempts are recorded. ### `start` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def start() -> None: ... ``` Start the worker loop: it runs due schedules and queued runs until `shutdown`. ### `unregister_agent` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def unregister_agent(agent_id: str, force: bool = False) -> None: ... ``` Remove an agent. Refused while it has active runs, unless `force`. ### `update_task` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def update_task(task_id: str, patch: dict[str, Any]) -> BackgroundTaskSpec: ... ``` Change a task: `patch` holds the fields to change (query, schedule, enabled, timeout\_seconds, retry\_policy, overlap\_policy, ...). ### `wait_for_run` ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} async def wait_for_run(run_id: str, timeout_seconds: float | None = None, poll_interval_seconds: float = 0.05) -> BackgroundRun: ... ``` Wait for one specific run to become terminal without executing work.