docs: AgentOS durable background execution (job queue) by ysolanky · Pull Request #759 · agno-agi/docs

ysolanky · 2026-08-25T09:39:18Z

Summary

User-facing docs for AgentOS durable background execution (the v3.0 job queue, agno-agi/agno#9079). Adds a Background Execution group to the AgentOS tab with five pages:

agent-os/background-execution/overview - mental model (db = truth, queue.redis = coordination, durable=True = promise), quickstart, 202 contract, modes, limitations
agent-os/background-execution/durable-queue - the guarantee, max_attempts crash semantics, queue stores, idempotency keys, session serialization, latency, full QueueConfig reference
agent-os/background-execution/multi-replica - events out / cancel in via queue.redis, coordination vs db=RedisDb ticket storage, RedisCoordination
agent-os/background-execution/hitl-continuations - continuing a paused durable run through the queue under the same run_id
agent-os/background-execution/operations - /queue endpoints, requeue, stats, retention, admin gating, deployment_id

Also adds a cross-link note to the SDK-level background-execution/overview Multi-Container section.

Verification

Ran cookbook/05_agent_os/background_tasks/durable_queue.py and durable_continue.py (feat/v3.0, 3.0.0a4) against local Postgres. Confirmed the 202/poll contract, ticket states, /queue/stats and /queue/jobs, Idempotency-Key dedup, paused ticket, 409 on inline continue, 202 durable continue and double-click attach, cancel of a paused run, requeue behavior.
Every QueueConfig field re-checked against libs/agno/agno/job_queue/config.py.
mint broken-links and scripts/inventory/run_all.py: 0 broken links.

Review notes

The session serialization and local-wake content (serialize_sessions, "starts in milliseconds", requeue claiming immediately) documents feat: serialize background runs per session (head-of-line durable claims) agno#9587 and feat: wake the local queue worker on enqueue (durable submissions start in milliseconds) agno#9667, which are still open. Those sections should ship with, or be removed if those PRs don't land in, v3.0.
Not verified live: multi-replica behavior, max_attempts=2 crash reclaim, RedisDb as queue store, streaming through the queue. All written from source.

🤖 Generated with Claude Code

Add an AgentOS Background Execution section covering the durable job queue shipped in v3.0: overview and quickstart, durable queue semantics (guarantee, max_attempts, stores, idempotency keys, session serialization, config reference), multi-replica Redis coordination, durable HITL continuations, and the /queue operations surface. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify · 2026-08-25T09:39:22Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
agno	🟢 Ready	View Preview	Aug 25, 2026, 9:42 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The 202 contract, PENDING status, /resume, /cancel and the db requirement are unchanged from v2. The only default change is the per-replica concurrency cap; durability, Redis coordination, idempotency keys and the /queue surface are opt-in via QueueConfig. Fix the migration guide and changelog, which presented the opt-in features as defaults. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Splice the four /queue paths and their schemas (QueueJobSchema, PaginatedResponse_QueueJobSchema_) from a v3 AgentOS OpenAPI dump into reference-api/openapi.yaml, add the schema pages and a Queue nav group, and document the queue and event_stream AgentOS parameters. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

kausmeows · 2026-08-28T07:29:16Z

@@ -0,0 +1,175 @@
+---
+title: Background Execution


maybe we say Durable Background Execution?

kausmeows · 2026-08-28T07:30:06Z

+agent_os = AgentOS(
+    agents=[agent],
+    db=db,
+    queue=QueueConfig(durable=True),


do we not pass redis here?

kausmeows · 2026-08-28T07:30:32Z

+
+## With more than one replica
+
+Set `QueueConfig(redis=...)` as soon as you run two or more replicas behind a load balancer. One setting installs both the event stream and the cancellation manager on each replica, backed by a shared Redis, so a run started on one replica can be watched, resumed, and cancelled from any other. No `set_cancellation_manager()` or `set_event_stream()` call is needed.


ok i see it here

kausmeows · 2026-08-28T07:31:14Z

+
+Set `QueueConfig(redis=...)` as soon as you run two or more replicas behind a load balancer. One setting installs both the event stream and the cancellation manager on each replica, backed by a shared Redis, so a run started on one replica can be watched, resumed, and cancelled from any other. No `set_cancellation_manager()` or `set_event_stream()` call is needed.
+
+See [Multi-replica deployments](/agent-os/background-execution/multi-replica) for what Redis does here, and why `queue.redis` is a different job from `db=RedisDb`.


do we opensource this- https://github.com/agno-agi/agentos-durable and people can test if needed?

mintlify Bot deployed to staging August 25, 2026 09:42 View deployment

docs: import QueueConfig from agno.os

74b6729

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 25, 2026 09:44 View deployment

mintlify Bot deployed to staging August 26, 2026 07:47 View deployment

docs: per-replica cancellation manager wiring and retry layering

cb60f6f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 26, 2026 08:01 View deployment

ysolanky and others added 2 commits August 26, 2026 14:23

docs: name both managers wired by queue.redis

99408c5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: make the two managers set by queue.redis prominent

3b9a830

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 26, 2026 08:55 View deployment

mintlify Bot deployed to staging August 26, 2026 08:56 View deployment

docs: tone pass on background execution pages

ed0c61b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 26, 2026 08:58 View deployment

docs: lead v2 upgrade notes with the concurrency cap

cbf198f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 27, 2026 08:27 View deployment

docs: standardize on job, drop internal queue jargon

ee3a0ad

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 27, 2026 10:01 View deployment

ysolanky and others added 2 commits August 27, 2026 15:32

docs: reword non-durable intro

276ab09

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: drop filler lead-ins before tables

ff41c3f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 27, 2026 10:04 View deployment

docs: note that the Control Plane uses background=true

cdf5d21

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 27, 2026 10:05 View deployment

mintlify Bot deployed to staging August 27, 2026 10:06 View deployment

docs: clarify durability is a server setting, not a request property

997fa43

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mintlify Bot deployed to staging August 27, 2026 10:16 View deployment

mintlify Bot deployed to staging August 27, 2026 10:25 View deployment

kausmeows reviewed Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: AgentOS durable background execution (job queue) - #759

docs: AgentOS durable background execution (job queue)#759
ysolanky wants to merge 14 commits into
mainfrom
docs/agentos-durable-background-execution

ysolanky commented Aug 25, 2026

Uh oh!

mintlify Bot commented Aug 25, 2026 •

edited

Loading

Uh oh!

kausmeows Aug 28, 2026

Uh oh!

kausmeows Aug 28, 2026

Uh oh!

kausmeows Aug 28, 2026

Uh oh!

kausmeows Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## With more than one replica

		Set `QueueConfig(redis=...)` as soon as you run two or more replicas behind a load balancer. One setting installs both the event stream and the cancellation manager on each replica, backed by a shared Redis, so a run started on one replica can be watched, resumed, and cancelled from any other. No `set_cancellation_manager()` or `set_event_stream()` call is needed.


		Set `QueueConfig(redis=...)` as soon as you run two or more replicas behind a load balancer. One setting installs both the event stream and the cancellation manager on each replica, backed by a shared Redis, so a run started on one replica can be watched, resumed, and cancelled from any other. No `set_cancellation_manager()` or `set_event_stream()` call is needed.

		See [Multi-replica deployments](/agent-os/background-execution/multi-replica) for what Redis does here, and why `queue.redis` is a different job from `db=RedisDb`.

Uh oh!

Conversation

ysolanky commented Aug 25, 2026

Summary

Verification

Review notes

Uh oh!

mintlify Bot commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kausmeows Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

kausmeows Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

kausmeows Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

kausmeows Aug 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented Aug 25, 2026 •

edited

Loading