Configurare CI/CD per l'agente di Databricks Apps

Una pipeline CI/CD esegue ogni modifica all'agente tramite la revisione del codice e una distribuzione automatizzata, quindi le implementazioni di produzione non dipendono da un portatile di uno sviluppatore. Una volta configurata la pipeline, ogni merge al ramo principale esegue il deployment e riavvia l'agente su Databricks Apps.

Questa pagina illustra le parti specifiche dell'agente. CI/CD per le app Databricks con GitHub Actions documenta la configurazione principale del flusso di lavoro: federazione dell'identità del carico di lavoro, ambiente GitHub e distribuzione YAML. Completa prima quella pagina, quindi torna qui per le informazioni aggiuntive relative alle app agente.

Requirements

Passaggio 1. Usare il flusso di lavoro iniziale

Diversi modelli di agente in databricks/app-templates includono un modello pronto per l'uso .github/workflows/deploy.yml, quindi non è necessario scrivere il flusso di lavoro da zero.

  1. Selezionare un modello di agente da databricks/app-templates, ad esempio agent-langgraph o agent-openai-agents-sdk.
  2. Nella directory dei modelli clonati verificare se .github/workflows/deploy.yml esiste.
  3. Configurare il flusso di lavoro:
    • Se deploy.yml esiste: aprirlo, verificare che il passaggio faccia riferimento alla databricks bundle run chiave di risorsa del bundle da databricks.ymle seguire i prerequisiti nel commento dell'intestazione del file.
    • Se deploy.yml non esiste: Copiarlo da un modello in cui esiste o da Passaggio 4. Aggiungere il flusso di lavoro di distribuzione. Aggiornare quindi il databricks bundle run <key> passaggio in modo che corrisponda alla chiave di risorsa del bundle.

Passaggio 2. Precompilare l'ID dell'esperimento MLflow

I modelli di agente lasciano MLFLOW_EXPERIMENT_ID vuoto in databricks.yml. Lo script quickstart lo compila localmente alla prima configurazione, ma un runner CI nuovo non lo fa. Se experiment_id è vuoto, databricks bundle deploy ha esito negativo con un errore di tipo Terraform (For input string: "").

Per correggerlo, effettua il commit del valore compilato:

  1. Eseguire uv run quickstart --profile <your-profile> localmente nel computer in cui è stato creato l'agente.
  2. Verificare che la risorsa dell'esperimento in databricks.yml (la voce con name: 'experiment' in resources.apps.<key>.resources) abbia ora un valore numerico experiment_id.
  3. Approvare la modifica.

L'esperimento è limitato all'area di lavoro, quindi lo stesso ID è valido per ogni deployment CI destinato a quell'area di lavoro. Se si distribuisce in più workspace, dichiarare un esperimento specifico per ogni destinazione in databricks.yml (uno per ogni blocco targets.<env>) oppure usare una variabile del bundle.

Concedere le autorizzazioni Postgres per i modelli di memoria Lakebase

I modelli di agente avanzati (agent-langgraph-advanced, agent-openai-advanced) dichiarano una risorsa Postgres di Lakebase con scalabilità automatica direttamente in databricks.yml. Con Databricks CLI v0.295.0 e versioni successive, databricks bundle deploy esegue il provisioning della risorsa insieme all'app.

La risorsa DAB postgres concede al service principal dell'app l'accesso al livello dell'area di lavoro al progetto Lakebase, ma Lakebase mantiene un livello separato di ruoli Postgres per l'accesso al database (schemi, tabelle e sequenze). Il service principal deve disporre di un ruolo Postgres con i privilegi necessari prima che l'agente possa leggere o scrivere nelle sue tabelle della memoria. Vedere Architettura di autenticazione per il modello a due livelli.

La concessione di questi privilegi a livello di Postgres è una configurazione monouso. Eseguilo localmente tra il primo bundle deploy e bundle run. CI viene ridistribuita dopo quel flusso attraverso il percorso standard deploy quindi run, perché il ruolo Postgres del service principal persiste per l'intero ciclo di vita dell'app.

  1. Distribuisci il bundle per eseguire il provisioning della risorsa Lakebase:

    databricks bundle deploy --target prod

  2. Concedi all'entità servizio i privilegi a livello di PostgreSQL necessari:

    uv run python scripts/grant_lakebase_permissions.py \
  "$(databricks apps get <app-name> --output json | jq -r '.service_principal_client_id')" \
  --memory-type openai \
  --autoscaling-endpoint <endpoint>

    Per il template LangGraph, fornire --memory-type langgraph. Lo script accetta --project <project> --branch <branch> anche per la scalabilità automatica di Lakebase o --instance-name <name> per Lakebase di cui è stato effettuato il provisioning.

  3. Avviare l'app:

    databricks bundle run <bundle-key> --target prod

Passaggio 3. Esegui un test di verifica dell'agente distribuito

databricks bundle run restituisce non appena il runner segnala all'agente di avviarsi, ma il processo dell'agente potrebbe comunque non riuscire ad avviarsi correttamente. Dopo il controllo di integrità del passaggio 5. Attendere che l'app sia integra, aggiungere il passaggio smoke-test seguente a deploy.yml che invia una richiesta canary a /invocations:

- name: Smoke test invocations
  env:
    APP_NAME: my-agent
  run: |
    APP_URL=$(databricks apps get "$APP_NAME" --output json | jq -r '.url')
    TOKEN=$(databricks auth token | jq -r '.access_token')
    STATUS=$(curl -sS -o /tmp/canary.json -w "%{http_code}" \
      -X POST "$APP_URL/invocations" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"input": [{"role": "user", "content": "ping"}], "stream": false}')
    if [ "$STATUS" != "200" ]; then
      echo "Smoke test failed with status $STATUS:" >&2
      cat /tmp/canary.json >&2
      exit 1
    fi
    echo "Smoke test passed."

Annotazioni

Databricks Apps accetta solo token OAuth per la chiamata. Utilizzare il token OAuth dell'area di lavoro presente in databricks auth token; Databricks Apps rifiuta qualsiasi altro tipo di token.

Passaggi successivi

  • Last updated on