Open Knowledge Format: A Shared Language for AI Agents

AI models can do far more than they could two years ago. Still, when we ask them to do real work inside a company, they often hit the same wall: they do not understand the internal reality of the business.

They do not know what "weekly active users" means in your company. They do not know which API was quietly deprecated. They do not know which dashboard can be trusted, which table is legacy, or which metric definition someone changed after a meeting six months ago.

That is why Google Cloud's Open Knowledge Format is worth paying attention to. OKF is not another knowledge base or another platform. It is a proposed format: markdown files, YAML frontmatter, and a small set of rules. Enough structure for an AI agent to understand. Enough freedom that a human does not hate maintaining it on day one.

This is the important part: the next AI platform shift will not be only about models. It will also be about which companies can make their own operations readable by humans and AI agents at the same time.

Context Is Not Missing. It Is Scattered.

In most organizations, the knowledge exists somewhere. It is just rarely where you need it.

A metric definition lives in a data catalog. A product or design decision lives in a Google Doc or Confluence. A runbook sits in a wiki. A schema explanation is buried in a notebook cell. The real background often lives in the head of the senior engineer who still remembers why a workaround became permanent architecture.

That is already expensive for the business. For AI agents, it is especially bad.

If an agent needs to answer "how do we calculate weekly active users from the event stream?", it cannot open one source and be done. It has to assemble the picture from logs, documents, code, dashboards, and team habits. Those systems were not designed to speak together.

The usual enterprise reflex is to add another knowledge base. But too often that only puts a new silo, with a better search box, on top of the old silos.

OKF approaches the problem from a more useful angle: we do not necessarily need another service. We need a shared format.

What OKF Actually Is

An OKF bundle is simply a directory of markdown files. Each file describes one concept: a metric, table, API, runbook, dataset, business process, or any other unit of knowledge.

At the top of the file sits YAML frontmatter. In the official v0.1 specification, a normal concept document has only one required field: type.

The rest is recommended, but optional:

• title for the human-readable name
• description for the short summary
• resource for the original data, API, or system reference
• tags for filtering and grouping
• timestamp for the last meaningful update

The body is plain markdown. It can contain headings, lists, tables, code examples, links, and sources. You can open it in a text editor, read it on GitHub, review it in a pull request, index it with search, and load it into an LLM context window.

If you have used Obsidian, Notion, Hugo, MkDocs, or any internal "LLM wiki" pattern, the shape will feel familiar. OKF does not invent a new way of thinking. It standardizes a pattern that is already emerging.

That is good product design: it does not try to change an entire behavior pattern. It gives existing workflows a shared collaboration contract.

Three Things Worth Taking Seriously

The OKF specification is short, but the design decisions behind it are useful.

First: it is minimally opinionated. It does not try to define every kind of knowledge that can exist inside a company. It does not define a central taxonomy. The type field is required; the rest is up to the document producer. The consumer has to tolerate unknown fields, extra data, broken links, and missing optional files. That matches reality. Enterprise knowledge is never perfectly clean.

Second: it separates producers from consumers. A human can write an OKF document by hand. An enrichment AI agent can generate one from a BigQuery dataset. A visualizer bot can turn it into a graph. Another agent can read it as operating context.

The file is the collaboration contract. The tooling can change.

Third: it is a format, not a platform. OKF is not tied to a cloud provider, model provider, database, agent framework, or UI. It can live in git, inside a repository subfolder, on a static file server, or as a zip.

That sounds boring. That is exactly why it is strong.

What This Means for Agentic UX

We have mostly designed digital products for humans. Buttons, labels, forms, dashboards, flows. The question was: what does the user see and understand?

AI agents need a different kind of surface. Not necessarily a visual one, but an interpretable one. They need to know what a piece of data means, where it came from, what depends on it, which concept connects to it, and which source supports the claim.

This is the same direction I wrote about with WebMCP: our digital systems need machine-readable affordances, not only human-readable ones. OKF does that for organizational knowledge. It makes company operations readable to AI agents while keeping them readable to people.

This is one foundation of Agentic Experience Design. We are no longer designing only the screen. We are also designing the context layer underneath it: knowledge, contracts, examples, permissions, sources, and workflows.

OKF is not a magic fix. A bad metric definition wrapped in YAML is still bad. A vague bundle written in markdown does not become operational knowledge just because the format is clean. But OKF gives teams a useful starting point. Put knowledge next to the systems it describes. Make the differences visible. Make it reviewable. Make it readable by both AI agents and humans.

In short: treat Context, with a capital C, as product infrastructure. Not as documentation leftovers or chat history.

Where to Start

If you are building an AI agent inside a company, ask this question first: what does the agent need to know that is currently buried in tools, documents, dashboards, and people's heads?

Start small. Choose something concrete but important.

For example:

• a revenue metric;
• a customer support workflow;
• a core dataset;
• an old but still critical API;
• or a good old onboarding playbook.

Describe each important knowledge unit in a separate markdown file. Add links and sources. Use version control. Treat it not as a one-off document, but as a living knowledge layer.

The point is not to make OKF perfect on the first attempt. Version 0.1 is only a starting point. What matters is that we finally have a simple, human-friendly format for a problem every serious AI product team will face.

AI in products will not be just a chat window. It will increasingly become part of the context layer underneath the interface. OKF is one of the clearest early signals of what that layer can look like.

Sources

• Google Cloud: Introducing the Open Knowledge Format
• Open Knowledge Format v0.1 specification