Agents

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, 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 beneath it. See Context & affordances 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.

Clarify

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.

Specify

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.

Solve

Generate SQL from the spec. Skipped when the semantic model already compiled the query — no hand-written SQL needed.

Execute

Run the query against a configured database and validate the shape of the result.

Interpret

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. 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 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:

# 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.
`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:

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 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.

From the home page at app.oxygen-hq.com, set the chat panel mode toggle to Ask, then type your question in plain language.
Submitting creates a Thread — a conversation you can return to and keep refining.
The selected agent runs its pipeline: it resolves the relevant tables and semantic model definitions, generates a query, and runs it.
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 and tune its instructions from the IDE.

When to use which file

.agentic.yml — Agent

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.

.automation.yml — Automation

A deterministic, fixed sequence of steps with no LLM decision-making between them. Use this for repeatable pipelines.

Next steps

How the pipeline works

The FSM in depth — stages, back-edges, retries, and suspension

Context & affordances

Every context type and the capability it grants

World Model

The semantic model, metric tree, and entity graph agents reason over

Data Apps

What the app builder agent generates

Get started

Data Infrastructure

World Model

Agentic Intelligence

SDK

Automations

Data Apps

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

Context-first, not prompt-first

The pipeline

A minimal agent

Configuration

Per-stage overrides

Using an agent in chat

Verified queries

Pick the right agent

When to use which file

.agentic.yml — Agent

.automation.yml — Automation

Next steps

How the pipeline works

Context & affordances

World Model

Data Apps

​Context-first, not prompt-first

​The pipeline

​A minimal agent

​Configuration

​Per-stage overrides

​Using an agent in chat

​Verified queries

​Pick the right agent

​When to use which file

.agentic.yml — Agent

.automation.yml — Automation

​Next steps

How the pipeline works

Context & affordances

World Model

Data Apps

Context-first, not prompt-first

The pipeline

A minimal agent

Configuration

Per-stage overrides

Using an agent in chat

Verified queries

Pick the right agent

When to use which file

Next steps