One source of truth for AI-agent grounding: OKF in practice

Last month I had three copies of the same truth in FinChat, and they were quietly lying to each other. The prose system instruction told the analyst agent which tables it could touch. A separate Python allow-list enforced it. And the docs described it for humans. Every time I changed one, I forgot at least one of the others. The agent would confidently reference a table that wasn't in scope, or the docs would describe a join that no longer existed. Classic drift — the kind that's invisible until an agent hallucinates a query in front of someone you're trying to impress.

The fix was to stop keeping three copies and start keeping one. That's what the Open Knowledge Format gave me.

What OKF actually is

OKF is Google's proposed open standard for the curated, organization-specific context an AI agent needs but a foundation model can't know — table semantics, metric definitions, join paths, the boundaries of what analytics is allowed to touch. It's markdown with structured frontmatter, versioned in git, authored alongside your code. Google's write-up is worth reading: how the Open Knowledge Format can improve data sharing.

The pitch that gets oversold is cross-cloud data portability. Ignore that part. The real value is narrower and more useful: it makes the knowledge plane portable and single-sourced, while your data stays exactly where it is — in my case, BigQuery.

How I use it in FinChat (my agent workflow POC)

FinChat has a knowledge/ bundle: markdown concept files for datasets, tables, views, metrics, and the property graph, plus two analyst playbooks. Those playbooks are the source of truth for the analyst's Conversational Analytics grounding. One of them carries a machine-readable perimeter: allow-list — the exact tables analytics may see — and a joins: block with the join keys. That frontmatter is the SSOT. Everything downstream is generated from it.

Inside the bundle

The whole thing is just a folder of markdown you can browse: github.com/jeremydegardeyn/finchat/tree/main/knowledge. The structure mirrors how you'd actually reason about a data platform:

• datasets/ — data-product level context (what the streaming ledger is, how its medallion layers fit).
• tables/ and views/ — physical semantics and the serving layer, one file per object.
• metrics/ — canonical metric definitions so agents don't re-derive them.
• graph/ — the property-graph model.
• playbooks/ — the two files that actually drive runtime behavior. Their frontmatter is the SSOT. Change grounding here, nowhere else.

Everything except the playbooks is documentation and compile source today. The playbooks are the part the running system consumes.

How it's consumed — two paths

Build time: a compile_okf.py script reads the frontmatter from the playbooks and generates a committed, dependency-free Python module — just two constants, ANALYST_PERIMETER and ANALYST_JOIN_BULLETS. The UI container's Dockerfile copies only named files, so the markdown bundle never ships in the image and there's no YAML parser at runtime. A CI test fails the build if that generated module drifts from the bundle. That drift guard is the whole game — without it, the compiled artifact rots the first time someone edits the bundle and forgets to recompile.

Runtime: the server imports those two constants and, on every analyst request, derives the table allow-list and injects the join-model bullets into the CA system instruction. The raw markdown is never read at runtime. The bundle is the source; the compiled constants are what actually runs.

The honest caveat: this documents, it doesn't enforce

OKF is a semantic documentation layer, not an enforcement layer. If a bug or a clever prompt got the agent to attempt an out-of-perimeter query, OKF wouldn't stop it. What stops it is IAM — the service account literally cannot read tables outside its grants, by design. OKF grounds what the agent believes is in scope and shapes what it attempts. IAM is the wall. If you want your metric definitions enforced rather than merely described, pair the OKF concepts with dbt or CA metrics. Don't let a tidy knowledge bundle lull you into thinking it's a security control.

Why it's worth the effort

• One source of truth across agent frameworks. I'm on ADK today; if I move to LangChain tomorrow, the knowledge doesn't get rewritten.
• Governance-as-code. Perimeter changes go through a pull request, CI, and git history. When a banking architecture board asks "how do you control what the AI can see," that answer sells itself.
• The knowledge is portable; the data never moves.

Lessons learned

• Compile at build time instead of parsing at runtime — no new runtime dependency, no bundle in the image.
• Frontmatter as SSOT beats three hand-kept copies that silently disagree.
• The CI drift guard is what makes the SSOT real. Skip it and you've just added a fourth copy.
• I still have one honest gap: a BigQuery graph view holds a third hand-kept copy of the join model. A future pass should generate that from the same SSOT too. Naming your remaining drift is better than pretending it's gone.
• Keep the security-adjacent perimeter build-time and in CI. That discipline is the governance story.

If you genuinely need runtime updates

People immediately ask: can I update the bundle without redeploying? You can — load the compiled artifact (or the descriptive docs) from a GCS bucket on cold start with a short TTL cache, keeping the committed module as a fallback so a bad read can't take down the app. Or serve the descriptive concept docs from the BigQuery Knowledge Catalog you already ingest into — a natural fit once you build retrieval over concepts.

But my honest recommendation is: don't build runtime loading before you need it. The descriptive docs have no runtime consumer yet, a redeploy is cheap for content you change rarely, and hot-swapping a security perimeter from a bucket quietly undermines the governance story you worked to build. Let the future retrieval feature drive the delivery mechanism. Keep the perimeter in git and CI where a reviewer can see it change.

One source of truth, compiled once, guarded by a test. That's the whole idea — and it's the difference between an agent you can put in front of an audit board and one you can only demo when you're feeling lucky.