Agent Spaces

Agent Spaces gives agent systems a shared coordination runtime for posting work, claiming it with leases, routing by capability, and recovering cleanly from worker crashes. Use it when queues are too narrow and workflow engines are too rigid: you need shared queryable state, atomic claims, and traceable multi-agent handoffs in one system.

Agent Spaces is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). See LICENSE.

Quickstart | Concepts | Python SDK | TypeScript SDK | Examples | Architecture | Observability | Discussions

How It Works

┌──────────────┐    out() / create     ┌──────────────────────┐    take() / in()     ┌──────────────┐
│ Producer or  │ --------------------> │ Agent Space          │ --------------------> │ Worker or    │
│ Router       │                       │ Postgres runtime     │                       │ Tool Server  │
└──────┬───────┘ <-------------------- │ query/read/events    │ <-------------------- └──────┬───────┘
       │         results / traces      └──────────┬───────────┘       complete()/out()       │
       └──────────────────────────────────────────>│                                         │
                                                   ▼                                         │
                                            ┌──────────────┐ <────────────────────────────────┘
                                            │ Result or    │
                                            │ next work    │
                                            └──────────────┘

Run It Locally In 3 Commands

make doctor
make up
make smoke

What This Proves

• The local server starts and answers health checks.
• The Python SDK connects to the HTTP API.
• Agent create, claim, and complete works end to end.

Run make down when you are finished, or continue with make example-fault-tolerance.

Why Agent Spaces?

• Celery: great for async tasks and retries, but task state is split across broker/result backend semantics. Agent Spaces adds shared queryable coordination state plus explicit lease ownership and reclaim.
• Temporal: great for durable workflow execution, but it assumes you want workflow code and history as the primary control plane. Agent Spaces gives you a shared coordination space for ad hoc routing, claiming, and handoff across many agents.
• Bare Redis / Redis Streams: great for fast transport and consumer groups, but they do not give you one lifecycle surface for read, take, in, complete, traces, and queryable metadata. Agent Spaces packages those coordination primitives behind one API.
• Kafka consumer groups: great for partitioned log processing, but they are built around partition ownership rather than stateful request routing and blocking match queries. Agent Spaces is designed for capability-driven claims and multi-agent handoffs.

Use Cases

• Background agent task processing
• Parallel inference pipelines
• Multi-agent tool coordination
• Fault-tolerant job distribution
• Stateful request routing

Quick Comparison

Capability	Agent Spaces	Celery	Temporal	Redis Streams
Atomic claim	Yes	Limited	Yes	Yes
Crash recovery	Yes	Yes	Yes	Yes
Execution traces	Yes	Limited	Yes	No
No broker dependency	Yes	No	No	No
Shared queryable coordination state	Yes	Limited	Limited	No

Supported Surface

Area	Status	Notes
Go server (cmd/server)	supported	Core runtime and lifecycle API
Lifecycle HTTP API	supported	create, query, read, take, in, complete, release, renew, complete-and-out
Python SDK (sdk/python/agent_space_sdk)	supported	pip install agent-space-sdk, sync + async clients
TypeScript SDK (sdk/typescript)	preview	Generated from OpenAPI with a thin fetch wrapper
Postgres runtime	supported	Queue-partitioned, strict claim mode by default
Valkey runtime	experimental	Single-node or sharded backend; telemetry and shard admin supported, but not the default local path
Local Docker path	supported	make up, make smoke, make down on Postgres
SQLite runtime	experimental	Local-only; not recommended for pilot or production deployments
Hello World example	supported	examples/hello-world
Fault tolerance example	supported	examples/fault-tolerance
Queue fanout example	supported	examples/queue-fanout
MCP mesh example	supported	examples/mcp-mesh
Inference routing example	supported	examples/inference-routing

Next Example

• examples/hello-world: the canonical smoke test and first-run path.
• examples/fault-tolerance: lease expiry, reclaim, and worker recovery.
• examples/queue-fanout: 10 workers on one queue, one crash, no double processing.
• examples/mcp-mesh: capability heartbeats for MCP worker discovery and routing.
• examples/inference-routing: model capability heartbeats and capacity-aware request routing.

Docs

• Getting Started
• Concepts
• Python SDK
• Configuration
• Benchmarks
• Observability
• Agent Spaces vs etcd
• Launch Blog Post
• Formal Results Blog Series
• Release and Verification

Architecture

The runtime is a small HTTP server over a pluggable coordination store, with Postgres as the supported default and Valkey available as an experimental backend. See docs/architecture.md for the supported component model and deployment shape.

Operations

Operational guidance for local Docker usage, auth, rate limiting, and deployment boundaries lives in docs/operations.md.

Community

Use GitHub Discussions for evaluation questions, launch feedback, and integration notes.

License

Agent Spaces is licensed under AGPL-3.0-only. See LICENSE.