Airlift Migration Assistant

View full size

The Airlift Migration Assistant helps a developer answer four immediate questions from any focused migration blocker:

1. What failed, and why did Airlift stop automation?
2. Which person or team acts next?
3. What implementation and diagnostic checks are appropriate?
4. Which immutable artifact and independent evidence clear the gate?

The canonical next action always comes from the Airlift ledger. When a model is configured, a finite Fabric Harness agent adds plain-language explanation and up to five diagnostic checks. It has no tools and cannot mutate state, execute SQL, approve evidence, waive policy, deploy, certify, or cut over.

Runtime layers

The product-facing assistant is Airlift Migration Assistant. A Databricks Genie Agent is an optional analytics specialist. It does not replace the Harness agent runtime. The legacy /airlift-genie route and AIRLIFT_GENIE_* variables remain compatibility aliases; they do not name the product surface.

Recommended: Unity AI Gateway

Use Unity AI Gateway when the workspace has an approved Unity Catalog model service. This keeps model access, provider routing, permissions, usage tracking, and inference policy in Databricks.

1. Select an approved model service, normally a fully qualified system.ai.* name.
2. Grant the Airlift Databricks App service principal permission to use it.
3. Set the bundle variables and deploy the App:

databricks bundle deploy -t dev \
  --var="airlift_genie_provider=unity-ai-gateway" \
  --var="airlift_genie_model=system.ai.<approved-model-service>" \
  --var="airlift_genie_inference_mode=ai-gateway"

The App receives these non-secret settings:

AIRLIFT_GENIE_PROVIDER=unity-ai-gateway
AIRLIFT_GENIE_MODEL=system.ai.<approved-model-service>
DATABRICKS_MODEL=system.ai.<approved-model-service>
DATABRICKS_INFERENCE_MODE=ai-gateway

Open Advanced tools → Migration Assistant. Model reasoning should read Unity AI Gateway. Then open a focused remediation case and select Ask Migration Assistant.

Databricks Model Serving

For a custom workspace serving endpoint, grant the App service principal query permission and use:

databricks bundle deploy -t dev \
  --var="airlift_genie_provider=model-serving" \
  --var="airlift_genie_model=airlift-approved-endpoint" \
  --var="airlift_genie_inference_mode=serving-endpoints"

The Harness Databricks adapter owns OAuth token rotation and the OpenAI-compatible transport. Airlift does not implement a Databricks client or persist the token.

External provider fallback

Use a direct provider only when workspace-native inference is unavailable. Do not paste a key into the Airlift UI or place it in an action, event, prompt, source file, or ordinary environment-value field.

Create an App-specific secret and add a Databricks App secret resource:

config:
  env:
    - name: AIRLIFT_GENIE_PROVIDER
      value: openai-compatible
    - name: AIRLIFT_GENIE_MODEL
      value: approved-model
    - name: AIRLIFT_GENIE_BASE_URL
      value: https://models.example/v1
    - name: AIRLIFT_GENIE_API_KEY
      value_from: airlift-genie-api-key
  resources:
    - name: airlift-genie-api-key
      secret:
        scope: airlift-genie
        key: model-api-key
        permission: READ

Supported provider settings are:

Use a separate secret scope for the App and grant it access to only the required key. The configuration page reports secret bound but never returns the value to the browser.

Optional Genie analytics

Set AIRLIFT_GENIE_AGENT_ID only when developers need questions over curated migration projections. Enable Databricks Apps user authorization with the genie scope, grant the intended user Can run, and restrict the agent to approved Unity Catalog sources.

Genie analytics runs as the signed-in user. Migration Assistant model reasoning runs as the App service principal. The different identities are intentional: shared guidance uses the approved application model, while data visibility continues to respect each user's existing permissions.

Failure behavior

• Missing model settings: show ledger-derived guidance.
• App lacks model permission: show ledger-derived guidance and leave the gate unchanged.
• Provider timeout, budget exhaustion, or malformed response: show ledger-derived guidance.
• Missing Genie user token or permission: skip Genie analytics.
• Generated diagnostic SQL: display for review; never execute automatically.

Model absence cannot block migration work, and model success cannot advance it.