How I Built a Databricks AI Agent with No Custom Tables (OpenAI Agents SDK + Gradio)

如何在不使用自定义表的情况下构建 Databricks AI Agent（OpenAI Agents SDK + Gradio）

Most Databricks agent tutorials start with “set up Unity Catalog and Vector Search first.” This one doesn’t. I built a fully working conversational agent using only samples.tpch — the dataset that ships in every Databricks workspace by default. No custom tables, no Vector Search index, no catalog setup. 大多数 Databricks Agent 教程都以“首先设置 Unity Catalog 和向量搜索”开头。但这篇教程不需要。我仅使用 samples.tpch（每个 Databricks 工作区默认自带的数据集）就构建了一个功能完备的对话式 Agent。无需自定义表，无需向量搜索索引，也无需进行 Catalog 设置。

The stack: OpenAI Agents SDK (with AsyncOpenAI — important, sync breaks it), Databricks Model Serving (Llama 3.3 70B via OpenAI-compatible endpoint), Databricks SQL Connector (not Spark — Apps have no Spark context), MLflow for experiment tracking, Gradio chat UI deployed via Databricks Apps, OAuth credentials injected automatically — no tokens in code. 技术栈包括：OpenAI Agents SDK（必须使用 AsyncOpenAI，同步模式会导致报错）、Databricks Model Serving（通过兼容 OpenAI 的端点调用 Llama 3.3 70B）、Databricks SQL Connector（不能使用 Spark，因为 Apps 没有 Spark 上下文）、用于实验跟踪的 MLflow、通过 Databricks Apps 部署的 Gradio 聊天界面，以及自动注入的 OAuth 凭据（代码中无需硬编码 Token）。

The pattern that made it work: Write an AGENTS.md instruction file with constraints, folder structure, SQL queries, and a validation checklist. Run one Codex prompt. Get a complete working codebase. codex “implement everything described in AGENTS.md” 实现这一目标的核心模式是：编写一个 AGENTS.md 指令文件，其中包含约束条件、文件夹结构、SQL 查询语句和验证清单。运行一次 Codex 提示词，即可获得完整的代码库。提示词为：codex "implement everything described in AGENTS.md"。

The three errors that will block you if you don’t know: 如果你不知道以下三个错误，它们会阻碍你的开发：

1. AsyncOpenAI not OpenAI — the Agents SDK is async internally, sync client crashes at the model call.

2. 使用 AsyncOpenAI 而非 OpenAI —— Agents SDK 在内部是异步的，同步客户端在调用模型时会崩溃。

3. nest_asyncio.apply() at module load — Databricks notebooks run a persistent event loop, Runner.run_sync() fails without this patch.

4. 在模块加载时使用 nest_asyncio.apply() —— Databricks Notebook 运行着一个持久的事件循环，没有这个补丁，Runner.run_sync() 将无法运行。

5. SQL Connector not Spark — Databricks Apps have no Spark context, spark.sql() crashes silently in the App runtime.

6. 使用 SQL Connector 而非 Spark —— Databricks Apps 没有 Spark 上下文，spark.sql() 在 App 运行时会静默崩溃。

Full walkthrough with all errors, architecture, deployment steps, and production caveats: 👉 Read the full article on Medium 包含所有错误排查、架构设计、部署步骤和生产环境注意事项的完整指南：👉 在 Medium 上阅读全文

GitHub: github.com/dipayanthedata/DatabricksAgentDemo GitHub 仓库：github.com/dipayanthedata/DatabricksAgentDemo