What AI Agents Taught Me About Building Databricks Apps

Description and use

AI agents can generate code quickly, but Databricks Apps often fail to run due to configuration, permission, and deployment traps. Implementing AGENTS.md rules and preflight checks resolves these issues, ensuring reliable deployment and operation.

Problem

AI agents can generate code quickly, but the resulting Databricks App often fails to run due to configuration, permission, and deployment traps that the agent does not learn from documentation.

Outcome

After implementing rule‑based preflight checks and a consistent deployment workflow, the Databricks App runs reliably, users can access it, and the AI agent’s code is validated against known traps before deployment.

Workflow

• 1. Create AGENTS.md with ten rules for Databricks App configuration.
• 2. Run a preflight lint script that checks for user_api_scopes placement, git_source, app.yaml usage, lockfile presence, registry settings, omit=optional, root path, secrets, target workspace consistency, and missing permissions.
• 3. Use a reviewed template to generate the app, ensuring OBO sessions, group checks, retry logic, and audit logs.
• 4. Deploy via bundle deploy and bundle run, not git snapshots.
• 5. Verify effective_user_api_scopes after each deploy.
• 6. Monitor logs for effective catalog, schema, and warehouse at boot.
• 7. Add retry and banner for warehouse startup errors.
• 8. Ensure all three permission sets (app, warehouse, table) are granted to the correct groups.
• 9. Promote from dev to sqa to prd through CI, keeping environment values in bundle targets.
• 10. Iterate fixes based on preflight failures and agent feedback.

Evidence

The agent writes most of the code. Everything around it was still on me, and I think that's good news

Source

The code showed up fast. Getting it to run correctly took way longer.

Source

The app's own service principal gets CAN_USE on the warehouse and nothing else.

Source

The first deployment pulled the code from a git branch and never started: "App process did not start within 10 minutes."

Source

The npm install had its own surprises: a corporate registry pinned in .npmrc that Databricks can't reach, an omit=optional setting that dropped native binaries, and a missing package-lock.json.

Source