Skip to main content
An Agent in Oxygen is a saved, named AI assistant that can answer questions about your data — writing SQL, executing it, and explaining the result. You build agents in the IDE: open Objects → Agents, click + New Agent, give it a name, and Oxygen generates a starter agent connected to your default database. From there you refine the system instructions and choose which tools it has access to (SQL execution, semantic-layer queries, etc.). There are two flavors:
  • Classic agents — a single LLM call with tools. Best for focused Q&A.
  • Agentic agents — a multi-step reasoning pipeline (FSM-based) that clarifies, plans, generates SQL, executes, and interprets results. Best for open-ended exploration. (Build an agentic agent →)
If your project has a _routing agent, it becomes the default entry point for chat questions and routes to other agents based on the question. (Routing agents →)

​
What an agent contains

  • A model to call (e.g. openai-4.1).
  • System instructions that tell the LLM how to behave.
  • Context files (schemas, sample SQL, semantic models) injected into the prompt.
  • Tools like execute_sql that let the agent take action.
  • Optional variables with JSON-Schema validation, used to template the system instructions.
See Provide context for how to feed schema information and semantic models into an agent.

​
You can also write this in YAML

Every agent is stored as a .agent.yml file in your workspace. If you prefer to edit YAML directly:
my-agent.agent.yml
model: openai-4.1
system_instructions: |
  You are a sales analyst. Answer questions using the orders table.
tools:
  - name: execute_sql
    type: execute_sql
    database: warehouse
Full schema reference: .agent.yml →

​
Next steps

Build your first agent

Provide context

Agentic agents

Test agents