Skip to main content

​
What is an Agent?

An Agent is an AI-powered chat interface that:
  • Converts natural language questions into SQL
  • Analyzes results and provides insights
  • Creates visualizations from query results
  • Learns from examples (Golden Assets)
Agent chat interface

​
Agent Components

Every agent is linked to a specific data model version. This ensures:
  • The agent knows what tables and columns exist
  • Changes to the data model don’t break the agent
  • You can test with different data model versions

​
System Prompt

A custom prompt that shapes how the agent responds:
  • Company context and terminology
  • Response style preferences
  • Special instructions

​
Golden Assets

Example queries and charts that teach the agent:
  • How to write SQL for common questions
  • What visualizations to create
  • Correct terminology and calculations

​
Evaluations (Evals)

Test sets to verify agent accuracy:
  • Known question-answer pairs
  • SQL validation
  • Result comparison

​
Creating an Agent

  1. Navigate to your project’s Agents tab
  2. Click Create Agent
  3. Enter a name and description
  4. Select the data model to use
  5. Click Create
Create agent dialog

​
Configuring Your Agent

​
Setting the System Prompt

  1. Open your agent
  2. Go to the System Prompt tab in the sidebar
  3. Write instructions for the agent
  4. Click Save
Example system prompt: 
You are a data analyst for an e-commerce company.
Use clear, business-friendly language.
When users ask about "revenue," they mean gross_sales minus refunds.
Always include date ranges in your analysis.
System prompt editor

​
Adding Golden Assets

Golden Assets are example queries that improve accuracy:
  1. Go to the Assets tab
  2. Click Add Asset
  3. Enter the question and corresponding SQL
  4. Optionally add a chart configuration
  5. Click Save
Golden assets list
Tip: The more golden assets you add for common questions, the more consistent your agent becomes.

​
Creating Evaluations

  1. Go to the Tests tab
  2. Click Add Test
  3. Enter a question
  4. Enter the expected SQL or answer
  5. Save and run the test
Agent test interface

​
Admin View vs User View

​
Admin View

As an admin, you see full details:
  • Every tool call the AI makes
  • SQL queries generated
  • Step-by-step reasoning
  • Token usage and timing
Admin chat view with tool calls expanded

​
User View

End users see a clean interface:
  • Just the question and answer
  • Charts and insights
  • No technical details
User chat view

​
Versioning

Like data models, agents are versioned:
  1. Go to the Versions tab
  2. See all versions with timestamps
  3. Each version tracks: assets, prompt, data model link
Agent versions list

​
Setting Production

Before users can access your agent, you must set a version as production.

​
Requirements

  1. The agent must be linked to a data model
  2. That data model version must already be production
  3. The agent’s schema requirements must fit within the data model

​
Steps

  1. Open your agent
  2. Go to the Versions tab
  3. Click Set as Production on the version you want
  4. The system validates everything
  5. If successful, users can now access this version
Set agent as production

​
Validation Errors

If validation fails, you’ll see specific errors:
  • “Data model version is not production” - Set the data model production first
  • “Missing tables/columns” - The agent uses data not in the data model

​
Changing Data Model Version

To link your agent to a different data model version:
  1. Go to the Data Model tab in the sidebar
  2. Select the data model
  3. Choose a version (production versions recommended)
  4. Click Save
This creates a new agent version with the new data model link.
Change data model version

​
Best Practices

​
1. Start with Golden Assets

Add 10-20 golden assets covering common questions before going live.

​
2. Use Descriptive Data Models

Column descriptions in your data model help the agent understand your schema.

​
3. Run Evals Regularly

Create a test suite and run it whenever you update the agent.

​
4. Monitor in Admin View

Periodically check admin view to see how the agent handles real questions.

​
Next Steps