Databricks Apps 에이전트에 대한 CI/CD 설정

CI/CD 파이프라인은 코드 검토 및 자동화된 배포를 통해 에이전트에 대한 모든 변경 내용을 실행하므로 프로덕션 롤아웃은 한 개발자의 랩톱에 종속되지 않습니다. 파이프라인이 구성되면 기본 브랜치로 병합될 때마다 Databricks Apps에서 에이전트가 배포되고 다시 시작됩니다.

이 페이지에서는 에이전트 관련 부분을 다룹니다. GitHub Actions를 사용하는 Databricks 앱용 CI/CD 문서에서는 워크로드 아이덴티티 페더레이션, GitHub 환경, 그리고 배포 YAML로 이루어진 핵심 워크플로 설정을 설명합니다. 먼저 해당 페이지를 완료한 다음 에이전트 앱에 적용되는 추가 사항을 보려면 여기로 돌아갑니다.

Requirements

• OpenAI 에이전트 SDK, LangGraph 또는 사용자 지정 프레임워크를 사용하여 Databricks 앱에 한 번 이상 배포된 에이전트 앱입니다. AI 에이전트를 작성하고 Databricks 앱에 배포하세요.
• 앱에 GitHub Actions 페더레이션 정책과 CAN MANAGE이 있는 서비스 주체입니다. 1단계를 참조하세요. 워크로드 ID 페더레이션을 구성합니다.
• 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 미리 채우기

에이전트 템플릿은 databricks.yml에서 MLFLOW_EXPERIMENT_ID을 비워 둡니다. quickstart 스크립트는 최초 설정 시 로컬에서 이를 채워 주지만, 새 CI 러너는 그렇지 않습니다. experiment_id가 비어 있으면 databricks bundle deploy가 Terraform 형식 오류(For input string: "")로 실패합니다.

이 문제를 해결하려면 채워진 값을 커밋합니다.

1. 에이전트를 작성한 머신에서 uv run quickstart --profile <your-profile>를 로컬로 실행하세요.
2. 이제 databricks.yml(resources.apps.<key>.resources 아래에 있는 name: 'experiment' 항목)의 실험 리소스에 숫자 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 역할이 필요합니다. 2 계층 모델에 대한 인증 아키텍처 를 참조하세요.

이러한 Postgres 수준 권한을 부여하는 것은 일회성 설정입니다. 첫 번째 bundle deploy와 bundle run 사이에서 로컬로 실행하세요. CI는 서비스 주체의 Postgres 역할이 앱의 수명 동안 지속되므로 표준 deploy 다음 run 경로를 통해 해당 흐름 후에 다시 배포합니다.

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를 전달합니다. 이 스크립트는 오토스케일링 Lakebase의 경우 --project <project> --branch <branch>도, 프로비저닝된 Lakebase의 경우 --instance-name <name>도 허용합니다.

3. 앱을 시작합니다.

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

3단계. 배포된 에이전트에 대해 스모크 테스트 수행하기

databricks bundle run 는 러너가 에이전트에 시작 신호를 보내는 즉시 반환되지만, 에이전트 프로세스는 부팅 중에 여전히 실패할 수 있습니다. 5단계. 앱이 정상 상태가 될 때까지 기다리기의 상태 검사 후, /invocations에 카나리아 요청을 전송하는 다음 스모크 테스트 단계를 deploy.yml에 추가합니다:

- 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 앱 에이전트를 프로덕션 환경에 배포하기
• Databricks Apps 에이전트를 부하 테스트하세요