DatabricksAgent — Conversational AI Agent on Databricks Sample Data

A production-pattern AI agent built with the OpenAI Agents SDK, deployed as a Databricks App with a Gradio chat UI. Queries the built-in samples.tpch dataset — no external catalog or custom tables required.

Architecture

• Agent framework: OpenAI Agents SDK
• LLM: Databricks Model Serving (Llama 3.3 70B or equivalent)
• Data: samples.tpch via Databricks SQL Connector
• Auth: Databricks Apps OAuth (no PAT, no secrets in code)
• Tracking: MLflow experiment logging
• UI: Gradio ChatInterface
• Deployment: Databricks Apps

Prerequisites

• Databricks workspace with Apps enabled
• samples catalog accessible (verify: SELECT * FROM samples.tpch.orders LIMIT 5)
• A SQL Warehouse (Serverless Starter works)
• A model serving endpoint (e.g. databricks-meta-llama-3-3-70b-instruct)

Repository Structure

DatabricksAgent/
├── AGENTS.md              ← Codex instruction file (generates this codebase)
├── app.py                 ← Gradio chat UI entry point
├── app.yaml               ← Databricks Apps config
├── requirements.txt
├── agent/
│   ├── tools.py           ← 4 @function_tool SQL tools
│   ├── agent.py           ← Agent + AsyncOpenAI client
│   └── runner.py          ← run_query() + MLflow wrapper
└── notebooks/
    ├── 00_setup_and_verify.py
    ├── 01_define_tools.py
    ├── 02_build_agent.py
    ├── 03_run_interactive.py
    └── 04_mlflow_log_and_test.py

Setup — Step by Step

1. Clone into Databricks Repos

In your Databricks workspace:

• Go to Workspace > Repos > Add Repo
• Paste this repo URL
• Connect with a GitHub PAT (repo scope)

2. Create a Cluster

• Runtime: Databricks ML Runtime 15.x (must be ML, not standard)
• Type: Single node is sufficient

3. Run Notebooks in Order

Notebook	Purpose
00_setup_and_verify.py	Verify samples catalog access
01_define_tools.py	Test all 4 SQL tools
02_build_agent.py	Confirm agent configuration
03_run_interactive.py	Run 5 test questions end-to-end
04_mlflow_log_and_test.py	Log model to MLflow

4. Configure app.yaml

Replace YOUR_WAREHOUSE_ID with your SQL Warehouse ID:

env:
  - name: DATABRICKS_WAREHOUSE_HTTP_PATH
    value: /sql/1.0/warehouses/YOUR_WAREHOUSE_ID

Find your warehouse ID under SQL Warehouses > Connection details > HTTP Path.

5. Deploy as Databricks App

• Go to + New > App
• Name your app
• Click Deploy > From workspace
• Set path to /Workspace/Repos/YOUR_EMAIL/DatabricksAgent
• Click Deploy

6. Add Resources in App Settings

Under Settings > Resources > + Add resource:

• SQL Warehouse → Can use
• Serving endpoint → Can query

Credential Handling

No credentials are stored in this repository.

The app uses Databricks Apps OAuth — DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET are injected automatically at runtime. WorkspaceClient() exchanges these for a valid bearer token.

The warehouse HTTP path in app.yaml is a resource identifier, not a secret.

Common Issues

Error	Fix
ModuleNotFoundError: No module named 'agents'	Each notebook needs its own %pip install cell
AgentRunner.run_sync() cannot be called when an event loop is already running	nest_asyncio.apply() is called at module load in runner.py
object ChatCompletion can't be used in 'await' expression	Use AsyncOpenAI not OpenAI in agent.py
Missing credentials	Ensure serving endpoint is added as a resource in App Settings
App shows "App Not Available"	Apps have no Spark context — use SQL connector, not spark.sql()

Blog Post

Full walkthrough: https://dipayan-x-das.medium.com/build-a-databricks-ai-agent-in-one-session-no-unity-catalog-or-vector-search-required-7b79f589d316?sharedUserId=dipayan-x-das

License

MIT