Agents

An agent is a skill that runs against your project — in your own Claude through the XCubes connector, or on XCubes' server when your admin has turned the agent runner on — and whose only output is a set of proposals. It never writes a cube cell. You approve what it proposed; where the agent's job is to change a cube, a Link carries the approved rows in and a revert takes them back out; where its job is to write something a person reads (a commentary, a list of flags), the reviewed table is the deliverable and approving a row publishes it. That is the whole contract, and every shipped agent follows it.

The shipped agents

The agents are numbered 0.x while they are in preview: each change to an agent's skill, scope or checks raises its minor number, and 1.0 will mark the first version declared stable. A run records the version that ran it.

The arithmetic is never the agent's. Consolidation pairs what it reads; Variance Commentary asks get_variances for the variance and its decomposition into the lines each formula reads; Anomaly Watch asks get_anomalies for the trailing-window statistics. The agent ranks, explains and writes; the numbers on a row are copied from the tool, and a row the tool did not flag or did not find material is never proposed.

What an agent may and may not do

Every agent ships with a scope: the cubes it reads, the proposals table it writes, the Link that applies approved rows (when it has one), and the tools its key is allowed to call. Installing it on a project resolves that scope against your objects — the install dialog says which cube it will read and what is missing — and mints nothing on its own.

An agent:

• reads the cubes in its scope and cites, on every row, the cells it read (the Source Cells column), so lineage runs both ways;
• writes rows to its proposals table only, through add_proposals, inside a run it opened with start_agent_run and closes with end_agent_run;
• never calls set_cube_data, never runs or reverts a Link, and never approves or edits a proposal — those tools are not in its key's scope, so the server refuses them before anything is read;
• stops on a failing precondition (no data in the period, a check row not zero) and reports it in the run's outcome rather than proposing on bad inputs.

Settings

Some agents take settings the reviewer fixes at install: Variance Commentary asks which two items to compare (Actual against Budget, BASE against BEST) and the materiality thresholds; Anomaly Watch asks for the window, the z threshold and the minimum deviation, and which version to watch. The install dialog seeds each with the agent's preferred default from your model, the agent's page shows them, and every run prompt repeats them so the agent uses what you chose. Changing a setting is a reinstall.

Row checks

An agent's bundle may declare row checks that add_proposals enforces on the agent's own rows: a column that must be filled (a narrative on every material line, a suggested check on every flag), or a sum that must land on another column within a tolerance (the drivers must add up to the variance), or a flag from the agent's own list (Anomaly Watch cannot write Consolidation's UNMATCHED). A row that fails is refused with the check named, and nothing from that call is written. The checks hold the agent to its contract, not you: a row a person types into the same table is never checked.

Installing an agent more than once

Anomaly Watch and Variance Commentary can be installed several times on one project: a watcher for each cube worth watching, a commentary for each comparison (Actual vs Budget, Actual vs Forecast). Consolidation installs once, since a group has one journal.

Each install has a name, "Anomaly Watch — FX Rates" for example, proposed from the cube it reads and editable when you install it or later from its page. An install owns everything it works with: the cube it reads, its own proposals table ("Anomalies — FX Rates"), its dashboard page, its settings, its schedule and its run log. A run is told the ids of its install's cube and table, so two watchers never write into each other's table. The review queue groups proposals by install.

On the gallery, an agent with one install shows Uninstall on its card; with several, each install is uninstalled from its own page, so nothing has to ask which one.

What a proposal is

A proposals table is a data table of kind proposals: it carries built-in columns nobody can remove — Proposal (the group id: the legs of one journal entry share it), Status, Author, Run, Reason, Source Cells, Flag, Reviewed By, Reviewed At — plus the dimension and value columns that address the cube or carry the agent's text. Every row an agent writes lands PROPOSED with the agent as Author and its run id in Run.

Flag is where the agent says it is unsure, or what it found. Each agent has its own vocabulary, listed in the roster above: Consolidation flags a doubt (FX when two sides translate to different amounts, TIMING when a counterpart sits in a neighbouring period, UNMATCHED when one side has no counterpart); Variance Commentary and Anomaly Watch flag what the tool found (a variance that is NEW this period, a TRENDING one, an OUTLIER). A blank flag means a clean proposal, which is what "Approve all clean" approves in one click.

Statuses

A Link on a proposals table reads only APPROVED rows — the filter is forced, not configurable — so nothing reaches a cube without a person having said yes. The table editor's review bar and the project's Review queue (Agents tab) are the two places to say it. A table with no Link (Commentary, Anomalies) stops at APPROVED: the reviewed rows are what the dashboard page and the reader see.

Runs

Every run is logged: which agent, which key, when it started and ended, its outcome, how many rows it proposed, and what became of them. A run left open for more than a day reads as abandoned, and its rows carry that warning in the review queue — half a journal from an agent that crashed is visible as such, not mistaken for a finished one. The agent's page in the Agents tab lists the runs; each opens to its proposals and to the Link executions that applied them.

Running an agent

From the agent's page, Open in Claude first makes sure you hold a key minted for that agent and that project — the key's scope is the agent's tool list and nothing else — then hands the work to Claude: Open in Claude starts a chat with the run prompt, Copy prompt is for Claude Code, Cowork or any MCP client. The key is never part of the link; the connector you configured with it does the work.

Running agents inside XCubes

When an admin turns on Admin → Agent runner, the agent's page also offers Run now and a Schedule — on a calendar, or when data arrives. The same skill, scope and proposals table are used either way; what changes is where the model runs and who pays for its tokens.

Run now asks for a period (blank lets the agent pick the latest with data) and a model from the admin's allow-list, then starts the run and follows it in the run log, with its tool calls counting up while it works.

A schedule is monthly (a day and a time), weekly, or a custom cron, in UTC and at most once an hour, and runs either for the previous month or for the latest period with data. It runs as the person who saved it, and that person must still be an editor of the project at every firing; proposals always carry someone accountable for the run. A firing that cannot run (no editor rights, a cap reached, no key) is logged as a failed run with the reason. After three failed runs in a row the schedule pauses itself and the project's owners and admins get an email; the agent's page says why, and Resume saves the schedule again, as the person who resumes it.

When data arrives. Instead of a calendar, an agent can run when new data lands in a cube it reads — Anomaly Watch looking at June as soon as June is loaded, whether that is the third working day or the sixth. Run when data arrives sets how long to wait after the last load (15 minutes by default, 5 to 240) and the model; the run is always for the latest period with data, and runs as the person who saved it, as a schedule does.

• What counts as a load: an import (a file, the grid's import dialog, a matrix from Claude), a saved import source refreshed, an integration sync, and any Link run that writes the cube. A load into a cube that the watched one reads through Reference() counts too: a P&L built from an input cube hears about the input cube's load.
• What does not: typing or pasting in the grid, the fill and spread operations, set_cube_data, restoring a snapshot and reverting a Link. Those are edits, not loads. The agent's own Link never wakes it either: Consolidation posting its journal wakes Anomaly Watch, not Consolidation.
• Bursts are one run. A run-all of five Links, or a sync followed by the Links it feeds, is one load as far as the agent is concerned: it runs once the last write is the wait time old. It runs at most once an hour.
• The agent's page shows Last data — which load it would react to and when — and the run log marks these runs Data, their description naming the load ("after an import into FX Rates"). Failed runs, the pause after three and Resume work as for a schedule.

Caps. An admin sets a per-run cap and a monthly cap in US dollars. A run stops when its estimated cost reaches the per-run cap, and no run starts once the month's estimated spend reaches the monthly cap. Estimates use the published per-token prices; the provider's invoice is the final word. Admin → Agent runner shows this month's spend by project.

Transcripts. Every server run keeps its full transcript — the instructions, every tool call and every result — encrypted, for the number of days the admin chose (90 by default). Download it from the run log.

Review is unchanged. A server run proposes; people approve. Rows from a run that failed carry a failed run mark in the review queue, and Approve all clean skips them, so an unfinished run is never published in bulk.

Custom agents

The shipped agents are bundles of a skill, a scope and a proposals-table shape. A skill forked into your own MCP client's skill folder can follow the same contract — open a run, propose, close the run — with a key you scope by hand in Settings → API keys → Restrict this key. Registering a custom agent in the gallery is not in the product yet.