Torna al Diario
•7 min di lettura

Evoluzione di Google Open Knowledge Format a v0.2: Segnali di Fiducia e Agenti IA

Come OKF v0.2 gestisce la fiducia degli agenti, la provenienza, i livelli di affidabilità, la data di scadenza e le elaborazioni attestate nei grafi di conoscenza IA.

Google CloudAI AgentsRAGOKFBigQueryData Engineering
Evoluzione di Google Open Knowledge Format a v0.2: Segnali di Fiducia e Agenti IA

Quando ho documentato per la prima volta la nostra implementazione dell'Open Knowledge Format di Google in Implementing Google's Open Knowledge Format (OKF) in Practice, l'obiettivo principale era risolvere l'isolamento del contesto per gli agenti IA. Organizzando semplici file Markdown in un grafo navigabile e collegato tramite YAML frontmatter, gli agenti potevano esplorare in modo ricorsivo i nodi della documentazione anziché affidarsi a ricerche vettoriali imprecise.

OKF v0.1 ha stabilito una solida base: Markdown standard, metadati YAML leggeri (type, title, description, tags) e link relativi espliciti.

Tuttavia, quando i team di ingegneria di piattaforma sono passati da documentazioni scritte da persone a sistemi autonomi multi-agente, è emersa una sfida fondamentale: Quando gli agenti IA scrivono e aggiornano continuamente migliaia di concetti durante la notte, come possono gli agenti successivi o le persone fidarsi di questo corpus?

La documentazione scritta da esseri umani offre una garanzia implicita di fiducia: uno sviluppatore l'ha scritta e si assume la responsabilità della sua accuratezza. Quando un agente genera autonomamente 10.000 definizioni di tabelle, specifiche di metriche e manuali operativi, quella garanzia implicita scompare.

Per affrontare questa sfida, Google Cloud ha pubblicato le specifiche Open Knowledge Format (OKF) v0.2. Questo aggiornamento introduce Segnali di Fiducia degli Agenti strutturati e Calcoli Attestati (Attested Computations) direttamente nei metadati YAML senza interrompere la retrocompatibilità con la versione v0.1.

Dal Descrivere il Contesto al Decidere la Fiducia

In OKF v0.1, i metadati YAML rispondevano a domande descrittive: Cos'è questo nodo, quali tag lo descrivono e dove punta?

OKF v0.2 introduce campi decisionali (deciding fields): metadati progettati per valutare l'origine, la freschezza e l'autorità di un nodo prima che un agente spenda token di contesto per leggere il testo in Markdown.

Analizzare l'intero corpo di migliaia di nodi di documentazione per valutare l'affidabilità è computazionalmente costoso. Elevare i segnali di fiducia nel frontmatter YAML consente agli agenti e ai sistemi deterministici di filtrare facilmente concetti non verificati, obsoleti o deprecati durante l'esplorazione del grafo.

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

I 5 Segnali di Fiducia Principali in OKF v0.2

OKF v0.2 definisce cinque famiglie di metadati standardizzate che rispondono a domande critiche su qualsiasi concetto di conoscenza:

1. Provenienza (sources)

Anziché assegnare un punteggio di fiducia arbitrario, OKF v0.2 registra i segnali di provenienza originali in un array sources. Le voci possono puntare a documentazione esterna, percorsi relativi del pacchetto o ambiti di database, arricchite da indicatori di credibilità (author, usage_count, last_modified).

All'interno del testo, specifiche affermazioni si collegano a queste fonti utilizzando note a piè di pagina in Markdown (ad esempio, [^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. Livelli di Affidabilità (generated vs verified)

OKF v0.2 separa esplicitamente chi ha creato un concetto da chi lo ha confermato:

  • generated: { by, at }: Registra l'entità creatrice (ad esempio, reference_agent/gemini-2.5-pro) e la data di creazione.
  • verified: [ { by, at } ]: Registra revisioni indipendenti effettuate da processi automatici o approvazioni umane.

Da questi campi, i consumatori deducono tre Livelli di Affidabilità (Trust Tiers):

  1. Non verificato (Unverified): La chiave verified è assente.
  2. Confermato da macchine (Machine-Confirmed): Verificato rigorosamente da strumenti automatici in background (ad esempio, linter CI/CD notturni).
  3. Revisionato da umani (Human-Reviewed): Approvato esplicitamente da una persona (ad esempio, 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

Una pipeline di reportistica aziendale può filtrare specificamente le metriche human-reviewed, mentre un ambiente di test può accettare concetti machine-confirmed.

3. Freschezza (stale_after)

Anziché utilizzare durate TTL relative (ad esempio, "valido per 30 giorni"), OKF v0.2 utilizza una data ISO-8601 assoluta (ad esempio, stale_after: 2026-12-31).

I TTL relativi dipendono dal momento in cui un concetto è stato letto, causando comportamenti non deterministici degli agenti. Le date assolute consentono confronti diretti: se la data attuale del sistema supera stale_after, il concetto viene contrassegnato per una nuova verifica prima di essere utilizzato.

4. Ciclo di Vita (status)

I concetti evolvono attraverso stati espliciti del ciclo di vita: draft → stable → deprecated (se omesso, il valore predefinito è stable).

Quando la logica aziendale si evolve, ad esempio aggiornando una formula di allocazione dei costi, la definizione precedente viene contrassegnata come status: deprecated. Questo mantiene la riproducibilità storica delle query impedendo agli agenti di applicare metriche obsolete a nuove attività:

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

Calcoli Attestati: Prevenire l'Improvvisazione SQL degli Agenti

La provenienza e la verifica confermano che la definizione di una metrica è conforme alle regole aziendali. Tuttavia, quando un agente riporta una metrica finanziaria (ad esempio, il fatturato annuo), rimane un rischio fondamentale: l'agente potrebbe improvvisare la propria query SQL.

OKF v0.2 introduce un nuovo tipo di concetto: Attested Computation. Definisce sia il calcolo autorizzato sia un meccanismo per verificare che la query eseguita corrisponda esattamente alla definizione autorizzata.

      ┌─────────────────────────────────────────────────────────┐
      │               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    │
                      └─────────────────────┘

Esempio in Produzione: Attestazione del Fatturato in BigQuery

Di seguito è riportato un nodo di concetto Attested Computation in OKF v0.2 per il fatturato in BigQuery:

---
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

Come Funziona l'Attestazione

  1. Assegnazione dei Soli Parametri: L'agente può solo fornire i parametri dichiarati (@year). Non può modificare il testo SQL né aggiungere clausole WHERE personalizzate.
  2. Ricevuta di Esecuzione: Lo strato di esecuzione restituisce una ricevuta firmata contenente il job_id, l'executed_sql e il risultato (result).
  3. Attestazione Deterministica: Uno script Python esterno (sql_equality.py) analizza sia l'SQL di origine sia l'executed_sql in Alberi Sintattici Astratti (AST). Se le parole chiave, i JOIN di tabelle o le condizioni dei filtri differiscono, l'attestazione fallisce e il risultato viene rifiutato.

Retrocompatibilità e Migrazione

OKF v0.2 è progettato come una versione aggiuntiva e totalmente retrocompatibile. I pacchetti v0.1 esistenti rimangono validi senza modifiche.

Le principali evoluzioni dello schema includono:

  • timestamp è sostituito da generated.at.
  • Le sezioni di citazione in Markdown (# Citations) sono sostituite dall'array strutturato sources nel frontmatter YAML.
  • In entrambi i casi, i parser v0.2 utilizzano direttamente i campi v0.1 se le nuove chiavi sono assenti.
// Modello di fallback nel parser OKF v0.2
const creationTime = frontmatter.generated?.at ?? frontmatter.timestamp;
const documentSources = frontmatter.sources ?? parseLegacyCitations(markdownBody);

Punti Chiave

La specifica OKF v0.2 di Google trasforma le basi di conoscenza in semplice Markdown in reti di grafi verificabili per agenti IA:

  1. Decidere Anziché Descrivere: I metadati nel frontmatter consentono un filtraggio dell'affidabilità economico prima di caricare il testo.
  2. Livelli di Affidabilità Espliciti: Chiara separazione tra metadati generated e verified per evidenziare le approvazioni umane rispetto alle conferme automatiche.
  3. Freschezza Deterministica: Le date assolute stale_after evitano valutazioni non deterministiche dei TTL.
  4. Calcoli Attestati: La combinazione tra esecuzione guidata dai parametri ed esaminatori di uguaglianza AST elimina le allucinazioni SQL degli agenti.

Adottando gli standard OKF v0.2, i team di ingegneria di piattaforma possono scalare in sicurezza i flussi di lavoro autonomi di intelligenza artificiale mantenendo una rigorosa governance dei dati e la piena tracciabilità.

Share this article