How agents work
How the pieces of Seed Agents fit together, with the design principles, the components of the apps and the server, and what happens to one message from the moment it is sent.

Seed Agents is the part of Seed that runs agents. An agent lives on a server called an app environment. The Seed app talks to that server to set up a model, create agents, chat with them, and see everything they did.

This page has three parts: the principles the design follows, the components, and the path one message takes. Read it after the introduction and before the pages on single parts.

Design principles


    Signed control plane: every HTTP action is wrapped in a signed DAG-CBOR envelope. See the signed API.

    Account isolation: everything the server stores belongs to one Seed account. To reach it you must be the owner, a reader or writer the owner invited, or any signed account when the owner turns on public access. See sharing.

    Durable sessions: a session is a log of events that only grows. A client can replay it from any sequence number.

    Live clients: clients subscribe over a signed WebSocket (see WebSocket subscriptions) and receive changes as they happen.

    Secret redaction: the server stores API keys encrypted and never returns them in a response.

    Visible tools: every tool call and every tool result is a saved session event, and the app shows it.

    Shared Hypermedia behavior: read uses the same SDK code as the CLI to resolve URLs. It does not run the CLI as a program.

    Inspectable operation: saved session events, the signed read actions, and diagnostic logs help you debug. Nothing can be inspected without a signature.

    Few verbs, one address space: the model starts with five verbs, read, write, call, delegate and plan, plus the two session verbs status and continue_session. A new feature arrives as a new address or a new callable. It never adds a verb. A callable the thread has used is promoted to a tool of its own.

    Configuration is content: an agent's tools and memory are in its Space. The agent and its owner can both address and read them.

    The log is symmetric: the person holds the same verbs as the agent. Every event in the Log has an actor, and there is no hidden channel between the two.

    Everything that executes is a run: turns, children, and scripts are rows in one tree, and that tree is also the queue. Waiting costs nothing, and a run survives a crash. See Runs.

The main terms above each have their own page. The Agents glossary lists them.

Major components

There are three groups: the apps people use, the server, and the libraries they share.

Seed app (desktop) and Seed web app, sharing frontend/packages/ui/src/agents ├─ Local app environment subprocess (desktop only; same artifact as the Docker image) │ configured with the desktop's typed HM API bridge plus its daemon's direct IPFS endpoint ├─ Agent views of a mount document, and pages for one agent, one session, one run ├─ Assistant sidebar: sessions of any agent on any server the app knows ├─ Provider and create-agent dialogs ├─ daemon-backed signing for the selected account ├─ signed CBOR HTTP client ├─ signed WebSocket subscription hook └─ chat message renderer shared with the desktop assistant panel App environment (Bun) ├─ /hm/api/apps/message signed action API ├─ /hm/api/apps/ws signed subscription API ├─ SQLite persistence (state, and the runs table that is also the queue) ├─ AES-GCM secret storage ├─ Pi Durable model execution loop, one durable conversation per session ├─ the verbs (read / write / call / delegate / plan, plus status / continue_session) ├─ tool documents in ~/tools + the <space> index with every turn's input ├─ run queue: leases, boot sweep, park/resume, wake sources ├─ QuickJS script engine with a content-keyed journal └─ diagnostic logging Shared Seed libraries ├─ @seed-hypermedia/client for Ed25519 signatures/principals and canonical DAG-CBOR │ (the service imports them through the @shm/shared/blobs and @shm/shared/cbor re-exports) ├─ @seed-hypermedia/client for URL resolution and markdown conversion └─ desktop daemon for selected-account signing

The desktop app signs through the Seed daemon. The server is described on the app environment page, and persistence covers the SQLite tables. Pi Durable is the library that runs the model loop; see durable sessions.

The life of a message

Steps 1 to 8 set an agent up. Steps 9 to 21 follow one message.

    A person opens a space in the Seed app. The app finds the space's agents through their mount documents.

    The app reads each agent's server address from its document and checks the server's health at /api/health.

    The app opens a signed WebSocket subscription for the selected account.

    The person sets up a model provider in the Model providers dialog.

    The app sends signed SetSecret and SetModelProvider actions.

    The person creates an agent from the New menu of the home document.

    The app publishes the agent's document and sends a signed CreateAgent.

    The server saves the agent and tells subscribed clients that the account changed.

    The person opens the agent and creates or opens a session.

    The app subscribes to sessions/<sessionId> over WebSocket.

    Someone with chat access (the owner, a writer, or a chatter) sends a message with a signed MessageSession. Others may send at the same time.

    The server saves each user message at once, with the account that acted and the exact signer. It sends the message to subscribers and creates a runs row. The first turn is claimed at once on the interactive queue. Later turns wait in the order their messages arrived, because only one model turn may own a session. The session status follows its runs, so it reads streaming while any of those turns is live.

    The server opens the session's durable store and brings its conversation up to date with the log. The turn is set up from the provider record, the encrypted secret, the system prompt, and the tools. The system prompt is the agent's own instructions plus the shared Seed instructions; see what an agent is told. The tools are the verbs, plus any callables this thread has already used.

    Pi Durable runs the loop: it asks the model, runs the tool calls, and asks again. It saves every model response, tool result, and partial answer to the store before anything else sees it.

    The server emits session-partial events with new model text, token usage so far, and what the turn is doing.

    The WebSocket sends appendPartial events to subscribed clients.

    The app draws the partial text with the shared markdown renderer.

    The server copies tool calls and results from the store into the log as saved events. They carry no actor field, so they read as the agent's. A call for a tool the thread has not used returns that tool's contract in place of an error. Once the contract is in the transcript, the tool is promoted for the rest of the thread.

    If the turn used delegate, each child gets its own run row: a model child with its own session, or a script child in the QuickJS engine. The parent's run parks on them, holds no resources, and goes on when they finish.

    The server saves the final assistant message as an event. Then the run finishes: it adds up the token usage of its children, settles the plan steps whose children all succeeded, and records any obligation it did not meet.

    The session status becomes idle, or error when the latest run failed.

A message sent while a turn runs is saved at once and answered by the next turn.

Limits

    A captured signed request can be replayed for up to five minutes, because the server checks a timestamp and does not remember the requests it has seen. See the security model.

    The key that encrypts secrets is stored in the same database as the secrets. See agent identity.

    Grants stop at the callable set, one publish grant, and the list of enabled MCP servers. There is no rule per address or per destination, and memory writes are never gated.

    The protocol of WebSocket subscriptions has no full heartbeat, no backpressure and no limit on subscriptions.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Connections0
Linked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkLinked document · Outgoing linkHow agents workHow agents work
Citations 0Children & links 42

Loading child documents…

Connections show where other documents or comments link to this document.

Related documents

Loading connections…