{"slug": "using-okf-with-knowledge-catalog-to-serve-context-for-agents", "title": "Using OKF with Knowledge Catalog to serve context for agents", "summary": "Google Cloud announced that OKF v0.2 bundles can now be published into Knowledge Catalog, Google Cloud's context engine for agents, enabling organization-wide discovery, governance, and secure access. The integration uses a one-time setup and a single push via sample code in the Knowledge Catalog repository, mapping bundle concepts to EntryType 'okf-bundle' and AspectType 'okf' with 13 fields. This allows agents to retrieve context from a governed index alongside existing technical metadata, with IAM-based access control.", "body_md": "We continue to iterate on the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) (OKF), an open specification that formalizes the [LLM-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) into a portable, interoperable format. But a big question remains: How can you share and govern access to an OKF bundle across an organization?\n\nOKF v0.1 established a portable format for the context agents need: markdown files with YAML frontmatter, one required field, and five conventions. Then, [OKF v0.2](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals) added the trust signals (provenance, verification, freshness, attestation) that a machine-authored bundle requires to be relied on, allowing a team to publish a trustworthy bundle for its own agents.\n\nHowever, what OKF does not answer is how teams share their bundles across an organization. A git repo per bundle is portable, but it is not searchable alongside the data it describes, it cannot be secured and governed using the same organizational identity and compliance policies, and it does not sit next to the technical metadata (schemas, lineage, ownership) that data teams already work in. Every downstream agent must know where each bundle resides, and that does not scale beyond a small number of bundles.\n\nTo scale an OKF bundle across an organization, you can use [Knowledge Catalog](https://cloud.google.com/products/knowledge-catalog), Google Cloud's context engine for agents. By mapping the bundle onto [Knowledge Catalog's existing types](https://docs.cloud.google.com/dataplex/docs/catalog-overview#terminology), every concept becomes discoverable, governed, and reachable by any agent already reading from the catalog.\n\nEvery agent that queries Knowledge Catalog reads from one governed index over what the organization already has in BigQuery, Cloud Storage, operational databases, and applications. Each entry carries schema, lineage, ownership, and tags, and can be extended with typed aspects that add domain-specific fields. The same catalog exposes search and cross-project lookup to retrieve optimized context for each agentic query. The context retrieval is secure and governed by IAM controls, so agents can only see the entries they have access to based on IAM identity.\n\nPublishing an OKF bundle into Knowledge Catalog takes a one-time setup and a single push. Both use the OKF [sample code](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo/okf) in the Knowledge Catalog repository, whose wrappers call `gcloud dataplex`\n\nfor setup and delegate push to `kcmd`\n\n(the Metadata-as-Code CLI in the same repository).\n\nThe setup registers three Knowledge Catalog resources: an EntryGroup to hold the bundle, an EntryType named `okf-bundle`\n\nfor its concepts, and an AspectType named `okf`\n\nthat carries the OKF signal fields (from the `okf-aspect.json`\n\nschema in the [sample code](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo/okf)). The push then creates one `okf-bundle`\n\nEntry per concept, each with two Aspects: an `overview`\n\nAspect for the markdown body, and an `okf`\n\nAspect for the structured signals. Display name, description, and tags live on the Entry itself. The bundle's `index.md`\n\nnavigation files and its root `log.md`\n\nare also published as Entries: index files carry only the `overview`\n\nAspect (no OKF frontmatter), and `log.md`\n\ncarries both Aspects with `okf_type: Log`\n\n.\n\nEverything Knowledge Catalog already does for technical metadata (search, IAM, lineage, cross-project discovery) applies equally to OKF bundles, alongside the data they describe.\n\nThe [ okf-aspect.json](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/demo/okf/okf-aspect.json) schema in the sample code defines the AspectType. It carries 13 fields covering the full\n\n|\n|\n|\n|\n|\n|---|---|---|---|\n|\n1 |\n|\nstring |\nThe OKF document type (freeform, e.g. |\n|\n2 |\n|\nrecord |\nActor and timestamp for the last meaningful change. |\n|\n3 |\n|\narray of |\nMaterials the concept derives from, with credibility signals. |\n|\n4 |\n|\narray of |\nVerification events. A |\n|\n5 |\n|\nstring |\nLifecycle state: |\n|\n6 |\n|\ndatetime |\nAbsolute point in time (RFC3339 with an explicit offset) on or after which the content is stale. |\n|\n7 |\n|\nrecord |\nPeriod the source usage counts were measured over. |\n|\n8 |\n|\nstring |\nHow an Attested Computation runs (e.g., |\n|\n9 |\n|\narray of |\nTyped named holes a caller may fill. The only surface a caller may vary. |\n|\n10 |\n|\nstring |\nPath to a file holding the computation body. |\n|\n11 |\n|\nrecord |\nHow the computation runs and what evidence it must return. |\n|\n12 |\n|\nrecord |\nDeterministic code that takes a receipt and returns a verdict. |\n|\n13 |\n|\nstring |\nProducer-defined frontmatter the template does not model, as JSON |\n\nEvery field is annotated with a display name, a description, and a mandatory index. Any top-level scalar field in the `okf`\n\nAspect (`okf_type`\n\n, `status`\n\n, `stale_after`\n\n, `runtime`\n\n, `computation`\n\n, `extra`\n\n) can drive Knowledge Catalog search predicates directly, so `aspect:acme-analytics.us-central1.okf.okf_type=Metric`\n\nreturns every OKF Metric in scope. Scalar subfields of record fields (`generated.by`\n\n, `usage_window.from`\n\n, `executor.resource`\n\n, `attester.resource`\n\n) also drive predicates. The array fields (`sources`\n\n, `verified`\n\n, `parameters`\n\n) are not server-side searchable on their subfields; agents narrow on them client-side after `entries.get`\n\nwith `view=ALL`\n\n. One caveat for search predicates on `datetime`\n\n-typed fields (`stale_after`\n\n, `generated.at`\n\n, `usage_window.from`\n\n/`.to`\n\n), use a bare date (`stale_after=2026-12-31`\n\n) or a range comparison (`stale_after>2026-01-01`\n\n), not the full RFC3339 timestamp.\n\n`kcmd push`\n\nreads an OKF bundle from git and writes each concept as an Entry in the target Knowledge Catalog EntryGroup. `index.md`\n\nfiles become Entries too, and each concept is parented to the index above it, so the bundle's directory structure survives as a browsable hierarchy.\n\n`kcmd`\n\nexpects a bundle in the Documents Layout: markdown files under a `catalog/`\n\nsubdirectory, and a `catalog.yaml`\n\nat the bundle root that lists the snapshot's entry and aspect types. The [sample code](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo/okf)'s `setup.ts`\n\ngenerates `catalog.yaml`\n\nfrom its `--entry-group`\n\nflag (default `okf_demo`\n\n), so a reader wiring the sample to a new bundle passes the flag rather than editing `catalog.yaml`\n\nby hand.\n\nHere is an end-to-end workflow for the [Acme Retail bundle](https://github.com/GoogleCloudPlatform/open-knowledge-format/tree/main/bundles/acme_retail) that we introduced in the [OKF v0.2 blog](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals?e=48754805):\n\nTo pick a different EntryGroup name or push a different bundle, pass `--entry-group your-name`\n\nto `setup.ts`\n\nand `--bundle path/to/your/bundle`\n\nto `push.ts`\n\n. For example: `bun run setup.ts --entry-group acme-bundle`\n\nfollowed by `bun run push.ts`\n\n. This regenerates the manifest, so subsequent `push`\n\n, `pull`\n\n, and `cleanup`\n\nall target the new EG; delete earlier EGs manually with `gcloud dataplex entry-groups delete <name> --project <your-project> --location <your-location>`\n\n.\n\nThe [Acme Retail bundle](https://github.com/GoogleCloudPlatform/open-knowledge-format/tree/main/bundles/acme_retail) is a synthetic OKF bundle for a US retailer's BigQuery estate. It contains nine leaf concepts across six directories (`attesters`\n\n, `tables`\n\n, `metrics`\n\n, `computations`\n\n, `policies`\n\n, `skills`\n\n), each with its own `index.md`\n\n, plus a bundle root with its own `index.md`\n\nand `log.md`\n\n. That's 17 pushed Entries in total; Dataplex auto-creates one `<eg>_entry`\n\nalongside, so `gcloud dataplex entries list`\n\nreturns 18 rows.\n\nAfter the push completes:\n\nEvery concept markdown file is a Knowledge Catalog Entry, discoverable by search across the whole project or organization, depending on IAM configuration.\n\nThe `revenue-ytd`\n\nAttested Computation appears in the console with its sanctioned SQL, its executor, its attester, its verification history, and the full concept body.\n\nAn analyst searching Knowledge Catalog for \"revenue\" finds Acme Retail's business definition alongside the BigQuery table it computes from, both under one permission model.\n\nA downstream agent that already calls LookupContext for BigQuery table Entries retrieves the bundle's context by adding the OKF entry names to its `resources`\n\nlist.\n\nFurther, `metrics/revenue.md`\n\nbecomes an Entry with two Aspects. The full `entries.get`\n\nresponse (with `view=ALL`\n\n) looks like:\n\nThe `overview`\n\nAspect holds the full body of `revenue.md`\n\n. The `okf`\n\nAspect carries the structured signal fields, so agents get provenance, source, and OKF type in a form they can filter on directly instead of parsing markdown. Server-side searchEntries filters on the top-level scalar fields and on the scalar subfields of record fields; agents narrow further on the array-element subfields client-side after entries.get. (Aspects and EntryTypes are keyed by project number in real API responses and search predicates; the `acme-analytics`\n\nproject ID is shown throughout for readability.)\n\nOnce the bundle is in Knowledge Catalog, it provides two capabilities to any agent that reads from the catalog:\n\n**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 and other resources in every query it matches.\n\n**Governance.** Bundle Entries inherit IAM from the EntryGroup, so a single agent call returns exactly what the caller is permitted to read, with no parallel permission model to maintain.\n\n**Discoverability across the organization** OKF bundle Entries appear in searchEntries results alongside BigQuery tables and other cataloged resources, so an agent already querying the catalog picks up new bundles automatically. To retrieve a concept's body, trust signals, or linked concepts from a match, the agent moves to LookupContext and\n\n`entries.get`\n\n.A LookupContext call looks like this:\n\nThe response is a single `context`\n\nfield containing a pre-formatted YAML block. The block carries the entry's `catalogEntry`\n\n, its type, its description, its tags as labels, and its `overview`\n\n: the full markdown body of the concept, including its trust and freshness section. LookupContext does not render custom Aspects, so an agent that needs the structured OKF signal fields (`okf_type`\n\n, `generated`\n\n, `sources`\n\n, and the other ten) reads them with `entries.get`\n\nand `view=ALL`\n\nalongside the LookupContext call.\n\nThere is no repository clone, no manual Aspect merging, and no re-parse of frontmatter. The agent uses the same API call any Knowledge Catalog client already makes.\n\nAn agent traversing an OKF bundle typically follows a three-step flow. An agent that already knows the specific Entry names it needs skips step 1. An agent that already knows the target EntryGroup and wants to enumerate the bundle exhaustively substitutes `entryGroups.entries.list`\n\nfor step 1.\n\nsearchEntries returns candidate Entry names and descriptions. Its `scope`\n\naccepts a project or organization; narrowing within that scope happens through query terms, including aspect predicates like `aspect:acme-analytics.us-central1.okf.okf_type=Metric`\n\n.\n\nLookupContext on the top few Entry names (up to ten per call) returns the full concept body as pre-formatted YAML; `context_budget`\n\ncaps the response size.\n\n`entries.get`\n\nwith `view=ALL`\n\non any Entry returns its structured OKF signals (`okf_type`\n\n, `generated`\n\n, `sources`\n\n, and the other ten) directly, which the agent can then filter or attest on.\n\nWhen a concept's `sources[]`\n\nreferences another concept by path, the agent calls LookupContext on that Entry name to walk the reference.\n\nThe full response for the Revenue Entry:\n\n**Governance** Permissions on the EntryGroup use standard Knowledge Catalog IAM. An agent that names both a bundle concept and the BigQuery table it grounds against in one call receives both, each subject to its own existing access control list (ACL), so the response carries only what the caller is already permitted to read. There is no parallel permission model to maintain.\n\nReading agents use `roles/dataplex.catalogViewer`\n\n, which grants the read paths: `entries.get`\n\n, LookupContext, and searchEntries. The identity that runs `kcmd push`\n\nuses `roles/dataplex.catalogEditor`\n\n, which grants the write paths: `entries.create`\n\nand `entries.patch`\n\n. One EntryGroup per bundle-owning team is the multi-team pattern, and IAM on the EntryGroup cascades to its Entries.\n\nLookupContext resolves the entry names it is given, up to ten per call, within a single location. It does not follow links out of a concept's body, so an agent that wants a referenced concept must name it explicitly. Place the bundle's EntryGroup in the same location as the data it describes to fetch both in one call.\n\n`kcmd push`\n\nis an idempotent upsert. Re-running is safe (no duplicates, no error), but every push writes every Entry. Concept deletes require an explicit `kcmd delete`\n\non the Entry, or `cleanup.ts`\n\nto remove the whole EntryGroup at once; `cleanup.ts`\n\ndeletes only the EntryGroup and its Entries, so the shared `okf`\n\nAspectType and `okf-bundle`\n\nEntryType stay in place for other bundles that reference them. For continuous ingestion in production, wire a CI job to `kcmd push`\n\non every commit to the bundle repository, using a service-account credential with `roles/dataplex.catalogEditor`\n\non the target EntryGroup.\n\nOKF defines what a trustworthy bundle looks like. Knowledge Catalog makes it reachable across the organization. To get started, check out the following resources:\n\nRead the [OKF v0.2 spec](https://github.com/GoogleCloudPlatform/open-knowledge-format/blob/main/SPEC.md) and browse the [Acme Retail bundle](https://github.com/GoogleCloudPlatform/open-knowledge-format/tree/main/bundles/acme_retail).\n\nAuthor a small bundle for one domain your team owns.\n\nSync it into your Knowledge Catalog project using the [sample code](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/toolbox/mdcode/demo/okf)'s `setup.ts`\n\n(which registers the resources) and `push.ts`\n\n(which delegates to `kcmd`\n\n).\n\nPoint your existing agents at Knowledge Catalog. New context becomes reachable through the same LookupContext and searchEntries calls they already use.", "url": "https://wpnews.pro/news/using-okf-with-knowledge-catalog-to-serve-context-for-agents", "canonical_source": "https://cloud.google.com/blog/products/data-analytics/scale-okf-bundles-across-an-organization-with-knowledge-catalog/", "published_at": "2026-08-26 16:00:00+00:00", "updated_at": "2026-08-26 16:15:54.736687+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-infrastructure", "developer-tools"], "entities": ["Google Cloud", "Knowledge Catalog", "Open Knowledge Format", "OKF", "BigQuery", "Cloud Storage", "Dataplex", "gcloud dataplex"], "alternates": {"html": "https://wpnews.pro/news/using-okf-with-knowledge-catalog-to-serve-context-for-agents", "markdown": "https://wpnews.pro/news/using-okf-with-knowledge-catalog-to-serve-context-for-agents.md", "text": "https://wpnews.pro/news/using-okf-with-knowledge-catalog-to-serve-context-for-agents.txt", "jsonld": "https://wpnews.pro/news/using-okf-with-knowledge-catalog-to-serve-context-for-agents.jsonld"}}