> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents
> Multi-step agents defined in .agentic.yml that ground questions in your World Model
An **Agent** in Oxygen is a multi-step reasoning agent, defined in a
`.agentic.yml` file. Unlike a single LLM call, an agent runs a fixed
**pipeline** — a finite state machine — that grounds a natural-language question
in your [World Model](/docs/guide/build/world-model), generates and runs SQL,
validates the result, and explains it back in plain language.
## Context-first, not prompt-first
An Oxygen agent is defined less by its prompt than by its **context**. You point
an agent at a set of files — semantic views, example queries, domain docs,
verified queries, automations — and each kind of context grants the agent a
specific **affordance**: a capability it can use while reasoning.
* Give it your **semantic model** (`.view.yml` / `.topic.yml`) and the agent can
resolve measures and dimensions by name and compile SQL deterministically —
instead of guessing at columns.
* Give it **verified queries** (`.sql`) and it can run a trusted, pre-approved
query as-is when a question matches.
* Give it **domain docs** (`.md`) and it inherits your business terminology.
* Give it **automations** (`.automation.yml`) and it can discover and delegate to
them.
The agent's behavior — which tools it can call, which shortcuts it can take — is
a direct function of the context you provide. This is why an agent is only as
good as the [World Model](/docs/guide/build/world-model) beneath it. See
[Context & affordances](/docs/guide/build/agents/provide-context) for the full map.
## The pipeline
Every agent moves through the same stages. It doesn't invent its own control
flow — it advances through a state machine, and when a check fails it loops back
to an earlier stage rather than pushing a bad answer forward.
Triage the question and resolve the metrics and dimensions it refers to
against your semantic model — asking a follow-up question if the request is
ambiguous.
Turn the intent into a concrete query spec: measures, dimensions, filters,
and the joins between them. If the semantic model can compile the spec
directly, the next stage is skipped.
Generate SQL from the spec. Skipped when the semantic model already compiled
the query — no hand-written SQL needed.
Run the query against a configured database and validate the shape of the
result.
Turn raw rows into a natural-language answer and, when useful, a chart.
For the full state machine — how stages loop back on failure, retry, and pause
for human input — see [How the pipeline works](/docs/guide/build/agents/pipeline).
There are two built-in kinds of agent that share this pipeline: an **analytics
agent** (answers business questions from your semantic model) and an **app
builder agent** (generates an `.app.yml` [Data App](/docs/guide/build/data-apps) from
a request).
## A minimal agent
The smallest agent that runs needs a database to query, a model to reason with,
and the semantic context to ground in:
```yaml theme={null}
# analytics.agentic.yml
databases:
- warehouse # a connector defined in config.yml
llm:
ref: claude-sonnet-4-6 # a named model from config.yml
context:
- ./semantics/**/* # your .view.yml and .topic.yml files
```
The file stem is the agent's ID — `analytics.agentic.yml` is referenced as
`analytics`.
## Configuration
| Field | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `databases` | Connector names from `config.yml` the agent can query. |
| `llm` | Model configuration — usually a `ref` to a named model in `config.yml`. |
| `context` | Globs, relative to the file, that ground the agent and grant affordances: `*.view.yml` / `*.topic.yml` (semantic model), `*.sql` (example or verified queries), `*.md` (domain docs), `*.automation.yml` (discoverable automations). See [Context & affordances](/docs/guide/build/agents/provide-context). |
| `instructions` | A system prompt injected across stages — persona, domain conventions, terminology. |
| `states` | Per-stage overrides (see below). |
| `thinking` | Reasoning mode: `adaptive`, `disabled`, or an explicit token budget. Never `thinking: false` — use `thinking: disabled`. |
### Per-stage overrides
Each stage — `clarifying`, `specifying`, `solving`, `executing`,
`interpreting` — can be tuned independently. Use a cheap model for triage and a
stronger one for SQL, cap retries, or disable reasoning where it isn't needed:
```yaml theme={null}
llm:
ref: claude-sonnet-4-6
extended_thinking: # activated by the UI "extended thinking" toggle
model: claude-opus-4-6
thinking: adaptive
states:
specifying:
max_retries: 10 # give disambiguation more attempts
interpreting:
thinking: disabled # prose generation needs no reasoning
```
See [How the pipeline works](/docs/guide/build/agents/pipeline) for what each stage
does and every override it accepts.
## Using an agent in chat
**Ask** mode is the fastest way to put an agent to work — no YAML, no terminal.
1. From the home page at [app.oxygen-hq.com](https://app.oxygen-hq.com), set the
chat panel mode toggle to **Ask**, then type your question in plain language.
2. Submitting creates a **Thread** — a conversation you can return to and keep
refining.
3. The selected agent runs its pipeline: it resolves the relevant tables and
[semantic model](/docs/guide/build/semantic-model/simple-model) definitions,
generates a query, and runs it.
4. Results stream back inline. Every answer that ran SQL includes an
`execute_sql` artifact, so you can see the exact query the agent ran and open
it in the SQL IDE.
### Verified queries
When a question matches a **Verified Query** — a plain `.sql` file in the
agent's context — the agent runs that query **as-is** instead of generating new
SQL, and the answer carries a **Verified** badge. This keeps trusted,
business-critical questions consistent every time they're asked.
### Pick the right agent
Each Thread runs against a selected agent. Switch agents from the chat panel to
change which data, instructions, and context are in scope. To shape how an agent
answers, give it [more context](/docs/guide/build/agents/provide-context) and tune its
instructions from the IDE.
## When to use which file
Multi-step reasoning grounded in the semantic model. Routing between
specialized behaviors is handled *inside* the pipeline — there is no separate
routing-agent file. **Use this for conversational data Q\&A.**
A deterministic, fixed sequence of steps with no LLM decision-making between
them. **Use this for repeatable pipelines.**
## Next steps
The FSM in depth — stages, back-edges, retries, and suspension
Every context type and the capability it grants
The semantic model, metric tree, and entity graph agents reason over
What the app builder agent generates