Agents

An agent is the worker a loop runs: its base instructions, the tools it knows how to use, and its model. The loop is the job. What a run may actually do comes from the agent’s role and the loop’s own limits, never from the agent, so changing an agent can never widen what it may touch.

The Agents page

Agents lists every agent in one list, each marked Yours or Platform; the chips above the list show one kind at a time:

Yours — the agents this account added. Any loop in the account can name one.
Platform — the ones every account has. You cannot change them here.

Open an agent to see what it is for, its model, the role a run starts as, and the tools it knows how to use. Change and Delete are at the top of your own agent; New agent is at the top of the list.

The platform’s agents

Every account has these. The page shows each by its name; a loop names it by its id.

Name	Id	What it does
General	`general`	Talks with a person and does what its loop grants: keeps records, asks on cards, calls the loop’s own tools. The agent for a chat.
Researcher	`researcher`	Reads the open web and files what it finds into a collection.
Analyst	`analyst`	Works over your workspace and collections. No network.
Summarizer	`summarizer`	Reads files and records and gives back a summary. Writes nothing.
Sender	`sender`	Sends what another agent of the loop worked out to an outside system. Reads nothing.
Automation builder	`automation_builder`	Proposes the automations that keep finding what a task found.
Loop builder	`loop_builder`	The agent behind LoopAssistant.
Agent builder	`agent_builder`	The agent behind AgentAssistant.

Add an agent

There are two ways: describe it to AgentAssistant, or fill in the form yourself.

With AgentAssistant

Press Ask AgentAssistant on the Agents page, or ask the console’s Assistant for an agent. A chat opens on AgentAssistant, a loop plutonium.io owns. Say what the agent is for in your own words. It asks for anything it still needs, such as the role it starts in or the tools it uses, and then shows the agent on a card. Approving the card installs the agent and runs nothing: an agent works only when a published loop names it. When you want a loop that uses it, ask LoopAssistant.

With the form

Press New agent and fill in the form:

Field	What it is
Name	How a loop names the agent, such as `support_triage`. It cannot change later, and it cannot be a platform agent’s name.
What it is for	One sentence for people.
Its base instructions	What every run of this agent is told, before the loop’s own instruction.
Model	A model from the catalog, or the deployment’s default.
A run starts as	The agent’s role, chosen from the platform’s roles and your account’s own.
Tools it knows how to use	Chosen from the tools your account has.

Each field says what it is for, and a field you change says what is wrong with it as you type. Press Add agent. The form checks the agent first and names any field it refuses, and then the page opens the new agent at its own address. To edit an agent later, press its Change button, then Save changes.

Roles

A role is a set of permissions. The platform defines the roles below, and an owner of your account can define more (your own roles). Each agent starts with one.

Role	What a run in it may do
`general`	Reads and writes records and tells the person what happened. Reads no web until a person names a site on a card. Sends nothing outside the platform.
`reader`	Reads the workspace, its collections and its search indexes. Writes nothing anywhere.
`librarian`	Reads and writes the workspace and its collections, and searches its indexes. Reaches nothing outside them.
`web_reader`	Reads the open web, the account’s search indexes and a service you connect. Writes records. Changes nothing else.
`outbound_writer`	Sends what another agent worked out to a system outside the platform. Reads nothing.
`builder`	Reads what a task already found, reads the web a site at a time, and proposes software that keeps finding it.
`loop_builder`	Interviews an admin and proposes a loop as a draft. Publishes nothing.
`noop`	Grants almost nothing.

An agent’s role is its outer bound, in every run: on the console it holds what its role allows, and in a loop’s run what its role allows and the loop’s capabilities list, never more. Four permissions are the loop’s own and need no role — spawn_tasks, client_navigate, client_act and call_endpoint (Permissions and trust says how each layer decides). An agent that needs a permission its role does not allow needs a different role, not a wider loop.

Your own roles

An owner of the account can define a role: a name, the words a person reads before trusting it, and its permissions, chosen from the list in Permissions and trust.

Roles, beside Agents, lists every role, each marked Yours or Platform. Open one to read its words, each permission in plain words with its id, and the agents that start with it. An owner presses New role to define one; the form offers only the permissions a role of your own may hold. Each field says what it is for, and a field you change says what is wrong with it as you type; the save checks the whole role again and tells you at each field what to fix. Change and Delete are at the top of your own role. A member reads the roles and changes none. The same rules hold for the roles API (PUT /api/roles/{roleId}; GET /api/roles lists every role and which agents start with it).

A role is refused, in words that name the fix, when it:

uses the id of a platform role,
lists a tool, such as web_fetch, where a permission belongs — the refusal names the permission the tool needs,
lists an install_ permission — only the platform’s own builders hold those,
lists one of the three permissions below. Their tools must be bounded (which sites, which folder, which level), and a role of your own carries no bounds, so an agent that needs one starts with a platform role that bounds it:

Permission a role of your own cannot hold	Start the agent with
`read_web` (reading the open web)	`web_reader`
`write_workspace` (writing files)	`librarian`, or `web_reader` for its `docs/` folder only
`rehearse_claim` (trying an automation on the live site)	`builder`, or `web_reader`

A role never widens what a loop may do: a run still holds the role and the loop’s capabilities, never more than both. Publishing pins the role with the agent, so editing the role later changes nothing for a published version until you publish again. A role that an agent starts with cannot be deleted; give that agent another role first. Delete shows what uses the role before anything is removed: each agent that starts with it, which stops the delete, and each published loop version that pinned it, which keeps running its pinned copy.

Reading and sending are two agents

An agent that reads your records must not also send to an outside system. When a loop does both, it uses two agents: one reads and writes records, and the other sends and reads no collection. Publish refuses one agent that holds both. Permissions and trust says why: the Rule of Two.

Use an agent in a loop

Name the agent in the loop’s record:

agents: [support_triage]

With more than one agent, entry_agent names the one a person meets first.

The draft uses the agent’s current version at once, so you can try it on the Chat bench. A draft that names an agent your account does not have still saves; publish refuses it and names the agents you can use.

Publishing pins an agent your account added. The published version keeps that agent’s instructions, tools, model and role as they were at that moment. Editing the agent later changes nothing for that version; the next version you publish picks up the edit.