Agent Teams and Mailboxes
Seshat’s team model is about persistent agent identities that collaborate asynchronously through a mailbox system. It is the beginning of a team runtime, not just a nicer name for sub-agents.
The Conceptual Shift
A sub-agent tool call is useful for bounded delegation inside one turn. A team runtime is a different architectural level: named agents with roles, inboxes, team membership, and message threads that can stay alive across sessions and restarts. That is closer to how a real organization works than to how a single prompt decomposes a task.
Persistent team members have stable IDs, nicknames, roles, optional team membership, preferred models, and profile-specific skills.
Each agent gets a persistent async inbox backed by SQLite. Messages survive restarts instead of living only inside one in-memory turn.
Send, Reply, Broadcast, and Assign turn roles and team membership into actual message delivery rules.
The TeamBus polls unread inboxes and hands each message to host-defined execution logic that can run a real session and send follow-ups.
`spawn_agent` creates a short-lived delegated execution path. Teams and mailboxes model persistent agent identities that can be offline, receive work asynchronously, reply later, and collaborate over multiple sessions without sharing one immediate turn.
The dispatcher can target a role and team, then route to the least-loaded matching agent based on unread mailbox counts.
Today the TeamBus is intentionally minimal. The caller wires the real session execution through the message handler instead of hiding it in a black box.
What Exists In The Runtime Today
Each agent has a stable UUID, nickname, role, optional team, persona template, preferred model, and preloaded skills.
Unread messages, read state, thread history, broadcasts, and reply links persist on disk instead of vanishing when one turn ends.
The runtime already supports direct send, threaded reply, team broadcast, and role-based assign with least-loaded routing.
Inbox polling and message dispatch exist, but the caller still plugs in the real session execution logic through the handler.
Message Model
The mailbox transport is intentionally explicit. The runtime does not hide coordination inside invisible internal state. Work moves as messages that can be inspected, stored, replayed, and threaded.
Assign a concrete unit of work to a specific agent.
Link a follow-up to a parent message through ReplyTo.
Send one announcement to all agents in a team, excluding the sender.
Carry runtime notifications like started, finished, or errored.
Architecture Responsibilities
- internal/agent defines who the agents are: profiles, identities, and profile registry.
- internal/mailbox defines how they communicate: typed messages and persistent inbox operations.
- internal/team defines how coordination happens: routing, team membership, TeamBus polling, and handler dispatch.
- The caller wires real session execution into the handler, which keeps the runtime honest about what is implemented versus what is still a higher-level roadmap.
Why This Matters
The point is not to add more agent names to one turn. The point is to move from isolated delegation toward persistent organizational coordination: identities, inboxes, shared team membership, delayed replies, and explicit message history.
- A manager agent can delegate and synthesize without doing every task itself.
- Two researchers can share a role while assignment still balances toward the least-loaded one.
- A team can survive process restarts because its communication state lives in the mailbox, not only in memory.
- Execution remains observable because messages and threads are first-class runtime records.
Current Boundary
The team primitives are real, but the fully autonomous persistent team loop is still not the official polished product surface. Profiles, mailbox, dispatcher, least-loaded assignment, TeamBus, and team registry exist. The remaining step is richer session execution on top of the mailbox handler and then first-class product surfaces around it.
Related Pages
Continue with Tools & Providers for the action-versus-transport architecture, or CLI Usage for the current user-facing runtime surface.