Configurar CI/CD para seu agente do Databricks Apps

Um pipeline de CI/CD processa cada alteração no seu agente, passando por revisão de código e implantação automatizada, para que as implantações em produção não dependam do notebook de um único desenvolvedor. Depois que o pipeline é configurado, cada mesclagem em sua ramificação principal implanta e reinicia seu agente nos Aplicativos do Databricks.

Esta página trata dos componentes específicos do agente. CI/CD para Aplicativos do Databricks com GitHub Actions documenta a configuração principal do fluxo de trabalho: federação de identidade de carga de trabalho, o ambiente de GitHub e o YAML de implantação. Conclua essa página primeiro e retorne aqui para as adições que se aplicam aos aplicativos do agente.

Requirements

Etapa 1. Usar o fluxo de trabalho inicial

Vários templates de agente em databricks/app-templates já vêm com um .github/workflows/deploy.yml pronto para uso, assim você não precisa escrever o fluxo de trabalho do zero.

  1. Escolha um modelo de agente de databricks/app-templates, como agent-langgraph ou agent-openai-agents-sdk.
  2. No diretório de modelo clonado, verifique se .github/workflows/deploy.yml existe.
  3. Configure o fluxo de trabalho:
    • Se deploy.yml existir: abra o arquivo, confirme se a etapa databricks bundle run faz referência à chave de recurso do seu pacote em databricks.yml e siga os pré-requisitos no comentário no cabeçalho do arquivo.
    • Se deploy.yml não existir: copie-o de um modelo que o faça ou da Etapa 4. Adicione o fluxo de trabalho de implantação. Em seguida, atualize a databricks bundle run <key> etapa para que corresponda à chave de recurso do pacote.

Etapa 2. Preencha a ID do experimento do MLflow

Os modelos de agente deixam MLFLOW_EXPERIMENT_ID em branco em databricks.yml. O script quickstart o preenche localmente na configuração inicial, mas um executor de CI novo não o faz. Se experiment_id estiver vazio, databricks bundle deploy falhará com um erro de tipo terraform (For input string: "").

Para corrigi-lo, confirme o valor preenchido:

  1. Execute uv run quickstart --profile <your-profile> localmente no computador onde você criou o agente.
  2. Verifique se o recurso de experimento em databricks.yml (a entrada com name: 'experiment' em resources.apps.<key>.resources) agora tem um experiment_id numérico.
  3. Confirme a alteração.

O experimento tem escopo de workspace, portanto, a mesma ID é válida para cada implantação de CI direcionada a esse workspace. Se você implantar em vários workspaces, declare um experimento para cada destino em databricks.yml (um por bloco targets.<env>) ou use uma variável de bundle.

Conceder permissões do Postgres para modelos de memória do Lakebase

Os modelos de agente avançados (agent-langgraph-advanced, agent-openai-advanced) declaram um recurso de dimensionamento automático do Lakebase Postgres diretamente em databricks.yml. Com a CLI do Databricks v0.295.0 e versões posteriores, databricks bundle deploy provisiona o recurso junto com o aplicativo.

O recurso DAB postgres concede ao service principal do aplicativo acesso no nível do workspace ao projeto Lakebase, mas o Lakebase mantém uma camada separada de funções do Postgres para acesso ao banco de dados (esquemas, tabelas e sequências). O principal de serviço precisa de uma role no Postgres com os privilégios necessários antes de o agente poder ler ou escrever em suas tabelas de memória. Consulte a arquitetura de autenticação para o modelo de duas camadas.

Conceder esses privilégios no nível do Postgres é uma configuração única. Execute-o localmente entre o primeiro bundle deploy e bundle run. A CI reimplanta depois desse fluxo pelo caminho padrão deploy , run pois a função Postgres da entidade de serviço persiste durante o tempo de vida do aplicativo.

  1. Implante o pacote para provisionar o recurso lakebase:

    databricks bundle deploy --target prod

  2. Conceda à entidade de serviço os privilégios em nível de Postgres necessários:

    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 o modelo do LangGraph, passe --memory-type langgraph. O script também aceita --project <project> --branch <branch> para o Lakebase com dimensionamento automático ou --instance-name <name> para o Lakebase provisionado.

  3. Inicie o aplicativo:

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

Etapa 3. Teste de fumaça do agente implantado

databricks bundle run retorna assim que o executor sinaliza o agente para iniciar, mas o processo do agente ainda pode falhar durante a inicialização. Após a verificação de integridade da Etapa 5. Aguarde até que o aplicativo esteja saudável, adicione a seguinte etapa de teste de smoke a deploy.yml, que envia uma requisição canário para /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

Os Aplicativos do Databricks aceitam apenas tokens OAuth para invocação. Use o token OAuth do espaço de trabalho de databricks auth token; o Databricks Apps rejeita qualquer outro tipo de token.

Próximas Etapas 

  • Last updated on