1. 소개
생성형 AI 모델은 강력한 추론 도구이지만 기관 컨텍스트가 부족합니다. 임원이 AI 에이전트에게 '1분기 수익이 얼마인가요?'라고 물으면 에이전트는 데이터 레이크에서 '수익'이라는 이름의 테이블을 수십 개 찾을 수 있습니다. 일부는 엄격한 재무 보고서이고, 일부는 실시간 마케팅 추정치이며, 많은 부분이 지원 중단된 샌드박스일 가능성이 높습니다.
명시적인 근거가 없으면 AI 에이전트는 간단한 이름 유사성을 기반으로 테이블을 선택하므로 검증되지 않은 데이터에서 파생된 "설득력 있게 잘못된" 답변이 생성됩니다.
이 Codelab은 거버넌스 인식 AI 에이전트를 빌드하는 방법을 알아보는 2부작 시리즈의 일부입니다.
이 첫 번째 부분에서는 데이터 기반을 빌드합니다. BigQuery에서 현실적인 '지저분한' 데이터 레이크를 설정하고, 엄격한 메타데이터 태그 (Knowledge Catalog 관점)를 적용하여 유효한 데이터를 노이즈와 구분하고, Antigravity (AGY) CLI를 사용하여 에이전트가 데이터 거버넌스 규칙을 엄격하게 준수하는지 로컬에서 테스트합니다.
모델 컨텍스트 프로토콜 (MCP) 및 Cloud Run을 사용하여 로컬 에이전트 프로토타입을 안전한 엔터프라이즈급 웹 애플리케이션에 배포하는 방법을 다루는 이 시리즈의 두 번째 부분을 읽어보세요. 👉 2부 읽어보기
학습할 내용
- 설정 스크립트를 사용하여 현실적인 다단계 데이터 레이크를 배포합니다.
- Knowledge Catalog에서 커스텀 메타데이터 템플릿 (관점 유형)을 설계하고 등록하여 공식 데이터 제품과 원시 샌드박스 테이블을 구분합니다.
- 애플리케이션 코드를 작성하기 전에 AGY CLI 를 사용하여 데이터 거버넌스 규칙을 로컬에서 확인합니다.
필요한 항목
- 결제가 사용 설정된 Google Cloud 프로젝트.
- Google Cloud Shell에 대한 액세스 권한 (AGY CLI는 Cloud Shell에 사전 설치되어 있음).
- BigQuery 및 Knowledge Catalog에 대한 기본적인 이해와 숙련도.
주요 개념
- Knowledge Catalog: 통합 메타데이터 관리 서비스입니다. 이를 사용하여 기술 메타데이터 (스키마)를 비즈니스 컨텍스트 (거버넌스)로 보강합니다.
- 관점 유형: 구조화된 메타데이터 템플릿입니다. 자유 형식 텍스트 태그와 달리 관점은 엄격한 유형 지정 (열거형, 부울)을 적용하므로 머신이 평가하는 데 안정적입니다.
2. 설정 및 요건
Cloud Shell 시작
Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.
Google Cloud 콘솔의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.
환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.
가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.
환경 초기화
Cloud Shell을 열고 모든 명령어가 올바른 인프라를 타겟팅하도록 프로젝트 변수를 설정합니다.
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
API 사용 설정
다음 안내를 실행하는 데 필요한 Google Cloud 서비스를 사용 설정합니다.
gcloud services enable \
bigquery.googleapis.com \
dataplex.googleapis.com
저장소 복제
GitHub 저장소에서 인프라 코드 및 자동화 스크립트를 가져옵니다. Cloud Shell에서 디스크 공간을 절약하기 위해 이 실습에 필요한 특정 폴더만 다운로드합니다.
# Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
# Specify and download only the folder we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context
'지저분한' 데이터 레이크 빌드
실제 데이터 환경은 거의 정리되지 않습니다. 현실을 시뮬레이션하려면 '공식' 데이터 마트와 신뢰할 수 없는 '샌드박스' 테이블을 혼합해야 합니다.
설정 스크립트를 사용하여 BigQuery 데이터 세트와 테이블을 배포합니다.
- 설정 스크립트를 실행 가능하게 만들고 실행합니다. 이렇게 하면 세 개의 BigQuery 데이터 세트 (
finance_mart,marketing_prod,analyst_sandbox)가 생성되고 테이블이 샘플 데이터로 채워집니다.
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
체크포인트: 이제 완전히 채워졌지만 완전히 관리되지 않는 데이터 레이크가 있습니다. AI에게는 모든 테이블이 똑같아 보입니다.
3. 데이터 거버넌스 템플릿 (관점 유형) 만들기
이제 데이터 거버넌스 규칙을 정의합니다. Knowledge Catalog에서는 재사용 가능한 강력한 유형의 메타데이터 템플릿인 관점 유형을 만들어 이 작업을 수행합니다.
gcloud CLI를 사용하여 이 템플릿을 등록하여 정의 방법을 확인할 수 있습니다.
관점 스키마 검사
aspect_template.json의 콘텐츠를 출력하여 스키마 정의를 확인합니다.
cat aspect_template.json
다음 JSON 구조가 표시됩니다.
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
...
}
]
}
이 스키마는 중요도 등급 (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC)에 enum과 is_certified에 bool과 같은 엄격한 데이터 유형을 적용합니다. 이렇게 하면 메타데이터가 구조화되고 머신이 읽을 수 있는 상태로 유지됩니다.
관점 유형 등록
다음 gcloud 명령어를 실행하여 Knowledge Catalog 레지스트리에 이 템플릿을 등록합니다.
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
4. 거버넌스 적용
이 단계는 매우 중요한 엔지니어링 단계입니다. 현재 테이블 finance_mart.fin_monthly_closing_internal 및 analyst_sandbox.tmp_data_dump_v2_final_real은 LLM과 동일하게 보입니다. 열이 있는 객체일 뿐입니다.
거버넌스 엔지니어는 이러한 테이블을 구분하기 위해 관점 (인증된 메타데이터 라벨)을 연결해야 합니다. 실제 엔터프라이즈에서는 CI/CD 파이프라인을 통해 이 작업을 자동화합니다. 스크립트를 사용하여 자동화를 시뮬레이션합니다.
거버넌스 페이로드 생성
Knowledge Catalog 관점 키는 전역적으로 고유해야 합니다 (프로젝트 ID로 시작). ./generate_payloads.sh 스크립트는 YAML 메타데이터 파일을 동적으로 생성합니다.
chmod +x ./generate_payloads.sh
./generate_payloads.sh
출력:
이렇게 하면 거버넌스 시나리오 (Gold/Internal, Gold/Public, Silver/Realtime, Bronze/Sandbox)를 정의하는 4개의 YAML 파일이 포함된 './aspect_payloads' 폴더가 생성됩니다.
CLI로 관점 적용
스크립트를 실행하기 전에 프로세스를 이해하기 위해 실제로 적용하는 내용을 살펴보겠습니다. 다음 명령어를 실행하여 내부 금융 페이로드의 구조를 확인합니다.
cat aspect_payloads/fin_internal.yaml
다음 콘텐츠가 표시됩니다.
your-project-id.us-central1.official-data-product-spec:
data:
product_tier: GOLD_CRITICAL
data_domain: FINANCE
usage_scope: INTERNAL_ONLY
update_frequency: DAILY_BATCH
is_certified: true
이 YAML은 is_certified: true 플래그를 설정하고 GOLD_CRITICAL 등급을 할당하는 등 비즈니스 컨텍스트를 명시적으로 정의합니다. LLM에 테이블 이름을 기반으로 추측하는 대신 평가할 명확하고 구조화된 규칙을 제공합니다.
이제 애플리케이션 스크립트를 실행합니다. 이렇게 하면 BigQuery 테이블을 반복하고 gcloud dataplex entries update 명령어를 실행하여 이 엄격한 메타데이터를 연결합니다.
chmod +x ./apply_governance.sh
./apply_governance.sh
검증 (선택사항)
계속하기 전에 콘솔에서 메타데이터가 올바르게 적용되었는지 확인합니다.
- Google Cloud 콘솔에서 Knowledge Catalog 페이지를 엽니다. 왼쪽 탐색 메뉴에 'Knowledge Catalog'가 표시되지 않으면 Google Cloud 콘솔 창 상단의 검색창을 사용하여 'Knowledge Catalog'를 입력하고 '주요 결과' 또는 '제품 및 페이지'에서 결과를 선택합니다.
fin_monthly_closing_internal을 검색합니다. 결과에 BigQuery 테이블이 표시됩니다. 테이블 이름을 클릭하여 세부정보 페이지로 이동합니다.
- 테이블의 세부정보 페이지에서 하단에 있는 "선택적 태그 및 관점" 섹션을 찾습니다.
official-data-product-spec관점을 찾습니다. 값이 적용한 "Gold Internal" 시나리오와 일치하는지 확인합니다.
이제 기술적으로 동일한 BigQuery 테이블 (fin_monthly_closing_internal 및 tmp_data_dump_v2_final_real)이 머신이 읽을 수 있는 메타데이터로 논리적으로 구분된다는 것을 확인했습니다.
5. 에이전트 구성 및 프로토타입 제작
애플리케이션을 빌드하기 전에 (2부에서 수행) 데이터 거버넌스 로직을 로컬에서 확인합니다. Knowledge Catalog 플러그인을 설치하고 에이전트 스킬을 구성해야 합니다.
확장 프로그램 설치
Cloud Shell에서 Knowledge Catalog 플러그인을 설치합니다. 확인 및 설정 세부정보를 묻는 메시지가 표시됩니다.
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
에이전트 스킬 검사
에이전트 스킬은 .agents/skills/knowledge_catalog_governance/SKILL.md에 있는 재사용 가능한 정적 정의 파일입니다. 여기에는 추상적인 인간 규칙 (예: '안전한 데이터가 필요함')을 엄격한 기술 조회로 변환하는 로직이 포함되어 있습니다.
파일을 검사하여 AI에 가르치는 알고리즘을 이해합니다.
cat .agents/skills/knowledge_catalog_governance/SKILL.md
모델에 엄격한 1단계 (메타데이터 검증) 및 2단계 (쿼리 실행) 루프를 따르도록 명시적으로 안내합니다. 모델은 SQL을 구성하기 전에 메타데이터를 검색하고 검증해야 합니다.
에이전트 시작 및 시나리오 테스트
AGY CLI 세션을 시작합니다. .agents/skills 디렉터리에서 스킬을 자동으로 검색하고 로드합니다.
agy
참고: 여러 컨텍스트 파일이 로드될 수 있습니다. 이는 정상적인 현상입니다. CLI는 이 프로젝트의 특정 규칙에 대한 로컬 스킬과 Knowledge Catalog 플러그인 자체의 기본 안내를 로드합니다.
설치 확인
/mcp를 입력하여 Knowledge Catalog 플러그인이 활성 상태인지 확인합니다. knowledge-catalog가 사용 가능한 도구와 함께 활성 플러그인으로 표시됩니다.
/mcp
예상 출력:
MCP Servers
...
> ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
테스트 시나리오 (프로토타입 제작)
실행 중인 에이전트 세션에 다음 프롬프트를 하나씩 붙여넣어 규칙을 준수하는지 확인합니다.
- 시나리오 A (CFO의 데이터 인증):
"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"
예상: 에이전트는 도구에서 활성 프로젝트와 리전을 자동으로 검색하고, 관점에서 GOLD_CRITICAL (정확함) 및 INTERNAL_ONLY (이사회 회의)와 의미상 일치하므로 fin_monthly_closing_internal을 쿼리하고 이를 추천합니다.
- 시나리오 B (공시):
"I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?"
예상: 에이전트는 월별 내부 테이블을 우회하고 EXTERNAL_READY 태그가 지정된 유일한 애셋이므로 fin_quarterly_public_report를 엄격하게 선택해야 합니다.
- 시나리오 C (운영 요구사항):
"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"
예상: 에이전트는 REALTIME_STREAMING 업데이트 빈도를 식별하여 금융 데이터의 GOLD_CRITICAL 등급보다 우선순위를 지정하므로 mkt_realtime_campaign_performance를 선택합니다.
- 시나리오 D (샌드박스 실험):
"I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment."
예상: 에이전트는 관점에서 BRONZE_ADHOC (원시 데이터) 및 is_certified: false (샌드박스 환경)와 의미상 일치하므로 tmp_data_dump_v2_final_real을 선택합니다.
(AGY 세션을 종료하려면 /exit 또는 /quit를 입력하세요.)
6. 수고하셨습니다 다음 단계
관리되는 데이터 기반을 빌드하고 AI가 로컬 CLI 프로토타입을 사용하여 메타데이터 규칙을 엄격하게 준수할 수 있음을 입증했습니다.
이제 체크포인트에 도달했습니다. 다음 단계를 선택하세요.
옵션 A: 지금 바로 2부로 계속 진행하고 싶습니다.
모델 컨텍스트 프로토콜 (MCP) 및 Cloud Run을 사용하여 이 로컬 프로토타입을 안전한 프로덕션급 웹 애플리케이션으로 전환할 준비가 되었다면 다음 단계를 따르세요.
옵션 B: 2부는 나중에 진행하거나 1부만 완료하고 싶습니다.
오늘 중지하고 클라우드 비용을 피하려면 리소스를 정리해야 합니다.
걱정하지 않으셔도 됩니다. 2부에서는 1부 환경을 2분 만에 완전히 재빌드하여 중단한 지점부터 정확하게 다시 시작할 수 있는 '빠른 트랙 스크립트'를 제공합니다.
👉 정리 섹션으로 이동합니다.
7. 정리 (옵션 B만 해당)
여기서 중지하는 경우 요금이 발생하지 않도록 리소스를 소멸시킵니다.
데이터 레이크 소멸
현재 AGY CLI 세션에 있는 경우 Ctrl+C를 두 번 누르거나 /quit를 입력하여 세션을 종료합니다. 그리고 다음 명령어를 실행합니다.
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
AGY CLI 플러그인 제거 및 로컬 파일 삭제
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos