Skip to main content
AI Dev Kit Builder App을 로컬 환경에 설치하고 Databricks 워크스페이스에 연결하는 단계별 가이드입니다.

​
사전 요구 사항

주의 다음 항목이 모두 준비되어야 합니다:
  • Databricks Workspace(Premium 이상)
  • SQL Warehouse(Serverless 권장)
  • Cluster(범용 클러스터 1개 이상)
  • Python 3.11+
  • Node.js 18+
  • uv 패키지 매니저 (pip install uv)
  • Anthropic API Key(Claude 모델 사용)

​
1단계: 레포지토리 클론

AI Dev Kit 전체 레포지토리를 클론합니다. Builder App은 databricks-builder-app 디렉토리에 있습니다. 
git clone https://github.com/databricks-solutions/ai-dev-kit.git
cd ai-dev-kit/databricks-builder-app
참고 왜 전체 레포를 클론하나요? Builder App은 databricks-mcp-server에 의존합니다. 전체 레포를 클론해야 MCP Server가 로컬에서 올바르게 참조됩니다. pyproject.toml의 [project.optional-dependencies]에서 databricks-mcp-server가 로컬 경로로 참조되는 것을 확인할 수 있습니다.

​
2단계: 자동 설치 (권장)

setup.sh 스크립트가 백엔드와 프론트엔드를 한 번에 설정합니다. 
./scripts/setup.sh
이 스크립트는 다음을 수행합니다:
  • Python 가상환경 생성 및 의존성 설치
  • Node.js 의존성 설치
  • .env.local 템플릿 생성
  • Alembic DB 마이그레이션 실행
왜 uv를 사용하나요?uv는 Rust로 작성된 초고속 Python 패키지 매니저입니다. pip보다 10~100배 빠르며, 의존성 해결이 더 정확합니다. AI Dev Kit의 복잡한 의존성 트리(LangChain, Claude SDK, MCP Server 등)를 안정적으로 설치하기 위해 uv를 기본으로 사용합니다.
팁 자동 설치가 실패하면 아래 수동 설치 절차를 따르세요.

​
2단계 (대안): 수동 설치

​
Backend 설정

# Python 가상환경 생성
uv venv
source .venv/bin/activate

# 의존성 설치
uv pip install -e ".[dev]"

​
Frontend 설정

cd client
npm install
cd ..

​
3단계: 환경 변수 구성

프로젝트 루트에 .env.local 파일을 생성합니다. 이 파일은 Builder App의 모든 외부 연결 정보를 관리합니다. 왜 .env.local인가? Builder App은 환경 변수를 세 단계로 로드합니다: .env (기본값) → .env.local (로컬 오버라이드) → 시스템 환경 변수. .env.local은 .gitignore에 포함되어 있어 민감한 정보가 Git에 커밋되지 않습니다. 
# .env.local

# Anthropic API Key (필수)
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# Databricks 연결 정보 (필수)
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_TOKEN=dapixxxxxxxxxxxxxxxx

# Lakebase 데이터베이스 (택 1)
# 옵션 A: Autoscale Endpoint
LAKEBASE_ENDPOINT=your-lakebase-endpoint

# 옵션 B: Provisioned Instance
LAKEBASE_INSTANCE_NAME=your-instance-name

# 옵션 C: 직접 PostgreSQL URL
LAKEBASE_PG_URL=postgresql://user:pass@host:port/dbname

​
환경 변수 상세 설명

