Skip to main content

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.

​
Background Agents

Background agents run tracked OmniCoreAgent tasks outside the foreground request path. Use the default in-memory store for local development, or choose sql, redis, or mongodb when tasks, runs, attempts, leases, retries, and cancellation state must survive process restarts. A task can run manually, once at a fixed time, on an interval, or from a five-field cron expression. Each run is tracked through queued, claimed, running, retrying, and terminal states. Background execution is part of the core package: 
pip install omnicoreagent
Redis and MongoDB task stores use optional backend drivers: 
pip install "omnicoreagent[redis]"
pip install "omnicoreagent[mongodb]"
No storage configuration is required to start. BackgroundAgentManager() uses an in-memory task store by default so the first run has no database requirement. Use task_store="sql", task_store="redis", or task_store="mongodb" when tasks, runs, attempts, leases, retries, and cancellation state must survive process restarts. The task store is separate from agent memory. MemoryRouter stores conversation/session history. The task store stores operational background state and owns the atomic claim, lease, retry, and schedule-cursor guarantees.

​
Quick Start

Set LLM_API_KEY first, then run the example; no task-store configuration is required. 
import asyncio

from omnicoreagent import BackgroundAgentManager, OmniCoreAgent


async def main():
    agent = OmniCoreAgent(
        name="system_monitor",
        system_instruction="Check system health and write concise reports.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    )

    manager = BackgroundAgentManager()
    await manager.register_agent("system_monitor", agent)
    await manager.register_task(
        task_id="health_report",
        agent_id="system_monitor",
        query="Check system health and summarize anything that needs attention.",
        schedule={"type": "manual"},
        timeout_seconds=60,
        retry_policy={"max_retries": 1, "initial_delay_seconds": 0},
    )

    run = await manager.run_now("health_report", wait=True)
    print(run.status)
    print(run.result_preview)


asyncio.run(main())

​
Scheduled Runs

Start the manager when you want it to dispatch due schedules: 
await manager.register_task(
    task_id="hourly_report",
    agent_id="system_monitor",
    query="Write the hourly operational report.",
    schedule={"type": "interval", "seconds": 3600},
    overlap_policy="queue_next",
)

await manager.start()
The worker loop reads due schedules from the task store, creates a run exactly once for each occurrence, advances the schedule state, claims queued runs, and executes them with lease fencing.

​
Runtime Controls

run = await manager.run_now("health_report")
latest = await manager.get_run(run.run_id)
attempts = await manager.list_attempts(run.run_id)
events = await manager.get_run_events(run.run_id)

await manager.cancel_run(run.run_id)
await manager.pause_task("hourly_report")
await manager.resume_task("hourly_report")
await manager.delete_task("hourly_report", delete_runs=True)

​
Run Event Replay

Each run emits ordered lifecycle events with a run-local sequence number. get_run_events(run_id) returns the most complete trace it can read from:
  • the current process cache
  • the run workspace events.jsonl mirror, when workspace event mirroring is enabled
If more than one source is available, OmniCoreAgent returns a complete terminal trace first. If no source has reached a terminal event yet, it prefers the process cache, then the workspace mirror. Sources with malformed or duplicate run-local sequence numbers are ignored during replay selection. A valid source uses contiguous integer sequence numbers starting at 1. Run-scoped lifecycle events include schedule dispatch, queueing, claiming, start, heartbeat, retry, terminal status, and recovery transitions when those transitions occur. Durable restart replay needs workspace event mirroring enabled. If a process exits with only in-memory events and no workspace mirror, the task store still preserves run status, attempts, leases, and results, but old event history may not be replayable.

​
OmniServe API

When an agent is served through OmniServe, the server registers that agent with the background manager during startup and exposes task control over HTTP: 
curl -X POST http://localhost:8000/background/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "health_report",
    "query": "Check system health and write the report.",
    "schedule": {"type": "manual"},
    "timeout_seconds": 60
  }'

curl -X POST http://localhost:8000/background/tasks/health_report/run \
  -H "Content-Type: application/json" \
  -d '{"wait": false}'
Use {"wait": true} when the HTTP request should wait for terminal run state. If the OmniServe worker is running, the API waits for that worker-owned run. If the worker is disabled, the API queues the run through the background manager and drives that run inline through the same execution contract. If the run does not finish before the background wait budget, OmniServe returns 504 and the run remains inspectable through the background run endpoints. The wait budget is derived from the configured request timeout and leaves a small margin for OmniServe to return the structured response before the outer HTTP timeout. The 504 response includes the run_id, task_id, latest status, wait_timeout_seconds, and request_timeout_seconds in detail. The background API includes manager status, task creation, task status, task listing, pause, resume, delete, manual run, cancellation, run status, attempt history, event replay, and workspace inspection. 
curl http://localhost:8000/background/status
curl http://localhost:8000/background/tasks/health_report/status
curl http://localhost:8000/background/runs/$RUN_ID
curl http://localhost:8000/background/runs/$RUN_ID/events
curl http://localhost:8000/background/runs/$RUN_ID/workspace

​
Task Configuration

FieldPurpose
task_idStable task identifier.
agent_idRegistered agent that executes the task.
queryInstruction passed to the agent for each run.
schedulemanual, interval, cron, or once.
timeout_secondsOptional per-run timeout.
retry_policyRetry count, delay, backoff, and retryable error types.
overlap_policyskip_if_running, queue_next, cancel_previous, or allow_parallel.
session_policytask, run, or fixed memory-session behavior.
workspace_policyWorkspace namespace used for run output.

​
Persistent State

The task store is the source of truth for:
  • registered agent specs
  • task definitions
  • schedule state and occurrence IDs
  • runs and attempts
  • leases, heartbeats, and cancellation flags
The current runtime includes the tracked run model, in-memory, SQL, Redis, and MongoDB task stores, schedule dispatch, manual runs, retries with delay/backoff, lease fencing, expired-lease recovery, cancellation, workspace lifecycle files, and run event replay. Task, schedule, run, attempt, lease, retry, and cancellation state is restart-persistent when the task store is SQL, Redis, or MongoDB. Event history follows the replay rules above through the manager process cache and workspace events.jsonl mirror. Durable stores are tested at the manager boundary. A queued run can be created, the manager can shut down, and a new manager over the same SQL, Redis, or MongoDB task store can claim and complete that run. The in-memory store is only for local development, tests, and single-process experiments. Choose one durable backend per deployment. Use SQL/SQLite for local durability or simple single-node services. Use Redis when your deployment already operates Redis with persistence and no eviction for task-store keys. Use MongoDB when MongoDB is your durable operational store. Redis durable deployments need persistence enabled and a no-eviction policy for task-store keys. MongoDB task-store writes use majority write concern. 
BackgroundAgentManager(task_store="sql")
BackgroundAgentManager(task_store={"backend": "redis", "url": "redis://localhost:6379/0"})
BackgroundAgentManager(
    task_store={
        "backend": "mongodb",
        "uri": "mongodb://localhost:27017",
        "database": "omnicoreagent",
    }
)