Eволюція Google Open Knowledge Format до v0.2: Сигнали довіри AI-агентів

Коли я вперше документував наше впровадження формату Open Knowledge Format від Google у статті Implementing Google's Open Knowledge Format (OKF) in Practice, головною метою було вирішення проблеми ізоляції контексту для AI-агентів. Організація простих файлів Markdown у зв'язний граф із метаданими YAML дозволила агентам рекурсивно проходити вузли документації замість використання неточного векторного пошуку.

OKF v0.1 створив надійну основу: стандартний Markdown, легкі метадані YAML (type, title, description, tags) та явні відносні посилання.

Однак у міру того, як інженерні команди переходили від написаної людьми документації до автономних мультиагентних систем, виникло фундаментальне питання: Коли AI-агенти безперервно генерують і оновлюють тисячі концептів за ніч, як наступні агенти або люди можуть довіряти цій базі знань?

Документація, написана людиною, містить неявну гарантію довіри — розробник написав її і несе відповідальність за точність. Коли агент автономно створює 10 000 описів таблиць, метрик та інструкцій, ця гарантія зникає.

Для вирішення цієї проблеми Google Cloud випустила специфікацію Open Knowledge Format (OKF) v0.2. Це оновлення вводить структуровані сигнали довіри агентів та завірені обчислення (Attested Computations) безпосередньо в метадані YAML без порушення зворотної сумісності з v0.1.

Від опису контексту до прийняття рішень про довіру

У OKF v0.1 метадані YAML відповідали на описові питання: Що це за вузол, які теги його описують і куди він веде?

OKF v0.2 вводить вирішальні поля (deciding fields) — метадані, призначені для оцінки походження, актуальності та авторитетності вузла до того, як агент витратить токени на читання основного тексту Markdown.

Аналіз повного тексту тисяч вузлів документації для оцінки довіри вимагає великих обчислювальних ресурсів. Винесення сигналів довіри в заголовок YAML дозволяє агентам та детермінованим системам недорого відфільтровувати перевірені, застарілі або виведені з эксплуатации концепти під час обходу графа.

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

5 ключових сигналів довіри в OKF v0.2

OKF v0.2 визначає п'ять стандартизованих сімейств метаданих, що відповідають на важливі питання про будь-який концепт знань:

1. Походження (`sources`)

Замість призначення довільної оцінки довіри OKF v0.2 записує вихідні сигнали походження в масив sources. Записи можуть вказувати на зовнішню документацію, відносні шляхи всередині пакета або області баз даних, доповнені маркерами надійності (author, usage_count, last_modified).

Усередині тексту конкретні твердження посилаються на ці джерела за допомогою стандартних виносок Markdown (наприклад, [^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. Рівні довіри (`generated` проти `verified`)

OKF v0.2 чітко розділяє того, хто створив концепт, і того, хто його підтвердив:

generated: { by, at }: Записує сутність-творця (наприклад, reference_agent/gemini-2.5-pro) та час створення.
verified: [ { by, at } ]: Записує незалежні перевірки автоматичними процесами або людьми.

На основі цих полів системи виділяють три рівні довіри (Trust Tiers):

Неперевірений (Unverified): Ключ verified відсутній.
Підтверджений машиною (Machine-Confirmed): Перевірений автоматичними фоновими інструментами (наприклад, нічними лінтерами CI/CD).
Перевірений людиною (Human-Reviewed): Підтверджений людиною (наприклад, 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

Система звітів для керівництва може фільтрувати тільки метрики human-reviewed, тоді як тестове середовище може приймати концепти machine-confirmed.

3. Актуальність (`stale_after`)

Замість відносних термінів TTL (наприклад, «дійсний 30 днів») OKF v0.2 використовує точну дату ISO-8601 (наприклад, stale_after: 2026-12-31).

Відносні TTL залежать від моменту читання концепту, що призводить до недетермінованої поведінки агента. Точні дати дозволяють використовувати просте порівняння: якщо поточний час перевищує stale_after, концепт відправляється на повторну перевірку.

4. Життєвий цикл (`status`)

Концепти проходять через чіткі стани життєвого циклу: draft → stable → deprecated (за замовчуванням stable).

При зміні бізнес-логіки (наприклад, оновленні формули розподілу витрат) попереднє визначення отримує статус status: deprecated. Це зберігає можливість відтворення старих запитів та запобігає застосуванню застарілих метрик до нових завдань:

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

Завірені обчислення: Захист від імпровізації SQL агентами

Походження та перевірка підтверджують, що визначення метрики відповідає регламенту компанії. Однак коли агент обчислює фінансовий показник (наприклад, річний виторг), залишається ризик: агент може вигадати власний SQL-запит.

OKF v0.2 вводить новий тип концепту: Attested Computation. Він визначає як дозволене обчислення, так і механізм перевірки того, що виконаний запит точно відповідає затвердженому визначенню.

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

Приклад у продакшені: Завірення виторгу в BigQuery

Нижче представлено вузол Attested Computation у OKF v0.2 для розрахунку річного виторгу в 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

Як працює завірення

Передача тільки оголошених параметрів: Агент може передавати тільки оголошені параметри (@year). Він не може змінювати текст SQL або додавати власні умови WHERE.
Квитанція про виконання: Слой виконання повертає підписану квитанцію з job_id, executed_sql та результатом (result).
Детермінована перевірка: Зовнішній скрипт Python (sql_equality.py) розбирає цільовий SQL та executed_sql у абстрактні синтаксичні дерева (AST). Якщо ключові слова, з'єднання таблиць або умови фільтрації відрізняються, перевірка не проходить і результат відхиляється.

Зворотна сумісність та міграція

OKF v0.2 розроблено як доповнюючу та повністю сумісну зі старими версіями версію. Існуючі пакети v0.1 залишаються дійсними без змін.

Основні зміни схеми:

Поле timestamp замінено на generated.at.
Розділи цитування в тексті (# Citations) замінені структурованим масивом sources у заголовку YAML.
В обох випадках парсери v0.2 використовують поля v0.1, якщо нові ключі відсутні.

// Резервний шаблон парсера OKF v0.2
const creationTime = frontmatter.generated?.at ?? frontmatter.timestamp;
const documentSources = frontmatter.sources ?? parseLegacyCitations(markdownBody);

Головні висновки

Специфікація Google OKF v0.2 перетворює прості бази знань Markdown на перевірювані графові мережі для AI-агентів:

Рішення замість опису: Метадані в заголовку дозволяють недорого фільтрувати дані за уровнем довіри до завантаження тексту.
Явні рівні довіри: Чіткий поділ generated та verified для виявлення людських перевірок на тлі автоматичних.
Детермінована актуальність: Точні дати stale_after запобігають помилкам оцінки терміну служби.
Завірені обчислення: Поєднання параметрів та AST-перевірки виключає галюцинації AI в SQL-запитах.

Впроваджуючи стандарти OKF v0.2, інженерні команди можуть безпечно масштабувати автономні процеси AI із збереженням суворого контролю та аудиту даних.