How to Set Up Hex Notebook Agent for Analysis

Hex's Notebook Agent writes SQL, runs Python, and builds charts based on a plain-English description typed directly into a data notebook. Unlike AI copilots layered on top of BI tools, it works from your actual warehouse schema, so every query it generates points to real tables. Setup takes roughly 15 minutes for a standard workspace and covers three steps: connecting a data source, configuring what the agent can see, and adding a context file that explains your business logic.

What the Notebook Agent Does

The Notebook Agent is a cell-level AI that creates and modifies Python, SQL, Markdown, Pivot, and Chart cells based on your prompts. It is not a query autocomplete tool. When you describe an analysis goal, it reads your connected schema, identifies the relevant tables, writes the logic, and populates a notebook cell with the result. If the output contains an error or returns unexpected data, you can tell the agent to fix it and it revises the cell in place.

In its Fall 2025 product launch, Hex upgraded the Notebook Agent to run on Anthropic's Claude Sonnet model, citing improvements in speed, multi-step task handling, and complex analytical reasoning. The upgrade rolled out to all paid plans. This means the agent now handles tasks that previously required multiple prompt iterations, such as chaining a data cleaning step with a statistical summary in a single request.

Accuracy depends heavily on workspace configuration. An unconfigured workspace, one with no table descriptions, no endorsed data, and no context file, produces queries that may reference the wrong table when two schemas share similar column names. A configured workspace behaves like an analyst who already understands your data model.

Step 1: Connect a Data Warehouse

Hex supports connections to BigQuery, Snowflake, Redshift, Databricks, PostgreSQL, MySQL, DuckDB, and several other warehouses. To add a connection:

1. Navigate to Settings > Connections in your Hex workspace.
2. Select your warehouse type and enter credentials. For Snowflake, you need your account identifier, warehouse name, database, role, and authentication method.
3. After connecting, open the connection's AI settings and enable it for agent use.
4. Set a schema filter. If your warehouse contains multiple schemas, limit the agent to the ones relevant to your current work. A large unfiltered schema increases the chance of the agent selecting the wrong table.

Enable scheduled schema refreshes under connection settings. Stale schema information is a documented cause of incorrect query generation, because the agent may reference tables that have been renamed or columns that no longer exist.

Step 2: Configure Agent Context

Three settings determine the Notebook Agent's usefulness from day one.

Endorse trusted data. In the Data Browser, you can mark databases, schemas, or individual tables as endorsed. The agent prioritizes endorsed objects when generating queries. If your warehouse has a raw events schema and a cleaned analytics schema, endorsing the analytics schema steers the agent toward the approved version of your data.

Add descriptions to tables and columns. Open any table in the Data Browser and add a plain-English description of what it contains and how it is used. For columns, list possible values where useful: "status: one of 'active', 'churned', or 'trial'." If you use dbt Cloud, Hex can sync descriptions automatically without manual entry.

Add a workspace context file. This is the highest-leverage configuration step. In Settings > AI > Workspace context, paste a Markdown document that explains your business logic, key metric definitions, and naming conventions. Useful entries include: "MRR is calculated from the subscriptions table, not the invoices table" or "customer_id maps to accounts.id, not users.id." This file acts as an onboarding document the agent reads before every analysis.

Step 3: Run the Notebook Agent

With a warehouse connected and context configured, open any Hex project and press Cmd+K on Mac or Ctrl+K on Windows and Linux to open the Notebook Agent prompt bar. From here you can:

• Type a full analysis description to have the agent scaffold an entire project
• Select an existing cell and ask the agent to revise or explain it
• Ask debugging questions: "this query returns duplicate rows, what is the likely cause?"
• Request a chart from an existing SQL result

The agent can read all cells in the current notebook, so it can build on previous results. A practical starting workflow: describe the full analysis goal in one prompt, review what the agent scaffolds, then refine individual cells using the cell-level chat (the sparkle icon on each cell). Keep iterations narrow; fixing one cell at a time prevents compound errors.

The agent currently creates and edits Python, SQL, Markdown, Pivot, and Chart cells. It does not modify published app layouts, but it can modify the underlying logic those apps depend on.

Prompting Patterns That Produce Better Results

The quality of agent output scales directly with prompt specificity. Four patterns that consistently work:

Anchor prompts to a defined metric. Instead of "show me sales data," write "calculate total gross revenue by month for 2025, excluding refunded orders, grouped by product category." Specifying what to include, what to exclude, and how to group produces accurate SQL on the first attempt more often than open-ended requests.

Request an interpretation alongside the query. Appending "and add a markdown cell explaining the trend" to any analysis prompt tells the agent to write the SQL and then interpret the result in plain English. This is useful for analysis that will be shared with stakeholders who will not read the SQL itself.

Use @ mentions to anchor the agent. Using @ to reference specific tables or cells in your prompt helps the agent focus on the correct data source rather than searching the full schema. For example, "@subscriptions table: calculate monthly churn rate for the last six months" is faster and more reliable than a general request about churn.

Keep threads short. Long conversation threads reduce agent accuracy. Start a new thread for each major analytical step rather than continuing a single thread across an entire project. This is consistent with how most agentic tools behave: context length and recency both affect output quality.

What the Agent Does Not Replace

The Notebook Agent accelerates structured query generation, chart creation, and iterative data exploration. It is weaker on decisions that require business judgment: determining which metrics actually matter for a specific question, interpreting a result against external context the agent cannot see, or designing a statistically valid test.

SQL generated by the agent should be checked before it flows into a shared dashboard. A common failure mode is joining tables on non-unique keys, which inflates row counts. Running a COUNT(*) sanity check after any multi-table join takes ten seconds and catches this class of error reliably.

Time and row filters reduce query costs when working with large tables. Applying a 30-day time filter during exploration and widening it only after the logic is confirmed keeps warehouse compute costs predictable during development.

Threads: Conversational Analysis for Non-Technical Users

Hex also ships Threads, a conversational interface designed for business users who need data answers without writing SQL. Threads uses the same agent framework and workspace context as the Notebook Agent, so configuration work done in Step 2 carries over. A user types a question, and Threads generates a chart or table from curated semantic models defined by an admin.

Setting up Threads requires creating at least one semantic model that defines approved metrics and their underlying SQL. The Modeling Agent in Hex can assist with this step. Once active, Threads is particularly useful for ops managers and founders who need repeatable answers to standard business questions without depending on a data analyst for each request.

The two tools are complementary: analysts use the Notebook Agent for exploratory and ad hoc work, while Threads serves recurring questions from non-technical users against approved data.

Summary

Setting up Hex's Notebook Agent takes three steps: connect a warehouse, endorse trusted tables and add descriptions, and create a workspace context file with your business logic. The configuration is front-loaded; once complete, the agent generates accurate SQL and Python from plain-English prompts and reduces the time required for routine exploratory analysis. For teams that do not have an existing warehouse to connect, VSLZ AI handles the same type of analysis from a direct file upload with no connection setup required.