Skip to main content

Notebook Agent best practices

This guide is designed to help you get the most out of the Hex Notebook Agent. The agent can generate and edit cells directly in your notebook, and it can also act as a thought partner that explains, summarizes, and guides.

This guide outlines patterns that have proven effective for getting the most out of the Notebook Agent. Nothing here is set in stone or universally applicable; think of these as starting points! We encourage you to experiment and adapt them to your own workflows.

Getting Started​

We have a few go-to prompts!

"What can you help me with?" - The agent will return a quick summary of its capabilities, giving you an overview of how it can assist

"Can you help me brainstorm {your question}" - Use this when you're not sure how to approach a problem. The agent can suggest directions or frameworks for getting started, and is a great iterative thought partner during the analytical process.

"Can you perform a basic EDA for {@ mention a table}" - If you know what table you want to start an analysis from, have the agent perform your upfront exploratory data analysis. It can easily pull summary statistics and synthesize the data to help you get started faster.

Mindset​

Treat the agent as a partner, not a replacement. You are the manager of its work! The most effective way to use it is to start broad, get a first draft, and then refine. Always validate the outputs the same way you would review a teammate's SQL or Python.

How Data Practitioners Use The Agent​

There are two common patterns for working with the Notebook Agent. You can combine them fluidly depending on your needs.

Agentic Data Work: Have the agent generate or edit SQL, Python, and Markdown. Example: "Write a query that calculates weekly active users, filtered to the last 30 days, and add a chart."

Thought Partner: Ask the agent to explain or summarize work, or propose next steps. If you explicitly want the agent to avoid creating cells, mention that in the prompt. Examples:

  • "Explain this SQL query in plain language."
  • "Can you suggest three ways to validate the results of this analysis?"
  • "What features should I add into this data app in the next iteration given my stakeholders' goals of XYZ?"

Clear and Specific Prompts​

The more specific you are, the better the agent will perform!

❌ Less effective: "Analyze our customer data."

✅ More effective: "Analyze our customer data from the last 30 days using the orders and customers tables. Focus on churn by product tier and highlight anomalies."

💡Tip: You can reference specific cells in your notebook with @ mentions. For example: "Using the results from cell_name, calculate churn rate by week and visualize it as a line chart." Referencing cell names or data frames helps the agent know exactly what to look at! If you select the cell, you can autocomplete the reference by tabbing.

Reviewing Changes​

All changes the agent makes are highlighted with a diff view that you need to keep or undo. A set of changes can be confirmed all together, or kept one cell at a time. While changes are proposed in the diff view, you can edit the contents directly and rerun the output to make tweaks before keeping the changes.

If you ask a follow-up question without confirming your changes, changes will be stacked and left in a pending state until keeping. We recommend keeping changes as soon as you're happy with them and not letting changes stack up too long. If you don't want to keep the changes, you can undo them cell by cell or undo all.

Iterative Refinement​

The agent works best in an iterative loop. Start with a high-level ask, check the output, then refine. Ask for alternatives before committing. Example: "Propose three approaches for analyzing retention." Then pick one: "Use option #2 and filter to users who joined in the last 90 days." Then refine: "Add comments to the SQL and create a bar chart of monthly cohorts."

Managing Query Costs​

The agent can run queries directly on your warehouse just like a human Hex user. We recommend scoping queries to avoid unnecessary costs. Apply time filters and row limits up front. Start with small samples until the shape looks right, then expand. Document expensive tables in the warehouse with descriptions like "always filter to the last 30 days" so the agent has guidance.

Using Metadata and Rules​

The agent performs better when the environment is well documented and it has access to data that is clean, curated, and contextual. Add table and column descriptions in the Data Browser so it knows the grain, keys, and intended use. Encode defaults in your Hex rules file, such as standard filters, naming conventions, and details about your business and data models. These help the agent remember your preferences across tasks!

For a full guide, see Workspace Rules: Best Practices.

Session Management​

We recommend keeping threads focused on a single task, and for new topics start a new thread. As threads get longer, it can cause quality of responses to degrade, so whenever you have a new question, start a new thread. You also have a version saved on every new thread, making it easy to trace back in time if you don't like the output of a session.

Context Window and Compression​

The agent automatically summarizes the conversation when about 70% of the context window is reached. While you can technically continue a very long conversation without hitting a hard stop, we recommend periodically starting a new thread when you begin a new or major analysis step. This helps preserve clarity and ensures the agent has the right context to work with.

Reviewing and Trust​

Do not blindly trust outputs; always read the SQL or Python before relying on it! Reproduce results with a smaller sample or a secondary check. Ask the agent to explain assumptions or summarize risks. If something looks off, tell it exactly what and why, then re-prompt for a fix.

FAQ​

Can the agent run queries on my warehouse?

  • Yes!

Who can use the notebook agent?

  • Editors+ roles in Hex have access to the notebook agent.

Can I prevent the agent from writing code / keep it in thought partner mode?

  • Yes. Ask for a plan first: "Outline your approach before creating cells." or explicitly tell the agent you only want to brainstorm, not create.

What if the agent makes a mistake?

  • Delete or undo the cell, re-prompt with specifics, and validate outputs before using them.

How do I provide feedback on the agent?

  • After the agent generates a response, you will see a 👍👎 - providing feedback is very useful for improving performance.

On this page