Configura CI/CD para el agente de Databricks Apps

Una canalización de integración y entrega continuas (CI/CD) hace pasar cada cambio de tu agente por una revisión de código y un despliegue automatizado, de modo que los despliegues en producción no dependen del portátil de un único desarrollador. Una vez configurada la canalización, cada fusión en la rama principal despliega y reinicia el agente en Databricks Apps.

Esta página abarca los elementos específicos del agente. CI/CD para Aplicaciones de Databricks con Acciones de GitHub documenta la configuración principal del flujo de trabajo: federación de identidades de carga de trabajo, el entorno de GitHub y la implementación de YAML. Complete primero esa página y vuelva aquí para las adiciones que se aplican a las aplicaciones del agente.

Requirements

Paso 1. Use el flujo de trabajo inicial

Varias plantillas de agente en databricks/app-templates envían un paquete listo para usar .github/workflows/deploy.yml, por lo que no es necesario escribir el flujo de trabajo desde cero.

  1. Elija una plantilla de agente de databricks/app-templates, como agent-langgraph o agent-openai-agents-sdk.
  2. En el directorio de la plantilla clonada, compruebe si .github/workflows/deploy.yml existe.
  3. Configure el flujo de trabajo:
    • Si deploy.yml existe: ábralo, confirme que el paso haga referencia a la clave de recurso de su paquete de databricks bundle rundatabricks.yml y siga los requisitos previos indicados en el comentario de cabecera del archivo.
    • Si deploy.yml no existe: cópielo desde una plantilla que sí o desde el paso 4. Agregue el flujo de trabajo de implementación. A continuación, actualice el paso databricks bundle run <key> para que coincida con la clave de recurso de su paquete.

Paso 2. Rellenar previamente el identificador del experimento de MLflow

Las plantillas del agente dejan MLFLOW_EXPERIMENT_ID vacías en databricks.yml. El quickstart script lo rellena localmente en la primera configuración, pero no lo hace un ejecutor de CI nuevo. Si experiment_id está vacío, databricks bundle deploy falla con un error de tipo de Terraform (For input string: "").

Para corregirlo, confirme el valor rellenado:

  1. Ejecute uv run quickstart --profile <your-profile> localmente en el equipo donde creó el agente.
  2. Compruebe que el recurso del experimento de databricks.yml (la entrada con name: 'experiment' en resources.apps.<key>.resources) ahora tiene un valor numérico experiment_id.
  3. Confirme el cambio.

El experimento tiene ámbito de área de trabajo, por lo que el mismo identificador es válido para cada implementación de CI que tenga como destino esa área de trabajo. Si despliega en varios espacios de trabajo, declare un experimento para cada destino en databricks.yml (uno por cada bloque targets.<env>) o use una variable del paquete.

Concesión de permisos de Postgres para plantillas de memoria de Lakebase

Las plantillas avanzadas del agente (agent-langgraph-advanced, agent-openai-advanced) declaran un recurso de Lakebase Postgres de escalado automático directamente en databricks.yml. Con la CLI de Databricks v0.295.0 y versiones posteriores, databricks bundle deploy aprovisiona el recurso junto con la aplicación.

El recurso DAB postgres concede al identificador de servicio de la aplicación acceso a nivel de espacio de trabajo al proyecto Lakebase, pero Lakebase mantiene una capa independiente de roles de Postgres para el acceso a la base de datos (esquemas, tablas y secuencias). La entidad de servicio necesita un rol de Postgres con los privilegios adecuados antes de que el agente pueda leer o escribir sus tablas de memoria. Consulte Arquitectura de autenticación para el modelo de dos capas.

Conceder estos privilegios de nivel de Postgres es una configuración única. Ejecútelo localmente entre el primero bundle deploy y bundle run. CI se vuelve a implementar después de ese flujo a través de la ruta estándar deploy y luego run, ya que el rol de Postgres de la entidad de servicio persiste durante toda la vida útil de la aplicación.

  1. Implemente el paquete para aprovisionar el recurso Lakebase:

    databricks bundle deploy --target prod

  2. Conceda a la entidad de servicio los privilegios de Postgres que necesita:

    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>

    Para la plantilla LangGraph, pase --memory-type langgraph. El script también acepta --project <project> --branch <branch> para el escalado automático de Lakebase o --instance-name <name> para Lakebase aprovisionado.

  3. Inicie la aplicación:

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

Paso 3. Prueba de humo del agente implementado

databricks bundle run devuelve tan pronto como el ejecutor indica al agente que se inicie, pero el proceso del agente puede seguir produciendo un error durante el arranque. Después de la verificación de estado del Paso 5. Espere a que la aplicación esté en buen estado, agregue a deploy.yml el siguiente paso de prueba de humo, que envía una solicitud canaria 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."

Note

Las aplicaciones de Databricks solo aceptan tokens de OAuth para la invocación. Utilice el token de OAuth del área de trabajo de databricks auth token; Databricks Apps rechazan cualquier otro tipo de token.

Recursos adicionales

  • Last updated on