The Seed app and the Seed web app are the clients of a Seed Agents server. The server has no browser UI of its own. Both apps render the same screens from one shared package, frontend/packages/ui/src/agents/, so a tool row, a run card, or a trigger form looks and behaves the same wherever it appears. This page describes what those screens do. The signed API describes what they send.
Two surfaces, one code
Two surfaces read the same sessions. The agent pages are full-window: one page per agent with its tabs, and one page per session or run. There is no agents index and no page per server: an agent is a document, found in the file browser of the space that holds it. The assistant panel is the same thing in a column: on the desktop it is toggled from the Agents button in the space header and opens in the side panel beside whatever you are reading, which it shares with Bookmarks and Activity, so opening one closes the others; on the web it is mounted above the site's page outlet so route changes never remount it, opened from the site header's assistant toggle into the same shared side panel Activity uses — opening one closes the other — and goes full-screen with a "Back to page" bar on narrow screens (only when opened there on purpose: a remembered open state never takes over a narrow screen by itself). The panel only opens when the reader asks for it. Opening it shows the chat list unless a chat was already open: unread chats are flagged in the list and on the toggle, never opened on the reader's behalf. On the web the open state, open chat, and agent filter are remembered per browser tab (sessionStorage), so a reload restores them while a new tab starts closed; a remembered chat whose agent is not one of the site's own is dropped instead of resumed. On the web the full pages live under /hm/agents/.
Both surfaces need a selected account, because an agents server, including the local one, rejects unsigned requests. With no account the pages render an invitation to sign in.
Agent mounting
An agent's owner can adopt it into a space: the dialog asks for a space (their own, or any whose home their signing identity can write to) and a URL path, never a location deeper inside the space, and the document takes the agent's name. From then on the document's name attribute is the agent's name: the server copies it onto the agent at adoption and at creation, a definition edit cannot change it, and renaming the document (edit the title, publish) renames the agent. The server checks every mounted agent's document once a minute and at start, so agents adopted before this rule catch up on their own. The user-facing verb is adopt; the protocol action and the code keep the name mount. Agents that live in no space yet are orphan agents, and an orphan's own page shows a persistent Adopt agent banner. In developer mode the options menu of an adopted agent's document offers Orphan agent, the undo: the server gives the agent its pre-adoption id back (or a fresh one) and keeps its sessions, memory and triggers (UnmountAgent, owner-only), the document is deleted, and the agent's own page opens so it can be adopted again. The document carries type: hm://hyper.media/agent and agentServerUrl; it represents an agent only when that server returns an agent with the document's exact versionless hm:// ID. Advertising a server alone does not make a document an agent. Document permissions and agent access remain separate: publishing a mount does not grant access to the agent's sessions or tools. A signed-in visitor the agent is not shared with sees that on the page: the server and the visitor's account are named, with the fix (ask the owner to share it from the Agent access tab, or sign in as the owner), and a note that an orphaned or deleted agent looks the same from outside. An account the owner has invited sees the invite there instead, with its role and an Accept invite button; accepting opens the agent in place.
Local and hosted agents can both be mounted. A new agent is created the way a new document or collection is: pick Agent from the New menu, or from the plus button beside Home in the file browser. This is the only way to create an agent; the assistant panel does not offer it. Agents are always children of the home document: the Agent entry appears only in the home document's New menu and is absent under every other document. The dialog asks for a name and a model; the agent runs on the server the space on screen advertises, else the configured default server (the hosted one unless settings say otherwise), never the app's own local server unless nothing else is on offer. When other servers are configured the dialog says Runs on that server with a Change link that unfolds the Run on choice; adding a server is done in settings, not here. Reasoning, thoroughness and the system prompt start at their defaults and are changed later in the agent's Settings and Prompt tabs. The agent's document is created under home at a path derived from its name (a numeric suffix avoids an existing document), and the server creates the agent directly with that document ID. If the document publishes but the server action fails, Retry reuses the same document, signing identity and request. The file browser marks mounted agents with an agent icon beside documents and collections. Localhost and private-network addresses remain usable only from devices that can reach that server; mounting does not turn a local server into a public one.
A mounted agent has no menu of its own and no separate delete: deleting the document (from the document's own menu) deletes the agent on its server with it, sessions, memory and triggers included, and the dialog says so. Mounted agents share the document's tab bar, trimmed to what matters for an agent: Comments shows only once a comment exists; Attributes, Connections and the people tab are not shown (the options menu has Attributes instead, and neither Document Settings nor Convert to Collection). Agent mount documents contain no body. Under the tabs the agent view is a plain column, no panel border or background of its own, and it takes the rest of the window: the page stops scrolling and the view scrolls inside, so a session's composer stays pinned at the bottom with nothing below it. The Publish button stays out of the header while the document has nothing to publish; it appears once the draft is dirty (attributes edited, say) and the options menu is there the whole time. There is no New button either: only documents and collections take children. Their base URL opens Sessions; there is no Home tab for now. Creating or mounting an agent grants the mount location's owning space recursive WRITER access across the agent's space. The API server still controls access to sessions and tools separately; /:sessions, /:settings, and /:session/SESSION_ID open the agent UI. Triggers, Memory, and Agent access use /:triggers, /:memory, and /:access. The pages under Settings are /:settings/prompt, /:settings/permissions, /:settings/identities and /:settings/mcp (older /:prompt and /:tools links remain readable; /:tools opens the permissions page). The document's options menu opens the profile of the account the agent signs as (Open <name> profile). An individual trigger uses /:triggers/TRIGGER_ID; older /:triggers?trigger=TRIGGER_ID links remain readable. Session and message sharing links open Seed's web UI instead of the API server. Root-space /:settings still opens space settings.
Mounting waits for an idle agent and completed memory uploads. The server changes relational references atomically, retains the existing memory directory and session history, and resolves old server IDs as aliases. If the document publishes but the server action fails, retry in the mount dialog to reuse it. Moving an already-mounted agent between documents or servers is not part of this flow.
Which servers a client talks to: on the desktop, the union of the app's local server and the servers the user configured in settings, plus whatever servers the mount documents of the space on screen name. On the web, only the servers named by the mount documents of the site on screen; the configured default (SEED_AGENT_SERVER_URL) is used to create an agent and for nothing else. A space has no agent settings of its own: its agents are its mount documents, found by a document query that runs on the client after the page is up, so no page waits on it. The environments page has the details.
The assistant panel
If the account owns orphan agents (agents from before agents were documents, on any server that can host mounts: the app's own servers and those the space's mount documents name), the agents toggle in the title bar or site header carries a red dot and a tooltip counting them, and a sticky Give your orphan agents a home card sits at the top of the panel's list (or above its empty state, on the web too, where the list is otherwise the site's mounted agents only): one row per agent with an Adopt button that opens the adopt dialog and, once adopted, opens the agent's new page, a fold-to-one-line toggle for the session, and Show all past four rows. It disappears once every owned agent has a space and never shows for a new account. The panel's dropdown filters the chat list to one agent or to All agents. Its agents are grouped by the space they live in (the account of their document id, named by that space's home document; the space on screen is tagged This space), not by server; orphan agents close the list under Orphan agents, each row naming its server since that is the only place it lives. Below the list sits the composer; sending a first message opens the new chat in place. The chat header has a back button to the same filtered list, plus Open, Copy URL, and Delete. The built-in Assistant is an ordinary agent auto-provisioned on the local server once a model provider exists and the local server is settled as in use (attached in development, or its switch is on), created with a deterministic idempotency key so two windows racing on first launch dedupe server-side and so deleting it is respected. Its only callable grant is search. It has no signing identity, so it cannot publish.
The panel contributes window context: the current URL, title, view, side panel, open comment, focused block and range, and draft state go along as a context content part on the first message only. They never appear in the transcript. The user bubble shows a "Context" chip that opens the exact lines the model was given. The panel does not mount the wrench palette.
Servers, accounts and providers
Servers are managed under Settings, in the Agent Servers section. Each server row shows its health (Checking, Unreachable, or Online) and opens the server's Accounts and Providers dialogs; a remote server can be removed and any server made the default. On desktop a Local agents server switch runs or stops the bundled server; it is off by default and the switch is disabled while the app is attached to a development server. The local agent system is suppressed in release builds except where it is already in use: on the first launch after the upgrade the app runs the bundled server once more if its database exists, looks for agents under every local account, keeps it on when any are found and turns it off otherwise (agentsLocalServer setting; resolveLocalAgentsServerSpawn in agents-server-process.ts, useLocalAgentsServerMigration in the desktop). A fresh install never spawns it. The dev default local server is http://localhost:3051. Release builds embed a server on port 3050. See environments. No screen lists pending agent invitations.
The providers dialog
Lists redacted providers with their logos and saves records for every type in the provider registry (OpenAI, Anthropic, Google, OpenRouter, DeepSeek, Groq, xAI, Ollama, custom). Two auth modes: an API key, saved through signed SetSecret then SetModelProvider (the dialog refuses to send a key to a remote plain-HTTP server), or Sign in with ChatGPT, offered only when the provider supports it and the server's health reports subscriptionAuth: true, because the flow needs the desktop app to catch the provider's localhost redirect. A provider whose sign-in expired shows a re-sign-in button. ollama and custom get an editable base URL and an optional key. Details in model providers.
The create-agent dialog
Choose server and provider, name the agent, pick a model from the provider's model list, pick a reasoning level where the model supports one, pick a thoroughness preset, and write the system prompt in the Seed block editor. The default prompt embeds the Agent Guide at hm://hyper.media/agent/guide, which the server resolves to its configured knowledge base. Whoever can edit that page shapes every new agent's prompt (prompt injection map). New agents get the default grants: search, web_search, execute, and publish. The dialog first creates a dedicated signing key for the agent, and the server auto-creates an enabled mention trigger following that identity, so mentioning the agent's account starts a session immediately.
The agent page
Five tabs: Sessions, Triggers, Memory, Collaborators, Settings.
Sessions lists sessions newest first, nesting child sessions under their parents behind a lazy disclosure with a rolled-up status dot, and creates new ones.
Triggers lists and edits triggers. The triggers page describes the forms and the firing history.
Memory browses and edits ~/memory: entries with sizes, a monospace editor with Save and Revert for text files, inline image, audio, and video previews, download, upload (including drag and drop onto the list or a folder), download from a URL, new file with nested paths, and Publish to IPFS with a copyable ipfs:// address. Files over 32 MB skip the preview. The tab refreshes live from agent-memory-changed events, so a sandbox run writing files updates it as it happens, and a ~/memory/… link in a tool row deep-links to the file.
The system prompt is a page inside Settings (/:settings/prompt, with a back button to Settings, the way a session sits under Sessions and a trigger under Triggers): it edits the prompt in the block editor, autosaving and converting to markdown before the signed UpdateAgent.
Permissions, Authorship identities and MCP servers are three more pages inside Settings (below), each reached from a row on the Settings tab that summarises it (the enabled grants, the granted identities, the number of servers).
Collaborators mirrors the document collaborators page (see permissions): an invite row with a reader or writer role, the member list with pending invitations, role changes, and revocation, plus the owner-only public read and public chat switches that let any signed account view, or view and message, the agent by id. Readers see the agent read-only. Writers can edit and chat but cannot manage access or delete the agent.
Settings edits the model, reasoning level, and thoroughness, and opens the four pages above.
Settings: Permissions
Five toggle rows configure the grant set. The verbs and authored tools are not grants:
toggle | grant |
|---|---|
Search Seed content |
|
Search the web |
|
Execute code |
|
Use the integrated browser |
|
Publish Seed content |
|
Toggles autosave. Stored definitions are normalized on read (execute_code becomes execute, the old write-group names become publish, names absorbed into verbs are dropped), so the page shows what the server acts on. Availability comes from the server's health response: web_search greys out when no search backend is configured, execute when the server reports codeExec: false, with targeted help when the cause is fixable locally. Each row's info button opens the exact model-facing description and schemas from the shared registry. The query and attributes callables have no toggle. See the roadmap.
With Publish enabled the row says which identities the agent authors as and links to the identities page. Custom tools continue the list: one row per authored lambda tool document with its runtime badge and summary, an editor for every document field (name, summary, description, runtime, source, input and output schemas), atomic renames, and a destructive delete.
Settings: Authorship identities
The signing identities the agent may sign and publish as, one row each with its profile icon and name, plus Grant (an existing server identity) and New Account (generates a key, publishes its profile, and creates a home document saying it is an agentic account). A notice links back to Permissions while publishing is off, since the identities are not used until then. Identity management is owner-only, enforced by the server as well as hidden in the UI: writers see the list and nothing else.
Settings: MCP servers
One row per account server with a checkbox that enables it for this agent, a tool-count or Unreachable chip, an Auth chip, and refresh and remove buttons. Clicking a row lists its tools and clicking a tool opens its contract. Add server takes a URL (the name suggests itself from the host), an optional Authorization value stored as an encrypted secret, and transport and header name under Advanced; Connect saves and discovers in one request. See MCP servers.
The session page
The header carries back-navigation to the agent, an inline editable title (debounced signed UpdateSession; an agent-generated title never overwrites one you typed), a system-prompt button showing exactly what would be sent if the session continued now, the model and thoroughness badges, and a menu with Copy session URL and Delete. A triggered session gets a trigger-context popover and a link to the originating activity.
The log
Durable events from the Log become rows, and finished run cards are interleaved into the same chronological scroll. A #event=<id> hash scrolls to that message. Every row knows its actor, and the actor is checked before the role. User messages are blue bubbles with the sender's live account icon. System messages are quiet grey rows behind a left rule, so continuation prompts and unmet-obligation notices read as runtime notes about the conversation. Agent messages render as assistant parts. A tool row run by a person carries a You chip. Every row can explain itself. A message's info dialog shows the exact markdown the model sees, a share URL, ids, and any hidden window context. A tool row's dialog shows raw input and output. Both end in a Details grid with the sender's account and signer, or the model, provider, duration, and token breakdown.
Tool rows get a purpose-built view per tool: delegate shows the brief and the child's work, execute shows its one-line description, the code, and a live output tail, read and write show the resolved target, a Hypermedia write gets its own phrasing, and a call row borrows the called tool's icon and label. A trigger-created session hides the raw <trigger_context> text and renders a context card instead. Other behaviours: optimistic user messages, concurrent sends while the agent is busy (queued and serialized server-side), live streaming partials, a scroll-to-latest pill, in-app hm:// links, Stop with recovery for sessions stuck in streaming, and Retry only on a trailing error.
The composer and the wrench palette
The composer is the Seed block editor. Dropped files upload as session-private attachments and are referenced by id. They are never written to memory or IPFS unless the agent does that itself. When a child session is being driven by its parent, the composer is replaced by a line saying so. Beside the send button is the wrench, the person's side of the symmetric log: it lists Read, Write, and every callable the agent is granted and the server can run, with a form generated from each tool's input schema. Running one sends InvokeSessionTool, and the call and result land on the log as user events the agent reads next turn. A contract miss keeps the form open and points at the contract row now in the thread. The wrench is disabled while the agent is busy.
The run card
A pinned card sits between the log and the composer while a run is still changing: the run title, a status pill, an elapsed timer, rolled-up token usage, cancel (cascading to the subtree), a context meter for the session, the plan steps with their status icons, children integrated with their steps (one child on a step makes the step that child's row; a batch renders every child as a uniform peer), collapsible tool calls, and two drawers: Code for a script's source and Activity, a terminal-style tail of the whole tree's journal. Once the run reaches a terminal status, a typed result is delivered, or the plan settles, the same card freezes into the transcript and the pinned slot clears. A waiting run never freezes, because the place to answer it is above the composer: children show "Waiting on N sub-sessions", a timer shows a countdown, an event wait renders the run's answerWith signal as an Answer button (with an optional payload editor), and a budget pause renders Resume. Everything on the card reconstructs from ListRuns and the signed runs/<rootRunId> subscription, so a reload loses nothing.
Continuation
When an agent calls continue_session, the successor opens with a handoff card and a link back to the predecessor. The predecessor shows where the conversation went. The session continuation page has the model.
Live data
Every list refreshes through React Query polling and WebSocket invalidations. There are no reload buttons. A signed Subscribe per open surface streams durable appends, live partials, session and agent changes, and run trees, reconnecting with backoff. While a remote session is open, every hm:// document or comment the agent creates or links is also subscribed on the local node's sync service. A link the agent just produced then opens without waiting for a background sync. Background sessions do not start content sync.
Where the code is
frontend/packages/ui/src/agents/: everything above. detail.tsx, session.tsx, run.tsx (the run page: one run's status, work, tool calls, code, and activity), header.tsx are the pages; assistant-panel.tsx with assistant-selection.ts, assistant-session-ref.ts, and assistant-window-context.ts is the panel; dialogs.tsx, mcp-servers.tsx, memory.tsx, trigger-types.tsx, user-tool-palette.tsx, run-card.tsx, run-work.tsx, run-parked-actions.tsx, continuation.tsx, session-children.tsx, sessions-feed.tsx, new-session-composer.tsx, prompt-editor.tsx, and message-rendering.tsx are the pieces named on this page; models.ts holds every React Query hook and the signed subscriptions; client.ts signs and sends actions and builds server, WebSocket, and webhook URLs; agent-tools.ts holds the grant names and defaults; agent-session-rows.ts turns events into rows; ../site-agents.ts (outside the agents chunk) finds a space's agents through its mount documents; platform.ts is the seam each app implements (signing, navigation, storage).
The desktop's platform implementation, frontend/apps/desktop/src/agents-platform.ts, signs through the daemon.
frontend/apps/web/app/routes/hm.agents.$.tsx mounts the pages (hm.agents._index.tsx redirects the old index to the site home); web-assistant-host.tsx mounts the panel; web-agents-platform.ts signs with the browser's device key and the capability the vault issued at sign-in.
frontend/packages/shared/src/routes.ts defines the agent (with tab, triggerId, memoryPath), agent-session, and agent-run routes. frontend/packages/shared/src/utils/agents-routing.ts maps them to the web URLs /hm/agents/agent/<id>?server=&tab=&trigger=&file=, /hm/agents/session/<id>?server=&agent=, and /hm/agents/run/<id>?server=&agent=, and back, so a copied web link opens in the desktop app.
agents/protocol/src/tool-registry.ts is the shared registry that drives tool-row rendering and the wrench palette's forms, the same source as the model-facing descriptions.
frontend/packages/agents-ui/ packages these screens for apps outside the repository: one provider implements the platform seam from a host's server URL and signer, and the build bundles the shared code. See Embedding the agents UI.
Manual smoke test
Start a server and the app; open Agents and confirm the server is online.
Save a provider and create an agent; confirm Settings > Permissions shows five grants and "No custom tools yet".
Send a message; confirm it appears immediately and the reply streams as markdown.
Ask the agent to read a Seed URL, including a custom-domain web URL; confirm the row shows the resolved target.
Ask for a task with three or more steps and two delegations; confirm the pinned card shows the checklist with both children as peers and freezes into the transcript when the run ends.
Ask the agent to write itself a tool and call it; confirm the row appears under Custom tools.
Run a read from the wrench; confirm the You chip and that the agent refers to it next turn.
Reload; confirm the transcript, run cards, and card state reconstruct.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime