Tool 목록 및 - Databricks 가이드

이 문서는 AI Dev Kit 섹션의 일부입니다.

Builder App 에이전트가 사용하는 MCP 도구, 빌트인 도구, 스킬 시스템의 전체 목록과 설명입니다.

Tool 설계 철학

Builder App의 도구 시스템은 세 가지 설계 원칙을 따릅니다:

1. 최소 권한 원칙 (Principle of Least Privilege)

각 도구는 필요한 최소한의 API 권한만 사용합니다. 예를 들어 execute_sql 도구는 SQL 실행 권한만 있으면 되고, 클러스터 관리 권한은 필요하지 않습니다. 사용자의 Databricks 토큰에 설정된 권한 범위 내에서만 도구가 작동합니다.

2. 멱등성 (Idempotency)

create_or_update_* 패턴의 도구들은 멱등적 으로 설계되었습니다. 같은 요청을 여러 번 실행해도 결과가 동일합니다. 대시보드, Genie Space, 파이프라인 등을 create_or_update로 만들면, 이미 존재하면 업데이트하고 없으면 생성합니다. 이는 에이전트가 실패 후 재시도할 때 부작용 없이 안전하게 실행 할 수 있게 합니다.

3. 비동기 장시간 작업 처리

10초 이상 소요되는 작업(파이프라인 실행, 대규모 SQL 등)은 백그라운드 스레드 에서 실행됩니다. 에이전트는 operation_id를 받아 주기적으로 상태를 폴링하고, 완료되면 결과를 수신합니다. 이 패턴 덕분에 에이전트가 장시간 작업을 기다리는 동안 다른 작업을 병렬로 수행 할 수 있습니다.

각 Tool의 내부 작동 방식

MCP 도구가 호출되면 내부적으로 다음 과정이 진행됩니다:

에이전트 → MCP Protocol → MCP Server → 입력 검증 → Databricks SDK 호출 → 결과 포매팅 → 반환

입력 검증: 파라미터 타입, 필수값, 범위를 검증합니다
Databricks SDK 호출: databricks-sdk-py를 사용하여 REST API를 호출합니다
에러 처리: API 오류 시 사용자 친화적 메시지로 변환합니다
결과 포매팅: JSON 응답을 에이전트가 이해할 수 있는 텍스트로 변환합니다

Databricks MCP Server Tools

databricks-mcp-server에서 제공하는 30개 이상의 도구가 mcp__databricks__<tool_name> 형태로 에이전트에 로드됩니다.

SQL 실행

Tool	설명
`execute_sql`	SQL Warehouse에서 단일 SQL 쿼리 실행
`execute_sql_multi`	여러 SQL 문을 순차 실행

"main 카탈로그의 sales 스키마에 있는 테이블 목록을 보여줘"
→ execute_sql: SHOW TABLES IN main.sales

Compute 관리

Tool	설명
`list_clusters`	워크스페이스 내 클러스터 목록 조회
`get_best_cluster`	사용 가능한 최적 클러스터 자동 선택
`get_cluster_status`	특정 클러스터 상태 확인
`start_cluster`	종료된 클러스터 시작
`list_warehouses`	SQL Warehouse 목록 조회
`get_best_warehouse`	사용 가능한 최적 Warehouse 자동 선택

DLT 파이프라인

Tool	설명
`create_pipeline`	새 DLT 파이프라인 생성
`create_or_update_pipeline`	파이프라인 생성 또는 업데이트
`update_pipeline`	기존 파이프라인 설정 변경
`start_update`	파이프라인 실행(업데이트) 시작
`get_pipeline`	파이프라인 상세 정보 조회
`get_pipeline_events`	파이프라인 이벤트 로그 조회
`get_update`	특정 업데이트 실행 상태 조회
`find_pipeline_by_name`	이름으로 파이프라인 검색
`stop_pipeline`	실행 중인 파이프라인 중지
`delete_pipeline`	파이프라인 삭제

파일 관리

Tool	설명
`upload_file`	Workspace에 파일 업로드
`upload_to_volume`	Unity Catalog Volume에 파일 업로드
`upload_folder`	폴더 전체 업로드
`download_from_volume`	Volume에서 파일 다운로드
`list_volume_files`	Volume 내 파일 목록 조회
`get_volume_file_info`	Volume 파일 메타데이터 조회
`create_volume_directory`	Volume 디렉토리 생성
`delete_volume_file`	Volume 파일 삭제
`delete_volume_directory`	Volume 디렉토리 삭제

Jobs 관리

Tool	설명
`manage_jobs`	Job 생성, 조회, 수정, 삭제
`manage_job_runs`	Job Run 실행, 모니터링, 취소

Genie Space

Tool	설명
`create_or_update_genie`	Genie Space 생성 또는 업데이트
`ask_genie`	Genie Space에 자연어 질문 전송
`get_genie`	Genie Space 상세 정보 조회
`delete_genie`	Genie Space 삭제

대시보드

Tool	설명
`create_or_update_dashboard`	AI/BI 대시보드 생성 또는 업데이트
`get_dashboard`	대시보드 상세 정보 조회
`publish_dashboard`	대시보드를 공개 상태로 배포
`delete_dashboard`	대시보드 삭제

Model Serving

Tool	설명
`query_serving_endpoint`	Serving Endpoint에 추론 요청 전송
`get_serving_endpoint_status`	Endpoint 상태 및 설정 조회
`list_serving_endpoints`	전체 Serving Endpoint 목록 조회

Unity Catalog

