# Pi Agents Specification Pi Agents lets Agents in Pi discover, message, and wait for each other. Programs built on these operations are specified in PROGRAM.md. Terms follow Pi's [Pi Durable specification](https://github.com/earendil-works/pi/blob/main/packages/durable/docs/spec.md). ## 1. Semantic model An **Agent** is an addressable conversation with a stable identity. The Agent that spawns another Agent is its **owner**. A root Agent has no owner and is usually opened by a user. Ownership forms trees. An Agent is shown by its name and **short ID**: the shortest prefix of its ID, at least 8 characters, that no other Agent visible to the reader has. An address is an ID, a name, or a unique ID prefix, tried in that order. A **message** carries text from one Agent to another. An **input** asks the recipient to act. A **write** only adds to the recipient's conversation. A **turn** is one continuous run of an Agent's model and tools. Its final assistant message is the **answer** to the inputs it handled. An owner can **wait** for answers to the inputs it sends to its owned Agents. **Visibility** determines which Agents an Agent can discover and message. ## 2. Operations ### 2.1 spawn `spawn` creates a named, owned Agent and sends it a first input. It accepts an optional working directory, model, thinking level, and forked context, and returns the Agent's ID. Names are unique among siblings. ### 2.2 send `send` sends a message to a visible Agent by address. An ambiguous or unknown address is rejected. An input to an Agent with a turn in progress is either answered by the current turn (`steer`) or by a new turn after it (`followUp`, the default). A write is added at the recipient's next tool boundary, or at once if it is idle. A write can go to several Agents at once. When the user of a root Agent clears its queued messages, messages from other Agents stay queued. After an Agent's turn is stopped, messages from other Agents, notifications included, become writes until its next input from its user or owner. ### 2.3 wait `wait` returns results of inputs sent to owned Agents. It can target specific Agents and take a timeout. ### 2.4 list `list` returns visible Agents with their ID, name, working directory, state, and latest request: the last user message or input it received. ### 2.5 abort `abort` stops an owned Agent's current turn and withdraws its queued inputs. The Agent stays available. ## 3. Lifecycle An Agent is `running` while a turn is in progress, `waiting` while its turn waits in `wait` (§4), `queued` while its next turn waits for a slot (§4), and `idle` otherwise. An Agent goes offline when its runtime unloads it; it stays `idle`. `send` returns once the recipient's runtime accepts the message, waking it if needed. Acceptance does not mean the recipient has handled it; a message not yet handled is lost if the recipient exits. An input to an offline Agent wakes it; a write to one is rejected. Owned Agents run independently of their owner's turns. When their owner goes offline, they go offline too, from the bottom of the tree up, and their unfinished inputs end as `aborted`. They return as `idle` when their owner is loaded again. On abort or when going offline, work that has not stopped within a timeout is abandoned: it no longer counts as live work and may keep running until the process exits; the timeout is reported. A root Agent is `running` while it has a turn in progress or pending messages, or while its tree has live work (§7 Task panel); otherwise it is `idle`. ## 4. Visibility and limits An Agent sees every Agent in its own tree. A root Agent also sees other root Agents. Limits apply to owned Agents in each tree. An owned Agent needs a slot to run a turn. `maxConcurrent` (default 3) is the number of slots. An input that would start a turn waits for a free slot, and `spawn` or `send` reports that it is queued. A `steer` input to an Agent with a turn in progress joins it and needs no new slot. An Agent gives up its slot while it waits in `wait`, and takes one again before continuing, ahead of inputs that have not started. An input is outstanding from acceptance until its turn ends or it is withdrawn. `maxOutstanding` (default 8) limits outstanding inputs; an input beyond it is rejected. Notifications (§5) do not count. ## 5. Results and notifications An input sent to an owned Agent ends as `completed` when its turn answers it, `failed` when its turn fails, or `aborted` when it is aborted or withdrawn. Its result is the answer or the error. Only inputs from the owner have results; the recipient replies to other senders with `send`. `wait` returns unread results in order and marks them read. On timeout, it returns the results so far and names the Agents still pending. A steer input to the waiting Agent, from any sender, ends `wait` the same way; a write does not. It can also return read results again. When an input ends and its owner is not waiting for that Agent, the owner receives a notification, unless the owner aborted it. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2), and it names the Agent and how the input ended. It does not include the result; the owner reads the result with `wait`. A recipient sees each message with its sender's name and ID. ## 6. Model-facing tool ### `agent` description: Create, message, and coordinate Agents. `spawn` creates an owned Agent and sends its first input; `send` sends an input or a write to a visible Agent; `wait` waits for owned Agents and returns unread results; `list` finds visible Agents; `abort` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input while its owner is not waiting for it, the owner receives a notification naming the Agent and outcome; `wait` returns the result. Owned Agents under the same root share `${maxConcurrent}` execution slots and a limit of `${maxOutstanding}` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit. promptSnippet: Create, message, and coordinate Agents promptGuidelines: - Use `agent(action='spawn', name=..., message=...)` for concrete, bounded work with a clear expected result. Keep the first message self-contained; use `context='fork'` only when the Agent needs the caller's conversation. - For independent work, start the Agents before waiting and partition tasks into non-overlapping responsibilities. - Use `agent(action='wait', ...)` when the next step depends on Agent results. Prefer one longer wait over repeated short polling. parameters: - `action`: Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?)`, `send(target, message, deliverAs?)`, `wait(target?, history?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`. - `name`: Name of the new Agent for `spawn`; unique among the caller's Agents. - `message`: Non-empty text for `spawn` or `send`. - `cwd`: Working directory for `spawn` (default: the caller's current working directory). - `context`: Context for `spawn` (default: fresh). fresh starts without the caller's conversation; fork snapshots it. - `model`: Model for `spawn` as provider/modelId (default: the caller's model). - `thinkingLevel`: Thinking level for `spawn`: off, minimal, low, medium, high, xhigh, or max (default: the caller's level). - `target`: Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending or unread results. - `deliverAs`: Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but never starts a turn and has no result. - `history`: Number of most recent read results to return again per selected Agent for `wait` (default: 0). - `timeout`: Maximum seconds for `wait` (default: 30, min: 10, max: 3600). Timeout does not abort Agents. - `query`: Search query for `list`, matching ID, name, cwd, summaries, and user messages. Case-insensitive; spaces mean AND; `|` means OR. - `state`: State for `list`: running, waiting, queued, or idle. - `limit`: Maximum Agents returned by `list` (default: 20, max: 200). - `offset`: Number of Agents to skip for `list` (default: 0). results: In these formats, `` is the Agent's short ID. Details use full IDs; arrays remain present when empty. `spawn`: ```text Agent () started. Agent () queued: all slots are busy. ``` Details: ```text { id, name, queued } ``` `send` returns acceptance, not completion: ```text Input accepted by (). Input accepted by (), queued: all slots are busy. Write accepted by (), ... ``` Details: ```text followUp / steer: { id, queued } write: { ids } ``` `wait` returns one block per result, followed by pending Agents on timeout: ```text Still pending: (), ... ``` When a steer input ended the wait, a line follows: ```text Still pending: (), ... Stopped waiting for a new message. Wait again to keep waiting. ``` A result returned again through `history` adds `history="true"`. A single unread completed result, with nothing pending, is returned as the answer alone. When there are no results or pending inputs: ```text No results. ``` Details: ```text { results: [{ id, name, state, history, result? }], pending: [{ id, name }], interrupted? } ``` `state` is the input outcome (§5); `history` marks a previously read result; `interrupted` is `true` when a steer input ended the wait. `list` returns one entry per Agent, followed by its latest request, if any, and its time. With a query, entries are ordered by their most recent match, and a matching summary or user message shows its latest excerpt instead: ```text () YYYY-MM-DD HH:MM ``` When more entries remain: ```text [N more results. Use offset=X to continue.] ``` When no Agents match: ```text No matching Agents. ``` Details: ```text { total, agents: [{ id, name?, ownerId?, state }] } ``` `agents` is the current page; `total` counts all matches. `state` is the Agent's current state (§3). `abort`: ```text Agent () aborted. Agent () has no turn or queued inputs. ``` Details: ```text { id, aborted } ``` For unnamed root Agents, show the ID without a name or parentheses. errors: Invalid calls fail with an error. Errors that need a follow-up say what to do: ```text No visible Agent matches "". Use list to find Agents. ``` ```text "" matches several Agents: () ... Retry with a longer ID prefix. ``` ```text Name "" is already used by . ``` ```text Input rejected: inputs have not ended. Wait for results or abort an Agent. ``` ```text () is not owned by the caller. ``` When an aborted turn does not stop within the timeout (§3), `abort` fails with the following; only restarting Pi stops it. ```text Agent () did not stop within the timeout and may still be running. ``` truncation: Text beyond Pi's output limits is truncated with Pi's native notice, and the full text is saved to a file whose path appears in the notice. `wait` adds results in order; the result that crosses the limit is truncated but keeps its closing tag, and later results are omitted. A truncated result counts as read. Omitted results stay unread, and the text ends with: ```text [Results omitted: (), ... Use wait with fewer targets.] ``` Details retain metadata, `truncation`, and `fullOutputPath`. `wait.results[].result` contains only retained text and is absent for omitted results. messages: A notification to the owner: ```text Agent () . ``` A recipient sees each message in an `agent-message` element naming the sender. An input from a sender other than the owner also carries a note asking for a reply: ```text ``` ```text ``` ## 7. Human interface ### Task panel A panel above the editor shows the current Agent's live work: ```text Tasks ( live, /tasks to view) Agent ()