BigQuery Knowledge Catalog란, OKF 번들로 AI 에이전트 컨텍스트 관리하는 방법

AS-IS, git 저장소로 OKF 번들 관리할 때의 한계

OKF는 LLM이 참고할 컨텍스트를 markdown 파일과 YAML frontmatter로 표준화한 포맷입니다. v0.1에서 포터블한 형식을 정했고 v0.2에서 provenance, verification, freshness, attestation 같은 신뢰 신호를 추가했는데요, 팀 하나가 자기 에이전트를 위해 신뢰할 만한 번들을 만드는 데까지는 문제가 없었어요. 그런데 이 번들을 조직 전체에 공유하는 방법은 OKF 스펙 자체가 답을 주지 않았습니다. git 저장소 하나에 번들 하나씩 두면 포터블하긴 한데, 그 번들이 설명하는 데이터 옆에서 검색되지 않고 조직이 이미 쓰는 신원, 컴플라이언스 정책으로 보안 관리도 안 되고 스키마, 리니지, 오너십 같은 기술 메타데이터 옆에도 있지 않아요. 다운스트림 에이전트마다 각 번들이 어디 있는지 알아야 하니 번들이 몇 개만 넘어가도 확장이 안 됩니다.

이번 내용, Knowledge Catalog에 매핑하면 바뀌는 것

Knowledge Catalog는 조직이 BigQuery, Cloud Storage, 운영 데이터베이스, 애플리케이션에 이미 가진 것 위에 하나의 거버넌스된 인덱스를 제공하는 에이전트용 컨텍스트 엔진입니다. OKF 번들을 여기 매핑하는 setup은 최초 1회만 하면 되고, 이후 push는 한 번의 명령으로 끝나요. setup 단계에서 번들을 담을 EntryGroup, 개념을 위한 EntryType(okf-bundle), OKF 신호 필드를 담는 AspectType(okf) 이렇게 3개 리소스가 등록됩니다. push는 개념마다 overview Aspect(markdown 본문)와 okf Aspect(구조화된 신호)를 가진 okf-bundle Entry 하나씩을 만들어요. 번들의 index.md 내비게이션 파일과 루트 log.md도 함께 Entry로 발행됩니다.

Google Cloud가 예시로 든 Acme Retail 번들은 attesters, tables, metrics, computations, policies, skills 6개 디렉터리에 걸친 9개 리프 개념으로 구성되고, 각각 자기 index.md를 갖고 번들 루트에도 index.md와 log.md가 있어서 총 17개 Entry가 push됩니다(Dataplex가 _entry 하나를 자동 생성해서 gcloud dataplex entries list로는 18개가 조회돼요). push 후엔 revenue-ytd Attested Computation이 콘솔에서 sanctioned SQL, executor, attester, 검증 이력, 전체 개념 본문과 함께 보이고, 애널리스트가 Knowledge Catalog에서 revenue를 검색하면 Acme Retail의 비즈니스 정의와 그 값을 계산하는 BigQuery 테이블이 하나의 권한 모델 아래 같이 나옵니다.

실무 적용 포인트

okf AspectType은 13개 필드로 OKF v0.2 스펙 전체를 커버하는데요, okf_type, status, stale_after, runtime, computation, extra 같은 최상위 스칼라 필드와 generated.by, usage_window.from 같은 레코드 필드의 스칼라 서브필드는 searchEntries로 서버사이드 검색이 됩니다(예: aspect:acme-analytics.us-central1.okf.okf_type=Metric). 반면 sources, verified, parameters 같은 배열 필드는 서브필드 단위 서버사이드 검색이 안 되니 entries.get with view=ALL로 가져온 뒤 클라이언트에서 필터링해야 해요. datetime 타입 필드(stale_after, generated.at, usage_window.from/.to)에 검색 조건 걸 때는 전체 RFC3339 타임스탬프 대신 bare date(stale_after=2026-12-31)나 범위 비교(stale_after>2026-01-01)를 쓰는 게 좋습니다.

에이전트가 실제로 쓸 때는 LookupContext로 개념의 catalogEntry, type, description, tags, overview(markdown 본문 전체)가 담긴 YAML 블록을 받고, LookupContext가 커스텀 Aspect는 렌더링하지 않으니 okf_type, generated, sources 같은 구조화된 신호 필드가 필요하면 entries.get with view=ALL을 같이 호출하면 됩니다. 저장소 클론이나 수동 Aspect 병합, frontmatter 재파싱 없이 Knowledge Catalog 클라이언트가 이미 쓰던 API 호출 그대로 쓰면 돼요.

자주 묻는 질문

bigquery 란

BigQuery는 Google Cloud의 완전관리형 데이터 웨어하우스로, 대용량 데이터를 SQL로 분석하는 서비스입니다. 이번 내용은 BigQuery 자체 기능이라기보다 BigQuery 테이블이 등록된 Knowledge Catalog에 AI 에이전트용 문서(OKF 번들)를 함께 넣어 같은 검색, 권한 체계로 관리하는 방법을 다뤄요.

ai 에이전트 란

AI 에이전트는 사람의 지시 없이도 데이터를 조회하고 판단해 작업을 수행하는 AI 시스템을 말합니다. 이 노트에서 다루는 에이전트는 searchEntries, LookupContext API로 Knowledge Catalog에 등록된 BigQuery 테이블이나 OKF 번들 문서를 찾아 그 내용을 컨텍스트로 활용하는 유형이에요.

ai 에이전트 활용 사례로 어떤 게 있나

원문에서 든 예시는 Acme Retail이라는 가상의 소매업체 BigQuery 환경입니다. 이미 BigQuery 테이블 Entry를 조회하던 에이전트가 리소스 목록에 OKF Entry 이름만 추가하면 매출 지표 정의, 계산 로직, 검증 이력 같은 번들의 컨텍스트를 같은 방식으로 가져올 수 있어요.

ai 에이전트 비교할 때 이 방식은 뭐가 다른가

핵심 차이는 컨텍스트를 어디서 관리하느냐예요. git 저장소 기반은 포터블하지만 검색과 권한 관리가 조직 시스템과 분리돼 있고, Knowledge Catalog에 매핑하면 IAM 기반 권한 통제와 데이터 카탈로그 검색을 다른 기술 메타데이터와 동일하게 적용받습니다.