Share a board between agents¶
Agents of one run can share a board. Each one posts what it is doing and what it found,
claims work before doing it, and reads what the others posted. Parallel agents stop
repeating each other, and a later agent picks up where an earlier one stopped. Two
examples run offline with scripted models: examples/parallel_research.py (fan-out, claims,
fan-in) and examples/board_handoff.py (one agent after another).
Every run has a board¶
Executor.context() puts one board in ctx.extras["aa.board"]. Nested calls, agent
tools, tool loops and flow nodes copy the context, so they all get the same board.
board_of(ctx) returns it (with no argument: the board of the call running now).
from agent_adapter.board import board_of
board = board_of(ctx)
await board.post("finding", "Oslo: 3 hotels under 100 EUR", key="hotels:oslo")
claim = await board.claim("search:oslo hotels") # the first caller wins
if claim.won:
... # do the work
else:
print(claim.holder, "already does it")
latest = await board.read(kind="finding", since=0, limit=10)
| Entry kind | What it says |
|---|---|
status |
"working on X": a summary keeps only each agent's latest status |
finding |
"found Y" |
claim |
"I'm doing X": claim(key) posts it for the winner |
handoff |
a summary for the next agent |
by (who posted) defaults to the agent tool or flow node that is running. Set it with
by=, or wrap your own code in posting_as("name"). watch() streams new entries as
they arrive, from any process the store reaches.
Fan out, claim, fan in¶
Three researchers run side by side and claim their topic first; the third asks for a topic already taken, so its search never runs. A writer then reads their findings.
sink = EventLog()
executor = Executor(tools, sink=sink)
team = Registry()
for name in ("alpha", "beta", "gamma"):
agent = LoopAgent(researcher(name), tools, board="auto")
researches = agent_tool(
agent, name=name, description="Researches a topic.", executor=executor, parallel_safe=True
)
team.add(researches)
author = LoopAgent(CallableModel(writer, model="writer"), Registry(), board="auto")
team.add(agent_tool(author, name="writer", description="Writes the report.", executor=executor))
- Agent tools of one run take turns.
agent_tool(..., parallel_safe=True)lets them run side by side, and the tool calls inside them too. board_tools()gives the modelboard_read,board_postandboard_claim. They only write to the run's board, so they need no approval. They still run through the executor, so guards, redaction and limits apply.- Agent tools post
started: <task>andfinished (ok)statuses on their own, and every flow node postsfinished; set <fields>when it ends. These posts never fail a run: a full board or a store error is logged and skipped.
Agents see the news, not the whole board¶
LoopAgent(board="auto") (or run_tool_loop(..., board="auto")) adds a short note
before a model call with what the other agents posted since that agent's last turn:
- only new entries, newest first when they do not all fit, then a pointer to the rest
(
+35 older: board_read(since=0)) and the claims the others still hold; - at most
board_charscharacters (600 by default); long texts end with[cut: board_read(entry=n)], so the model reads one in full only if it needs it; - nothing at all when nothing is new.
The note is a user message of fenced data, kept in the history, so each entry reaches a
model once. Its first line records how far the board was read, which also survives a
checkpoint. Measured in tests/board/test_tokens.py: three agents next to 50 long
entries got notes of at most 600 characters each, under a fifth of the board's text in all.
Agents one after another¶
The board outlives each step of a run. A planner posts a handoff; the writer that runs
next finds it in its note.
tools = Registry()
tools.add_many(board_tools(include=("post",)))
crew = Registry()
executor = Executor(crew)
plan = LoopAgent(CallableModel(planner, model="planner"), tools)
write = LoopAgent(CallableModel(writer, model="writer"), Registry(), board="auto", board_chars=600)
crew.add(agent_tool(plan, name="planner", description="Plans the trip.", executor=executor))
crew.add(agent_tool(write, name="writer", description="Writes the plan.", executor=executor))
async def main() -> None:
ctx = executor.context()
board = board_of(ctx)
for n in range(40): # what earlier agents of this run left on the board
await board.post("finding", f"museum {n}: open 10-17, ticket {10 + n} EUR", by="scout")
await executor.run("planner", {"task": "plan two days in Oslo"}, ctx)
answer = await executor.run("writer", {"task": "write the plan"}, ctx)
Plan for 2 days in Oslo, museums first, 300 EUR in all
board: 45 entries, 1554 characters
writer's note: 559 characters (cap 600), 1 note
A flow node can read the board itself: await board_of(ctx).read(kind="handoff", limit=1).
Short reads¶
board.summary(1_500)leaves out the running agent's own entries (include_own=Truekeeps them), keeps each agent's latest status only, and cuts long texts with a pointer.board_readreturns the 10 newest entries by default (limit, up to 50), filtered bykind,byandsince;entry=nreturns one entry in full.
Stores¶
| Store | Shared by |
|---|---|
MemoryBoardStore() (the default) |
this process; keeps the boards of the last 256 runs |
SQLiteBoardStore("board.db") |
every process on one host (WAL) |
RedisBoardStore(lambda: redis.asyncio.Redis()) |
every worker and host; boards expire after ttl_s (7 days) |
from agent_adapter.board import BoardSettings, SQLiteBoardStore
executor = aa.Executor(registry, board=SQLiteBoardStore("board.db"))
# every run of one thread shares a board; caps per board
settings = BoardSettings(store=SQLiteBoardStore("board.db"), scope="thread", max_entries=200)
executor = aa.Executor(registry, board=settings)
Claims and caps are atomic in every store: two processes claiming one key get one winner.
Durable runs keep the board¶
A paused or checkpointed flow seals the board's entries into its checkpoint, and so does a
durable tool loop (run_tool_loop(checkpoints=...)). FlowRunner.resume, recover and
recover_tool_loop put them back first, so a run resumed in a fresh process still sees
what its agents posted before the pause or crash.
Safety¶
- Caps. A board takes at most
max_entries(500) entries andmax_bytes(256 KiB); a post past that raisesToolError, so a model reads why. Text past 2,000 characters is cut. - Data, not instructions. Notes, summaries and
board_readshow each entry on one line inside<shared-board>under a header saying it is data; fence tags inside an entry are neutralised. - One board per run. Runs never see each other's boards, unless you choose
scope="thread". - Events carry no text.
board.postedhas the entry id, kind, key, author and length;board.claimedhas the key, who asked, who holds it andwon.
To see how the parallel work went (waits, repeats, claims, tokens per agent), read See how parallel agents went.