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

# Context & affordances

> Every context type an Oxygen agent can be given, and the affordance each one grants

An Oxygen agent is **context-first**: what it can do is determined by the context
you give it. Each entry in the `context:` block is a glob (relative to the
`.agentic.yml` file) that pulls in a set of files, and each *kind* of file grants
the agent a specific **affordance** — a capability it unlocks while reasoning.

```yaml theme={null}
# analytics.agentic.yml
context:
  - ./semantics/**/*.view.yml       # semantic model
  - ./semantics/**/*.topic.yml      # topics
  - ./example_sql/*.sql             # example / verified queries
  - ./docs/*.md                     # domain documentation
  - ./workflows/**/*.automation.yml # discoverable automations
```

The `context:` block is a list of **glob patterns**, not named objects — the
agent classifies each matched file by its extension and wires up the matching
affordance automatically.

## The affordances

| Context type         | File pattern                | Affordance it grants                                                                                                                                                                                                        |
| -------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Semantic model**   | `*.view.yml`, `*.topic.yml` | The agent resolves questions against defined **measures** and **dimensions** and lets the semantic engine compile SQL and resolve joins — so it can skip hand-writing SQL. Raw-schema tools are hidden to keep it grounded. |
| **Example queries**  | `*.sql` (plain)             | Injected into the SQL-generation stage as style examples, teaching the agent your codebase's SQL conventions.                                                                                                               |
| **Verified queries** | `*.sql` (marked verified)   | Discoverable and run **as-is** when a question matches — bypassing SQL generation and earning a **Verified** badge.                                                                                                         |
| **Domain docs**      | `*.md`                      | Injected as business context, giving the agent your terminology and metric definitions.                                                                                                                                     |
| **Automations**      | `*.automation.yml`          | Made discoverable so the agent can find and **delegate** to a trusted, pre-built [automation](/docs/guide/build/automations).                                                                                                    |

## Semantic model — the primary affordance

Pointing an agent at your [semantic model](/docs/guide/build/semantic-model/simple-model)
is the highest-leverage context you can add. With it, the agent:

* **Resolves by name.** It searches your catalog for the measures and dimensions
  a question needs, instead of guessing at raw columns.
* **Compiles deterministically.** When the request maps cleanly onto defined
  measures, the semantic engine compiles the SQL directly — the SQL-generation
  stage is skipped, and joins and fan-out are handled for you.
* **Stays grounded.** When a semantic model is present, the agent's raw
  `list_tables` / `describe_table` tools are withheld so it doesn't drift from
  your definitions.

This is why an agent is only as good as the [World
Model](/docs/guide/build/world-model) beneath it: richer semantic context means more
questions the agent can answer correctly and deterministically.

```yaml theme={null}
context:
  - ./semantics/**/*.view.yml
  - ./semantics/**/*.topic.yml
```

## Example vs. verified queries

Both come from `*.sql` files, but they grant different affordances:

* **Example queries** shape *how* the agent writes SQL — they're shown as
  reference so generated SQL matches your house style. Add a comment at the top of
  each file explaining what it's for, so the model has that context.
* **Verified queries** are trusted answers. When a question matches one, the
  agent runs it **exactly as written** and skips generation entirely — the answer
  carries a **Verified** badge. Use these for business-critical questions that
  must return the same query every time.

## Domain docs

Plain-Markdown files under your `context:` globs are injected as domain context,
so the agent inherits your business vocabulary — what "active customer" means,
how a fiscal quarter is defined, which segment names are canonical. This mostly
shapes the **Clarify** and **Interpret** stages, where the agent is mapping human
language to metrics and back.

## Automations

Point an agent at `*.automation.yml` files and it can **discover** them and
delegate a matching request to a pre-built [automation](/docs/guide/build/automations)
instead of solving from scratch — useful when a trusted multi-step pipeline
already answers a class of questions.

## Next steps

<CardGroup cols={2}>
  <Card title="How the pipeline works" icon="diagram-project" href="/docs/guide/build/agents/pipeline">
    See which stage each affordance affects
  </Card>

  <Card title="Build a semantic model" icon="cube" href="/docs/guide/build/semantic-model/simple-model">
    The context that matters most
  </Card>
</CardGroup>