AI 에이전트(AI agents)는 당신이 제공하는 컨텍스트(context)만큼만 똑똑합니다. OKF는 조직의 지식을 일반 마크다운(markdown) 파일로 패키징하는 새로운 오픈 사양(open specification)으로, 별도의 커스텀 통합(custom integrations)이나 독점적인 SDK(proprietary SDKs) 없이도 어떤 에이전트든 이를 읽을 수 있게 합니다.

AI 에이전트를 구축하는 모든 팀은 동일한 벽에 부딪힙니다. 모델은 유능하고, 에이전트 프레임워크(agent framework)도 설정되어 있습니다. 하지만 에이전트는 당신의 조직에 대해 아무것도 모릅니다. orders 테이블이 무엇을 의미하는지, churn_score 지표 공식이 무엇인지, 또는 파이프라인이 깨졌을 때 온콜 런북(on-call runbook)에 무엇이라고 적혀 있는지 알지 못합니다.

그러한 지식은 존재합니다. Confluence 페이지, Notion 위키(wikis), 데이터 카탈로그(data catalog) 항목, Slack 스레드, 그리고 시니어 엔지니어들의 머릿속에 흩어져 있습니다. 이를 에이전트에 넣으려면 모든 소스마다 커스텀 통합을 구축해야 합니다. 모든 팀이 이 문제를 처음부터 직접 해결하고 있습니다.

2026년 6월 12일에 발표된 Open Knowledge Format (OKF)은 가장 단순한 접근 방식인 '마크다운 파일 디렉토리'를 통해 이 문제를 해결하는 벤더 중립적(vendor-neutral) 사양입니다. 🎯

🏗️ OKF의 실제 정체

OKF 번들(bundle)은 개념(concepts)을 나타내는 마크다운 파일들의 디렉토리입니다. 여기서 개념이란 테이블(tables), 데이터셋(datasets), 지표(metrics), 플레이북(playbooks), 런북(runbooks), API 등을 포함하여 당신이 캡처하고 싶은 모든 것을 의미합니다. 각 개념은 하나의 파일로 구성됩니다.

이것이 모델의 전부입니다. YAML 프론트매터(frontmatter)가 포함된 .md 파일들의 디렉토리입니다. 형식은 의도적으로 최소화되었습니다: 하나의 필수 필드(type), 선택적 메타데이터(title, description, resource, tags, timestamp), 그리고 자유 형식의 마크다운 본문입니다.

개념 문서는 다음과 같이 생겼습니다:

---
type: table
title: "orders"
...

이 방식이 강력한 세 가지 이유는 다음과 같습니다:

1. 파일 경로가 곧 정체성(identity)입니다. tables/orders.md 파일은 tables/orders라는 개념 식별자(concept identifier)를 가집니다. 레지스트리(registry), ID 생성, 데이터베이스가 필요 없습니다.

2. 마크다운 링크가 곧 지식 그래프(knowledge graph)입니다. 개념 A에서 개념 B로의 링크는 관계를 단언합니다. 구체적인 관계의 종류는 링크 자체가 아니라 주변 산문(prose)을 통해 전달됩니다. 개념들이 서로 연결됨으로써 디렉토리는 탐색 가능한 그래프(graph)로 변모합니다.

3. 별도의 도구가 필요하지 않습니다. API, 인증, SDK가 필요 없습니다. 파일 시스템(file system) 자체가 곧 API입니다.

📁 번들 구조 (Bundle Structure)

knowledge-bundle/
├── index.md                    # 선택 사항: 디렉토리 목록
├── log.md                      # 선택 사항: 변경 이력
...

두 개의 예약된 파일 이름은 모든 디렉토리 수준에서 정의된 의미를 가집니다. index.md 파일은 점진적 공개(progressive disclosure)를 지원하기 위해 디렉토리의 콘텐츠를 열거하며, 이를 통해 사람이나 에이전트가 개별 문서를 열기 전에 무엇을 사용할 수 있는지 확인할 수 있게 합니다. log.md 파일은 날짜별로 그룹화된 항목으로 변경 사항을 기록하며, 최신 항목이 가장 먼저 나타납니다.

🧪 실제 사례 (Real-World Examples)

사례 1: 데이터 팀 지식 베이스 (Data Team Knowledge Base)

데이터 팀이 테이블, 지표(metrics), 알려진 데이터 품질 문제를 문서화합니다. SQL 쿼리를 작성하는 에이전트는 쿼리를 생성하기 전에 번들을 읽어 컬럼 의미론(column semantics), 조인 패턴(join patterns), 그리고 주의 사항(gotchas)을 이해할 수 있습니다.

---
type: metric
title: monthly_recurring_revenue
...

수익 대시보드 쿼리를 작성하기 전에 이를 읽는 에이전트는 주니어 분석가들이 끊임없이 범하는 연간 계획 분할 오류(annual-plan division error)를 방지할 수 있습니다.

사례 2: 플랫폼 팀 런북 (Platform Team Runbook)

SRE 팀이 OKF 개념으로서 런북(runbook)을 작성합니다. 온콜(on-call) 에이전트는 번들을 탐색하여 장애를 진단하고 대응할 수 있습니다.

---
type: runbook
title: ML Pipeline Failure Response
...

에이전트는 런북을 읽고, 관련 개념으로 연결되는 교차 링크(cross-links)를 따라가며, 진단하거나 에스컬레이션(escalate)할 수 있습니다. 이 모든 과정은 사람이 사용하는 것과 동일한 마크다운 파일에서 이루어집니다.

사례 3: API 문서 번들 (API Documentation Bundle)

