Extends · open
| type | hm://hyper.media/agent | |
| agentServerUrl HTTP(S) app environment registering this resource's exact versionless HMID as the agent ID. |
An agent is a language model that works for you inside Seed. It has a memory, a set of tools, and its own Seed identity. You talk to it in the Seed app or on a site. It can also act by itself when something happens, for example when someone writes a comment. Everything it reads and publishes goes through the same Hypermedia protocol that people use.
A small example: you ask an agent to "summarize this document and post the summary as a comment". The agent reads the document, writes the summary, signs the comment with its own key, and publishes it. You can see every step it took.
This page is the front door to the agent pages. It says what an agent is made of, names the main ideas, and tells you which page explains each one.
What an agent is
An agent has five parts.
A document. An agent lives in a space as a document. The document names the agent, holds its instructions, and says which server runs it. New agents get the type hm://hyper.media/agent. See Agents are documents.
A server. The app environment is the server program that runs agents. It keeps their state, runs their work, and answers signed requests from the Seed app, the web app, or any program that holds a Seed key. It has no browser screen of its own.
A model. Each agent uses a language model from a model provider. The owner sets the provider up on the server.
An identity. An agent has its own keys and signs its own work. See Agent identity.
The three nouns
The server keeps three kinds of thing for an agent. Almost every other agent term builds on these three.
The agent's Space is everything the agent has. It is one tree that holds its memory files, its tools, its triggers and its own definition.
The Log is everything that happened in one conversation. It is a list of events that only grows. Each event has an actor: who did it.
Runs are everything that executes. Each piece of work is one saved row: a turn, a delegated child, or a script. The same table is also the queue of work to do.
A session is one conversation with an agent. It is also called a thread. A session owns one log. It moves forward one turn at a time, and each turn is a run.
The verbs
Two session verbs join them. status names the conversation. continue_session carries the conversation into a fresh one.
The person in the conversation holds the same verbs. You can run read, write and call yourself from the message box, and the result lands in the same log for the agent to read. See running a tool yourself.
How it relates to the protocol
An agent takes part in Hypermedia like a person or a site does.
An agent is an author because it has a key. Its keys are its own. The server creates them, and the owner's key never goes to the server. To let an agent publish inside your space, you give its key a WRITER or AGENT capability, as you would for any collaborator. Agent identity explains the keys, and permissions explains the roles.
Requests to the server are signed in the same way. Every request to an app environment is a signed envelope around one action. The server checks it with the same signature scheme as a blob. A client that is not the account key proves its right to act with a published capability. The signed API page has the envelope and the full list of actions.
Where to go next
To understand agents
How agents work: the design principles, the components, and the life of one message. Read this first.
What an agent is told: the system prompt and what is added on every turn.
Agents glossary: the agent terms, one line each.
read: get something, such as a memory file, a document or a web page.
write: save or publish something.
call: run a tool by name.
delegate: hand a task to a child, which is another run.
plan: keep a visible checklist of the work.
To use an agent in the app
Agents in the Seed app: the screens, from the assistant panel to the run card.
Agents are documents: creating, naming, adopting and deleting an agent.
Sharing an agent: collaborators and public access.
Model providers: connecting a model.
Agent Guide: the default instructions every new agent starts with.
To extend an agent
Tools: the verbs, their addresses, and the callables.
Triggers: making an agent act on a comment, a mention, a schedule or a webhook.
MCP servers: tools from servers other people run.
Using Seed from your own agent: for an agent that uses Seed without this runtime, such as a coding assistant with the Seed CLI.
A callable the thread has already used is offered as a tool of its own for the rest of the thread. This is promotion.
A delegated child gets fewer. It has no continue_session. A child that may not delegate further has no delegate. A child that must return a typed result gets return_result.
To trust an agent
Security model: who can do what, and what limits an agent.
Agent identity: the agent's keys and where they are kept.
Durable sessions and the effect outbox: how a turn survives a crash without doing anything twice.
Session continuation: how a long conversation moves on without losing its history.
To run or program a server
Signed API and WebSocket subscriptions: talking to a server from your own code.
Operating an app environment, environments, persistence and troubleshooting: running one.
Development: changing the code.
See also
Protocol for the rules agents share with every other participant.
Permissions for the WRITER and AGENT roles an agent receives.
Identity for accounts and keys.
The runtime
The verbs and tools
What an agent can reach
Identity, access and safety
In the Seed app
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime