# Agents & graphs

> Scheduled LLM agents that read your dashboards, charts, sheets and datasets and report what they find — and graphs that run several of them in order, each reading what the one before it concluded.

*[View this page in the Flax docs](https://flax-analytics.com/docs/automation-ai/agents)*

An **agent** runs an LLM on a schedule over artifacts you already built, then reports what
it found — by email, webhook, Slack or Discord. A **graph** runs several agents in order,
where each one can read what the agents before it concluded. Both live at `/app/agents`.

The reason this is more than a chatbot on a timer: an agent reads the *governed* artifacts
of your business — a dashboard, a sheet, a derived dataset — across sources, and it runs
with **its creator's access**. It can never see more than the person who made it.

## An agent

Pick what it reads, tell it what to look for, and choose when it runs.

- **What it reads** — any mix of dashboards, charts, sheets and datasets. Each run queries
  them live, so the agent sees current data, not a snapshot of when you made it.
- **What it does** — plain instructions. "Summarise how revenue moved this week and flag
  anything unusual" is a complete brief.
- **Outputs** — email, webhook, Slack or Discord. Every output carries its **provenance**:
  which artifacts and figures the conclusion was based on. A suggestion that cannot show
  its evidence is not worth acting on.
- **Attach a rendered image** — renders the dashboards and charts it reads and shows them to
  the model, so it can comment on how they *look*, not only on what the numbers say. Needs the
  "Look at rendered images" skill. It renders up to four artifacts per run, and if a render
  fails the agent answers from the data alone and the run records that it did.

### Reporting inside Flax

Three outputs land where people already look, rather than in a channel they have to be
subscribed to:

- **In-app notification** — the agent's headline in the notification bell, linking to the
  full run. Goes to you by default; you can widen it to the whole org.
- **Comment on a dashboard** — the report posted as a comment thread entry, so the
  conversation happens next to the numbers. Defaults to the first dashboard the agent reads.
- **Write into a dashboard tile** — the report becomes the content of a text block on a
  dashboard, refreshed every run.

The tile output has one rule worth knowing: an agent writes into an **empty** text block and
then owns it. It will never overwrite a block you have typed into, or one another agent owns
— so add a blank text block, and paste its id into the output. Agent-written blocks are
labelled *"Written by an agent"* on the dashboard, and say so in their text as well.

### Proposing a change in git

An agent can also write its report into your repository as a **draft pull request** — a
weekly review that lands in `docs/reports/`, a changelog entry, a note for the team. Pick
**Draft pull request** as an output, choose the project whose repository to write to, and
give a path. `{date}`, `{agent}` and `{run}` are filled in, so
`docs/reports/{date}-{agent}.md` becomes `docs/reports/2026-07-31-weekly-revenue-watch.md`.

Three things about this are not configurable, on purpose:

- **It is always a draft, and never merged.** An agent proposes; a person decides.
- **It can only write where an admin allowed.** Set the paths under Data → the project → git
  write-back. **Empty means agents cannot open pull requests for that project at all** —
  there is no "anywhere" setting. A path outside the list is refused before anything is
  committed, and the run records why.
- **It says a machine wrote it**, in the pull request and in the file itself, along with the
  evidence it used.

This needs git write-back configured for the project (the same credential the semantic-layer
write-back uses).

### What it costs, and what bounds it

Agents use your own LLM key, so an unattended run spends **your** provider budget. Every
agent is bounded even if you never touch the limits:

| Limit | Bounds |
| --- | --- |
| **Max tool rounds** | how many times one run may query before answering |
| **Token ceiling per run** | one run's spend; on a breach the agent **pauses itself** and admins are notified |
| Org monthly cap | all LLM use across the org, set by an admin |

A paused agent says why on its card. Editing it, or switching it back on, clears the pause.

## History: what ran, and did it work

The **History** tab lists every run across your agents and graphs, newest first — and, for
each one, what it actually delivered.

That distinction matters more than it sounds. A run can finish **ok** and still have sent
nothing: a webhook that returned 404, an email skipped because its skill was revoked. The
agent's own page would show a green run. History shows the delivery too, so anything that
needs a look says so on the row without opening it, and the header counts how many runs need
attention. **Only problems** filters to those.

Each row shows which agent ran, whether it was part of a graph, whether someone triggered it
by hand, and what it cost in tokens. Open one to read what the agent concluded and which
artifacts it based that on.

## Skills: what an agent is allowed to do

There are two separate questions about an agent, and different people answer them. **What is
it set up to do?** — anyone who can create agents decides that. **What is it allowed to do?**
— only an organization admin decides that, under Agents → Skills.

A new agent can notify its own creator and nothing else. Everything that reaches a colleague
or leaves Flax is granted deliberately:

| Skill | Lets the agent |
| --- | --- |
| Notify its owner | Post an in-app notification to whoever created it *(always on)* |
| Look at rendered images | Render its dashboards and charts so the model can see them |
| Notify the organization | Notify everyone |
| Write inside Flax | Comment on a dashboard or chart, and write into a tile it owns |
| Send email | Email its report — leaves Flax and cannot be recalled |
| Post to Slack or Discord | Post into a chat channel |
| Call a webhook | Send its report to a URL |
| Open draft pull requests | Propose a change in your repository, always as a draft |

If an agent is configured with an output it has not been granted, that output is **skipped**
and the run says why — the agent still runs and still reports. Revoking a skill takes effect
on the next run; it does not change how the agent is set up, so granting it again resumes
exactly what was there before.

Agents that already existed when skills arrived keep the skills they were already using.

## Knowledge: what every agent should already know

Some things are true for every agent you will ever write — the fiscal year starts in April,
accounts prefixed `test-` are not real, revenue is net of refunds. Pasting those into each
agent's instructions means six copies, and the day a rule changes, five of them are quietly
wrong.

A **knowledge document** is that shared context, written once under the Knowledge tab and
attached to as many agents as you like. Change it and every agent that uses it follows on its
next run.

Two things are worth understanding:

- **Knowledge is instruction, not evidence.** The artifacts an agent reads are treated as
  data to weigh; knowledge is treated as rules to apply. That is the difference between
  "here are the numbers" and "here is how we count".
- **The list tells you what a change affects.** Each document shows how many agents use it,
  and opening one names them — so you know what you are about to change the behaviour of.

Each run records which documents it was given, alongside the artifacts it read, so a report
that looks wrong can be traced back to the rules it was operating under.

Keep documents to the rules that matter: the text goes into every run of every agent that
uses it, and you pay your LLM provider for it each time.

## A graph

A single agent answers one question. A graph is for the shape real analysis has: collect,
judge, then write up — where the writer sees what the collectors found.

**Steps** are the agents in the graph. The same agent may appear more than once if two
branches both need it. **Dependencies** say what waits for what, read as sentences: *after
Collect, run Write up*. Steps with no dependencies run first, together.

Each step's report is passed to the steps that depend on it, as **reference material** —
clearly marked as another agent's conclusion rather than as instructions.

### Steps that pick a branch

A step can be a **supervisor**: it runs, and its answer decides which branches continue.
Give each branch out of a supervisor a name — *revenue fell*, *revenue grew* — and the
supervisor is asked to name its choice.

It can only choose from the branches you named. If its answer names none of them, the
graph **stops there** rather than running everything — the safe direction when real emails
and webhooks are on the other side.

### What bounds a graph

A graph multiplies cost by the number of steps that run, so it carries its own limits on
top of each agent's — five agents at 120,000 tokens each is 600,000 tokens that no
per-agent ceiling would catch.

| Limit | Bounds |
| --- | --- |
| **Max depth** | how many levels deep it may go, so a long chain cannot run away |
| **Max nodes** | how many steps may run in one execution |
| **Token ceiling** | the whole execution, re-checked before each level |

On a breach the graph pauses itself and admins are notified.

## Reading what happened

Open a graph to see its **runs**: status, how many steps ran, the depth reached, and the
tokens the whole execution spent. Open a run to see each step in the order it happened and
what it concluded — including which branch a supervisor chose and why it skipped the rest.

A run also records its decisions in plain words, so a graph that stopped early tells you
whether it hit a limit, a step failed, or a supervisor found nothing worth following.

## Over the API and MCP

Everything here is available programmatically: `list_agents` / `create_agent` /
`run_agent`; for knowledge `list_knowledge`, `create_knowledge` and `set_agent_knowledge`; for skills
`list_agent_capabilities` and `set_agent_capabilities`; for run health
`get_agent_run_history`;
and for graphs `list_agent_graphs`, `create_agent_graph`, `set_agent_graph_shape`,
`run_agent_graph` and `get_agent_graph_run_nodes`. Creating a
graph and wiring it are two calls — create it, then set its shape.

## Related

- [AI settings & usage](/docs/automation-ai/ai-settings-and-usage) — your LLM key and what
  it has been spent on.
- [Actions](/docs/automation-ai/actions) — the trigger→effect framework agents deliver
  through.
- [Scheduled deliveries](/docs/automation-ai/scheduled-deliveries) — send a dashboard on a
  schedule, without an LLM.