플랫폼 팀은 서비스와 함께 OKF 번들 (bundle)을 배포합니다. 해당 API와 통합되는 모든 에이전트는 OpenAPI 명세 (spec)를 파싱하거나 MCP 서버를 호출할 필요 없이, 엔드포인트 의미론 (semantics), 인증 패턴 (auth patterns), 그리고 속도 제한 (rate limits)을 파악하기 위해 이 번들을 읽습니다.

---
type: api
title: Payments API
...

🔄 OKF vs RAG vs MCP

이 세 가지는 경쟁 관계가 아니라 상호 보완적인 관계입니다:

	OKF	RAG	MCP
정의	큐레이션된 지식 형식 (Curated knowledge format)	청크 (chunks)로부터의 쿼리 시점 검색 (Query-time retrieval)	런타임 도구/데이터 연결 프로토콜 (Runtime tool/data connection protocol)
...

RAG는 쿼리 시점에 원시 청크 (raw chunks)로부터 지식을 재도출합니다. 반면 OKF 번들은 에이전트가 직접 읽고 업데이트할 수 있는, 큐레이션되고 상호 연결된 개념 (concepts)들을 저장합니다.

MCP는 AI 에이전트가 도구 및 실시간 데이터 소스에 연결하는 방식, 즉 런타임 배관 (runtime plumbing)을 관리합니다. OKF는 MCP를 대체하지 않습니다.

실제적인 패턴은 다음과 같습니다: 안정적인 지식 (테이블 스키마, 지표 정의, 런북)에는 OKF를 사용하고, 대규모 문서 아카이브에는 RAG를, 실시간 API 및 도구 호출에는 MCP를 사용하는 것입니다.

🔧 5분 만에 시작하기

# 번들 생성
mkdir my-knowledge-bundle && cd my-knowledge-bundle

...

생성한 번들에 대해 오픈 소스 OKF 검증기 (validator)를 실행하세요: node validator/okf-validate.mjs ./your-bundle. 이 검증기는 통과(pass) 또는 실패(fail)를 반환하며, 파일이 위반한 모든 규칙의 이름을 나열하고, CI (지속적 통합)에서 게이트 역할을 할 수 있는 종료 코드 (exit code)와 함께 종료됩니다.

에이전트가 해당 디렉토리를 가리키도록 설정하세요:

import pathlib

def load_okf_bundle(bundle_path: str) -> dict:
...

⚠️ 도입 전 알아두어야 할 사항

현재 v0.1이며 명시적으로 실험적인 단계입니다. OKF v0.1은 Google이 완성된 표준이 아닌 시작점으로 부르는 초기 실험적 명세 (spec)입니다. 명세가 진화할 것을 예상하십시오. 필드 이름이 변경되지 않을 것이라고 가정하고 미션 크리티컬 (mission-critical)한 툴링을 구축하지 마십시오.

의미론적(semantic)인 것이 아닌, 구조적 상호운용성(Structural interoperability). OKF는 이미 에이전트들에게 컨텍스트를 찾고 읽을 수 있는 공유된 방식을 제공합니다. 하지만 그 컨텍스트가 무엇을 의미하는지에 대한 공유된 의미론(semantics)을 아직 제공하지는 않습니다. OKF를 사용하는 두 팀은 번들(bundle)을 교환할 수 있습니다. 다만 그들의 에이전트가 이를 동일하게 해석할지 여부는 아직 표준화되지 않은 관례(conventions)에 달려 있습니다.

설계 단계부터 벤더 종속성(vendor lock-in) 방지. OKF 번들은 어떤 git 저장소나 파일 시스템에서도 존재할 수 있으며, 마크다운(markdown)을 파싱할 수 있는 모든 도구에서 읽을 수 있습니다. 콘텐츠를 마이그레이션(migration)하지 않고도 소비자(consumer)를 전환할 수 있습니다.

AGENTS.md 및 CLAUDE.md를 보완. 해당 관례 파일(convention files)들은 에이전트에게 저장소 내에서 어떻게 행동해야 하는지를 알려줍니다. 반면 OKF는 데이터와 지식의 집합을 기술합니다. 이들은 동일한 문제의 서로 다른 계층(layer)을 해결합니다.

기본적으로 감사(audit) 준비 완료. 모든 OKF 번들은 임의의 디렉토리 수준에 선택적인 log.md 파일을 가질 수 있습니다. 변경 사항은 ISO 8601 형식으로 추적됩니다. 규제 산업의 경우, 이는 귀하의 지식 베이스(knowledge base)가 기본적으로 감사 준비가 되어 있음을 의미합니다.

⏭️ 선점자(Early Mover)의 이점

이 스펙(spec)은 Apache 2.0 라이선스로 자유롭게 사용할 수 있으며, 배우는 데 5분이면 충분합니다. 지금 채택해야 하는 솔직한 이유는 10년 전 스키마 마크업(schema markup)과 같습니다. 배포 비용이 저렴하고, 귀하에 대한 질문에 답하기 시작하는 에이전트들이 귀하의 지식을 읽을 수 있게 만들며, 선점자들은 이 형식이 중요해지기 전에 미리 익힐 수 있습니다.

한 팀에서 가장 고통을 겪고 있는 지식부터 시작하십시오. 항상 잘못 사용되는 테이블, 항상 잘못 정의되는 메트릭(metrics), 새벽 2시에 아무도 찾을 수 없는 런북(runbook) 같은 것들 말입니다. 세 개의 OKF 컨셉(concept) 파일을 작성하십시오. 에이전트가 이를 참조하게 하십시오. 무엇이 변하는지 확인하십시오.

스펙, 참조 구현체(reference implementations), 그리고 샘플 번들은 GitHub에서 확인할 수 있습니다: github.com/GoogleCloudPlatform/knowledge-catalog

이 내용이 도움이 되었나요? 더 많은 AI 아키텍처 심층 분석을 위해 팔로우하세요! 💬