Terug naar Journal
•6 min leestijd

Evolutie van Google Open Knowledge Format naar v0.2: Agent-vertrouwen en Signalen

Hoe OKF v0.2 agent-vertrouwen, herkomst, vertrouwensniveaus, verloopdata en geverifieerde berekeningen aanpakt in AI-kennisgrafieken.

Google CloudAI AgentsRAGOKFBigQueryData Engineering
Evolutie van Google Open Knowledge Format naar v0.2: Agent-vertrouwen en Signalen

Toen ik onze eerste implementatie van Google's Open Knowledge Format documenteerde in Implementing Google's Open Knowledge Format (OKF) in Practice, was het hoofddoel het oplossen van context-isolatie voor AI-agenten. Door platte Markdown-bestanden te structureren in een navigeerbare, gekoppelde grafiek met YAML-frontmatter, konden agenten recursief door documentatiebomen navigeren in plaats van te vertrouwen op onnauwkeurige vectorzoekopdrachten.

OKF v0.1 zorgde voor een solide basis: standaard Markdown, lichtgewicht YAML-metadata (type, title, description, tags) en expliciete relatieve links.

Naarmate platformengineeringteams overstapten van menselijk geschreven documentatie naar autonome multi-agentsystemen, ontstond er echter een fundamentele uitdaging: Wanneer AI-agenten 's nachts continu duizenden kennisconcepten schrijven en bijwerken, hoe kunnen volgwachtende agenten of mensen die corpus dan vertrouwen?

Menselijk geschreven documentatie biedt een impliciete vertrouwensgarantie: een ontwikkelaar heeft het geschreven en neemt de Verantwoordelijkheid voor de juistheid ervan. Wanneer een agent autonoom 10.000 tabeldefinities, metriekspecificaties en runbooks genereert, verdwijnt die impliciete garantie.

Om deze uitdaging aan te pakken, heeft Google Cloud de Open Knowledge Format (OKF) v0.2-specificatie uitgebracht. Deze update introduceert gestructureerde Agent-vertrouwenssignalen en Geverifieerde Berekeningen (Attested Computations) rechtstreeks in de YAML-metadata, zonder de achterwaartse compatibiliteit met v0.1 te verbreken.

Van Context Beschrijven naar Vertrouwen Beslissen

In OKF v0.1 beantwoordden YAML-metadata beschrijvende vragen: Wat is deze node, welke tags beschrijven deze en waar wijst deze naartoe?

OKF v0.2 introduceert beslissingsvelden (deciding fields): metadata die zijn ontworpen om de herkomst, versheid en autoriteit van een node te beoordelen voordat een agent context-tokens uitgeeft aan het lezen van de Markdown-body.

Het analyseren van de volledige tekst van duizenden documentatienodes om vertrouwen te beoordelen is computationeel duur. Door vertrouwenssignalen naar de YAML-frontmatter te tillen, kunnen agenten en deterministische systemen ongecontroleerde, verouderde of afgeraden concepten goedkoop uitfilteren tijdens de navigatie door de grafiek.

OKF Concept Frontmatter
├── Describing Fields (v0.1)  ──> type, title, description, resource, tags
└── Deciding Fields   (v0.2)  ──> generated, verified, status, stale_after, sources

De 5 Belangrijkste Vertrouwenssignalen in OKF v0.2

OKF v0.2 definieert vijf gestandaardiseerde metadatafamilies die kritieke vragen over elk kennisconcept beantwoorden:

1. Herkomst (sources)

In plaats van een willekeurige vertrouwensscore toe te kennen, legt OKF v0.2 ruwe herkomstsignalen vast in een sources-array. Vermeldingen kunnen wijzen naar externe documentatie, relatieve bundelpaden of databasebereiken, verrijkt met geloofwaardigheidsmarkers (author, usage_count, last_modified).

In de hoofdtekst verwijzen specifieke beweringen naar deze bronnen via standaard Markdown-voetnoten (bijv. [^warehouse-schema]):

