为您的 Databricks Apps 代理配置 CI/CD

CI/CD 管道会让对代理的每一次更改都经过代码审查和自动化部署，因此生产环境发布不再依赖任何单个开发人员的笔记本电脑。 配置好流水线后，每次合并到主分支都会在 Databricks Apps 上部署并重启你的代理。

本页涵盖代理专属内容。 CI/CD for Databricks Apps with GitHub Actions 记录核心工作流设置：工作负荷标识联合、GitHub环境和部署 YAML。 首先完成该页面，然后返回此处，获取适用于代理应用的添加内容。

Requirements

• 使用 OpenAI 代理 SDK、LangGraph 或自定义框架在 Databricks 应用上至少部署一次代理应用。 请参阅 “创作 AI 代理”并将其部署到 Databricks 应用。
• 具有 GitHub Actions 联合身份验证策略并在该应用程序上具有 CAN MANAGE 的服务主体。 请参阅 步骤 1. 配置工作负载身份联合。
• Databricks CLI 在本地安装和进行身份验证。 请参阅安装或更新 Databricks CLI。

第 1 步。 使用入门工作流

databricks/app-templates 中的多个代理模板提供现成的用途.github/workflows/deploy.yml，因此无需从头开始编写工作流。

1. 从 databricks/app-templates（例如 agent-langgraph 或 agent-openai-agents-sdk）中选择代理模板。
2. 在克隆的模板目录中，检查是否存在 .github/workflows/deploy.yml 。
3. 设置工作流：
   • 如果 deploy.yml 存在：打开它，确认 databricks bundle run 步骤引用了 databricks.yml 中你的软件包资源键，并遵循该文件头部注释中的前提条件。
   • 如果 deploy.yml 不存在：请从包含该文件的模板中复制它，或从 步骤 4. 添加部署工作流 中复制它。 然后更新步骤 databricks bundle run <key> 以匹配捆绑包的资源密钥。

第 2 步。 预先填充 MLflow 实验 ID

代理模板将 MLFLOW_EXPERIMENT_ID 在 databricks.yml 中留空。 quickstart 脚本会在首次设置时于本地将其补全，但全新的 CI 运行器不会这样做。 如果 experiment_id 为空，databricks bundle deploy 会失败，并报 Terraform 类型错误（For input string: ""）。

若要修复此问题，请提交已填充的值：

1. 在你编写该代理的那台机器上本地运行 uv run quickstart --profile <your-profile>。
2. 验证 databricks.yml 中的实验资源（即 name: 'experiment' 下带有 resources.apps.<key>.resources 的条目）现在是否具有数值型的 experiment_id。
3. 提交更改。

试验是工作区范围的，因此，对于面向该工作区的每个 CI 部署，相同的 ID 都有效。 如果要部署到多个工作区，请在 databricks.yml 中声明针对每个目标的实验（每个 targets.<env> 块一个），或使用捆绑包变量。

为 Lakebase 内存模板授予 Postgres 权限

高级代理模板（agent-langgraph-advanced、agent-openai-advanced）直接在 databricks.yml 中声明了自动扩缩容的 Lakebase Postgres 资源。 在 Databricks CLI v0.295.0 及更高版本中，databricks bundle deploy 会在预配应用的同时预配该资源。

DAB postgres 资源授予应用的服务主体对 Lakebase 项目的工作区级访问权限，但 Lakebase 另设独立的 Postgres 角色层，用于数据库访问（架构、表和序列）。 服务主体需要具有适当权限的 Postgres 角色，然后代理才能读取或写入其内存表。 请参阅两层模型的 身份验证体系结构 。

授予这些 Postgres 级特权是 一次性设置。 在第一个 bundle deploy 和 bundle run 之间在本地运行它。 CI 在那之后会沿着标准的 deploy 然后 run 路径重新部署，因为服务主体的 Postgres 角色会在应用的整个生命周期内一直保留。

1. 部署捆绑包以预配 Lakebase 资源：

   databricks bundle deploy --target prod
   

2. 向服务主体授予它所需的 Postgres 级特权：

   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>
   

   对于 LangGraph 模板，请传递 --memory-type langgraph。 该脚本还接受 --project <project> --branch <branch> 用于自动扩缩容的 Lakebase，或接受 --instance-name <name> 用于预配的 Lakebase。

3. 启动应用：

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

步骤 3. 对已部署的代理进行冒烟测试

databricks bundle run 在运行器向代理发出启动信号后便立即返回，但代理进程在启动期间仍可能失败。 在完成 步骤 5：等待应用处于正常状态 中的健康检查后，将以下冒烟测试步骤添加到 deploy.yml 中，以向 /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."

其他资源

• 将您的 Databricks Apps 智能体投入生产环境
• 对 Databricks 应用程序代理进行负载测试