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 |
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.
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
|
|
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
|
|
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 |
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 |
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).