sources:
  - id: warehouse-schema
    resource: https://wiki.acme.internal/data/warehouse/schemas/sales
    title: Acme Retail Warehouse Schema
    author: team:data-platform
    usage_count: 1240
    last_modified: 2026-06-15
  - id: revenue-policy
    resource: policies/revenue-recognition.md
    title: Revenue Recognition Policy (FY2026)
    author: human:jsmith@acme
    last_modified: 2026-06-15

2. Vertrouwensniveaus (generated vs verified)

OKF v0.2 scheidt expliciet wie een concept heeft gemaakt van wie het heeft bevestigd:

  • generated: { by, at }: Legt de makende entiteit vast (bijv. reference_agent/gemini-2.5-pro) en het tijdstempel.
  • verified: [ { by, at } ]: Legt onafhankelijke beoordelingen vast door geautomatiseerde processen of menselijke goedkeuringen.

Uit deze velden leiden consumenten drie Vertrouwensniveaus (Trust Tiers) af:

  1. Niet-gecontroleerd (Unverified): De sleutel verified ontbreekt.
  2. Machine-bevestigd (Machine-Confirmed): Strikt gecontroleerd door geautomatiseerde achtergrondtools (bijv. nachtelijke CI/CD-linters).
  3. Menselijk beoordeeld (Human-Reviewed): Expliciet goedgekeurd door een mens (bijv. human:kliu@acme).
generated: 
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-30T14:00:00Z
verified:
  - by: human:jsmith@acme
    at: 2026-07-01T09:00:00Z

Een rapportagepipeline voor het bestuur kan specifiek filteren op human-reviewed metrieken, terwijl een staging-omgeving ook machine-confirmed concepten accepteert.

3. Versheid (stale_after)

In plaats van relatieve TTL-duur (bijv. "30 dagen geldig"), gebruikt OKF v0.2 een absolute ISO-8601-datum (bijv. stale_after: 2026-12-31).

Relatieve TTL's zijn afhankelijk van het moment waarop een concept is opgehaald, wat leidt tot niet-deterministisch agentgedrag. Absolute datums maken eenvoudige datumvergelijkingen mogelijk: als de huidige systeemtijd stale_after overschrijdt, wordt het concept gemarkeerd voor hercontrole vóór gebruik.

4. Levenscyclus (status)

Concepten doorlopen expliciete levenscyclusfasen: draft → stable → deprecated (indien weggelaten is de standaardwaarde stable).

Wanneer de bedrijfslogica verandert – zoals bij het bijwerken van een kostenallocatieformule –, wordt de vorige definitie gemarkeerd als status: deprecated. Dit behoudt de historische reproduceerbaarheid van zoekopdrachten en voorkomt dat agenten verouderde metrieken toepassen op nieuwe taken:

type: Metric
title: Gross Margin (Legacy, pre-FY2026)
status: deprecated

Geverifieerde Berekeningen: Voorkomen dat Agenten SQL Improviseren

Herkomst en verificatie bevestigen dat een metriekdefinitie voldoet aan het bedrijfsbeleid. Wanneer een agent echter een financiële metriek rapporteert (bijv. de jaaromzet), blijft er een risico bestaan: de agent zou zijn eigen SQL-zoekopdracht kunnen improviseren.

OKF v0.2 introduceert een nieuw concepttype: Attested Computation. Het definieert zowel de toegestane berekening als een mechanisme om te controleren of de uitgevoerde zoekopdracht exact overeenkomt met de toegestane definitie.

      ┌─────────────────────────────────────────────────────────┐
      │               Attested Computation Node                 │
      │  - runtime: bigquery                                    │
      │  - parameters: [year]                                   │
      │  - executor: skills/run-on-bq.md                        │
      │  - attester: attesters/sql_equality.py                  │
      └──────────────────────────┬──────────────────────────────┘
                                 │
                 1. Binds declared parameters
                 2. Executes sanctioned SQL
                                 ▼
                      ┌─────────────────────┐
                      │ Execution Receipt   │
                      │ - job_id            │
                      │ - executed_sql      │
                      │ - result            │
                      └──────────┬──────────┘
                                 │
                 3. Deterministic AST verification
                                 ▼
                      ┌─────────────────────┐
                      │  Attester Verdict   │
                      │  - OK / REJECTED    │
                      └─────────────────────┘

