Databricks quickstart

Scaffold, mock, connect, build, and deploy a governed Databricks agent with Fabric Harness.

Create the workspace

npx @fabric-harness/cli init --template databricks --dir analytics-agent
cd analytics-agent
npm install

The template creates a finite analytics job, role, skill, Databricks App config, governed SQL policy, certification manifest, AGENTS.md, and environment sample. Lakebase coordinates are optional.

.fabricharness/jobs/databricks-analyst.ts

import { defineDatabricksAgent } from '@fabric-harness/databricks';
import { schema } from '@fabric-harness/sdk';
import policy from '../policies/databricks.js';

export default defineDatabricksAgent({
  name: 'databricks-analyst',
  description: 'Answer governed questions using SQL and Unity Catalog.',
  input: schema.object({ question: schema.string() }),
  output: schema.string(),
  model: 'system.ai.gpt-oss-20b',
  tools: ['sql', 'tables', 'table-info'],
  triggers: { manual: true, webhook: true },
  sandbox: 'empty',
  policy,
});

Validate without a workspace

fh doctor --getting-started --tools
fh agents
fh describe databricks-analyst
fh run databricks-analyst --question "Describe main.sales.orders" --mock

Mock mode covers discovery, schemas, tool assembly, model-loop behavior, and HTTP routing. It cannot validate Databricks permissions or API behavior.

Read Local naming and authentication before connecting a workspace. It distinguishes job, persistent-agent, App, model, Fabric principal, tenant, and Databricks principal identities with PAT, OAuth M2M, and OBO examples.

Add products with recipes

On an existing Fabric project, scaffold individual Databricks surfaces:

fh add databricks core
fh add databricks sql
fh add lakebase
fh add vector-search
fh add lakeflow
fh add jobs

See Databricks recipes for the full catalog, aliases (lakehouse, databricks-rag, …), and how recipes map to examples.

Connect a workspace

.env.local

DATABRICKS_HOST=https://<workspace-host>
DATABRICKS_CLIENT_ID=00000000-0000-0000-0000-000000000000
DATABRICKS_CLIENT_SECRET=resolve-from-a-secret-store
DATABRICKS_WAREHOUSE_ID=0123456789abcdef
DATABRICKS_MODEL=system.ai.gpt-oss-20b
DATABRICKS_INFERENCE_MODE=auto
# Optional explicit override:
# DATABRICKS_AI_GATEWAY_BASE_URL=https://<workspace-host>/ai-gateway/mlflow/v1

Grant the service principal workspace access, CAN QUERY on the SQL Warehouse, permission to invoke the model service, and only the required Unity Catalog privileges. Then run the same command without --mock.

Copy DATABRICKS_HOST from the workspace URL, including https:// and without a trailing path. system.ai.* models route through Unity AI Gateway at ${DATABRICKS_HOST}/ai-gateway/mlflow/v1. Custom endpoint names continue to route through /serving-endpoints; set DATABRICKS_INFERENCE_MODE when you need to choose explicitly.

Use the composable bundle

For more integrations, configure the databricks() bundle and pass its surfaces to init():

import { databricks } from '@fabric-harness/databricks';
import { init } from '@fabric-harness/sdk';

const dbx = databricks({
  host: process.env.DATABRICKS_HOST!,
  principal: {
    kind: 'service-principal',
    host: process.env.DATABRICKS_HOST!,
    clientId: process.env.DATABRICKS_CLIENT_ID!,
    clientSecret: process.env.DATABRICKS_CLIENT_SECRET!,
  },
  model: process.env.DATABRICKS_MODEL,
  warehouseId: process.env.DATABRICKS_WAREHOUSE_ID,
  vectorSearch: {
    index: 'main.knowledge.docs_index',
    textColumn: 'chunk',
    idColumn: 'id',
  },
  genie: { spaceId: process.env.DATABRICKS_GENIE_SPACE_ID! },
  lakeflow: true,
  consumption: true,
  governance: {
    catalogs: ['main'],
    stewardAudience: 'data-steward',
  },
});

const runtime = await init({
  modelProvider: dbx.modelProvider,
  tools: dbx.tools,
  policy: dbx.policy,
  store: dbx.store,
});

Build and deploy

fh build --target databricks-app
cd .fabricharness/build/databricks-app
databricks bundle validate
databricks bundle deploy

Use Databricks App resources and secret references instead of committing credentials. The detailed Databricks App tutorial covers App configuration, Lakebase durability, persistent agents, and the live validation gate.