Add a Genie Agent resource to a Databricks app

Add Genie Agents as Databricks Apps resources to enable natural language querying in your applications. Genie Agents provide a conversational interface for data exploration, allowing users to ask business questions in plain English and receive SQL-based insights from your curated datasets.

When you add a Genie Agent as a resource, your app can:

  • Convert natural language queries from users into SQL
  • Access pre-configured business context and metadata
  • Use curated sample queries and data definitions
  • Generate responses based on your organization's datasets

Add a Genie Agent resource

Before you add a Genie Agent as a resource, review the app resource prerequisites.

  1. In the App resources section when you create or edit an app, click + Add resource > Genie Agent.
  2. Choose a Genie Agent from the list of available spaces in your workspace.
  3. Select the permission level for your app:
    • Can view: Grants the app permission to read the Genie Agent configuration and metadata.
    • Can run: Grants the app permission to submit queries to the Genie Agent and receive responses.
    • Can edit: Grants the app permission to modify the Genie Agent configuration.
    • Can manage: Grants the app full administrative access to the Genie Agent.
  4. (Optional) Specify a custom resource key, which is how you reference the Genie Agent in your app configuration. The default key is genie-space.

When you add a Genie Agent resource:

  • Azure Databricks grants your app's service principal the specified permissions on the selected Genie Agent.
  • The app can submit natural language queries to the agent and receive structured responses with SQL queries and results.
  • The app accesses the agent's curated business context, including metadata, sample queries, and data definitions.
  • Access is scoped to the selected agent only. Your app can't access other Genie Agents unless you add them as separate resources.

Note

The app's service principal also needs appropriate permissions on the underlying data sources that the Genie Agent queries. This typically includes USE CATALOG, USE SCHEMA, and SELECT permissions on the relevant Unity Catalog tables and views.

Environment variables

When you deploy an app with a Genie Agent resource, Azure Databricks exposes the space ID through environment variables that you can reference using the valueFrom field in your app.yaml configuration.

Example configuration:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space # Use your custom resource key if different

Using the space ID in your application:

import os
from databricks.sdk import WorkspaceClient

# Access the Genie Agent using the injected environment variable
space_id = os.getenv("GENIE_SPACE_ID")

# Initialize the workspace client
w = WorkspaceClient()

# Start a conversation with a natural language query
response = w.genie.start_conversation_and_wait(
    space_id=space_id,
    content="What were our top-selling products last quarter?"
)

# Process the response (responses contain attachments with text, queries, and so on)
for attachment in response.attachments:
    print(f"Genie response: {attachment.text.content}")

# Continue the conversation with additional questions
follow_up = w.genie.create_message_and_wait(
    space_id=space_id,
    conversation_id=response.conversation_id,
    content="Can you break that down by product category?"
)

For more information, see Access environment variables from resources.

Remove a Genie Agent resource

When you remove a Genie Agent resource from an app, the app's service principal loses access to the agent. The Genie Agent itself remains unchanged and continues to be available for other users and applications that have appropriate permissions.

Combine Genie Agents with other app resources

Combine Genie Agents with other Databricks Apps resources to create more sophisticated data applications. Common integration patterns include:

Natural language analytics dashboard

Use the following resources together to run interactive analytics:

  • Genie Agent: Converts user questions into SQL queries
  • SQL warehouse: Runs the queries and returns results for visualization
  • Secrets: Stores API keys for external visualization tools

Example configuration:

env:
  - name: GENIE_SPACE_ID
    valueFrom: genie-space
  - name: SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: EXTERNAL_API_KEY
    valueFrom: viz-secret

AI-enhanced business intelligence

Use the following resources to integrate with AI models:

  • Genie Agent: Generates the initial query and data context
  • Model serving endpoint: Returns AI-generated summaries and recommendations
  • SQL warehouse: Runs complex analytical queries

Service principal permissions

Grant your app's service principal the following permissions when integrating with other app resources:

  • CAN RUN on the Genie Agent
  • CAN USE on the SQL warehouse (if using a separate one from the Genie Agent)
  • CAN QUERY on model serving endpoints
  • USE CATALOG and USE SCHEMA on relevant Unity Catalog objects
  • SELECT on tables the app queries directly

Best practices

Follow these best practices when you work with Genie Agent resources:

  • Grant minimal permissions. Only provide access to the specific Genie Agents your app needs to function.
  • Ensure the Genie Agent contains well-curated datasets and metadata to improve the quality of natural language query responses.
  • Test your app's queries against the Genie Agent to validate that it can generate accurate results for expected user questions.
  • Monitor query performance and adjust your app's interaction patterns with the Genie Agent to optimize response times.
  • Implement error handling for cases where the Genie Agent can't interpret or respond to user queries effectively.
  • Last updated on