Productievoorbeeld: BigQuery Omzetattestatie

Hieronder staat een Attested Computation-conceptnode volgens OKF v0.2 voor de BigQuery-jaaromzet:

---
type: Attested Computation
title: Revenue for a Fiscal Year
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: skills/run-on-bq.md
receipt: [job_id, executed_sql, result]
attester:
  resource: attesters/sql_equality.py
generated:
  by: reference_agent/gemini-2.5-pro
  at: 2026-06-30T14:00:00Z
verified:
  - by: human:jsmith@acme
    at: 2026-07-01T09:00:00Z
status: stable
stale_after: 2026-12-31
sources:
  - id: revenue-policy
    resource: policies/revenue-recognition.md
    title: Revenue Recognition Policy (FY2026)
    author: human:jsmith@acme
    last_modified: 2026-06-15
---

# Computation

```sql
SELECT
  SUM(
    CASE 
      WHEN o.currency = 'USD' THEN o.net_amount
      ELSE o.net_amount * fx.rate_to_usd
    END
  ) AS revenue_usd
FROM `acme.sales.orders` AS o
LEFT JOIN `acme.finance.fx_daily_rates` AS fx
  ON fx.currency = o.currency 
 AND fx.rate_date = DATE(o.order_ts)
WHERE o.order_status = 'delivered'
  AND DATE_DIFF(CURRENT_DATE(), DATE(o.order_ts), DAY) >= 30
  AND EXTRACT(YEAR FROM o.order_ts) = @year

Hoe Attestatie Werkt

  1. Alleen Opgegeven Parameters: De agent mag alleen de opgegeven parameters (@year) doorgeven. Hij kan de SQL-tekst niet bewerken of aangepaste WHERE-clausules toevoegen.
  2. Uitvoeringsbewijs: De uitvoeringslaag retourneert een ondertekend bewijs met de job_id, de executed_sql en het resultaat (result).
  3. Deterministische Controle: Een extern Python-script (sql_equality.py) analyseert zowel de doel-SQL als de executed_sql in abstracte syntaxbomen (AST). Als trefwoorden, tabel-JOIN's of filtervoorwaarden verschillen, mislukt de controle en wordt het resultaat geweigerd.

Achterwaartse Compatibiliteit en Migratie

OKF v0.2 is ontworpen als een toevoegende en volledig achterwaarts compatibele versie. Bestaande v0.1-pakketten blijven zonder wijzigingen geldig.

Belangrijke schema-ontwikkelingen:

  • timestamp wordt vervangen door generated.at.
  • Citatiesecties in Markdown (# Citations) worden vervangen door de gestructureerde sources-array in de YAML-frontmatter.
  • In beide gevallen vallen v0.2-parsers rechtstreeks terug op v0.1-velden als de nieuwe sleutels ontbreken.
// OKF v0.2 Parser Terugvalpatroon
const creationTime = frontmatter.generated?.at ?? frontmatter.timestamp;
const documentSources = frontmatter.sources ?? parseLegacyCitations(markdownBody);

Belangrijkste Inzichten

De OKF v0.2-specificatie van Google verandert eenvoudige Markdown-kennisbanken in controleerbare agent-grafieknetwerken:

  1. Beslissen in Plaats van Beschrijven: Metadata in de frontmatter maken goedkope vertrouwensfiltering mogelijk voordat de tekst wordt geladen.
  2. Expliciete Vertrouwensniveaus: Duidelijke scheiding tussen generated- en verified-metadata om menselijke goedkeuringen af te zetten tegen automatische bevestigingen.
  3. Deterministische Versheid: Absolute stale_after-datums voorkomen niet-deterministische TTL-evaluaties.
  4. Geverifieerde Berekeningen: De combinatie van parameter-gebonden uitvoering en AST-gelijkheidscontrollers elimineert SQL-hallucinaties bij agenten.

Door de OKF v0.2-standaarden toe te passen, kunnen platformengineeringteams autonome AI-workflows veilig opschalen met behoud van strikt gegevensbeheer en controleerbaarheid.

Share this article