Ablo Docs

Collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.

Two agents reach for the same row. One claims it, does slow work — an LLM call, a fetch, a chain of tools — and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. Contention becomes an ordering problem instead of a retry loop.

// Take the row. Anyone else who wants it waits, then reads it fresh.
await using claim = await ablo.reports.claim({ id: reportId });

await ablo.reports.update({
  id: claim.data.id,
  data: { forecast: await generateForecast(claim.data) },
});

Claims do not lock. A lock is held against a caller who may never come back; a claim is a durable lease with a wait-line behind it, so you can always ask who holds a row and who is queued for it. The write returns a receipt, and a write based on a row that has since changed is turned away rather than applied.

What people build

Run agents in parallel

Many agents over one dataset. Claims put them in a line instead of a race.

Hand work between agents

One agent claims, works, releases. The next picks up with the fresh row and a durable note about why.

Scope what an agent may write

A revocable key bound to one project’s models. Attribution comes from the credential, not the call site.

Confirm what landed

Every write returns a receipt. Nothing is fire-and-forget, and stale writes are rejected.

Audit every agent action

Trace any committed change back to the key that made it, and to the person who authorized that key.

Keep a person in the loop

Add the humans() plugin and people get presence and live queries. A person’s claim is just another holder the agent waits behind.

Using Ablo

Declare the models agents share

npx ablo init scaffolds ablo/schema.ts, the typed client, and the type registration. Declare only the models agents coordinate over — your auth, billing, and everything else stay in your own migrations.

npx ablo init
npx ablo dev

dev gives the current Git branch an isolated Ablo branch, wires its temporary key, pushes the schema, and watches for changes. Until the server has your schema, a write to a new model fails with server_execute_unknown_model. See Branch-first development.

Connect the database the rows live in

Ablo writes through a scoped role and confirms by tailing your write-ahead log. It runs no DDL and owns no schema — your migration tool stays in charge of the shape of your database.

npx ablo connect

No database yet? Pass an apiKey only and Ablo keeps the rows in its own log, so you can build the whole system today and point it at Postgres when you are ready.

Build with Ablo

You are writing the agent yourself — a worker, a job handler, a tool inside a model loop. Agents hold no socket; the credential is the identity.

const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });

Read with list / get, coordinate with claim, write with create / update / delete. See Agents for the loop and API Reference for the shape.

Or point an MCP host at it

The agent is Claude, Cursor, or another MCP host, and you want it operating your data directly. The coordination server exposes the same claim-and-commit loop as tools.

claude mcp add ablo -- npx -y @abloatai/mcp

See Model Context Protocol — and read the surface table below before you pick, because Ablo publishes two MCP servers and only one of them is a data plane.

Surfaces

Every surface reaches the same coordinated state. Pick by who is calling.

Surface	Use it for
SDK: `@abloatai/ablo`, `transport: 'http'`	The agents themselves. Stateless, request/response, nothing held open. The main path.
Coordination MCP: `@abloatai/mcp`	An agent living inside an MCP host that needs claim and commit as tools. A data plane.
`humans()`: with `@abloatai/ablo/react`	The interfaces a person watches agent work arrive in: presence, live queries, a local copy.
CLI: `ablo`	Scaffolding, schema push, connecting a database. Terminals and CI.
REST: `/api/v1`	Runtimes with no SDK.
Integration-helper MCP: hosted `/api/mcp`	Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only.

The two MCP servers are not interchangeable. The coordination server changes your data; the integration-helper server serves documentation and has no per-model data tools at all. An agent that edits rows uses the SDK or the coordination server — never the helper.

Where people fit

The bare client is the coordination layer: commit, read, observe, claim. People are something you add to it. humans() is the plugin that declares the local, watchable copy — the offline store, live queries, presence, and the framework bindings — and it needs a duplex connection, so a stateless agent cannot install it and is told so at construction rather than left with a subscription that never delivers.

There is no agents() plugin, and the absence is the point: agents are the default caller, not a special one.

Concepts

How Ablo Works — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. Read this first.
Coordination — claim, claim.state, and claim.queue: who holds a row, and who is waiting.
Concurrency Convention — the precise rule for guarded and unguarded writes.
Guarantees — what a confirmed write, a stale-write rejection, and a claim each promise.
Idempotency — make a retried write safe; what replays, what re-runs, and for how long.
Schema Contract — one schema becomes typed clients, agent writes, React reads, and the push.
Agents — the stateless participant: wake, read, claim, commit, idle.
Agent Messaging — durable handoffs between agents, linked to the claim they discuss.
Identity & Sync Groups — who is connecting, and which slice of state they see.
Change Propagation — how one row’s change reaches the actors that depend on it.
Client Behavior — options, errors, retries, timeouts, and imports.

Authority

Projects — one organization, many apps; each with its own schema, planes, and keys.
API Keys — the credential that carries an agent’s identity and its scopes.
Sessions — short-lived scoped credentials your backend mints.
Customer Organizations — serve many isolated customer organizations from one schema and backend.
Audit Log — trace any confirmed write back to the person behind it.
Operating on Your Database — which actions run freely, which to verify first, and which belong to a human.
Session Settings — point your row-level-security policies at Ablo’s writes, by naming the settings they already read.

Build

Quickstart — make your first coordinated write.
Integration Guide — the canonical end-to-end integration.
Integrations — long-running tasks, ingestion, and other application-edge runtimes.
CLI & Migrations — init / connect / push / migrate / generate.
Connect Your Database — where rows land when your own database is canonical.
Deployment — the database, the keys, and the schema push that take an integration to production.
React — provider, hooks, and reactive reads.
Webhooks — react to confirmed change from outside the SDK.
Debugging & Logs — watch claims, queueing, and grants while you build.

Reference

API Reference — model-by-model method shape.
Errors — the code registry, its categories, and what to do about each.
Upgrade Guide — upgrade a pinned pre-1.0 SDK safely.
Changelog — what shipped recently.

Examples

AI SDK Tool — put Ablo inside a model’s tool call.
Agent + Human — yield when a person is holding the same report.
Server Agent — a schema-backed worker.
Existing Python Backend — add coordination without replacing your API server.
Next.js — app-router setup with React bindings.

README — product overview and first example.
AGENTS.md — installation guidance for coding assistants.