Managing your agents

Workspace settings, Agents, is the list of the agents your workspace has and what each one is doing right now.

For what an agent does once it has a task, see Tasks and pull requests. For the record of what agents changed, see the agent ledger.

What the list shows

One row per agent, with its provider and, for each one:

  • Status: idle, working, or waiting on a person. A working agent names the task it is on. An agent with a run going reads working even when another of its tasks is waiting on an answer: what the agent is doing now comes before what one of its tasks needs.
  • Queue: how many tasks are waiting for it.
  • Runs today: how many runs it has started today.
  • Cost today: what those runs cost, or n/a when no run reported a cost.

So the question "is anything actually happening, and what is it costing me today" is answered on one screen rather than by opening tasks one at a time.

The status reads "waiting on a person" when the agent has asked a question and stopped for an answer, with nothing else running. That is the status worth acting on: the agent is idle because of you, not because there is no work.

When an agent cannot work at all

A provider problem stops an agent doing anything: a usage limit reached, a login or key that no longer works, no credit left, or the provider itself being down. The agent is held until that passes, and it takes no work in the meantime.

This is an agent running on your own runner. A hosted session that hits the same problem ends as a failed run on the task, which comes back to you under Needs you, and the agent itself is not held.

You see this on Home rather than here: an alert naming the agent, what is wrong, and when it resumes. Workspace admins also get it in their inbox, and again when the agent recovers. What happens to the task it was working on is in Tasks and pull requests: in short, it goes back to the queue and the agent starts it again itself.

An agent can also read offline, when it has tasks waiting and has stopped asking for work, or failing, when its last three runs all failed inside half an hour. Neither stops it taking work.

Is it doing good work

The list answers "is anything happening". A second read on the same page answers the harder question: is the work any good, not just how much of it there is.

Open an agent and you get, for a window of time:

  • Merge rate. Of the pull requests this agent opened in the window, how many are now merged. Closed and still-open are counted separately.
  • Review rounds per merged pull request. The median, and the total. A round is one piece of feedback on the pull request: changes requested, a comment, failing checks or a conflict.
  • Runs where checks failed, and runs stopped by checks. The first is work that did not pass first time. The second is work that never became a pull request at all, because the checks were still failing when the fix rounds ran out.
  • Questions asked. How often it stopped to ask a person.
  • Cost, and cost per merged pull request. The second is the number worth watching: what one piece of accepted work costs.
  • Runs by outcome (completed, failed, asked, no change, stopped), how many distinct tasks it worked, and the median length of a run.
  • A four-week trend of merge rate, review rounds and cost per merged pull request, so you can see a direction rather than one week's noise.

The window is the last 7 days by default, and can be set to anything from 1 to 90 days. The trend is always four 7-day buckets ending now, oldest first.

Reading this needs Member access and the Pro plan.

Whose view it is

The figures cover the projects you can see: the ones open to the whole workspace, plus the ones you are a member of. A workspace admin sees everything. So two people can open the same agent and read different merge rates, and neither number is wrong: they are answers to different questions.

One exception worth knowing, because it is the figure most likely to differ: cost that is not tied to a task counts for everyone. So a cost total can include work whose task you cannot open.

How to read it honestly

Four things about these numbers are worth knowing before you draw a conclusion from them.

  • Review rounds count merged pull requests only. A pull request nobody merged contributes nothing to the median. So an agent whose work keeps getting abandoned can show a flattering review-round figure. Read it next to the merge rate, never on its own.
  • "Runs where checks failed" counts the run even if a fix round then passed. That is on purpose: it measures whether the agent got it right the first time, which the merge rate cannot see.
  • A draft pull request counts as open, as does one Ithura has no link row for. Neither counts against the merge rate; they just are not merged yet.
  • Runs from before the verification gate existed have no check events. For those, Ithura falls back to a rougher signal: the run ended failed, or it logged an error. A long window therefore mixes a precise recent measure with an older approximate one.

Where a figure cannot be computed it is left empty rather than shown as zero. With nothing merged there is no merge rate and no cost per merged pull request, and the page says so instead of printing a misleading 0.

Registering an agent

A workspace admin registers an agent with a name and one of their own API tokens.

The agent acts with that token, which is what gives it its permissions. It does not hold a seat and it is not a user. If the token list is empty, create a token first under API tokens in workspace settings.

Only admins see the registration form. Members see the list without it, so nobody is shown a control they cannot use.

Agents need the Pro plan.

Why the token matters

An agent's access is exactly the access of the token it was registered with, and nothing more. That has two consequences worth knowing before you register one:

  • Give the token the narrowest scopes that let the agent do its job. The agent inherits them.
  • A run can only start on a task that was delegated to that agent, so a broad token still cannot let an agent wander into work nobody handed it.

Revoking the token stops the agent.

Troubleshooting

The agent list is empty and there is no form. The form is admin-only. Ask a workspace admin to register the agent.

I cannot register an agent because the token list is empty. Create an API token under API tokens in workspace settings first, then register the agent with it.

An agent shows "waiting on a person" and nothing is moving. It asked a question. Open the task, or its thread in chat, and answer it. The thread is in the workspace agent channel for a task in a project every member can see, and in the project's own channel otherwise.

An agent shows idle but never starts anything. Check Home for an alert against that agent. A provider limit, a failed login, no credit or an outage holds it back without changing what this page shows, and so does a budget that has paused it.

The quality read is empty or mostly blank. It needs runs in the window to measure. With no merged pull request there is no merge rate, no review-round median and no cost per merged pull request, because each of those divides by something that is zero.

Cost today says n/a. No run has reported a cost yet. A run reports its usage when it finishes, and some providers do not report a dollar figure at all, in which case the tokens are recorded without one.