--- title: "One agent" slug: admin/agents-detail url: https://projectri.com/docs/admin/agents-detail section: admin audience: admin app_route: "/[slug]/admin/agents/[id]" permissions: [agent.view, agent.manage, agent.disable] plan: agents.runs mobile: "/admin/agents/[id]" updated: 2026-09-08 source: Projectri documentation --- # One agent 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. ![One agent](https://projectri.com/docs-shots/admin-agents-detail.png) ## What it is One agent's own page. The order of the page is the argument it makes — configuration at the top, a test run in the middle, activation at the bottom behind the test. An agent activated without ever having been run is one whose first execution is against the live workspace, unattended, on a schedule somebody set six weeks earlier. ## How to get there Open any card on [Agents](/docs/admin/agents) and press **Open**, or land here from a notification about one of its runs. Reading the page needs `agent.view`; saving, arming a trigger, rehearsing and activating need `agent.manage`; stopping needs `agent.disable`. ## How to use it ### Understand why it is not acting A banner at the top names the state when the agent is not active: - **Draft** — it holds none of the permissions listed below and cannot do anything until it is activated. - **Paused** — its configuration is intact and it holds nothing. - **Stopped** — somebody stopped it, and the reason they typed is shown. A second banner appears when the owner does not hold everything the agent was granted, listing the withheld keys. ### Rehearse it 1. Press **Run a test** on the **Test run** card. 2. It reads the real workspace and calls a real model. It costs the same tokens a real run costs and is metered the same way. 3. Nothing that would change anything is carried out. The approval gate still runs, the preview is still built, and the sentence you would have been asked to approve goes into the transcript in place of the write. 4. A draft can be rehearsed. Its permissions are resolved as they *would* be once activated, which is safe precisely because nothing mutating can execute. 5. Everything the gate would refuse is still refused — out of scope, not granted, owner demoted. A rehearsal is a test, not a demonstration. 6. The page waits about three minutes for the scheduler to pick the run up. If it is still queued it says so; the run will appear in the list below when it finishes. ### Read a run 1. The **Runs** card lists the last fifteen with their status, a one-line summary, and the actions and tokens each spent. 2. A rehearsal carries a **TEST** badge before the status, because the badge changes what the status means. 3. Click a row for the transcript. Each step is labelled — a tool call, a refusal with its reason, a summary, and a rehearsed action as **would have** rather than as a tool call with a badge on it. 4. Refusals are in the transcript on purpose. An agent that did nothing and an agent that tried and was denied look identical from outside otherwise. ### See what it asked people for The **Approvals asked for** card sits directly above the runs, and lists what this agent proposed and what people answered — approved, refused with the reason they typed, or **expired unanswered**. An expiry is shown as its own outcome and carries no name, because it is a decision nobody made. ### Configure it The builder on this page is the same one the create dialog uses — name, mark, purpose, instructions, accountable owner, permissions, tools, scope and the two per-run budgets. Press **Save**. Both budgets bind the run already in flight, so a cap lowered in a hurry takes effect on the run you lowered it for. ### Arm what starts it 1. The **triggers** card sits between the configuration and the activation, because a trigger is what makes the configuration above unattended. 2. **Schedule** — a cadence (every day, every working day, weekly, every other week, monthly, quarterly), a time, and a timezone. Cadences rather than cron: the working week here is data, and "09:00 daily" is a different instant either side of a daylight-saving boundary. 3. **Event** — a key from the automation vocabulary, offered already filtered to the ones an agent may use. 4. **Mention** — the agent starts when it is named in a task comment. Without this trigger a mention of the agent is still recorded and renders correctly, and nothing starts. Being named is not consent to run. 5. Arming a trigger needs the agent feature switched on and the plan entitlement. Switching one off and deleting one need neither, so a workspace whose rollout was reversed is never left holding a schedule it cannot reach. ### Activate, pause or stop it 1. **Activate** asks first, and says how many permissions it will hold intersected with its owner's. If it has never completed a test run, the dialog says so in amber. 2. **Pause it** keeps the configuration and stops it acting. 3. **Stop it** is the kill switch, needs a reason, and cancels any run waiting on an approval. 4. **Clear the stop** returns it to paused, never straight to active. ## What it affects - **Runs are queued, not run inline.** A trigger writes a queued run and returns; the executor picks it up on its next pass, eight runs at a time, one after another. - **Cancelling a run stops the next step**, not the current one. The executor may be inside a model call, so the worst case is one more read before it stops. A run still queued is cancelled outright. - **A run that hits its budget ends as over budget**, with the overshoot recorded as a refusal and a summary saying it stopped early — "it ran out" and "it had nothing to do" are otherwise the same picture. - **A schedule is skipped, not disarmed, while the agent is not active.** The trigger stays armed and its next time still advances, so a fortnight's pause leaves the schedule intact and produces no cancelled runs. - **Every model call is metered** against this workspace's AI budget and its credit balance, attributed to this agent and this run. - **An agent whose owner's AI seat is switched off cannot call a model at all.** ## On mobile `Admin → Agents → ` shows what it holds and what it has been doing, with the run list as the body — somebody who tapped "your agent finished" wants the run, not the system prompt. Rehearsals are marked there too. The trigger editor is on the phone as well, above the run list, arming the same three kinds; its default timezone is the phone's own rather than UTC. Configuring the agent is web only. ## Limits and gotchas - A rehearsal costs real tokens and is gated exactly as a real run is. A stopped agent cannot be rehearsed — a kill switch with a "but you can still test it" exception is not one. - An approval requirement must name a permission the agent actually holds. Narrowing the grants re-validates the approval list even if you never touched it. - Some permissions always require a person and cannot be un-ticked. See [Approvals](/docs/admin/agents-approvals) for what is on that floor. - Per-run cost is not printed on the run row. It is derivable from the AI ledger, and a second figure that can disagree with the first was not worth storing. - There is no way to interrupt an action already in progress. ## Related - [Agents](/docs/admin/agents) — the directory, and the three permission keys. - [Approvals](/docs/admin/agents-approvals) — the inbox its proposals land in. - [AI](/docs/admin/ai) — the meter every run spends against. - [Automation](/docs/admin/automation) — the event vocabulary an event trigger draws on. ## Related - [Agents](https://projectri.com/docs/admin/agents.md): The directory of unattended actors in this workspace — what each one may do, who is accountable for it, and the button that stops it. - [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. - [Automation](https://projectri.com/docs/admin/automation.md): Rules that react to what happens in this workspace — a trigger, optional conditions, and an ordered flow of actions, waits and branches.