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.

Each row says what the agent does. Open an agent to see what it is for, its model by name, what it may do (its role, in words, with the role’s name after it), 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 two job-board sites, weworkremotely.com and remoteok.com, and files what it finds into a collection. Through a Google connection, it also lists your newest Gmail messages and one day’s calendar events.
Analyst	`analyst`	Works over your workspace and collections. No network.
Summarizer	`summarizer`	Reads files and records and gives back a summary. Writes nothing anywhere.
Schedule builder	`automation_builder`	Looks at what a run found — or fetches it — and proposes the schedules that keep finding it.
Loop builder	`loop_builder`	Interviews an admin about the loop they want and proposes it as a draft they publish. The agent behind LoopAssistant.

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, and a chat opens on AgentAssistant, a loop plutonium.io owns. Or ask the console’s Assistant for an agent: it first shows a card, “Send this brief to AgentAssistant? … Nothing happens until you answer.”, with Send this brief, Not now and Reply. After Send this brief, AgentAssistant opens in a new tab of the Assistant’s panel, with your request sent as the first message. 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. The card lists what its role allows. A loop that runs it can narrow this to what the loop declares, such as the one collection it reads. Approving the card installs the agent and runs nothing: an agent works only when a published loop names it. The chat then says, in the platform’s words, that the agent is installed and may do what its card lists. 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	The default (recommended), or a model by its name and price, as the chat’s model list shows it.
What it may do	The agent’s role, each offered by what it does, such as Reads the account’s records and nothing else. (reader), from the platform’s roles and your account’s own.
Tools it knows how to use	Chosen from the tools your account has, each by what it does with its name after it, such as Ask the person a question (ask_user).

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. Reads a connected service only through a tool an admin approved. 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 two job-board sites (weworkremotely.com and remoteok.com), 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.
`service_writer`	Changes things outside through a tool an admin approved, for another agent of its loop. Reads nothing.
`builder`	Reads what a task already found, reads the web a host at a time, and proposes software that keeps finding it.
`connection_builder`	Reads a service’s API docs a host at a time and proposes the tools that read it. It holds no key and installs nothing until the admin approves each tool’s card.
`loop_builder`	Interviews an admin and proposes a loop for them. It publishes nothing; that is the admin’s separate act.
`noop`	Grants almost nothing. What a task runs as when nobody has said otherwise.

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 in My conversations. A draft that names an agent your account does not have still saves; publish refuses it and names the agents you can use. A role’s name in agents, such as librarian, is refused when you save, and the refusal names the agent that plays that role.

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.