Embedding the agents UI
This guide shows how another web app displays Seed Agents with the same interface the Seed apps use, through the @seed-hypermedia/apps-ui React package and a signer the app controls.

@seed-hypermedia/apps-ui is a React package that puts the Seed Agents interface inside your own web app. It is the same code that the Seed desktop app and the Seed web app show. When you update the package, your app gets each new agents feature without building the interface again.

The interface covers:

    the list of agents;

    each agent with its sessions, triggers, memory, tools, MCP servers, system prompt, collaborators and settings;

    each session with its tool calls, plans, sub-sessions and runs.

The package includes Seed's components, its editor for blocks and the types of the agents protocol. Your app brings only React 18 or 19. The package is browser code. If your app renders pages on the server, load the package only in the browser.

What your app provides

Every request to an app environment, the server that runs the agents, is a signed action. So your app passes two things, in an object called SeedAgentsHost:

    serverUrl, the address of the app environment as the browser reaches it. The table under this list shows which paths the interface calls. Any path before them is kept, so the URL can be your app's own reverse proxy in front of a server you do not expose.

    signer, an object with the account id and a sign(bytes) function. The function returns the Ed25519 signature over exactly those bytes. The key does not have to be in the page: the function may ask a server your app trusts to sign. When the signing key is not the account's own key, the signer also names its key and the capability the account gave it.

serverUrl

Actions

Subscriptions

Health

ends in /hm/api/apps or /hm/api/agents

<serverUrl>/message

<serverUrl>/ws

<serverUrl>/health

any other URL

<serverUrl>/api/message

<serverUrl>/agents/ws

<serverUrl>/agents/api/health

An app environment answers both forms. The second row is the older set of paths.

Three optional members do more. hmApiUrl reads names and avatars from a Seed API other than https://hyper.media. The others choose where settings are saved and replace the editor.

import {SeedAgentsProvider, SeedAgentsView} from '@seed-hypermedia/apps-ui' import '@seed-hypermedia/apps-ui/styles.css' <SeedAgentsProvider host={{serverUrl: 'https://app.example/agents-proxy', signer}}> <SeedAgentsView /> </SeedAgentsProvider>

Routes and links

A SeedAgentsRoute is one place in the interface: an agent and one of its tabs, a session, or a run. The routes are the same ones the Seed apps use.

seedAgentsRouteToPath writes a route as text. The text is the part of a web URL after /hm/agents/, for example session/<id>?agent=<id>. Your app keeps that text in its own URL and passes the route back in. So one link opens the same place in your app, in the Seed web app and in the desktop app.

Calling the service from code

createSeedAgentsClient({serverUrl, signer}) sends any agents action with the same signer, without the interface. Its types come from the protocol. So send({_: 'GetSession', sessionId}) returns the GetSessionResponse shape, and an action that does not exist does not compile.

Styles

The stylesheet holds the styles of the included components, Seed's colors and its text styles.

    It has no reset, and it styles nothing outside the agents interface.

    Dark mode follows a .dark class on a parent element. Put it on <html> so that dialogs and menus follow it too.

    The colors are CSS variables such as --background, --foreground, --primary and --border. Set them again in your own CSS to change the look.

An example: a dashboard that keeps the key on its server

Take a dashboard whose backend holds the account key.

    The backend signs agents actions for the page, and nothing else.

    The backend serves the app environment and the Seed API through proxies on the dashboard's own origin. An HttpOnly cookie opens them.

    The page passes those proxy URLs as serverUrl and hmApiUrl.

    The page passes a signer whose sign function calls the backend.

The key never reaches the browser, and nobody reaches the app environment directly.

The package's README describes the options. Its source is in frontend/packages/apps-ui.

See also

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

Unsubscribe anytime