Durable Queue

from agno.os import AgentOS, QueueConfig

agent_os = AgentOS(
    agents=[agent],
    db=db,  # Postgres. The queue table lives here too.
    queue=QueueConfig(
        durable=True,
        max_concurrency=8,  # per replica
        max_queue_depth=1000,  # 429 beyond this
        max_attempts=1,  # a crashed run fails visibly, never re-executes
    ),
)

With durable=True, a queueable background=true, stream=false submission is written to the agno_jobs table before the 202 is returned. That job row is the acceptance. The run itself is stored in your sessions database as usual (the run row). A worker on every replica polls the jobs table, claims jobs, and executes them under a lease that it refreshes with heartbeats. Non-streaming submissions return 202 with run_id; streaming submissions return an SSE response.

The guarantee

An accepted durable submission has a committed job row that a compatible worker can claim or recover. With healthy storage and available matching workers, execution settles as COMPLETED, ERROR, CANCELLED, or PAUSED awaiting human input. A missing component or unmatched deployment affinity can leave work waiting until a compatible worker is available. Acceptance does not guarantee autonomous completion of a paused run.

What happens to a run whose worker dies mid-execution depends on max_attempts:

At the default, a crashed run is marked failed and an operator grants one more attempt through requeue. The run's content carries the reason:

Worker lost and attempt budget exhausted; run was not re-executed. Crashed runs
fail visibly instead of silently re-executing (at-most-once, max_attempts=1 by
default): set QueueConfig(max_attempts=2) or higher to allow automatic
re-execution, or grant one attempt via POST /queue/jobs/{id}/requeue.

Failures that retrying cannot cure (schema violations, guardrail refusals, a TypeError in the call) go straight to failed regardless of remaining budget.

How it stays correct

Each claim increments the job's attempt counter. That number is recorded on every write the attempt makes: the job row, the run row, and the event stream. A write carrying an older attempt than the one currently recorded is refused. This is what makes max_attempts > 1 safe: a worker that was swept while still alive cannot corrupt the retry's output.

Queue retries and model retries

Model retries and queue retries are independent layers:

When model retries are exhausted, the run finishes with status ERROR. The worker then consults the queue budget: with attempts remaining it requeues the job after a jittered delay, otherwise the job is failed. At the defaults, a model outage fails the run on the first error with no re-execution at either layer.

agent = Agent(
    model=OpenAIResponses(id="gpt-5.5", retries=3, delay_between_retries=2, exponential_backoff=True),
    db=db,
)
agent_os = AgentOS(agents=[agent], db=db, queue=QueueConfig(durable=True, max_attempts=2))

Use model retries for transient provider errors. They are cheap and keep the run's context. Use queue attempts for worker loss. A queue attempt repeats every tool call the previous attempt already made, so keep max_attempts=1 for runs with side effects. The two budgets multiply: at most max_attempts * (retries + 1) model calls per step.

Queue stores

The queue store defaults to the AgentOS db. A dedicated store isolates queue polling from your session data.

from agno.db.redis import RedisDb

queue=QueueConfig(
    durable=True,
    db=RedisDb(db_url="redis://localhost:6379"),  # queue jobs only
)

db= requires durable=True. Passing a queue store without durability raises at construction.

Idempotency keys

Send an Idempotency-Key header to make a resubmission return the original run instead of enqueueing a second one:

curl -X POST localhost:7777/agents/durable-agent/runs \
  -H "Idempotency-Key: order-42" \
  -F "message=Process order 42" \
  -F "background=true" -F "stream=false"

Keys are scoped per user: the same key from two different user_id values is two runs. Anonymous submissions share one namespace.

Asking is idempotent. Executing is not. A run that reached a tool with side effects has already acted, and a retry acts again. Agno does not keep a side-effect ledger. If a tool must not run twice, make the tool itself idempotent.

Session serialization

The durable queue does not provide a serialize_sessions option or strict per-session FIFO execution. Several accepted runs for one session can execute concurrently. If a later run depends on an earlier result or human approval, coordinate those submissions in your application. A paused run does not block other jobs in its session.

Latency

Workers poll for claimable jobs. poll_interval defaults to 1.0 seconds between idle claim passes; an available matching worker picks up a new or requeued job on a subsequent pass. Actual start time also depends on capacity, storage, retry availability, and deployment affinity. Submission does not wake a local worker immediately.

Configuration

The timing fields (lock_grace_seconds, stop_timeout_seconds, retention_seconds, max_attempts, timeout_seconds) must be identical on every replica sharing a queue table. See Fleet-wide settings.

Next Steps