How to Set Up the Hex Notebook Agent

What the Hex Notebook Agent does

The Hex Notebook Agent is an AI-powered assistant embedded directly in the Hex data workspace. It reads your project context, understands your connected data schema, and generates working SQL, Python, charts, and dashboard components from natural language instructions. Instead of writing queries from scratch, you describe what you want to see and the agent produces notebook cells that you can review, edit, and run.

Hex positions the agent as a collaborator rather than a replacement. It handles the repetitive parts of analysis, such as writing boilerplate SQL, formatting chart axes, or chaining multiple query steps, while you focus on interpreting results and making decisions. The agent is powered by Claude Sonnet 4 and operates within the constraints of your warehouse schema and workspace rules, so outputs stay grounded in your actual data.

Why this matters for data teams

Analysts spend a disproportionate amount of time on mechanical tasks: looking up column names, writing joins, reformatting outputs, and rebuilding the same types of charts. The Notebook Agent compresses that cycle. A query that might take 10 minutes to write and debug can be generated in seconds, reviewed, and refined through follow-up prompts.

For teams where only one or two people know SQL well, the agent also lowers the barrier. A product manager or ops lead can open a Hex project, describe what they need, and get a working starting point without waiting in a request queue.

Prerequisites

Before setting up the Notebook Agent, make sure you have the following ready.

A Hex account on any paid plan. The free tier lets you explore the platform, but AI features require a paid plan with monthly AI credit grants. Hex offers Professional, Team, and Enterprise tiers.

A supported data warehouse connection. Hex connects directly to Snowflake, BigQuery, Redshift, Databricks, PostgreSQL, and several other sources. You will need connection credentials (host, port, database, user, password or key) from your data platform.

Admin or editor permissions in your Hex workspace. AI features are toggled at the workspace level by an admin. If you are not the workspace admin, you will need them to enable the AI settings before you can use the agent.

Step 1: Create your Hex account

Go to hex.tech and click "Get started." You can sign up with a work email or SSO. After account creation, you land in your workspace dashboard where projects, data connections, and settings are organized.

If you are joining an existing team workspace, ask your admin for an invite link. This ensures you inherit the correct data connections and permissions rather than starting from zero.

Step 2: Connect your data source

Navigate to the "Data sources" section in your workspace settings. Click "New connection" and select your warehouse type. Hex supports direct connections to Snowflake, BigQuery, Redshift, Databricks, PostgreSQL, MySQL, Trino, Athena, and more.

Fill in the required credentials. For Snowflake, this includes account identifier, warehouse, database, schema, and authentication details. For BigQuery, you upload a service account JSON key. Hex tests the connection automatically and confirms access to your tables.

A connected data source is essential because the Notebook Agent uses your schema context, including table names, column types, and relationships, to generate accurate queries. Without a live connection, the agent has no data to work with.

Step 3: Enable AI features

Go to "Settings" then "AI & Agents" in your workspace admin panel. Here you control which AI capabilities are active across the workspace. Toggle on the Notebook Agent, Typeahead (inline code completions), and optionally Threads (a conversational interface for non-technical users to query endorsed data).

You can also configure workspace-level rules that guide the agent's behavior, such as preferred SQL dialects, naming conventions, or specific tables to prioritize. Enterprise plans support Bring Your Own Key (BYOK) if your organization requires routing AI requests through its own API agreements.

Each seat on a paid plan receives a monthly AI credit allocation. Credits are consumed per agent interaction. Admins can monitor usage through Context Studio, which shows how credits are distributed across users and projects.

Step 4: Create your first project and use the agent

Click "New project" from your workspace dashboard. You land in the Hex notebook editor, a reactive environment where cells execute in dependency order. The Notebook Agent appears as a sidebar panel on the right.

Type a natural language instruction into the agent panel. For example: "Show me total revenue by region for the last 12 months as a bar chart." The agent reads your connected schema, generates a SQL cell to pull the data, and creates a chart cell to visualize it. Both cells appear in your notebook, fully editable.

You can refine results through follow-up prompts. Say "Break that down by product category" or "Add a filter for orders over $500." The agent modifies existing cells or creates new ones as needed. It also handles Python cells if your analysis requires statistical computation, data transformation, or custom logic that goes beyond SQL.

Step 5: Work with advanced agent features

The Notebook Agent goes beyond basic code generation. Here are capabilities that become useful as your projects grow.

Input parameters and filters. Ask the agent to add dropdown or date-range filters. It creates input parameter cells and automatically wires them into downstream SQL queries, so your notebook becomes an interactive dashboard without manual configuration.

Chart styling. The agent handles chart formatting, including axis labels, color schemes, and layout adjustments. Describe the styling you want in plain English and the agent applies it to existing chart cells.

Single value cells. For executive summaries or KPI dashboards, the agent can generate single-value display cells that show headline metrics like "Total ARR: $4.2M" pulled from live queries.

Notebook organization. Over time, notebooks accumulate unused cells and redundant queries. The agent can identify and remove dead cells, group related cells into sections, and clean up the project structure.

Step 6: Publish and share your work

Once your analysis is ready, click "Publish" to create a shareable app. Hex converts your notebook into a clean, interactive interface where stakeholders can use filters, explore charts, and read summaries without seeing the underlying code.

Published apps update automatically when the underlying data refreshes. You can also schedule notebook runs on a cadence (daily, weekly, or hourly) so dashboards stay current without manual intervention.

For teams that need conversational access to published work, enable the "Chat with App" feature. This lets consumers of a published app ask follow-up questions, adjust filters, and summarize what they see, all through natural language.

Tips for getting reliable results

Write specific prompts. "Show revenue" is vague. "Show monthly recurring revenue by customer segment for Q1 2026, filtered to accounts with ARR above $10K" gives the agent enough context to produce accurate SQL on the first try.

Review generated queries before running them. The agent produces syntactically correct code, but a valid query can still return misleading results if it joins tables incorrectly or applies the wrong aggregation. Always inspect the logic.

Use workspace rules to encode your team's conventions. If your team always filters out test accounts or uses a specific date column, set those as workspace-level rules so the agent applies them by default.

Start with a single, well-scoped question per prompt. Chaining multiple requests in one instruction can confuse the agent. Break complex analyses into sequential steps.

When to consider alternatives

Hex is designed for teams that have a data warehouse and need a collaborative analytics environment. If your data lives primarily in spreadsheets or CSV files and you do not use SQL, a tool built for file-based analysis may be a better starting point. If you want to skip warehouse setup entirely, platforms like VSLZ let you upload a file, describe what you need in plain English, and get end-to-end analysis from a single prompt.

For teams already embedded in the modern data stack with dbt, a warehouse, and version-controlled analytics, Hex and its Notebook Agent fit naturally into that workflow.

Summary

Setting up the Hex Notebook Agent takes about 15 minutes if your data warehouse credentials are ready. Create an account, connect your data, enable AI in workspace settings, and start prompting. The agent handles SQL generation, chart creation, and notebook organization while you focus on the analytical decisions that require human judgment. As your team grows, features like Threads, published apps, and scheduled runs extend the value beyond the initial analyst who set it up.