BrightAgent Prompting Guide

Last updated: September 10, 2025

BrightAgent is a powerful tool designed to accelerate your path from data to insights. This guide provides an overview of how to setup your Brighthive environment to set BrightAgent for success and prompting tips to effectively use BrightAgent for each type of request.

Recommendations - Setting BrightAgent up for success

  1. Data Asset Descriptions: Check and update data asset descriptions. BrightAgent automatically populates your data asset description, but you can make changes/edits to add more business context.

  2. Data Asset Schemas: Use BrightAgent's governance feature to update descriptions for your schema columns. This ensures columns are clear, consistent, and enriched with business context.

  3. Glossary: Add terms related to your business context under Glossaries to maintain a unified understanding of business terms across teams.

  4. State Data Asset Name: Be clear about the data asset you would like BrightAgent to work on.

1. Governance

BrightAgent supports governance-focused tasks to help ensure your datasets are both high-quality and well-documented. These features let you validate, describe, and better manage your data assets.

Data Quality Test

Validates a dataset against expectations to identify potential quality issues such as missing, invalid, or inconsistent data.

Example Prompts:

- Perform a data quality test on my insurance dataset
- Validate the healthcare dataset for null values or formatting issues
- Run a data quality check on the transactions dataset to detect anomalies

Metadata

Automatically generates concise, AI-powered column descriptions for your datasets. This makes your data more discoverable and easier to understand across teams.

Example Prompts:

- Write data documentation for my insurance dataset
- Generate column descriptions for the marketing spend dataset
- Create metadata documentation for the property claims dataset

2. Retrieval

BrightAgent can generate insights by answering a wide range of questions about your dataset. These questions can include broader topics such as trends, retention rates, or aggregated metrics. When asking a question, clearly specify the data asset BrightAgent should use and the type of information you need. You can then select the data asset that BrightAgent should use to answer your queries.

Example Prompts:

- What is the retention rate of customers over the past three years based on the CRM dataset?
- From the property claims dataset, what are the most common causes of preventable losses?
- Using web analytics data, what are the trends in total web revenue across years?
- Based on the healthcare dataset, what is the average patient wait time in the Emergency department?

BrightAgent will return a table or visualization that matches your query.

3. Visualization

BrightAgent supports creating visualizations.

Example Prompt:
Using the crm dataset, create a line chart of deal values over the months for each industry.

How to Write a Great Visualization Prompt:

  • [Required] Data Asset Name:
    Clearly specify the dataset you want to use (e.g., “using the crm dataset”).

  • [Optional] Chart Type:
    If you have a preferred chart type, mention it (e.g., “line chart”).

  • [Required] X-Axis:
    Clearly state the variable for the x-axis.
    Tip: For time series, specify the time period (e.g., day, month, week, year).

  • [Required] Y-Axis:
    Clearly state the variable for the y-axis (e.g., “deal values”).

  • [Optional] Grouping:
    Mention any variable you want to group or segment by (e.g., “for each industry”).

Here are some example prompts:

- Use the retail dataset. Visualize customer distribution across segments.
- Using the education dataset, create a line chart showing the number of student enrollments over the months.
- Visualize the distribution of deal values across different industries.
- Create a line chart showing the number of orders each month from the web analytics dataset.
- Create a line chart of enrollment trend over time (e.g., by semester or year) from the Blackwood Academic students dataset based on their year of entry.

BrightAgent will generate a chart or graph (e.g., bar chart, pie chart) to represent the data visually. Current supported visualizations include: bar charts, pie charts, line charts, scatter plots and area charts.

4. Engineering

BrightAgent can help you write dbt (data build tool) code for your data transformation needs. To use this feature, follow the steps below and be as specific as possible about the data sources, fields, and logic.

There are two use cases for writing the dbt agent:

  1. Retrieving raw data, creating DBT models, and committing them to GitHub

  2. Retrieving transformed datasets, visualizing them, and optionally downloading or ingesting the results

Authentication

  • Option 1 - GitHub Auth Flow

  • Option 2 - Personal Access Token (prerequisites only apply to this option)

    • Follow the steps below:

      • Log in to GitHub: Go to github.com and sign in to your account.

      • Go to Settings: Click your profile picture in the top right, then select Settings.

      • Access Developer Settings: Scroll down in the left sidebar and click on Developer settings.

      • Personal Access Tokens: Under Developer settings, click Personal access tokens. Then choose Tokens (classic) or Fine-grained tokens (GitHub now recommends fine-grained tokens for better security).

      • Generate New Token: Click Generate new token (or Generate new token (classic) if you want the classic type).

      • Configure the Token: Name your token for easy identification. (eg BrightAgent)

      • Set expiration (recommended: set an expiration date).

      • Select scopes/permissions you need:

        • Full control of private repositories (Full control of private repositories)

      • Generate and Copy the Token: Click Generate token at the bottom. Copy the token immediately—you won’t be able to see it again!

Using the DBT Agent: Retrieve Raw Data, Create DBT models and Commit to Github

  1. Retrieve the data asset. 

    Retrieve the hubspot_contact dataset for me

    1. This step is crucial to add data assets to the context of BrightAgent

  2. Trigger the dbt agent e.g. "Write me a dbt query" to bring up the Engineering Agent

    1. GitHub Authentication

    2. dbt Query Selection Form:

      - Write me a dbt query on the hubspot dataset to find the count of leads by lifecycle stage
- Generate me dbt code on web analytics data to create a table of metrics calculated daily. Pull these metrics together. The metrics are (i) Conversion Rate: SUM(is_converted) / COUNT(visit_id) and (ii) Abandoned Cart Rate: SUM(is_abandoned_cart) / COUNT(visit_id)

    3. dbt Model Review & Commit Form

BrightAgent will generate the appropriate dbt SQL code based on your description.

Our dbt Agent works directly in your dbt Git repository. To interact with your repository successfully, you will need to set up your personal token.

5. Analytics

(In Development) BrightAgent can help create analytical workflows in Jupyter notebooks. You can request complete data analysis processes including data loading, cleaning, exploration, visualization, and modeling.

Example Prompt:

- Create a Jupyter notebook analysis to identify customer churn patterns based on usage data and demographic information.
- Create a Jupyter notebook performing regression analysis on grades against other factors.

BrightAgent will generate a structured notebook with code cells and markdown explanations for a comprehensive analysis workflow.

Tips for Effective Prompting

  1. Be Specific: Clearly describe what you need, including any filters, groupings, or timeframes.

  2. Iterate as Needed: If the output isn’t exactly what you need, refine your prompt or provide additional details based on your knowledge of the dataset.

By following this guide, you can make the most of BrightAgent’s capabilities and streamline your data-related tasks.