See an agent's runs and why they fell short

An agent's page lists what stops the agent from running, each line with a link to the page where you fix it: an agent can look ready and still never run. Only the users who build the base see this list, on the agent's page in Settings, Agents. When nothing stops the agent, the list folds to one line.

• Nothing starts this agent: no automation, no workflow step, no mention and no role that may chat with it. The link opens Automations.
• The sign-in to an MCP server has expired, or it expires soon. The link opens that server's page, where you sign in again (Connect an MCP server).
• The agent's machine is offline, or it needs an update. The link opens the Machines page (See a machine's state and its coding tools).
• The API key does not work, for an agent on the Claude API or the OpenAI API, or for a Claude Code agent on a secret of the base: its secret does not exist, it is saved for another service, the service refuses the key, or the account there has no credit. The link opens Secrets (Run an agent on your own Claude API or OpenAI API key and Run a Claude Code agent on your base's own Anthropic key).
• The AI has reached this base's fair-use limit for this month. It works again on the 1st of the next month (When the AI reaches a fair-use limit). This never stops an agent on the Claude API or the OpenAI API.
• The base keeps its data from AI. The link opens the settings page with that switch (Keep your records away from AI).

The same list is there under a builder's API token (Use your base from a calendar or a script), at GET /api/builder/agents/<id>/blockers. Through Base Captain's MCP server, the tool read_agent_blockers gives the same, and the assistant does too: ask, for example, "Why does Order check not run?"

An agent's run keeps a record of everything it did when the agent works by itself, in Base Captain or on a machine: nobody watches it, so you never have to guess why an order got the wrong priority or why a quote was sent back. The records are only for the users who build the base: other users see none of them. A record holds:

• what the run was told, the agent's instructions and the item it was given;
• each time it asked the AI model: what the model answered and how it reasoned, and how long it took;
• each tool it used, an MCP server's tools too: what it asked for and what it got back, and whether it went through or the error it met;
• the version of the base it ran under, its outcome, the summary it wrote, and when it started and ended.

1. In Activity, Agent runs, narrow the list to the runs you want: by agent, by the version of the base, by workflow and step, by outcome, by state, by why it fell short, and by when it started.
2. Above the list, the totals count every run that matches, not just the page: how many runs and how long they took. Narrow to one agent, one version and one step, and you see how well that step works.
3. Or click the tab By agent version: the same runs, under the same filters, in one row for each agent, version of the base and step, such as Reviewer's runs on Quotes · Review under one version, or An automation for the runs an automation started. Each row shows its Runs, its Pass rate (of the finished runs, the share that went through), and its Mean time. Compare the rows of one step, and you see whether a new version of the agent works better. Click a row to open the list of those runs.
4. Click a run to open its page: the run at the top, then each step it took, in order. Long text is folded; click to read it all.

An item's page lists the runs on that item too, each linked to its own page, so from an order you go straight to what Order check did with it.

A run on a machine shows what its coding tool reported for each turn, and each of the base's tools it used. It also shows each call of the coding tool as a row of its own: a command it ran, a file it read or changed, a page of the browser it opened. Each row has its input, its output and its start and end times, and the rows appear while the run goes, so you can follow it live.

Limits and details:

• A very long input or output is cut, and a line on the row says how much was cut.
• No secret is ever in the record: the values of the base's secrets and of its MCP servers' keys are taken out before it is kept.

An agent's run fell short when what happened to it says so, for one of six reasons, the first that holds: no AI grades it. A run went through when it did its job and nobody had to step in. The reasons are for the users who build the base:

• Failed: it ended in an error.
• Hit a limit: its step's time limit stopped it, or the workflow's limit on how often an item enters a step refused the item's next turn.
• Asked a person: it asked someone instead of choosing an outcome.
• Stopped without finishing: it ended its turn without an outcome or a question.
• Done again: an outcome sent the item back into the same step, so its work was done again.
• Changed by a person: within a day of the run, a person changed a field the agent had set on that item.

Where you see it:

• In Settings, Agents shows each agent's share of runs that went through in the last 30 days; an agent with none says "No runs yet". Its own page shows the same.
• In Agent runs, the reason shows beside the state, and the filter lists all runs, the runs that fell short, or one reason's.

To find the fault, click Ask the assistant why on the page of an agent whose runs fell short. The assistant opens with the question asked, such as "Why do Order check's runs fall short, and what would fix it?" It reads the runs that fell short and what each did, says what they have in common, and proposes better instructions or a new skill on a card: click Apply to make the change. It does this only when you ask, never by itself or on a schedule.

Limits and details:

• A run of an automation can only have failed or been changed by a person.
• A run still running or waiting has no reason yet.
• A person's chats are never counted.

The same is there under a builder's API token (Use your base from a calendar or a script): GET /api/builder/runs?reason=short (or one reason, such as reason=changed, and days=30, or the filters of the Agent runs page, such as agent, version, workflow and step, outcome, from and to, or table and item for one item's runs), with their totals; the same runs grouped by agent, version and step, as the tab By agent version shows them, with group=step; one run with everything it did at GET /api/builder/runs/<id>, a page at a time: give each page's next as after for the next one, until it is null; and each agent's share at GET /api/builder/agents/share. Through Base Captain's MCP server, the tools list_runs (grouped when asked to), read_run and agent_share answer the same, and the assistant does too: ask, for example, "How does each version of Reviewer do on the Review step?" The runs are for the users who build the base, each agent's share for the admins and the AI managers.

An agent's changes show in an item's history and comments, with the agent's name or yours:

• In an item's History, a change an agent made in your chat shows under your name, "via agent": it acted for you. A change it made by itself shows under its own name and picture, with the mark Agent, also "via agent".
• An agent's comments on an item carry its name, its picture and the mark Agent, and a workflow step's summary is posted as its comment.
• After a chat in which an agent changed something, Undo under its answer takes those changes back.