How to Set Up Hex Notebook Agent for Analytics

Hex's Notebook Agent turns a shared analytics workspace into an AI-powered environment where analysts can describe what they need in plain English and receive working SQL queries, Python transformations, and charts without writing code manually. The agent runs inside an existing Hex project, reads the actual schema and notebook context automatically, and can be activated in minutes after connecting a data source.

This guide covers every step: account setup, data connection, notebook creation, and Notebook Agent activation, along with practices for getting consistent results from agentic prompting.

What Hex Is and Why the Notebook Agent Matters

Hex is a collaborative analytics platform where teams work in a shared notebook containing SQL cells, Python cells, no-code chart cells, and text together in one document. Results from a SQL query become a dataframe that a subsequent Python cell can transform; output from Python can feed into a built-in chart cell without any export or copy-paste. This is different from traditional BI tools that separate the querying layer from the visualization layer.

The Notebook Agent, introduced in August 2025 and updated through April 2026, adds an AI layer that operates on top of this unified canvas. Instead of prompting a generic large language model that has no knowledge of your schema, the Notebook Agent reads the active project, including all cells, queries, and outputs, before generating any code. This grounding in real context produces more accurate suggestions than pasting schema details into a chat interface.

Hex's State of Data Teams 2026 report found that 24% more respondents named AI and automation a top priority compared with the previous year, with data trust cited as the primary concern holding teams back. The Notebook Agent addresses trust by making its reasoning visible: every suggestion is written as a code cell the analyst can review, edit, or delete before running.

Prerequisites

Before starting, confirm the following:

• A Hex account (the Community plan is free and sufficient for this guide)
• A data source to connect (Snowflake, BigQuery, Redshift, PostgreSQL, DuckDB, MotherDuck, or a CSV upload all work)
• Editor-level workspace permissions (the Notebook Agent requires Can Edit or higher on the project)

Step 1: Create a Hex Account and Workspace

Go to hex.tech and click Get started. Sign up with a Google account or a work email. After confirming the email, Hex creates a personal workspace.

The Community plan includes notebooks, SQL support, published apps, and lightweight compute at no cost. For teams that need shared workspaces, custom compute, or advanced permissions, the Professional plan starts at $36 per editor per month. The Community plan is sufficient for this guide.

Step 2: Connect a Data Source

Navigate to Settings in the left sidebar and select Data connections. Click Add connection and choose your database or warehouse from the list. Hex supports over 30 connections including Snowflake, BigQuery, Redshift, PostgreSQL, MySQL, Databricks, MotherDuck, and local DuckDB.

For each connection, Hex prompts for credentials and tests the connection before saving. Snowflake connections require an account identifier, warehouse name, database, schema, username, and password or key-pair authentication. PostgreSQL connections require host, port, database name, and credentials.

If you have no warehouse and want to test immediately, Hex supports uploading a CSV file as a DuckDB data source. Click Add connection, select DuckDB, and upload a local file. Hex registers it as a queryable table with no additional configuration.

Once saved, the connection appears in the Data connections panel and becomes available inside any new or existing notebook.

Step 3: Set Up a Notebook

Click New project in the workspace sidebar. Hex opens a blank notebook with a single empty cell. Name the project using the title field at the top.

Add a SQL cell by clicking the + button and selecting SQL. In the connection dropdown inside the SQL cell, select the data source connected in Step 2. Write a basic query such as SELECT * FROM your_table LIMIT 10 and click Run. The output appears as a table directly below the cell, and Hex stores it as a dataframe named after the cell, available for use in subsequent cells.

For the Notebook Agent to give useful suggestions, add a markdown cell at the top of the notebook describing the dataset and the analysis goal. For example: "This notebook analyzes Q1 sales by region using the orders table. The goal is to identify top-performing SKUs and flag month-over-month declines." This context travels with the notebook and primes the Agent before it reads any code.

Step 4: Activate the Notebook Agent

The Notebook Agent appears in the bottom-right corner of any project as an Ask a question icon. Click it to open the agent sidebar.

The first time the Agent is opened, Hex asks for confirmation that AI features are enabled for your workspace. Admins can toggle this in Settings under Workspace settings, then AI features. Once enabled, the Agent is available to any user with Editor permissions on the project.

To start a thread, click the + icon at the top of the Agent sidebar. Type a plain-English request describing what you need. For example: "Create a bar chart showing total revenue by region for Q1" or "Identify the top 10 customers by order count and calculate their average order value."

The Notebook Agent reads the full project context, identifies relevant cells, generates the appropriate SQL or Python, and adds a new cell to the notebook with the proposed code. The cell is not run automatically. You review it, make any edits, and run it manually. If the output differs from what was expected, reply in the thread and the Agent revises its approach.

Starting a new thread with the + icon clears the conversation context. Use this when switching to a different analysis question so the Agent does not carry forward assumptions from a prior conversation.

Step 5: Prompting the Notebook Agent Effectively

The Notebook Agent performs best with specific, bounded requests. Three practices produce consistently better results.

First, describe the output you want rather than the steps to get there. "Show average session duration by user cohort as a line chart" works better than "write Python to group users and calculate duration then plot it."

Second, reference tables and columns by their exact names when known. The Agent reads the schema automatically, but specifying "the orders.created_at column" removes ambiguity on complex joins.

Third, iterate in the thread rather than re-prompting from scratch. If the first suggestion returns incorrect columns, reply with "update to include product_name and exclude returns" rather than rewriting the original request. The Agent maintains thread context and produces smaller, targeted changes.

Hex's April 2026 update introduced automatic user memory, which allows the Agent to remember recurring patterns and preferences across sessions. Over time it learns preferred chart types, column naming conventions, and formatting standards, reducing the back-and-forth needed to produce a clean result.

Step 6: Publish as a Data App

Once the notebook contains the completed analysis, Hex can publish it as an interactive data app that non-technical stakeholders can view and use without any code access.

Click the Publish button at the top right of the notebook. Hex generates a shareable URL and renders the notebook as a clean application where viewers can interact with input parameters, adjust filters, and see updated outputs without touching the underlying cells.

Published apps update automatically when the connected data source refreshes, so a weekly sales summary continues to show current numbers without any manual re-run.

Practical Summary

Hex Notebook Agent is a practical tool for teams that want AI-assisted analytics without leaving the environment where analysis already happens. The setup is lightweight: a free account, one data connection, and a notebook is enough to start prompting. The Agent's grounding in real project context and its transparent cell-based output make it more auditable than generic chatbot-style analytics tools. For analysts already comfortable with SQL or Python, the Notebook Agent accelerates the exploratory phase without removing control over what runs against the database.

If you want to skip the connection setup entirely and work directly from a file upload, VSLZ handles end-to-end analysis from a single file drop, returning queries, charts, and statistical summaries from one plain-English prompt with no configuration required.