oxy-agents

Oxy agents (.agentic.yml)

An Oxy agent is one YAML file, <name>.agentic.yml. It configures a fixed pipeline that turns a natural-language question into a grounded query against the semantic model, runs it, checks the result and explains it. You configure the pipeline. You do not define its states or its tools.

There is one kind of agent

• .agentic.yml is the agent. The classic .agent.yml format (a single LLM call with custom tools) has been removed. Do not create one, and do not copy one from an old workspace.
• There is no kind: field. Every .agentic.yml runs the same analytics pipeline. A file named app_builder.agentic.yml is not special. Generating .app.yml data apps, views or agent files is the in-product Builder Agent (chat Build mode), and no .agentic.yml configures it.
• Automations are a different file. Deterministic multi-step work is an automation, .automation.yml (.procedure.yml still works). .workflow.yml is no longer recognised at all. An agent can run an automation it finds in its context. It cannot be one.
• Instruction-only agents skip the pipeline. A file with instructions: and no databases:, context: or states: is answered with one LLM call and queries nothing. Add any of those three and you get the full pipeline.

Use an agent for conversational questions over data that has a semantic model. Use a verified query (a .sql file with an oxy: header, below) when one question must always get exactly the same SQL. Use an automation when the steps are fixed and need no LLM to choose between them.

Minimal file

llm:
  ref: claude            # a `name:` under config.yml `models:`
context:
  - ./semantics/**/*.view.yml
  - ./semantics/**/*.topic.yml

That is enough when the views declare a datasource. The agent can query every database its context references. The full annotated file is templates/agentic-template.yml.