--- title: "Agents" slug: admin/agents url: https://projectri.com/docs/admin/agents section: admin audience: admin app_route: "/[slug]/admin/agents" permissions: [agent.view, agent.manage, agent.disable] plan: agents.runs mobile: "/admin/agents" updated: 2026-09-08 source: Projectri documentation --- # Agents The directory of unattended actors in this workspace — what each one may do, who is accountable for it, and the button that stops it. ![Agents](https://projectri.com/docs-shots/admin-agents.png) ## What it is An agent is a non-human principal in the workspace. It holds permissions of its own, it takes actions, and it appears in the audit log beside the people — it is not a user account with a robot picture. This screen lists every one this workspace has, what each holds, who is answerable for it, and how to stop it. ## How to get there **Work → Agents** in the admin console rail, at `//admin/agents`. The console itself is ADMIN-only. Three permission keys govern agents, and they are deliberately separate: - `agent.view` — the directory, each agent's grants, scope, owner, instructions and activity. - `agent.manage` — creating an agent, reconfiguring it, deleting it, and clearing a stop. - `agent.disable` — the stop button, and nothing else. `agent.disable` is the cheapest of the three on purpose. Somebody watching an agent misbehave at two in the morning has to be able to stop it without holding the rights to have built it. Clearing a stop needs `agent.manage`, so the kill switch is not a toggle anyone who can press it can also un-press. `agent.view` is excluded from the blanket VIEWER grant. It hands over the workspace's own system prompts and an unfiltered audit feed across every object in the workspace. Creating an agent needs the `agents.runs` plan entitlement and the agent feature switched on for this workspace. Neither gate touches the list, the detail page or the stop button — a workspace that stops paying, or whose rollout is reversed, must still be able to see and stop the agents it already has. ## How to use it ### Read the directory 1. Each card carries the agent's name, its own icon, a status pill and the facts underneath. 2. **Accountable** is the human owner. If they are no longer active in the workspace the card says so in red. 3. **Permissions** reads "*n* of *m* in effect". Granted, effective and withheld are three different numbers — an agent granted twelve keys whose owner was demoted holds nine, and the card names how many are withheld and why. 4. **Can see** is the scope. An agent with no scope set reads *the whole workspace*, in those words, because a blank field would read as "restricted". 5. **Recent actions** counts the agent's audited actions over the last seven days. 6. An agent holding a commercially sensitive permission carries a red note naming the keys, because anything it writes into a summary can carry them. ### Create one 1. Press **New agent**. The button is disabled with an explanation when the agent layer is not switched on for this workspace. 2. Pick a starter, or **Start from nothing**. Five starters ship — a standup summariser, an overdue chaser, a risk spotter, a client brief and a triage helper. Each states in plain words why its permissions are the size they are. A starter that writes is marked **Can change things**; the others are **Read only**. 3. Fill in the name, its mark, what it is for, and the instructions. Instructions are written as instructions to a colleague, not as a prompt. 4. Choose an **accountable owner**. An agent can never do more than its owner can, and the intersection is recomputed on every check. 5. Tick the permissions it needs. Each is explained rather than listed, and the form shows only the ones its tools can use until you press **Show all**. 6. Tick the tools it may use. Leaving every tool box clear gives it everything its permissions allow. A tool the grant cannot run is marked amber before the save, not refused in a transcript at 3am. 7. Set the scope — projects and clients. Leaving it empty is a real choice and means the whole workspace. 8. Set the budget — actions per run and tokens per run. Both are checked before every step, not after. 9. **Create as draft.** Nothing this form produces is live. A draft holds nothing and cannot act; activating it is a separate act on its own screen. ### Stop one 1. Press **Stop** on the card. It appears on any agent that is not already stopped, whatever the feature flag says. 2. Type why. The reason is required and is kept — an agent found stopped six weeks later with no note is one somebody turns back on. 3. It stops immediately and holds nothing until somebody clears the stop. Any run waiting on an approval is cancelled with it. ## What it affects - **The agent's authority is its owner's, intersected.** Demote the owner and the agent loses every key the new role lacks, at once. Suspend them and it holds nothing. Remove them from the workspace and it holds nothing **and** is paused. Restore them and the grants come back — the grant is never destroyed, only withheld. - **A new permission key reaches no existing agent.** Agent grants do not accept wildcards, so a key added by a later release has to be granted by name by a human. - **The audit log.** Every agent action writes an audit row with the actor kind recorded as an agent, the agent named, and the accountable human recorded alongside. Audit streaming carries the same distinction outward. - **Task assignment.** An agent can hold a task in its own slot, exclusive with the human assignee, so no workload or capacity count doubles. Stopping an agent does **not** reassign its queue; the tasks stay put, visibly held, and the owner is notified with the count. Deleting an agent is refused while it holds open work. - **Timelines and comments.** Where an agent acted, the agent's name is in bold and its owner is the byline. Its avatar is a rounded square, never a circle, so it cannot be mistaken for a person. - **AI spend.** Every model call an agent makes is metered against this workspace and attributed to the agent and its run. See [AI](/docs/admin/ai). ## On mobile The Expo app has the directory at **Admin → Agents**, with the same three permission numbers on each card and the stop button. It reads and stops; it does not build. The builder is a long form with a permission matrix and a rehearsal step, and deciding what an unattended actor may do is desk work. ## Limits and gotchas > [!WARNING] > Scope is enforced on reads as well as writes. An agent scoped to one project > that could nonetheless read the whole workspace would summarise the whole > workspace into whatever it posts to. A target carrying no id on a scoped > dimension counts as **outside** the scope. - Clearing a stop returns the agent to **paused**, never straight to active. Whoever stopped it did so for a reason, and the person clearing the stop is not necessarily the person who should decide it may run again. - A notification link of the older shape — `?approval=…` on this page — is bounced to [Approvals](/docs/admin/agents-approvals) rather than rewritten in people's inboxes. - The agent screens on the web are still in English. The phone screens are translated. - There is no agent in the assignee picker yet. A task is handed to an agent through the API today. ## Related - [One agent](/docs/admin/agents-detail) — configure it, rehearse it, activate it. - [Approvals](/docs/admin/agents-approvals) — answering what an agent asks for. - [AI](/docs/admin/ai) — what the models cost, and the ceiling on it. - [Permissions](/docs/admin/permissions) — where the three agent keys are granted. - [Approvals](/docs/features/approvals) — how approval gates work across the product. ## Related - [One agent](https://projectri.com/docs/admin/agents-detail.md): A single agent — its configuration, a rehearsal that changes nothing, what starts it, what it has run, and the button that makes it act unattended. - [Agent approvals](https://projectri.com/docs/admin/agents-approvals.md): What this workspace's agents are asking permission to do, filtered to the requests you could carry out yourself. - [AI usage and models](https://projectri.com/docs/admin/ai.md): What this workspace spends on AI models, the monthly ceiling on it, the credit balance it spends past the plan, and which model each kind of work is sent to. - [Permissions](https://projectri.com/docs/admin/permissions.md): The role-by-permission grid and the per-member override table — what each role may do in this workspace, and how one person differs from their role. - [Approvals](https://projectri.com/docs/features/approvals.md): The two things in Projectri that wait for a person to say yes — an approval chain on a task, and an AI agent asking permission before it changes anything.