knowledge-catalog 딥다이브
— AI 에이전트가 '회사 데이터'를 알아듣게 만드는 구글의 메타데이터 도구상자

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

knowledge-catalog = "회사 데이터 창고에 붙이는, AI도 읽는 설명서를 자동으로 만드는 도구 + 그 설명서의 개방 표준(OKF)." 큰 회사의 데이터는 보통 BigQuery 같은 데이터 창고에 수천 개의 테이블로 쌓여 있다. 그런데 정작 "이 테이블이 무슨 뜻인지", "이 컬럼이 매출인지 환불인지"는 아무 데도 안 적혀 있거나, 누군가의 머릿속에만 있다. 사람도 헤매지만, 요즘 부쩍 늘어난 AI 데이터 분석 에이전트는 더 막막하다 — 설명이 없으면 엉뚱한 테이블을 골라 잘못된 답을 낸다. 이 프로젝트는 그 "설명서(메타데이터)"를 Gemini가 BigQuery 스키마와 사내 문서를 읽어 자동으로 써 주고, 그 결과를 누구나 읽을 수 있는 마크다운 파일로 떨어뜨린다.

정리하면 이 레포에는 두 켤레의 이야기가 들어 있다. 하나는 "지식을 어떤 모양으로 적을까"라는 포맷(OKF) 이야기, 다른 하나는 "그 포맷을 누가 자동으로 채울까"라는 에이전트(Gemini + Google ADK) 이야기다. 그리고 같은 아이디어를 Python과 TypeScript 두 언어로 각각 구현한 참조 코드가 여러 벌 들어 있어, "구글식 AI 에이전트를 어떻게 짜는가"의 살아 있는 교본이기도 하다.

2왜 주목받는가

TrendShift 일간 22위 — 구글이 내놓은 '에이전트용 지식 포맷'이라는 점이 핵심.

2025~2026년의 화두는 "AI 에이전트에게 우리 회사 데이터를 어떻게 이해시킬까"다. 모델은 똑똑해졌지만, 정작 우리 데이터가 뭘 뜻하는지는 모델이 알 길이 없다. 그 빈칸을 메우는 게 메타데이터인데, 지금까지 메타데이터는 대개 벤더 전용 카탈로그 안에 갇혀 있었다. knowledge-catalog가 주목받는 이유를 다섯 가지로 정리하면:

① 코드가 아니라 '개방 표준'을 같이 던졌다 (OKF)

대부분의 도구는 "우리 SDK 쓰세요"로 끝난다. 이 레포는 okf/SPEC.md에 벤더 중립 포맷 OKF v0.1을 문서로 못박았다. 핵심 주장은 "지식은 SDK 없이 읽혀야 하고, git으로 diff·리뷰되어야 하고, Obsidian·Notion·MkDocs 어디로든 옮겨져야 한다"는 것. 그래서 결과물이 평범한 마크다운 폴더다. 특정 회사에 종속되지 않으려는 설계가 개발자들의 공감을 샀다.

② "메타데이터를 코드처럼" — git diff·PR로 관리

TypeScript CLI kcmd가 내세우는 슬로건이 Metadata as Code(메타데이터를 코드처럼)다. 카탈로그의 메타데이터를 로컬에 pull로 끌어와 YAML·마크다운으로 편집하고, git diff로 변경을 확인하고, PR로 리뷰한 뒤 push로 되돌린다. 인프라를 코드로 다루는 IaC(Infrastructure as Code)의 발상을 메타데이터에 옮긴 것이다.

③ '에이전트가 크롤러' — 단, 안전장치를 코드에 박았다

OKF 참조 에이전트는 웹 문서를 직접 돌아다니며 읽는다. 위험해 보이지만, 이 레포의 묘수는 "몇 페이지까지·어떤 도메인만·몇 단계 깊이까지"라는 한계를 LLM에게 맡기지 않고 도구(fetch_url) 안에 강제로 박아 둔 점이다. 모델이 아무리 욕심내도 도구가 거부한다. "AI에게 권한을 주되 고삐는 코드가 쥔다"는 좋은 본보기다.

④ '증강 가드' — LLM이 정보를 깎아 먹지 못하게

LLM이 문서를 다시 쓰다 보면 원래 있던 스키마 항목이나 출처(citation)를 슬쩍 빠뜨리기 쉽다. 이 레포는 write_concept_doc에 증강 가드(augmentation guard)를 넣어, 스키마 필드 개수가 줄거나 인용 수가 줄어드는 쓰기를 코드가 기계적으로 거부한다. "LLM 출력은 믿지 말고 불변식으로 검사하라"는 교훈의 모범 사례다.

⑤ 구글 ADK + Gemini의 '공식 레퍼런스'