변수필수용도발급 방법
ANTHROPIC_API_KEY필수 (로컬)Claude 모델 호출Anthropic Console → API Keys
DATABRICKS_HOST필수Workspace 연결 URLWorkspace URL 복사 (예: https://adb-123.12.azuredatabricks.net)
DATABRICKS_TOKEN필수 (로컬)API 인증Workspace → User Settings → Developer → Access Tokens
LAKEBASE_ENDPOINT선택대화 이력 영구 저장Workspace → Catalog → Lakebase → Endpoints
주의 Databricks Apps로 배포할 때는ANTHROPIC_API_KEY와 DATABRICKS_TOKEN을 직접 설정할 필요가 없습니다. Apps 환경에서는 Databricks Foundation Model API(FMAPI)를 사용하고, 사용자 인증은 X-Forwarded-Access-Token 헤더로 자동 전달됩니다.

​
LLM 선택: Anthropic 직접 vs Databricks FMAPI

옵션설정장점단점
Anthropic 직접ANTHROPIC_API_KEY 설정최신 모델 즉시 사용, 안정적API 키 관리 필요, 별도 과금
Databricks FMAPILLM_PROVIDER=DATABRICKSAPI 키 불필요, 워크스페이스 과금 통합사용 가능한 모델 한정
Azure OpenAILLM_PROVIDER=AZUREAzure 엔터프라이즈 환경 통합Azure 리소스 별도 구성 필요

​
4단계: 데이터베이스 마이그레이션

Lakebase를 사용하는 경우 Alembic 마이그레이션을 실행합니다. 
alembic upgrade head
Alembic 마이그레이션이란? Alembic은 SQLAlchemy 기반의 데이터베이스 스키마 버전 관리 도구입니다. upgrade head 명령은 현재 DB 스키마를 최신 버전으로 업데이트합니다. Builder App의 DB 스키마가 변경될 때(새 테이블 추가, 컬럼 변경 등) 이 명령으로 안전하게 마이그레이션합니다.

​
Lakebase 데이터 모델

Builder App은 다음 테이블들을 Lakebase에 저장합니다:
테이블역할주요 필드
projects프로젝트 메타데이터id, name, created_at, user_id
conversations대화 세션id, project_id, title, created_at
messages개별 메시지id, conversation_id, role, content
executions에이전트 실행 기록id, conversation_id, status, tool_calls
주의 Lakebase 없이도 Builder App을 실행할 수 있습니다. 이 경우 프로젝트 데이터는 로컬 파일 시스템(projects/ 디렉토리)에만 저장됩니다. 프로덕션 환경에서는 Lakebase 사용을 강력히 권장합니다.

​
5단계: 개발 서버 실행

./scripts/start_dev.sh
또는 수동으로 백엔드와 프론트엔드를 각각 실행합니다: 
# 터미널 1: Backend (FastAPI)
uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload

# 터미널 2: Frontend (React)
cd client
npm run dev
왜 두 개의 서버를 실행하나요? 개발 환경에서는 프론트엔드(React)와 백엔드(FastAPI)를 분리하여 실행합니다. React의 Hot Module Replacement(HMR)로 프론트엔드 코드 변경이 즉시 반영되고, FastAPI의 --reload 옵션으로 백엔드 코드 변경도 자동 재시작됩니다. 프로덕션 배포 시에는 프론트엔드를 빌드하여 정적 파일로 만든 후 FastAPI가 함께 서빙합니다.

​
개발 서버 아키텍처

개발 환경:
  브라우저 → React Dev Server (:3000) → API Proxy → FastAPI (:8000) → MCP Server

프로덕션 환경:
  브라우저 → FastAPI (:8000) → 정적 파일 서빙 (빌드된 React)
                             → API 엔드포인트
                             → MCP Server
실행 후 접속:
  • Frontend: http://localhost:3000
  • Backend API: http://localhost:8000
  • API 문서: http://localhost:8000/docs (Swagger UI 자동 생성)

​
6단계: 첫 프로젝트 생성 및 테스트

  1. 브라우저에서 http://localhost:3000에 접속합니다.
  2. New Project 버튼을 클릭하여 새 프로젝트를 생성합니다.
  3. 채팅 창에 다음과 같은 메시지를 입력합니다:
내 워크스페이스에 있는 카탈로그 목록을 보여줘
  1. 에이전트가 execute_sql 도구를 호출하여 SHOW CATALOGS 결과를 반환합니다.

​
무엇이 일어나고 있는가?

사용자의 자연어 요청이 에이전트에게 전달되면, 다음과 같은 과정이 자동으로 수행됩니다: 
1. [Claude Agent] "카탈로그 목록" 요청을 분석
2. [Claude Agent] 사용 가능한 MCP 도구 중 execute_sql을 선택
3. [MCP Server]  execute_sql 도구에 "SHOW CATALOGS" SQL 전달
4. [Databricks]  SQL Warehouse에서 쿼리 실행
5. [MCP Server]  결과를 에이전트에게 반환
6. [Claude Agent] 결과를 사용자 친화적 형태로 포매팅하여 응답
팁 에이전트가 사용하는 도구 호출 과정이 실시간으로 스트리밍됩니다. 어떤 MCP 도구가 호출되었는지, 어떤 SQL이 실행되었는지 확인할 수 있습니다. 이 투명성은 에이전트의 행동을 검증하고 디버깅하는 데 필수적입니다.

​
추가 테스트 시나리오

첫 프로젝트가 성공적으로 동작하면, 다음 시나리오를 시도해보세요:
테스트입력 예시확인 사항
SQL 실행”main 카탈로그의 테이블 목록 보여줘”execute_sql 도구 호출 확인
클러스터 상태”현재 실행 중인 클러스터 보여줘”list_clusters 도구 호출 확인
파일 업로드”이 CSV 파일을 Volume에 업로드해줘”upload_to_volume 도구 호출 확인
스킬 활용”합성 데이터로 매출 테이블 만들어줘”synthetic-data 스킬 로드 + SQL 실행

​
Databricks Apps로 배포 (프로덕션)

Builder App을 Databricks Apps에 배포하면 팀 전체가 사용할 수 있습니다.

​
프론트엔드 빌드

cd client
npm run build
cd ..

​
app.yaml 구성

command:
  - uvicorn
  - server.app:app
  - --host
  - 0.0.0.0
  - --port
  - "8000"

env:
  - name: ANTHROPIC_API_KEY
    valueFrom: secret
  - name: LAKEBASE_ENDPOINT
    value: your-lakebase-endpoint

​
배포

databricks apps deploy builder-app --source-code-path .
참고 Databricks Apps로 배포하면 X-Forwarded-User와 X-Forwarded-Access-Token 헤더를 통해 자동으로 사용자별 인증이 적용됩니다. 별도의 DATABRICKS_TOKEN 설정이 필요 없습니다.

​
문제 해결

증상원인해결 방법
ANTHROPIC_API_KEY not set환경 변수 누락.env.local 파일에 키 추가
SQL 실행 실패Warehouse 미실행Workspace에서 SQL Warehouse 시작
MCP 도구 로드 실패databricks-mcp-server 미설치uv pip install -e ".[dev]" 재실행
DB 마이그레이션 오류Lakebase 연결 실패LAKEBASE_* 환경 변수 확인
프론트엔드 빈 화면Node 의존성 누락cd client && npm install

​
다음 단계