Volver al Diario
•8 min de lectura

Evolución del Open Knowledge Format de Google a v0.2: Confianza y Señales Agénticas

Cómo OKF v0.2 aborda la confianza agéntica, la procedencia, los niveles de confianza, la caducidad y las computaciones atestadas en grafos de conocimiento de IA.

Google CloudAI AgentsRAGOKFBigQueryData Engineering
Evolución del Open Knowledge Format de Google a v0.2: Confianza y Señales Agénticas

Cuando documenté por primera vez nuestra implementación del Open Knowledge Format de Google en Implementing Google's Open Knowledge Format (OKF) in Practice, el objetivo principal era resolver el aislamiento de contexto para los agentes de inteligencia artificial. Al organizar archivos Markdown planos en un grafo vinculado y navegable con encabezados YAML, los agentes podían recorrer de forma recursiva los nodos del árbol de documentación en lugar de depender de búsquedas vectoriales imprecisas.

OKF v0.1 estableció una base sólida: Markdown estándar, metadatos YAML ligeros (type, title, description, tags) y enlaces relativos explícitos.

Sin embargo, a medida que los equipos de ingeniería de plataformas pasaron de la documentación escrita por humanos a sistemas autónomos de múltiples agentes, surgió un desafío fundamental: Cuando los agentes de IA escriben y actualizan continuamente miles de conceptos de conocimiento durante la noche, ¿cómo pueden los agentes posteriores o los humanos confiar en el corpus?

La documentación redactada por humanos ofrece una garantía implícita de confianza: un desarrollador la escribió y se responsabiliza de su precisión. Cuando un agente genera de forma autónoma 10.000 definiciones de tablas, especificaciones de métricas y manuales de operaciones, esa garantía implícita desaparece.

Para abordar este desafío, Google Cloud publicó la especificación Open Knowledge Format (OKF) v0.2. Esta actualización introduce Señales de Confianza Agéntica estructuradas y Computaciones Atestadas directamente en los metadatos YAML sin romper la compatibilidad con v0.1.

De Describir el Contexto a Decidir la Confianza

En OKF v0.1, los metadatos YAML respondían a preguntas descriptivas: ¿Qué es este nodo, qué etiquetas lo describen y a dónde apunta?

OKF v0.2 introduce campos de decisión (deciding fields): metadatos diseñados para evaluar el origen, la frescura y la autoridad de un nodo antes de que un agente gaste tokens de contexto leyendo el cuerpo en Markdown.

Analizar el cuerpo completo de miles de nodos de documentación para evaluar la confianza resulta computacionalmente costoso. Elevar las señales de confianza al encabezado YAML permite a los agentes y a los sistemas deterministas filtrar conceptos no verificados, obsoletos o desaprobados de forma económica durante el recorrido del grafo.

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

Las 5 Señales de Confianza Principales en OKF v0.2

OKF v0.2 establece cinco familias de metadatos estandarizadas que responden a preguntas críticas sobre cualquier concepto de conocimiento:

1. Procedencia (sources)

En lugar de asignar una puntuación de confianza arbitraria, OKF v0.2 registra las señales de procedencia originales en una lista sources. Las entradas pueden apuntar a documentación externa, rutas relativas del paquete o ámbitos de bases de datos, enriquecidas con marcadores de credibilidad (author, usage_count, last_modified).

Dentro del texto del cuerpo, las afirmaciones específicas se enlazan con estas fuentes mediante notas al pie en Markdown (por ejemplo, [^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. Niveles de Confianza (generated vs verified)

OKF v0.2 separa explícitamente quién creó un concepto de quién lo confirmó:

  • generated: { by, at }: Registra la entidad creadora (por ejemplo, reference_agent/gemini-2.5-pro) y la marca de tiempo.
  • verified: [ { by, at } ]: Registra revisiones independientes realizadas por procesos automáticos o firmas humanas.

A partir de estos campos, los consumidores deducen tres Niveles de Confianza (Trust Tiers):

  1. No verificado (Unverified): Falta la clave verified.
  2. Confirmado por máquina (Machine-Confirmed): Verificado estrictamente por herramientas automáticas en segundo plano (por ejemplo, verificadores en flujos CI/CD).
  3. Revisado por humanos (Human-Reviewed): Firmado explícitamente por un actor humano (por ejemplo, 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

Un pipeline de informes ejecutivos puede filtrar específicamente métricas human-reviewed, mientras que un entorno de pruebas puede aceptar conceptos machine-confirmed.

3. Frescura (stale_after)

En lugar de duraciones TTL relativas (por ejemplo, "válido por 30 días"), OKF v0.2 utiliza una fecha ISO-8601 absoluta (por ejemplo, stale_after: 2026-12-31).

Los TTL relativos dependen del momento en que se recuperó el concepto, lo que genera un comportamiento no determinista en el agente. Las fechas absolutas permiten comparaciones directas: si la marca de tiempo actual del sistema supera stale_after, el concepto se marca para su reverificación antes de servirse.

4. Ciclo de Vida (status)

Los conceptos avanzan a través de estados explícitos de ciclo de vida: draft → stable → deprecated (si se omite, se asume stable).

Cuando la lógica de negocio evoluciona, como al actualizar una fórmula de asignación de costos, la definición anterior se marca como status: deprecated. Esto conserva la reproducibilidad histórica de las consultas mientras evita que los agentes apliquen métricas obsoletas en nuevas tareas:

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

Computaciones Atestadas: Previniendo la Improvisación de SQL por el Agente

La procedencia y la verificación confirman que la definición de una métrica coincide con la política de la empresa. Sin embargo, cuando un agente informa una métrica financiera (por ejemplo, los ingresos acumulados en el año), persiste un riesgo importante: que el agente improvise su propia consulta SQL.

OKF v0.2 introduce un nuevo tipo de concepto: Attested Computation. Define tanto el cálculo sancionado como un mecanismo para verificar que la consulta ejecutada coincide exactamente con la definición sancionada.

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

Ejemplo en Producción: Atestación de Ingresos en BigQuery

A continuación se muestra un nodo de concepto Attested Computation de OKF v0.2 para ingresos fiscales en 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

Cómo Funciona la Atestación

  1. Asignación Exclusiva de Parámetros: El agente solo puede proporcionar los parámetros declarados (@year). No puede modificar el texto SQL ni añadir cláusulas WHERE personalizadas.
  2. Recibo de Ejecución: La capa de ejecución devuelve un recibo firmado que contiene el job_id, el executed_sql y el resultado (result).
  3. Atestación Determinista: Un script de Python externo no generado por LLM (sql_equality.py) analiza tanto el SQL objetivo como el executed_sql en Árboles de Sintaxis Abstracta (AST). Si las palabras clave, los JOIN de tablas o las condiciones de filtro difieren, la atestación falla y el resultado es rechazado.

Compatibilidad hacia Atrás y Migración

OKF v0.2 está diseñado como una versión aditiva y totalmente compatible con versiones anteriores. Los paquetes v0.1 existentes siguen siendo válidos sin modificaciones.

Las evoluciones clave del esquema incluyen:

  • timestamp es reemplazado por generated.at.
  • Las secciones de citas en Markdown (# Citations) son reemplazadas por la matriz estructurada sources en el encabezado YAML.
  • En ambos casos, los analizadores v0.2 recurren directamente a los campos v0.1 si las nuevas claves están ausentes.
// Patrón de respaldo en el analizador OKF v0.2
const creationTime = frontmatter.generated?.at ?? frontmatter.timestamp;
const documentSources = frontmatter.sources ?? parseLegacyCitations(markdownBody);

Conclusiones Clave

La especificación OKF v0.2 de Google transforma las bases de conocimiento en Markdown plano en redes de grafos verificables para agentes de IA:

  1. Decidir sobre Describir: Los metadatos elevados permiten un filtrado de confianza económico antes de cargar el contenido de texto.
  2. Niveles de Confianza Explícitos: Clara separación entre generated y verified para exponer revisiones humanas frente a confirmaciones automáticas.
  3. Caducidad Determinista: Las fechas absolutas stale_after evitan evaluaciones no deterministas de TTL.
  4. Computaciones Atestadas: La combinación de ejecución con parámetros limitados y atestadores de igualdad AST elimina las alucinaciones de SQL en los agentes.

Al adoptar los estándares de OKF v0.2, los equipos de ingeniería de plataformas pueden escalar flujos de trabajo autónomos de IA de forma segura manteniendo una gobernanza de datos y auditabilidad estrictas.

Share this article