이 레포는 같은 아이디어를 Python(google-adk)과 TypeScript(@google/adk) 두 갈래로 구현해 뒀다. 구글의 에이전트 프레임워크 ADK로 실전 에이전트를 어떻게 짜는지, MCP 서버를 어떻게 붙이는지, 평가(eval)는 어떻게 자동화하는지를 한 레포에서 다 볼 수 있다. "구글식 에이전트 설계"를 배우려는 사람에게 교본 가치가 크다.

3기술 스택 전체 지도

okf/pyproject.toml · agents·toolbox의 package.json · 실제 소스 트리에서 확인한 구성.

마음의 준비부터. 이 레포는 "백엔드+프론트엔드+DB" 웹 스택이 아니라 AI 에이전트 스택이다. 중심엔 Gemini(모델)와 Google ADK(에이전트 프레임워크)가 있고, 그 둘이 BigQuery·Dataplex 같은 구글 클라우드 서비스를 도구로 부른다. 같은 아이디어가 Python과 TypeScript 두 갈래로 구현돼 있어 표도 언어별로 나눠 본다.

ⓐ 에이전트의 두뇌 — 모델 · 프레임워크 (양쪽 공통)

ⓑ OKF 참조 에이전트 — Python 쪽 (okf/)

ⓒ Metadata-as-Code CLI — TypeScript 쪽 (agents/mdcode = kcmd)

ⓓ 구글 클라우드 서비스 (도구로 호출)

에이전트가 실제로 부르는 외부 서비스들이다. Dataplex/Knowledge Catalog(dataplex.googleapis.com — Entry·EntryGroup·Glossary 관리, 의미 검색 search_entries), BigQuery(스키마·쿼리 이력 INFORMATION_SCHEMA.JOBS), Vertex AI(Gemini 추론), 그리고 선택적으로 Google Drive/Docs(사내 문서 수집), BigLake/Iceberg(레이크 테이블), GitHub(GitHub MCP로 코드 컨텍스트). "에이전트 = Gemini(두뇌) + 이 서비스들(손발)"이라고 보면 그림이 맞는다.

ⓔ (선택) 시각화 뷰어 — 유일한 프론트엔드

visualize 명령을 쓰면 OKF 번들 전체를 JSON으로 담은 자기완결 HTML 한 장(viz.html)이 나온다. Cytoscape.js(힘-방향 그래프)와 marked.js(브라우저 안 마크다운 렌더)를 CDN으로 불러, 개념들을 점·선 그래프로 띄우고 "이 개념을 인용한 곳(backlink)"까지 보여 준다. 서버가 필요 없는 대신 인터넷이 있어야 열린다(CDN 의존).

4아키텍처 심화 분석

먼저 전체 그림을 한 장으로 본 뒤, 대표 흐름 '데이터셋 → 설명서 번들'을 끝까지 따라간다.

간판인 okf/ 에이전트를 기준으로 보자. 이 에이전트의 일은 "두 번 훑어 설명서를 채우는 것"이다. (1) BQ 패스 — BigQuery 메타데이터만으로 개념마다 설명서 초안을 쓴다. (2) 웹 패스(선택) — 사내·공개 문서를 크롤링해 그 초안을 보강한다. (3) 인덱스 재생성 — 폴더마다 목차(index.md)를 다시 만든다. 부품 이름을 외우기 전에 숲부터 보자.

독수리 시점 — 전체 구조 한 장

흐름 ① — "이 BigQuery 데이터셋을 설명서로 만들어줘" (BQ 패스, 해피패스)

사용자가 enrich --source bq --dataset ...를 실행하면 EnrichmentRunner가 BQ 에이전트를 돌린다. 핵심 단계만 따라가면:

# okf/src/enrichment_agent — BQ 패스 한 사이클
1. 개념 나열   BigQuerySource.list_concepts() — 데이터셋의 테이블을 '개념'으로
2. 한 개씩 LLM   개념 하나당 Gemini 호출 1회 (한 번에 하나만, 집중)
3. 재료 읽기   read_concept_raw / sample_rows — 스키마·샘플 행을 도구로 조회
4. 초안 작성    Gemini가 # Schema · # Examples · # Citations 본문을 구성
5. 문서 쓰기   write_concept_doc — frontmatter 검증 통과해야 디스크에 저장

이 레포 특유의 관례 하나 — "개념 하나당 LLM 호출 하나"다. 테이블 50개면 호출 50번. 한 번에 다 시키지 않고 잘게 쪼개, 모델이 한 개념에만 집중하게 한다. 또 하나, events_20210131처럼 날짜별로 쪼개진 테이블(date-sharded)은 events_* 한 개념으로 자동으로 합친다 — 안 그러면 같은 설명이 수백 장 생긴다.

흐름 ② — "웹 문서로 보강해줘" (웹 패스 + 증강 가드)

웹 패스에선 에이전트가 스스로 크롤러가 된다. 씨앗 URL(--web-seed)부터 시작해, 페이지를 읽고 권위 있어 보이는 링크를 따라간다. 각 페이지마다 (a) 기존 문서 보강, (b) references/에 새 문서 생성, (c) 그냥 건너뜀 중 하나를 고른다. 여기서 두 가지 안전장치가 빛난다:

