Skip to content

Shared board

One board per run: agents post statuses, findings, claims and handoffs, and read what the others are doing. Guide: Share a board.

Shared board: agents of one run see what the others are doing and have found.

BOARD_KEY = 'aa.board' module-attribute

KINDS = ('status', 'finding', 'claim', 'handoff') module-attribute

Board

One board: what the agents of a run (or thread) are doing and have found.

Entries are only added, never changed. by defaults to the agent or flow node that is running (posting_as); every post and claim is a board.posted / board.claimed event on sink. A post that would pass max_entries or max_bytes is refused.

Raises:

Type Description
ToolUsageError

an empty scope, a store that is not a BoardStore, or bad caps.

claim(key, *, by=None, text='', data=None) async

Take key if nobody holds it; the first caller wins, later ones see the holder.

The winner's claim is also posted as a claim entry. Claiming again a key one already holds wins again and posts nothing.

Raises:

Type Description
ToolUsageError

an empty key or author.

ToolError

the board is full when the winner's entry is posted.

post(kind, text, *, key='', data=None, by=None) async

Add an entry; text past MAX_TEXT characters is cut.

Raises:

Type Description
ToolUsageError

an unknown kind, a bad key, author or data.

ToolError

the board is full (the model sees why).

read(*, kind=None, by=None, key=None, since=0, limit=None) async

Entries after seq since (oldest first), filtered; limit keeps the newest.

restore(rows) async

Put back snapshot entries the store lacks (by id); returns how many were added.

snapshot() async

Every entry as plain data, for a checkpoint.

summary(max_chars=1500, *, exclude_by=None, include_own=False) async

The board as short prompt text, fenced and marked as data ("" when empty).

The running agent's own entries are left out (exclude_by names another author; include_own=True keeps them), only each author's latest status is kept, the newest entries win the space, and a long text ends with a pointer to read it whole (board_read(entry=n)).

watch(*, since=0, kind=None, poll_s=0.1) async

New entries as they arrive, forever; stop by breaking out or cancelling.

Every store is polled each poll_s seconds, so it works across processes too.

BoardSettings dataclass

How an executor makes each run's board: the store, the scope and the caps.

scope="thread" lets every run of one thread_id share a board (a run without a thread keeps its own).

Raises:

Type Description
ToolUsageError

a store that is not a BoardStore, an unknown scope or bad caps.

board(*, run_id, thread_id='', sink=None)

The board of a run (or of its thread, with scope="thread").

BoardStore

Bases: Protocol

Where boards keep their entries and claims, one scope (run or thread) per board.

append gives the entry the board's next seq and refuses it (None) when the board would pass max_entries or max_bytes; claim records the first holder of a key and returns (holder, True when this call recorded it). Both are atomic across every process the store serves. Backend errors propagate.

Claim dataclass

The outcome of Board.claim: who holds the key, and whether that is the caller.

Entry dataclass

One board post: who wrote it, what kind, an optional key, the text and JSON data.

seq is the entry's place on its board (1, 2, ...), set by the store; read(since=) and watch() use it.

from_dict(row) classmethod

An entry from to_dict data.

Raises:

Type Description
ValueError

a missing field or one of the wrong type.

size()

Bytes this entry counts against the board's max_bytes.

to_dict()

The entry as plain JSON data (a snapshot row).

MemoryBoardStore

A BoardStore in this process (threads and event loops share it), the default.

Keeps the boards of the last max_scopes runs; the least recently used is dropped.

Raises:

Type Description
ConfigError

max_scopes is not a positive int.

append(scope, entry, *, max_entries, max_bytes) async

Add entry as the board's next one, or None when a cap would be passed.

claim(scope, key, holder) async

The key's holder: holder when it was free (True) or already theirs.

drop(scope) async

Forget a board's entries and claims.

read(scope, *, since=0) async

The board's entries after seq since, oldest first.

RedisBoardStore

A BoardStore on Redis (agent-adapter[redis]), shared by every worker and host.

client_factory() returns a redis.asyncio.Redis (one per event loop). append and claim are Lua scripts (Redis 5 or later), so cap checks and first-wins claims hold across processes. A board's keys share a hash tag (one Cluster slot) and expire ttl_s after its last write (None: never).

Raises:

Type Description
ConfigError

client_factory is not callable, a bad prefix or ttl_s.

append(scope, entry, *, max_entries, max_bytes) async

Add entry as the board's next one, or None when a cap would be passed.

claim(scope, key, holder) async

The key's holder: holder when it was free (True) or already theirs.

drop(scope) async

Forget a board's entries and claims.

keys_of(scope)

The entries, bytes-used and claims keys of one board.

read(scope, *, since=0) async

The board's entries after seq since, oldest first.

SQLiteBoardStore

A BoardStore in a SQLite file (WAL), safe across threads, loops and processes.

Each call runs in a worker thread on its own connection; append and claim hold BEGIN IMMEDIATE, so the cap check and the write are one step for every process. timeout is how long one waits for the file lock (seconds).

Raises:

Type Description
ConfigError

a bad path or timeout (here); on first use, a database without WAL support or with another schema version.

append(scope, entry, *, max_entries, max_bytes) async

Add entry as the board's next one, or None when a cap would be passed.

claim(scope, key, holder) async

The key's holder: holder when it was free (True) or already theirs.

drop(scope) async

Forget a board's entries and claims.

read(scope, *, since=0) async

The board's entries after seq since, oldest first.

board_of(ctx=None)

The board of ctx's run (default: the call running now), made on first use.

Contexts from Executor.context() carry the executor's board; any other context gets an in-memory board that its nested calls share.

Raises:

Type Description
ToolUsageError

no ctx and no call is running.

board_tools(include=('read', 'post', 'claim'))

board_read, board_post and board_claim (or the ones in include).

They only write to the run's board, so they need no approval; add them to a registry and they run through the executor like any tool (guards and redaction apply).

current_author()

The innermost posting_as name, else the current flow node's name, else "".

posting_as(name)

Board posts inside the block default to by=name (agent tools set their name).