> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vigilos.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The AI Agent

> Learn how the Vigilos AI agent understands your questions, reasons through problems, and returns visualized results.

## Overview

The Vigilos AI agent is more than a chatbot. It's an intelligent agent that learns your data, remembers context across conversations, and gets sharper with every question.

It thinks through problems, not just translates words to queries. When you ask a question, the agent maps your intent to your semantic model's business vocabulary, explores the live database schema, generates an optimized query, and returns results with an interactive visualization and natural language explanation.

## How the Agent Works

When you ask a question, the agent follows a structured process to deliver accurate results:

<Steps>
  <Step title="Understand your question">
    The agent reads your question and maps it to your semantic model's business vocabulary - entity names, column descriptions, relationships, and predefined measures. This ensures it interprets "revenue" or "active users" exactly the way your team defines them.
  </Step>

  <Step title="Explore the live schema">
    The agent fetches the current schema directly from your database to verify that tables and columns are up to date. This prevents errors from stale assumptions if your schema has recently changed.
  </Step>

  <Step title="Generate the query">
    Based on the complexity of your question, the agent generates either a structured query configuration using the built-in BI engine, or advanced SQL for complex analytical questions. The BI engine compiles configurations into optimized SQL for your specific database (PostgreSQL, ClickHouse, Snowflake, Redshift, or BigQuery).
  </Step>

  <Step title="Execute against your database">
    The generated query runs directly against your database through the encrypted connection. Vigilos acts as a pass-through - it sends the query and receives the result set.
  </Step>

  <Step title="Analyze and visualize">
    The agent examines the returned data, selects an appropriate chart type, and provides a natural language explanation of what it found - including key trends, outliers, and notable patterns.
  </Step>
</Steps>

## Visual Builder vs. Advanced Queries

The agent selects the query generation approach based on question complexity:

| Approach           | Used When                                                 | Examples                                                                                                        |
| ------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Visual builder** | Simple aggregations with grouping, filtering, and sorting | "Total revenue by country", "Top 10 customers by order count"                                                   |
| **Advanced SQL**   | Complex analytical queries                                | "Month-over-month growth rate", "Running total of revenue", "Customers who ordered in January but not February" |

<Info>
  Advanced SQL mode supports the full power of your database engine, including window functions, Common Table Expressions (CTEs), subqueries, UNION, and complex JOIN patterns.
</Info>

The visual builder produces a structured configuration with:

* **Dimensions** - columns to group by
* **Measures** - aggregations to compute
* **Filters** - conditions to narrow results
* **Sorts** - ordering rules
* **Limit** - maximum number of rows
* **Chart config** - chart type and display options

## Chart Types

When the agent returns results, it selects an appropriate chart type:

| Chart Type         | Best For                                    |
| ------------------ | ------------------------------------------- |
| **Bar**            | Comparing categories                        |
| **Horizontal bar** | Long category labels                        |
| **Stacked bar**    | Part-to-whole comparisons across categories |
| **Line**           | Trends over time                            |
| **Area**           | Volume trends over time                     |
| **Pie**            | Proportional distribution                   |
| **Funnel**         | Sequential stage drop-off                   |
| **Metric**         | Single KPI values                           |
| **Table**          | Detailed row-level data                     |

Chart options include title, legend visibility, stacking, smoothing, area fill, custom colors, and value formatting (number, currency, or percent).

## Model Selection

Vigilos supports two modes for the underlying AI model:

<Tabs>
  <Tab title="Managed mode">
    Vigilos provides and manages the AI models. You do not need to supply any API keys. This is the default and recommended option for most teams.
  </Tab>

  <Tab title="BYOK (Bring Your Own Keys)">
    Connect your own AI provider account for full control over model selection and billing. Supported providers:

    * **Anthropic** (Claude models)
    * **OpenAI** (GPT models)
    * **AWS Bedrock** (managed AI models)
    * **OpenRouter** (multi-provider gateway)

    Configure your API keys in **Settings > AI Configuration**.
  </Tab>
</Tabs>

## Conversation Context

The AI agent maintains full context within a conversation. This means you can:

* Ask follow-up questions that reference previous results ("Now break that down by region")
* Refine queries incrementally ("Exclude returns from that total")
* Ask the agent to explain its approach ("Why did you use a window function?")
* Request different chart types ("Show that as a line chart instead")

Each conversation is independent. Starting a new conversation resets the context.