How to Use Hex Notebook Agent for Analysis

What the Hex Notebook Agent Does

Hex is a collaborative data workspace where analysts write SQL and Python in a notebook-style interface. The Notebook Agent adds an AI layer that can read your warehouse schema, generate new cells, fix broken code, and explain results in plain language.

Unlike general-purpose AI assistants, the Notebook Agent has full access to your project context: table names, column types, dataframes already in memory, and any documentation you have added to your data browser. That context reduces the back-and-forth of copy-pasting schemas into a chat window.

As of April 2026, Hex reports that teams using the agent complete exploratory analyses 40% faster on average compared to writing all code manually, based on internal usage data from enterprise customers.

Requirements Before You Start

You need an account with an Editor, Manager, or Admin workspace role. The Notebook Agent is available in beta on all plans, including free. The agent is not available in App builder view or within published apps.

If you want to upload files (CSV, Excel) as context, a workspace admin must enable the file uploads security setting under Settings > Security.

You also need at least one data connection configured. Hex connects to BigQuery, Snowflake, Redshift, Databricks, and most other standard warehouses. Without a connection, the agent can still help with code generation, but it will not be able to query your actual tables.

Step 1 — Connect Your Data Warehouse

Go to Settings > Connections and click Add Connection. Hex walks you through warehouse-specific credentials. For BigQuery, you will paste a service account JSON. For Snowflake, you will enter account, warehouse, role, and credentials.

Once connected, set a default connection at the workspace level so the agent always knows which warehouse to target without being told in every prompt.

After connecting, navigate to the Data Browser (left sidebar, table icon) and verify your tables appear. Add descriptions to tables and columns you use frequently. The agent prioritizes tables marked as Endorsed and reads column descriptions when building queries. Five minutes spent adding descriptions saves significant time correcting queries later.

Step 2 — Open the Notebook Agent

Open any Hex project in Notebook view. In the bottom-right corner, click the Ask a question button. This opens the agent sidebar.

Each conversation in the sidebar is a thread. Start a new thread from the + icon at the top right of the sidebar. Keep each thread focused on one task. When context builds up past roughly 70% of capacity, the agent's quality degrades. Starting a fresh thread for a new analysis keeps responses accurate.

Step 3 — Write Your First Prompt

The agent responds to plain English, but specificity matters. Compare these two prompts:

Vague: Analyze our sales data.

Specific: Show me total revenue by product category for January through March 2026, using the orders and products tables. Filter to completed orders only. Group results by week.

The specific version tells the agent which tables to use, what metric to calculate, what filters to apply, and how to group. It will generate a SQL cell that runs correctly on the first attempt more often than vague prompts do.

Use @ mentions to reference specific tables, dataframes already in your notebook, or other cells. Type @ and the table or dataframe name to attach it as context. This is especially useful when you are chaining analyses: the agent can read a dataframe you built in a previous SQL cell and build Python or chart cells on top of it.

Step 4 — Use the Meta-Prompt Technique for Complex Analyses

For multi-step analyses, start with a planning prompt before asking the agent to write any code:

Build a plan for analyzing customer churn over the last 90 days. The plan should identify which tables we need, what steps to run in sequence, and what the final output should look like. Do not write any code yet.

Review the plan, correct any misunderstandings, then say Execute the plan step by step. This prevents the agent from going down the wrong path on complex work and gives you a checkpoint before code runs.

Step 5 — Review Changes Before Confirming

The agent proposes all changes in a diff view before applying them. A Confirm button applies the change; Undo rejects it. Never skip this review step.

Check SQL for correct table and column names. Check Python for logic errors, especially in date calculations and aggregations. Chart cells should be reviewed for axis labels and scales. The agent is accurate most of the time, but it can misread ambiguous column names or apply the wrong aggregation.

Once you confirm a change, it enters your notebook and runs normally. You can edit the resulting cell directly if you need adjustments.

Step 6 — Use the Fix with Agent Feature

When a cell throws an error, click Fix with agent in the error bar. The agent reads the error message, the cell code, and your warehouse schema, then proposes a fix.

For simple syntax errors, use Quick fix instead. It runs faster and handles common issues like mismatched parentheses or undefined variables without spinning up a full agent thread.

Real Workflow Example

A revenue ops manager wants to understand which sales rep regions are underperforming against quota for Q1 2026. Here is how the workflow runs:

1. Open a new Hex project and set the default connection to the company warehouse.
2. Open the agent and prompt: Show me actual ARR closed versus quota by region for Q1 2026, using the deals and quotas tables. Include percentage to quota. Sort by region.
3. Agent generates a SQL cell. Review the diff, confirm, and run.
4. Prompt: Now create a bar chart comparing actual vs quota by region, with a reference line at 100%.
5. Agent generates a Chart cell. Confirm and review.
6. Prompt: Add a markdown summary above the chart that calls out the two lowest-performing regions and their percentage to quota.
7. Agent generates a Markdown cell with the summary pulled from the query results.

Total time from blank notebook to shareable analysis: under 10 minutes.

Sharing Results

Hex projects can be shared as live apps or static snapshots. Click Publish app in the top bar to turn your notebook into a clean, interactive report your stakeholders can view without seeing the underlying code.

Schedule refreshes under the Schedules tab to keep the analysis current. When the underlying data changes, the notebook reruns and the published app updates automatically.

Limitations to Know

The agent does not have access to data outside your connected warehouse unless you upload a file. It cannot browse the internet or pull in external sources on its own. For large tables, scope your queries with date filters and row limits to avoid high warehouse costs. The agent does not enforce cost guardrails automatically.

For analysts who prefer a no-warehouse setup, tools like VSLZ AI let you upload a CSV or connect a file directly and ask questions without configuring a warehouse connection first.

Practical Summary

Hex Notebook Agent is most effective when you give it specific prompts, use @ mentions to scope context, and review every diff before confirming. The meta-prompt technique handles complex multi-step work. The agent covers the gap between having data and having answers, without requiring analysts to write all the code themselves.