Tool	설명
`manage_uc_objects`	Catalog, Schema, Table, Volume 등 UC 객체 관리
`manage_uc_grants`	UC 객체에 대한 권한(GRANT/REVOKE) 관리
`manage_uc_tags`	UC 객체 태그 관리
`manage_uc_connections`	외부 연결 관리
`manage_uc_storage`	Storage Credential 및 외부 위치 관리
`manage_uc_sharing`	Delta Sharing 관리
`manage_uc_monitors`	테이블 모니터 관리
`manage_uc_security_policies`	보안 정책 관리

Vector Search

Tool	설명
`create_or_update_vs_endpoint`	Vector Search Endpoint 생성/업데이트
`create_or_update_vs_index`	Vector Search Index 생성/업데이트
`query_vs_index`	벡터 인덱스에 유사도 검색 실행
`manage_vs_data`	인덱스 데이터 동기화 관리
`get_vs_endpoint`	Endpoint 상태 조회
`get_vs_index`	Index 상태 조회

기타

Tool	설명
`manage_workspace`	Workspace 객체(노트북, 폴더) 관리
`manage_ka`	Knowledge Assistant 관리
`manage_mas`	Multi-Agent System 관리
`manage_metric_views`	Metric View 관리
`get_current_user`	현재 사용자 정보 조회
`create_or_update_app`	Databricks App 생성/업데이트
`execute_databricks_command`	클러스터에서 명령 실행
`run_python_file_on_databricks`	Python 파일을 클러스터에서 실행

Built-in Tools (Claude Agent SDK)

에이전트가 프로젝트 파일을 직접 조작하는 데 사용하는 빌트인 도구입니다.

Tool	설명
Read	파일 내용 읽기
Write	새 파일 생성
Edit	기존 파일 수정 (diff 기반)
Glob	파일 패턴 검색
Grep	파일 내용 정규식 검색
Skill	스킬 파일 로드 및 실행

참고 Built-in Tools로 에이전트는 프로젝트 디렉토리 내에서 노트북, SQL 파일, Python 스크립트 등을 직접 생성하고 편집할 수 있습니다.

Skills System

29개의 마크다운 기반 스킬 파일이 에이전트에게 Databricks 작업 수행 패턴을 가르칩니다. 에이전트는 /skill 명령으로 필요한 스킬을 로드합니다.

주요 스킬 목록

스킬	설명
synthetic-data	합성 데이터 생성 가이드
dashboard	AI/BI 대시보드 생성 패턴
genie-space	Genie Space 구성 및 인스트럭션 작성
sdp	Spark Declarative Pipeline(SDP) 패턴
unity-catalog	UC 객체 생성 및 권한 관리
python-sdk	Databricks Python SDK 사용 패턴
agent-bricks	Knowledge Assistant, Genie Agent 등 Agent Bricks 구축
lakebase	Lakebase(PostgreSQL) 설정 및 사용
jobs	Databricks Jobs 생성 및 스케줄링
dabs	Databricks Asset Bundles 구성
apps	Databricks Apps 풀스택 개발(APX 프레임워크)
mlflow	MLflow 실험 및 모델 평가
model-serving	Model Serving Endpoint 구성
vector-search	Vector Search Index 생성 및 RAG 패턴

팁 스킬은 에이전트의 “사전 지식”입니다. 예를 들어 “대시보드를 만들어줘”라고 요청하면, 에이전트가 dashboard 스킬을 로드한 후 올바른 Lakeview 대시보드 JSON 구조를 생성합니다.

커스텀 스킬 추가

프로젝트 디렉토리의 skills/ 폴더에 마크다운 파일을 추가하면 에이전트가 해당 스킬을 인식합니다.

<!-- skills/my-custom-skill.md -->
# My Custom Skill

## 개요
이 스킬은 특정 비즈니스 로직을 수행하는 방법을 안내합니다.

## 단계
1. 먼저 데이터를 조회합니다.
2. 필요한 변환을 수행합니다.
3. 결과를 저장합니다.

도구 사용 패턴

에이전트가 도구를 조합하여 복잡한 작업을 수행하는 대표적인 패턴입니다.

순차 실행 패턴

이전 도구의 출력이 다음 도구의 입력이 되는 패턴입니다.

manage_uc_objects (스키마 생성) → execute_sql (테이블 생성) → create_or_update_dashboard (대시보드 생성)

조건 분기 패턴

이전 도구의 결과에 따라 다음 행동을 결정하는 패턴입니다.

list_clusters (클러스터 목록 조회)
  ├─ 실행 중인 클러스터 있음 → get_best_cluster → execute_databricks_command
  └─ 없음 → start_cluster → (대기) → execute_databricks_command

반복 확인 패턴

장시간 작업의 완료를 대기하는 패턴입니다.

start_update (파이프라인 실행)
  → get_update (상태 확인) → RUNNING → (대기) → get_update
  → get_update (상태 확인) → COMPLETED → 결과 보고

참고 에이전트는 이러한 패턴을 스킬 파일 에서 학습합니다. 예를 들어 sdp 스킬은 파이프라인 생성 → 실행 → 상태 확인의 전체 흐름을 안내합니다.

​Tool 설계 철학

​1. 최소 권한 원칙 (Principle of Least Privilege)

​2. 멱등성 (Idempotency)

​3. 비동기 장시간 작업 처리

​각 Tool의 내부 작동 방식

​Databricks MCP Server Tools

​SQL 실행

​Compute 관리

​DLT 파이프라인

​파일 관리

​Jobs 관리

​Genie Space

​대시보드

​Model Serving

​Unity Catalog

​Vector Search

​기타

​Built-in Tools (Claude Agent SDK)

​Skills System

​주요 스킬 목록

​커스텀 스킬 추가

​도구 사용 패턴

​순차 실행 패턴

​조건 분기 패턴

​반복 확인 패턴

​참고 링크