Scale OKF Bundles Across Your Org with Knowledge Catalog

Google Cloud’s Open Knowledge Format (OKF) just got a serious upgrade. The new integration with Knowledge Catalog means your agent context bundles can finally swim with the big fish—discoverable, governed, and served right alongside your data. No more hunting through git repos like a lost capybara in a swamp.

What’s the Big Deal?

OKF v0.1 gave us a portable format for agent context—markdown files with YAML frontmatter. v0.2 added trust signals like provenance and freshness. But sharing those bundles across an organization? That was like trying to navigate a swamp without a map. Git repos are portable, but they’re not searchable, not governed, and not integrated with your existing data catalog.

Enter Knowledge Catalog, Google Cloud’s context engine for agents. By mapping OKF bundles onto Knowledge Catalog’s existing types, every concept becomes discoverable, governed, and reachable by any agent already reading from the catalog. It’s like turning your scattered lily pads into a single, navigable pond.

How It Works

Publishing an OKF bundle into Knowledge Catalog takes a one-time setup and a single push. The setup registers three resources: an EntryGroup, an EntryType named okf-bundle, and an AspectType named okf that carries the OKF signal fields. The push then creates one Entry per concept, each with an overview Aspect for the markdown body and an okf Aspect for the structured signals.

Here’s the workflow for the Acme Retail bundle:

# One-time setup
curl -fsSL https://bun.sh/install | bash
export BUN_INSTALL="$HOME/.bun" && export PATH="$BUN_INSTALL/bin:$PATH"
git clone https://github.com/GoogleCloudPlatform/knowledge-catalog
cd knowledge-catalog/toolbox/mdcode && npm install && npm run build

# Authenticate and enable APIs
gcloud auth login
gcloud config set project <your-project>
gcloud config set compute/region <your-location>
gcloud services enable dataplex.googleapis.com
gcloud auth application-default login

# Push the Acme Retail bundle
cd demo/okf
bun run setup.ts   # creates the EG (default 'okf_demo')
bun run push.ts    # pushes okf/bundles/acme_retail into the EG setup created

The okf AspectType

The okf-aspect.json schema defines 13 fields covering the full OKF v0.2 spec. Here’s what’s in the pond:

• okf_type: The document type (e.g., BigQuery Table, Metric).
• generated: Actor and timestamp for the last meaningful change.
• sources: Materials the concept derives from, with credibility signals.
• verified: Verification events, with human verification as the highest trust tier.
• status: Lifecycle state—draft, stable, or deprecated.
• stale_after: When the content goes stale.
• usage_window: Period for source usage counts.
• runtime: How an Attested Computation runs.
• parameters: Typed named holes a caller may fill.
• computation: Path to the computation body.
• executor: How the computation runs and what evidence it returns.
• attester: Deterministic code that returns a verdict.
• extra: Producer-defined frontmatter, kept lossless.

Top-level scalar fields like okf_type and status can drive search predicates directly. So aspect:acme-analytics.us-central1.okf.okf_type=Metric returns every OKF Metric in scope. Array fields like sources aren’t server-side searchable, but agents can narrow on them client-side after entries.get.

What This Enables

Once your bundle is in Knowledge Catalog, two big things happen:

Discoverability Across the Organization

Agents find bundle concepts through the same searchEntries and LookupContext APIs they already use for cataloged data. So an OKF bundle appears alongside BigQuery tables in every query it matches. No more digging through git repos—just search and go.

Governance

Bundle Entries inherit IAM from the EntryGroup. A single agent call returns exactly what the caller is permitted to read, with no parallel permission model to maintain. It’s like having a well-trained caiman guarding the pond—only the right fish get through.

Lifecycle and Getting Started

kcmd push is an idempotent upsert, so re-running is safe. For continuous ingestion, wire a CI job to push on every commit. To get started:

1. Read the OKF v0.2 spec and browse the Acme Retail bundle.
2. Author a small bundle for one domain your team owns.
3. Sync it into your Knowledge Catalog project using the sample code.
4. Point your existing agents at Knowledge Catalog. New context becomes reachable through the same calls they already use.

OKF defines what a trustworthy bundle looks like. Knowledge Catalog makes it reachable across the organization. Together, they’re the dynamic duo of agent context—like a capybara and a caiman teaming up to rule the swamp.

Original announcement published on Google Cloud.