① 도구가 고삐를 쥔다  fetch_url 안에서 직접 검사:
   - 페이지 수 한도(--web-max-pages, 기본 100) 초과 → 거부
   - 허용 도메인·경로 밖, 깊이(--web-max-depth, 기본 2) 초과 → 거부
   (LLM이 "더 읽자" 해도 도구가 그냥 error 를 돌려준다)

② 증강 가드  write_concept_doc 가 보강 결과를 검사:
   - # Schema 의 필드 이름이 줄었으면        → 거부
   - # Citations(출처) 수가 BQ 패스보다 줄었으면 → 거부
   (LLM이 정보를 깎아 먹는 쓰기를 코드가 기계적으로 막는다)

마지막으로 regenerate_indexes()가 모든 폴더의 index.md를 다시 써서 "이 폴더엔 뭐가 있는지" 한 줄 요약(Gemini가 작성)을 붙인다. 이렇게 완성된 번들은 visualize로 점·선 그래프 viz.html이 된다.

이 레포에서 배울 핵심 설계 패턴 둘. 첫째, 꽂아 쓸 수 있는 Source 인터페이스(sources/base.py) — 지금은 BigQuery 하나뿐이지만 "개념 나열/읽기/샘플"이라는 똑같은 구멍에 다른 데이터원을 끼울 수 있게 설계됐다. 둘째, "쓰기 전에 검증" — bundle/document.py가 frontmatter 필수 키를 확인하고, 빠지면 모델에게 "이걸 채워 다시 호출하라"는 안내 오류를 돌려준다. LLM에게 자유를 주되, 결과는 결정론적 규칙으로 검사하는 일관된 철학이 코드 전반에 흐른다.

5디렉토리 구조 해부

한 레포 안에 같은 아이디어의 구현이 네 벌 — 모노레포다. 큰 덩어리만 보면 된다.

파일이 400개가 넘지만 대부분은 완성된 OKF 샘플 번들(마크다운)과 평가용 코퍼스다(.md 179개). 실제 코드는 네 개의 독립 하위 프로젝트로 나뉘고, 전부 "카탈로그 메타데이터를 풍부하게 채우고 동기화한다"는 같은 목표를 돈다. 그중 okf/가 간판이다.

6학습 포인트 (기술별)

이 레포 한 채로 배울 수 있는 기술과, 각각의 실습 아이디어.

이 레포는 "요즘 에이전트 개발에서 중요한 것"이 골고루 들어 있어 공부 소재로 훌륭하다. 기술별로 무엇을 건질지 짚어 본다.

# okf/bundles/.../tables/orders.md
---
type: table
title: orders
description: 전자상거래 주문 원장 테이블
resource: bigquery://proj.dataset.orders
tags: [sales, ecommerce]
---
# Schema
- `order_id` (STRING) — 주문 고유 ID
- `total` (NUMERIC) — 주문 총액
# Citations
- https://internal.docs/orders

7시스템 요구사항

"포맷(OKF)만 쓸 때"와 "에이전트를 돌릴 때"는 요구사항이 크게 다르다.

OKF 포맷 자체는 그냥 마크다운이라 아무 데서나 읽고 쓸 수 있다 — 요구사항이 없다. 하지만 자동 생성 에이전트를 돌리려면 구글 클라우드 환경이 필요하다. GPU나 로컬 모델은 필요 없다(추론은 전부 호스팅 Gemini).

가장 빠른 출발점은 okf/다. 루트 README의 "Open in Cloud Shell" 버튼을 쓰면 브라우저 안 셸에서 인증·설치가 거의 끝나, 로컬 환경 구성 없이 바로 enrich를 돌려 볼 수 있다.

8직접 해볼 수 있는 실습 과제

"OKF 읽기"는 공짜, "에이전트 돌리기"는 GCP 필요. 난이도 순으로.

9관련 기술 심화 학습 로드맵

이 레포를 100% 소화하기 위한 6주 코스(주당 5~7시간 가정).

10핵심 키워드 사전

이 문서와 레포에 등장한 용어를 한자리에.

11참고 링크

원문·명세·관련 기술 더 파기.

• GitHub 저장소 — github.com/GoogleCloudPlatform/knowledge-catalog (README·소스·샘플 번들)
• OKF 규격 — okf/SPEC.md (이 레포의 핵심 주장, 먼저 읽을 한 장)
• TrendShift 페이지 — trendshift.io/repositories/51719
• Google ADK — google.github.io/adk-docs (에이전트 프레임워크 문서)
• Dataplex / Knowledge Catalog — cloud.google.com/dataplex/docs (데이터 카탈로그 서비스)
• Gemini API — ai.google.dev (모델 접근·API 키)
• MCP 공식 명세 — modelcontextprotocol.io (도구 연동 표준)