드래그 앤 드롭 없이 완성하는
Power BI 에이전트 한국어 실습 매뉴얼_
단 한 개의 시각적 개체(Visual)도 직접 마우스로 만들지 않고, 제공된 한결전자(K-Retail) 5종 한글 CSV 데이터셋과 Claude AI, Microsoft 공식 Authoring Agent Skills, MCP 서버, 그리고 Desktop Bridge CLI만으로 15분 만에 4페이지 분량의 한국어 경영진 대시보드를 설계·구축·시각 검증하는 실전 가이드입니다.
단순 프롬프트 + 기본 MCP만 사용했을 때
- 기능 한계: DAX 측정값 생성과 1페이지짜리 기본 차트 4~5개 배치에만 그침
- 디자인 부재: 한글 폰트(맑은 고딕/Pretendard) 최적화, 여백, 색상 조화, 시각적 계층 구조가 없는 투박한 결과물
- 검증 불가 (맹목적 생성): 에이전트가 JSON 파일만 뱉어낼 뿐, 실제 화면에서 한글 레이블이 잘렸는지 차트가 깨졌는지 스스로 확인하지 못함
공식 Agent Skills + 2종 CLI + Desktop Bridge 결합
- End-to-End 워크플로우: 요구사항 기획(Planner) → 디자인 아키타입(Design) → PBIR 코드 생성(Authoring) → 배포(Management)
- 자체 시각 검수 루프 (Self-Correction): 에이전트가 직접 Power BI Desktop을 새로고침(Reload)하고 스크린샷을 찍어 눈으로 보고 깨진 UI를 스스로 고침
- 기업 표준 일관성: 한국형 브랜드 테마(
Retail_IQ_Light_KR.json)와 모던 비주얼/네비게이션 바를 완벽 적용
전체 워크플로우를 지탱하는 5계층 기술 스택
에이전트가 한글 데이터를 이해하고(Semantic Model), 화면을 그리고(PBIR Report), 눈으로 확인(Desktop Bridge)하기 위해 필요한 전체 구성 요소입니다.
| 계층 (Layer) | 핵심 구성 요소 | 역할 및 기술적 상세 설명 |
|---|---|---|
| 1. 프로젝트 파일 계층 | PBIP / PBIR / TMDL |
• PBIP (Power BI Project): 단일 바이너리(.pbix)는 외부 AI가 수정할 수 없으므로 반드시 폴더 기반 프로젝트 포맷인 K_Retail_Sales_Demo.pbip로 변환해야 합니다.• TMDL: 시맨틱 모델(테이블, 한글 컬럼, 1:N 관계, DAX 측정값)을 정의하는 텍스트 언어입니다. • PBIR: 리포트 페이지, 비주얼 좌표/바인딩, 필터, 테마( report.json)를 담는 JSON 포맷입니다.
|
| 2. 에이전트 런타임 | Claude Code / Copilot CLI |
• 로컬 파일 시스템을 읽고 쓰며, 터미널 명령어(CLI)와 MCP 도구를 호출하는 멀티모달 LLM 호스트입니다. • 영상에서는 Claude Code에서 Bypass Permissions 모드를 켜서 사람의 개입 없이 루프를 돌렸으며, VS Code 기반 GitHub Copilot에서도 동일하게 동작합니다.
|
| 3. 시맨틱 모델 제어 | Power BI Authoring MCP |
• 구 명칭: Power BI Modeling MCP Server. • 실행 중인 Power BI Desktop의 로컬 Analysis Services(XMLA) 인스턴스에 연결하여 스키마를 프로파일링하고, 라이브 DAX 쿼리를 실행하며, 한글 KPI 측정값을 생성/검증합니다. |
| 4. 리포트 생성 & 브릿지 | powerbi-report-authorpowerbi-desktop |
• Report Authoring CLI: PBIR JSON 스키마 생성, 최신 비주얼 메타데이터 조회 및 구문 검증(validate)을 수행합니다.• Desktop Bridge CLI: 실행 중인 Power BI Desktop 화면을 즉시 새로고침( reload)하고 페이지별 PNG 스크린샷(screenshot)을 캡처합니다.
|
| 5. 지능형 작업 지침서 | microsoft/skills-for-fabric |
• Microsoft가 공식 배포하는 에이전트 플러그인 모음(powerbi-authoring)입니다.• 기획( planning), 디자인(design), 구현(authoring), 배포(management) 4대 스킬이 에이전트의 행동 규칙(MUST/PREFER/AVOID)을 통제합니다.
|
실습 데이터셋(K-Retail)과 .pbip 폴더 해부도
실습 패키지(K_Retail_PowerBI_Agent_실습패키지.zip)에 포함된 5개의 한글 CSV 파일을 Power BI Desktop에 로드한 뒤, 파일 > 다른 이름으로 저장 > Power BI project files (*.pbip)로 저장하면 아래 우측과 같은 코드 구조가 생성됩니다.
1개의 Fact 테이블 + 4개의 Dimension 테이블
- Fact_Sales.csv (매출 팩트 · 2,356건):
주문번호,주문항목번호,주문일자,배송완료일자,CustomerKey,StoreKey,ProductKey,주문수량,통화코드(KRW)
★ 핵심 설계 포인트:주문수량만 있고 단가 컬럼이 없습니다! 에이전트가 MCP를 통해 스스로Dim_Products를 스캔하여 단가를 찾아내도록 설계되었습니다. - Dim_Products.csv (제품 차원 · 18종): 갤럭시 북4 프로, 그램 프로, 올레드 에보 TV, 비스포크 AI 콤보 등 한글
제품명,카테고리,브랜드(삼성/LG/쿠쿠),원가_KRW,판매단가_KRW - Dim_Stores.csv (매장 차원 · 12곳): 강남 본점, 여의도 더현대점, 판교 테크노밸리점, 공식 온라인몰 등
매장명,권역(서울/수도권/영남권/온라인 등),매장유형,매장면적_제곱미터 - Dim_Customers.csv (고객 차원 · 200명):
고객명,성별,연령대,거주권역,고객등급(VIP/골드/실버/일반) - Dim_Date.csv (날짜 차원 · 2024~2026):
Date,연도,분기,월,연월,평일주말구분
K_Retail_Sales_Demo.pbip 저장 시 생성 구조
K_Retail_Practice/
├── Fact_Sales.csv 외 4개 CSV # 원본 한글 실습 데이터
├── Retail_IQ_Light_KR.json # 한국형 커스텀 테마 JSON
├── K_Retail_Sales_Demo.pbip # 프로젝트 진입점 파일
├── K_Retail_Sales_Demo.SemanticModel/ # [MCP 담당 영역]
│ └── definition/
│ ├── tables/ # Fact_Sales.tmdl, Dim_Products.tmdl 등
│ ├── relationships.tmdl # 4개 1:N 관계 배선 정의
│ └── model.tmdl
└── K_Retail_Sales_Demo.Report/ # [CLI & Authoring Skill 담당 영역]
├── StaticResources/
│ └── SharedResources/BaseThemes/ # Retail_IQ_Light_KR.json 복사 위치
└── definition/
├── report.json # 리포트 전역 설정 및 테마 등록
└── pages/ # 4개 한글 페이지 및 Visual JSON
필수 1:N 관계 연결 확인 (모델 보기 탭):
• Dim_Products[ProductKey] → Fact_Sales[ProductKey]
• Dim_Stores[StoreKey] → Fact_Sales[StoreKey]
• Dim_Customers[CustomerKey] → Fact_Sales[CustomerKey]
• Dim_Date[Date] → Fact_Sales[주문일자]
MCP 서버와 2종의 공식 CLI는 실습에서 어떻게 작동하는가?
한결전자 실습 데이터를 처리할 때 에이전트가 백그라운드에서 실행하는 3가지 핵심 엔진의 실제 동작입니다.
Power BI Authoring MCP
실행 중인 K_Retail_Sales_Demo 인메모리 모델과 직접 통신합니다.
- 인스턴스 탐색 및 연결: 로컬에서 열려 있는 Power BI Desktop 프로세스를 찾아 연결합니다.
- 한글 스키마 추론:
Fact_Sales에주문수량만 있고 단가가 없음을 발견한 뒤, 스스로Dim_Products를 읽어판매단가_KRW와원가_KRW를 찾아냅니다. - 탐색용 DAX 쿼리 실행: 2024년~2026년 상반기까지의 날짜 범위와 원화(KRW) 매출 규모(억/천만 원 단위)를 먼저 조회합니다.
- 한글 DAX 측정값 생성 및 검증:
총매출액 = SUMX(Fact_Sales, Fact_Sales[주문수량] * RELATED(Dim_Products[판매단가_KRW]))등 10여 개 측정값을KPI 측정값폴더에 생성하고 검증합니다.
powerbi-report-author
패키지명: @microsoft/powerbi-report-authoring-cli
- 모던 비주얼 규격 조회: 최신 비주얼 타입과 상단 페이지 이동 바인
pageNavigator(v2.1.0)의 정확한 데이터 역할(Role) 바인딩 구조를 조회합니다. - PBIR JSON 스키마 검증 (
validate): 에이전트가 생성한 4개 한글 페이지(경영진 종합 요약, 제품 및 브랜드 분석, 권역 및 매장 분석, 고객 세그먼트 비교)의 JSON 파일 무결성을 검사합니다. - 에러 피드백 루프: JSON 스키마 에러나 테마 선행 오류가 있으면 즉시 라인 위치를 반환하여 에이전트가 스스로 수정하게 만듭니다.
powerbi-desktop (Desktop Bridge)
Power BI Desktop 내부의 로컬 서버와 통신하는 브릿지 CLI입니다.
- 무중단 실시간 새로고침 (
reload): 디스크의 PBIR JSON을 수정한 직후, 열려 있는 Power BI Desktop 화면을 즉시 리로드합니다. - 고해상도 스크린샷 캡처 (
screenshot): 4개 한글 리포트 페이지가 실제로 어떻게 렌더링되었는지 PNG 이미지로 찍어 에이전트에게 전달합니다. - 시각적 자가 교정 지원: 한글 제목이나 네비게이션 버튼(경영진 종합 요약 등)의 레이아웃이 깨지거나 줌 비율이 어긋나면 에이전트가 스크린샷을 눈으로 보고 재수정합니다.
에이전트를 전문가로 바꾸는 4대 Authoring Skills
Microsoft는 microsoft/skills-for-fabric 리포지토리를 통해 에이전트용 플러그인을 제공합니다. 각 스킬(SKILL.md)에는 데이터 시각화 베스트 프랙티스와 엄격한 작업 순서가 정의되어 있으며, VS Code에서 열람 및 우리 회사 표준에 맞게 수정(Edit)할 수 있습니다.
powerbi-report-planning
"임원용 대시보드 만들어줘" 같은 모호한 요청을 받아 Guided Q&A를 통해 타겟 독자, 핵심 질문, KPI를 정의하고 승인된 리포트 명세서(report-spec.md)를 확정(Lock)합니다.
powerbi-report-design
코드를 짜기 전 페이지 아키타입(Archetypes), 적절한 차트 유형, 컬러 팔레트, 타이포그래피, 웹 접근성 기준을 먼저 수립합니다.
powerbi-report-authoring
2종의 CLI를 구동해 PBIR 페이지, 비주얼, 필터, 테마 파일을 생성하고, Desktop 리로드 및 스크린샷 시각 검수 루프를 완수합니다.
powerbi-report-management
검증이 끝난 로컬 PBIP 리포트와 시맨틱 모델을 Microsoft Fabric 워크스페이스로 배포하고 관리합니다.
스킬 내부 규칙 해부 (클릭하여 확인해 보세요)
MUST · 에이전트가 반드시 지켜야 하는 강제 사항
- 시맨틱 모델 선행 검사: 디자인이나 차트 결정을 내리기 전에 반드시 시맨틱 모델의 테이블과 사용 가능한 한글 필드/측정값을 먼저 검사(Inspect)해야 합니다.
- 두 가지 공식 CLI 사용 강제: 임의로 불완전한 JSON을 추측해서 작성하지 않고, 반드시
powerbi-report-author와powerbi-desktopCLI가 둘 다 설치되어 있는지 확인하고 이를 통해 작업해야 합니다. - Completion Gate (완료 관문) 통과:
[파일 편집 → CLI validate 통과 → Desktop reload → 전체 페이지 screenshot 촬영 및 시각적 검토]를 모두 통과하기 전에는 작업 완료를 선언할 수 없습니다.
PREFER · 품질 향상을 위한 권장 사항
- 핵심 설계 입력만 질문: 결과물에 실질적인 영향을 미치는 누락된 디자인 입력값만 간결하게 질문합니다.
- 모던 비주얼 및 네비게이터 활용: 다중 페이지 리포트의 경우 사용자가 리포트 안에서 자연스럽게 이동할 수 있도록 최신
pageNavigator(v2.1.0)와 모던 카드/차트 비주얼을 우선 채택합니다.
AVOID · 환각 및 오류 방지를 위한 금지 사항
- 설계 단계에서 파일 직접 생성 금지:
powerbi-report-design단계에서는 페이지, 비주얼, 필터, 테마나 PBIR 파일을 직접 생성하지 말고 디자인 가이던스만 확정해야 합니다. - 레거시/구형 비주얼 사용 금지: 구형 Q&A 비주얼, Bing Maps 등 더 이상 권장되지 않는 레거시 시각적 개체를 생성하지 않습니다.
기업 맞춤형 스킬 수정 (Edit in VS Code)
Claude Code의 Customize > Plugins > PowerBI Authoring 메뉴에서 각 스킬 우측의 Edit > Edit with VS Code를 누르면 로컬에 설치된 SKILL.md 파일이 열립니다. 여기에 우리 회사의 고정 폰트(맑은 고딕/Pretendard), 원화(₩/원) 단위 표기 규칙, 로고 위치 등을 적어두면 사내 모든 분석가가 동일한 표준으로 리포트를 생성할 수 있습니다.
그대로 복사해서 실행하는 한국어 실습 매뉴얼
다운로드한 K_Retail_PowerBI_Agent_실습패키지.zip의 CSV 5종을 Power BI Desktop에 불러와 K_Retail_Sales_Demo.pbip로 저장한 뒤, 아래 5단계를 순서대로 진행합니다.
사전 준비: CLI 설치 및 플러그인 마켓플레이스 연동
Node.js가 설치된 상태에서 공식 CLI를 설치하고, Claude Code(또는 Copilot CLI)에 Microsoft 스킬 리포지토리를 등록합니다.
# 1. Power BI Report Authoring CLI 설치 확인 npm install -g @microsoft/powerbi-report-authoring-cli # 2. Claude Code GUI에서 추가 시: # Customize -> Plugins -> Add (+) -> Add marketplace -> Add from repository 선택 # 입력 URL: https://github.com/microsoft/skills-for-fabric -> Sync 클릭 -> 'powerbi-authoring' 설치 # 3. 터미널/Copilot CLI 명령어로 추가 시: /plugin marketplace add microsoft/skills-for-fabric /plugin install powerbi-authoring@fabric-collection
시맨틱 모델 연결 및 한글 KPI DAX 측정값 자동 생성 (MCP 구동)
Power BI Desktop에서 K_Retail_Sales_Demo.pbip 파일을 열어둔 상태로, 해당 폴더에서 Claude Code 세션을 열고 아래 한국어 프롬프트를 입력합니다.
현재 열려 있는 K_Retail_Sales_Demo.pbip 파일에 연결해 줘. 시맨틱 모델 스키마를 확인한 뒤, 대시보드 KPI 카드와 차트에 사용할 핵심 DAX 측정값들을 'KPI 측정값'이라는 별도 폴더 안에 생성하고 모델에서 검증해 줘. (포함할 측정값 예시: 총매출액, 총원가, 매출총이익, 이익률(%), 총주문건수, 총판매수량, 고객당 평균매출, 전년 동기 대비 매출 성장률 YoY % 등)
Authoring Skill 호출 및 4페이지 한국어 대시보드 구축 (CLI + 자체 검수 루프)
중요 트러블슈팅 팁: 슬래시 커맨드 인식 오류를 방지하기 위해 플러그인 네임스페이스가 포함된 정식 등록 명칭인 powerbi-authoring:powerbi-report-authoring을 프롬프트에 직접 명시합니다.
powerbi-authoring:powerbi-report-authoring 스킬을 사용해서 K_Retail_Sales_Demo.pbip 파일에 4페이지 분량의 한국어 경영진 리포트를 만들어 줘. 기존 빈 페이지는 삭제해도 돼. 각 페이지 구성은 다음과 같아: - 1페이지: 경영진 종합 요약 (Executive Summary - 핵심 KPI 카드 5개, 월별 매출 추이, 카테고리별 성과, 연도 슬라이서) - 2페이지: 제품 및 브랜드 분석 (Product Analysis - 카테고리/브랜드별 매출 및 이익률 비교) - 3페이지: 권역 및 매장 분석 (Store Analysis - 서울/수도권/영남권/온라인 등 권역별 및 매장 유형별 성과) - 4페이지: 고객 세그먼트 및 매출 비교 (Customer & Sales Comparison - 고객등급/연령대별 분석 및 전년 대비 비교) 리포트 상단에는 각 페이지로 이동할 수 있는 페이지 네비게이션(Page Navigator) 바를 추가하고, CLI 검증과 스크린샷 캡처 리뷰까지 완료해 줘.
한국형 브랜드 테마(Retail_IQ_Light_KR.json) 일괄 적용 및 색상 재정비(Re-sweep)
실습 폴더에 함께 들어 있는 맑은 고딕/Pretendard 기반 테마 파일(Retail_IQ_Light_KR.json)을 적용하여 리포트 전체 디자인을 통일합니다.
폴더 안에 있는 Retail_IQ_Light_KR.json 파일을 이 리포트의 커스텀 테마로 등록하고, 개별 비주얼에 하드코딩된 색상들을 새 테마 팔레트에 맞게 전체 재정비(Re-sweep)한 뒤 다시 검증해 줘.
최종 확인 시 주의사항: "저장하지 않고 닫기 (Don't Save)"
에이전트가 디스크의 PBIR 파일들을 직접 수정했으므로, 만약 수동으로 Power BI Desktop을 껐다 켜서 확인해야 할 때는 기존에 열려 있던 창을 닫을 때 반드시 '저장 안 함(Don't Save)'을 클릭한 뒤 K_Retail_Sales_Demo.pbip를 다시 열어야 합니다. '저장'을 누르면 예전 빈 화면 상태가 에이전트가 작성한 새로운 JSON 파일들을 덮어써 버립니다.
토큰 비용 분석과 Microsoft 공식 레퍼런스
영상 마지막에 공개된 실제 토큰 사용량(`/context` 명령어 조회 결과)과 이 아키텍처를 구성하는 Microsoft 공식 문서(MS Learn, GitHub, Fabric Blog) 전체 목록입니다.
4페이지 대시보드 구축 총 비용: 약 $3 ~ $5 USD
- 총 소모 토큰:
259,000 Tokens (259k) - 시스템 & 스킬 도구 영역: 약
52k Tokens(전체 비중의 약 20%) - 대화 & 스크린샷 멀티모달 검수 영역: 약
207k Tokens(고해상도 스크린샷을 반복 캡처하여 시각적으로 리뷰하는 과정에서 대부분의 토큰 사용) - 비용 환산: 1M 입력 토큰당 $5, 1M 출력 토큰당 $25 기준 시 약 $3~$5 USD (한화 약 4,200원~7,000원)로 엔터프라이즈급 4페이지 리포트 완성
영상에서 예고된 차세대 확장 워크플로우
- PowerShell + GitHub Copilot 연동: Claude 대신 PowerShell 터미널에서 MS Copilot과 CLI를 직결하는 방식
- Fabric Apps for Semantic Models: Power BI June 2026 업데이트의 또 다른 핵심 기능으로, 시맨틱 모델 위에 바로 맞춤형 애플리케이션을 구축하는 기능
- New Desktop Bridge 고도화: 로컬 Power BI Desktop과 외부 AI 에이전트 간의 양방향 실시간 제어 확장
참조된 Microsoft 공식 문서 및 GitHub 링크 모음
| 분류 | 문서 / 리포지토리 제목 | 공식 URL 링크 |
|---|---|---|
| GitHub (필수) | Microsoft Skills for Fabric 공식 리포지토리 Claude Code / Copilot 플러그인 마켓플레이스 등록 소스 |
github.com/microsoft/skills-for-fabric |
| GitHub | PBIR CLI Authoring 상세 레퍼런스 (SKILL 문서)powerbi-report-author 및 powerbi-desktop 명령어 명세 |
skills/powerbi-report-cli/references/authoring.md |
| MS Learn | Power BI Report Authoring Skill 공식 개요 Planner, Design, Authoring 에이전트 스킬 아키텍처 설명 |
learn.microsoft.com/.../power-bi-report-authoring-skill-overview |
| MS Learn | Power BI Authoring (Modeling) MCP Server 문서 시맨틱 모델 연결, TMDL 조작 및 DAX 쿼리 실행 MCP 가이드 |
learn.microsoft.com/.../mcp/power-bi-authoring-mcp |
| MS Learn | Power BI Desktop Projects (PBIP / PBIR / TMDL) 개요 코드 기반 프로젝트 포맷 및 폴더 구조 공식 문서 |
learn.microsoft.com/.../projects/projects-overview |
| Fabric Blog | AI-Powered Power BI Reporting with Agent Skills 영상 초반(01:32)에 소개된 June 2026 공식 발표 블로그 원문 |
community.fabric.microsoft.com/.../5190703 |
| Fabric Blog | Power BI June 2026 Feature Summary & Desktop Bridge 2026년 6월 전체 업데이트 요약 및 Desktop Bridge 프리뷰 안내 |
community.fabric.microsoft.com/.../5193264 |