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

# Agent Mode

> Everything the Agentic Loop can do inside the AI Analyst — a full reference to autonomous multi-step actions in Tablix.

**Agent Mode** (shown in the app as the **Agentic Loop**) is a mode of the [AI Assistant](/ai-assistant) that turns a single request into an autonomous, multi-step run: the AI plans a goal, executes one step, reads the result, and decides the next step on its own — repeating until the goal is done.

<Note>
  This page documents Agent Mode specifically. For the AI Analyst sidebar in general (Chat mode, voice input, quick insights), see [AI Assistant](/ai-assistant).
</Note>

## Turning On Agent Mode

In the AI Analyst sidebar, switch the mode selector from **Chat** to **Agent** before submitting your prompt. Once submitted:

* The badge **Agentic Loop Active** appears
* The sidebar shows a live status such as *"Cleaning data... (Step 2)"* or *"Generating chart... (Step 3)"*
* You can stop the loop at any time with the stop button

## How the Loop Works

<Steps>
  <Step title="You give a goal">
    e.g. *"Clean this data, calculate average profit by region, and chart it."*
  </Step>

  <Step title="Step 1 runs">
    The AI writes and runs code for **only the first part** of the goal (e.g. cleaning).
  </Step>

  <Step title="The AI reads its own result">
    The output (or error) of Step 1 is fed back to the AI automatically with the instruction: *"Continue to the next step. Fix any errors, or output `[TASK_COMPLETE]` if done."*
  </Step>

  <Step title="Step 2, 3... run automatically">
    The AI keeps going step by step — one code block per step — using each result to decide what's next.
  </Step>

  <Step title="The loop ends">
    Either the AI outputs `[TASK_COMPLETE]` (goal finished), or the loop hits its step limit.
  </Step>
</Steps>

<Warning>
  The Agentic Loop is capped at **5 steps**. If the goal isn't finished by then, the loop stops automatically and the sidebar shows: *"Agentic loop reached maximum steps limit."*
</Warning>

### Self-Correction

If a step's code throws an error, that error is included in the next step's context, and the AI's next step is specifically to **fix the error** rather than move forward — so a single bad step doesn't necessarily end the run.

## Everything Agent Mode Can Do

In Agent Mode, the AI always has access to **every capability category** at once (in Chat mode, only the category matching your specific wording is loaded, to save time) — so it can freely combine any of the following across its steps:

<AccordionGroup>
  <Accordion title="Clean data" icon="broom">
    Using `update_cells()` to edit in place (never rebuilding the table):

    * Remove duplicate rows (keeping the first occurrence)
    * Trim, uppercase/lowercase, or standardize text
    * Strip footnote brackets (e.g. `[1]`, `[a]`), encoding garbage, and other unwanted symbols — while preserving things like year ranges (`2023-2024`)
    * Fix blank/missing values
    * Delete specific rows (`{'action': 'delete_row', 'row': N}`)
  </Accordion>

  <Accordion title="Reshape the sheet" icon="table-cells">
    Using `insert_col()` / `insert_row()` to modify structure in place:

    * Insert a new calculated column next to an "anchor" column (e.g. a Profit Margin column next to Revenue/Cost)
    * Append a new total/summary row
    * Move a column (insert at the new position, then blank out the original)
    * Split a single messy column into multiple columns, detecting delimiters (commas, pipes, underscores, multiple spaces, etc.) automatically
  </Accordion>

  <Accordion title="Sort & filter" icon="filter">
    Using `sort_table()` / `apply_filter()` / `clear_filter()` on the existing table in place:

    * Sort ascending or descending by any column
    * Apply one or more filters (equals, not-equals, contains, greater/less than, empty/not empty, starts/ends with, or matches a list of values)
    * Combine multiple filters (e.g. Status = Active **and** Price > 100)
    * Clear one filter or all filters
  </Accordion>

  <Accordion title="Format cells" icon="paintbrush">
    Using `apply_format()` — changes appearance only, never the underlying values:

    * Background/text color (e.g. highlight negative numbers in red)
    * Number formats: currency (multiple symbols), percentages, dates
    * Bold, italic, underline/strikethrough, font size, font family, alignment, borders, decimal places
    * Can be applied to a single range or looped across the entire sheet
  </Accordion>

  <Accordion title="Build charts — including full dashboards" icon="chart-column">
    Using `create_chart()`:

    * Picks an appropriate chart type from all 26 supported types (see [Charts](/charts)) based on your request and the data shape
    * Can chart existing columns directly, or **compute new series first** (e.g. extracting "Month" from a Date column) when the category you asked for doesn't exist yet
    * **Dashboards:** if you ask for a "dashboard" (e.g. *"create a sales dashboard"*), the agent calls `create_chart()` **3–4 times** in one step, all charts kept on-topic to the type of dashboard requested (a "profit dashboard" gets profit-focused charts, not generic ones) — see [Dashboard](/dashboard)
    * **Forecasting:** for "forecast" or "future trend" requests, it fits a simple linear trend (via `numpy.polyfit`) to historical data and charts the projected values alongside the historical ones
  </Accordion>

  <Accordion title="Summarize & explain (no sheet changes)" icon="file-lines">
    For analytical questions ("why did X happen", "summarize this", "explain the trend"), the agent does **not** modify the sheet. It calculates real figures in Python and prints a "Key Insights" style report: several bullet points, each a specific, numbers-backed observation (not generic advice), covering every relevant metric in the data — not just two or three cherry-picked ones.
  </Accordion>
</AccordionGroup>

## Automatic Chart Suggestion After a New Table

Whenever any step (agent or chat) creates a brand-new table with `set_data()` — for example a groupby/pivot result — Tablix automatically evaluates whether to add a chart beside it:

* Skipped if the table has more than 60 rows
* Skipped if the table is only 1 row or 1 column
* Otherwise, a chart type is picked automatically:
  * Dates in the first column → Line (or Stacked Area if multiple value columns)
  * A single category column with a small number of rows → Pie or Doughnut
  * More than 10 categories → Bar (or Stacked Bar with multiple value columns)
  * Multiple value columns otherwise → Stacked Column
  * Default → Column
* Titles and axis labels are generated automatically from the column headers

## Data-Handling Guardrails the Agent Follows

These aren't things you do yourself, but they shape what you'll see the agent produce:

* Numeric columns are cleaned of currency symbols, `%`, and commas before any math is run on them, to avoid silent `NaN` results
* Sums/averages are computed on full column ranges (e.g. `q.cells("A:E")`), not hardcoded row ranges, so results stay correct if you add more rows later
* "Highest/top/best \[metric] by \[category]" is always interpreted as **grouped total (SUM)**, not the single largest individual row, unless you specifically ask for a single transaction or an average
* Empty rows are dropped before aggregation/charting, but preserved during column-splitting (to keep row alignment intact)
* Every step ends with a short, plain-language summary of what changed — not a dump of the raw output data

## Stopping and Limits

* Click the stop button at any time to cancel the current step and end the loop; a *"Stopped by user."* message is added to the chat
* The loop has a hard ceiling of **5 steps** per run — for very large multi-part goals, you may need to continue with a follow-up prompt after it stops