Configura o CI/CD para o teu agente Databricks Apps

Um pipeline CI/CD executa todas as alterações ao seu agente através de revisão de código e implementação automatizada, por isso os lançamentos em produção não dependem do portátil de um único programador. Depois de configurado o pipeline, cada fusão na sua branch principal faz a implementação e reinicia o seu agente nas Databricks Apps.

Esta página aborda os aspetos específicos dos agentes. CI/CD para aplicações Databricks com GitHub Actions documenta a configuração central do fluxo de trabalho: federação da identidade da carga de trabalho, o ambiente GitHub e o deployment YAML. Preencha essa página primeiro, depois volte aqui para as adições que se aplicam às aplicações de agentes.

Requirements

Passo 1. Use o fluxo de trabalho inicial

Vários modelos de agente em databricks/app-templates incluem um .github/workflows/deploy.yml pronto a utilizar, para não ter de criar o fluxo de trabalho do zero.

  1. Escolha um modelo de agente entre databricks/templates-app, como agent-langgraph ou agent-openai-agents-sdk.
  2. No teu diretório de modelos clonados, verifica se .github/workflows/deploy.yml existe.
  3. Configurar o fluxo de trabalho:
    • Se deploy.yml existir: Abra-o, confirme que a etapa databricks bundle run faz referência à chave de recurso do seu pacote em databricks.yml, e siga os pré-requisitos indicados no comentário de cabeçalho do ficheiro.
    • Se deploy.yml não existir: Copie de um modelo que exista, ou do Passo 4. Adicione o fluxo de trabalho de implementação. Depois, atualize a etapa databricks bundle run <key> para que corresponda à chave de recurso do seu pacote.

Passo 2. Pré-preencher o ID do experimento MLflow

Os modelos de agente deixam MLFLOW_EXPERIMENT_ID em branco em databricks.yml. O script quickstart preenche-o localmente aquando da configuração inicial, mas um runner de CI limpo não o faz. Se experiment_id estiver vazio, databricks bundle deploy falha com um erro de tipo Terraform (For input string: "").

Para corrigir isto, faça commit do valor preenchido:

  1. Executa uv run quickstart --profile <your-profile> localmente na máquina onde criaste o agente.
  2. Verifique se o recurso experimental em databricks.yml (a entrada com name: 'experiment' under resources.apps.<key>.resources) tem agora um número experiment_id.
  3. Confirme a alteração.

O experimento está limitado ao espaço de trabalho, pelo que o mesmo ID é válido para todas as implementações de CI dirigidas a esse espaço de trabalho. Se implementares para múltiplas áreas de trabalho, declara um experimento por alvo em databricks.yml (um por bloco targets.<env>) ou usa uma variável do pacote.

Conceder permissões Postgres para templates de memória Lakebase

Os templates avançados de agente (agent-langgraph-advanced, agent-openai-advanced) declaram um recurso Lakebase Postgres com auto-escalabilidade diretamente em databricks.yml. Com o Databricks CLI v0.295.0 e versões posteriores, databricks bundle deploy aprovisiona o recurso juntamente com a aplicação.

O recurso DAB postgres concede ao service principal da aplicação acesso ao projeto Lakebase ao nível do espaço de trabalho, mas o Lakebase mantém uma camada separada de funções do Postgres para o acesso à base de dados (esquemas, tabelas e sequências). O principal de serviço precisa de um papel Postgres com os privilégios corretos antes de o agente poder ler ou escrever as suas tabelas de memória. Ver Arquitetura de autenticação para o modelo de duas camadas.

Conceder estes privilégios ao nível do Postgres é uma solução única. Execute-o localmente entre o primeiro bundle deploy e bundle run. O CI é novamente implementado depois disso através do percurso padrão deploy e depois run, porque a função do Postgres do principal de serviço persiste ao longo de toda a vida útil da aplicação.

  1. Implemente o pacote para provisionar o recurso Lakebase:

    databricks bundle deploy --target prod

  2. Conceda ao principal do serviço os privilégios de nível Postgres que necessita:

    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 LangGraph, passe --memory-type langgraph. O script também aceita --project <project> --branch <branch> para autoescalar Lakebase, ou --instance-name <name> para Lakebase provisionado.

  3. Inicie o aplicativo:

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

Passo 3. Teste de fumo ao agente lançado

databricks bundle run regressa assim que o runner sinaliza ao agente que inicie, mas o processo do agente ainda pode falhar durante o arranque. Após a verificação de estado do Passo 5. Aguarde até a aplicação estar operacional, adicione a deploy.yml o seguinte passo de teste inicial, que envia um pedido 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

As aplicações Databricks só aceitam tokens OAuth para invocação. Utilize o token OAuth da área de trabalho de databricks auth token; as aplicações do Databricks rejeitam qualquer outro tipo de token.

Recursos adicionais

  • Last updated on