Richten Sie CI/CD für Ihren Databricks Apps-Agenten ein

Eine CI/CD-Pipeline führt jede Änderung an Ihrem Agent durch Codeüberprüfung und eine automatisierte Bereitstellung aus, sodass Produktionsrollouts nicht von einem Laptop eines Entwicklers abhängen. Sobald die Pipeline konfiguriert ist, wird Ihr Agent bei jedem Merge in Ihren Haupt-Branch auf Databricks Apps bereitgestellt und neu gestartet.

Auf dieser Seite werden die agentspezifischen Teile behandelt. CI/CD für Databricks-Apps mit GitHub Actions dokumentiert die Einrichtung des grundlegenden Workflows: Workload Identity Federation, die GitHub-Umgebung und die Deploy-YAML-Datei. Schließen Sie diese Seite zuerst ab, und kehren Sie dann hier für die Ergänzungen zurück, die für Agent-Apps gelten.

Requirements

Schritt 1. Verwenden Sie den Startworkflow

Mehrere Agentvorlagen in Databricks/App-Vorlagen liefern eine einsatzbereite .github/workflows/deploy.ymlVorlage, sodass Sie den Workflow nicht von Grund auf neu schreiben müssen.

  1. Wählen Sie eine Agentvorlage aus databricks/app-templates, beispielsweise agent-langgraph oder agent-openai-agents-sdk.
  2. Überprüfen Sie im Verzeichnis der geklonten Vorlage, ob .github/workflows/deploy.yml vorhanden ist.
  3. Richten Sie den Workflow ein:
    • Falls deploy.yml vorhanden ist: Öffnen Sie die Datei, vergewissern Sie sich, dass der Schritt databricks bundle run auf den Ressourcenschlüssel Ihres Bundles aus databricks.yml verweist, und befolgen Sie die Voraussetzungen im Kommentar im Dateikopf.
    • Wenn deploy.yml nicht vorhanden: Kopieren Sie sie aus einer Vorlage, die dies tut, oder aus Schritt 4. Fügen Sie den Bereitstellungsworkflow hinzu. Aktualisieren Sie dann den databricks bundle run <key> Schritt, um dem Ressourcenschlüssel Ihres Bundles zu entsprechen.

Schritt 2. Vorfüllen der MLflow-Experiment-ID

Agentvorlagen lassen MLFLOW_EXPERIMENT_ID in databricks.yml leer. Das quickstart Skript füllt es bei der Ersteinrichtung lokal aus, ein frischer CI-Runner jedoch nicht. Wenn experiment_id leer ist, schlägt databricks bundle deploy mit einem Terraform-Typfehler (For input string: "") fehl.

Um ihn zu beheben, übernehmen Sie den aufgefüllten Wert:

  1. Führen Sie uv run quickstart --profile <your-profile> lokal auf dem Computer aus, auf dem Sie den Agenten erstellt haben.
  2. Stellen Sie sicher, dass die Experiment-Ressource in databricks.yml (der Eintrag mit name: 'experiment' unter resources.apps.<key>.resources) jetzt über eine numerische experiment_id verfügt.
  3. Führen Sie für die Änderung einen Commit aus.

Das Experiment ist auf den Arbeitsbereich beschränkt, sodass dieselbe ID für jede CI-Bereitstellung gültig ist, die auf diesen Arbeitsbereich abzielt. Wenn Sie in mehreren Arbeitsbereichen bereitstellen, deklarieren Sie in databricks.yml ein Experiment pro Ziel (je eines pro targets.<env>-Block) oder verwenden Sie eine Bundle-Variable.

Gewähren von Postgres-Berechtigungen für Lakebase-Speichervorlagen

Die erweiterten Agent-Vorlagen (agent-langgraph-advanced, agent-openai-advanced) deklarieren eine automatisch skalierende Lakebase Postgres-Ressource direkt in databricks.yml. Ab Databricks CLI v0.295.0 stellt databricks bundle deploy die Ressource zusammen mit der App bereit.

Die DAB-Ressource postgres gewährt dem Service Principal der App Zugriff auf Arbeitsbereichsebene auf das Lakebase-Projekt, aber Lakebase verwendet für den Datenbankzugriff (Schemata, Tabellen und Sequenzen) eine separate PostgreSQL-Rollenebene. Der Dienstprinzipal benötigt eine Postgres-Rolle mit den richtigen Berechtigungen, bevor der Agent seine Speichertabellen lesen oder schreiben kann. Siehe Authentifizierungsarchitektur für das zweistufige Modell.

Die Gewährung dieser Berechtigungen auf Postgres-Ebene ist ein einmaliges Setup. Führen Sie den Vorgang lokal zwischen bundle deploy und bundle run aus. CI wird danach über den standardmäßigen deploy-dann-run-Pfad neu bereitgestellt, da die Postgres-Rolle des Dienstprinzipals während der gesamten Lebensdauer der App bestehen bleibt.

  1. Stellen Sie das Bundle bereit, um die Lakebase-Ressource bereitzustellen:

    databricks bundle deploy --target prod

  2. Gewähren Sie dem Dienstprinzipal die Berechtigungen auf Postgres-Ebene, die er benötigt:

    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>

    Für die LangGraph-Vorlage --memory-type langgraph übergeben. Das Skript akzeptiert auch --project <project> --branch <branch> für eine automatisch skalierte Lakebase oder --instance-name <name> für eine provisionierte Lakebase.

  3. Starten Sie die App:

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

Schritt 3. Rauchtest des bereitgestellten Agents

databricks bundle run kehrt zurück, sobald der Runner dem Agenten signalisiert, zu starten, aber der Agentprozess kann beim Hochfahren dennoch fehlschlagen. Nach der Zustandsprüfung in Schritt 5. Warten Sie, bis die App funktionsfähig ist, fügen Sie deploy.yml den folgenden Smoke-Test-Schritt hinzu, der eine Canary-Anfrage an /invocations sendet:

- 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."

Note

Databricks-Apps akzeptieren nur OAuth-Token für Aufrufe. Verwenden Sie das Arbeitsbereich-OAuth-Token von databricks auth token; Databricks-Apps lehnen alle anderen Tokentypen ab.

Nächste Schritte

  • Last updated on