Format de connaissance ouverte : fichiers Markdown en tant que couche de connaissance portable pour les agents

Les agents consomment des tokens en relisant sans cesse les mêmes documents internes, et Google Cloud a proposé une solution : le Open Knowledge Format, ou OKF. La version 0.1 a été annoncée sur le blog de Google Cloud le 12 juin 2026. L’idée est simple. Chaque concept qui intéresse une équipe devient un fichier Markdown, et un dossier contenant ces fichiers fonctionne comme un graphe de connaissances léger que tout agent peut lire. Il n’a besoin d’aucun SDK, d’aucune base de données et ne crée aucun lien de dépendance. Un sceptique pourrait s’attendre à une autre plateforme présentée sous forme de format, mais il s’agit en réalité simplement de fichiers, et c’est là le point intéressant. Les équipes ajoutent constamment de la complexité aux agents, alors que l’une des questions les plus difficiles est en fait plus simple : où se trouve réellement la connaissance utile ?

Le problème : les agents doivent apprendre sans cesse

Voici le schéma habituel : un agent reçoit une question concernant une métrique, récupère l’intégralité du wiki interne, y insère le texte et en déduit le sens à partir de zéro. Lors de la requête suivante, il fait exactement la même chose. Le texte brut peut être mémorisé en cache, mais personne ne mémorise la compréhension obtenue.

Imaginez un agent qui doit relire à chaque requête un document définissant ce qu’est un utilisateur actif, car cette définition n’a pas de place dédiée et se trouve sur une page Notion située trois dossiers plus loin. Chaque appel est peu coûteux, mais les gaspillages s’accumulent, comme c’est le cas pour de petits gaspillages lorsque personne ne les surveille ; et dans une équipe effectuant quotidiennement les mêmes quelques requêtes, la consommation de tokens devient réelle. Il n’existe pas de chiffre officiel à ce sujet, puisque les personnes extérieures n’ont pas accès aux données internes de Google, mais le problème est familier à la plupart de ceux qui gèrent des agents.

Un cas plus concret : un document d’analyse définit un utilisateur actif comme toute personne ayant effectué au moins une action significative sur le produit au cours d’un mois calendaire. Si l’on demande à un agent combien d’utilisateurs actifs il y avait le mois dernier, deux éléments différents sont nécessaires : les chiffres, ainsi que la définition de ce qu’on entend par « actif » dans ce contexte. Il s’agit de problèmes distincts. La base de données rapporte ce qui s’est produit, tandis qu’une couche de connaissances enregistre ce que l’entreprise entend par cela. OKF vise à rendre cette deuxième partie plus facile à représenter.

La solution réside dans un format, pas dans un modèle plus complexe

OKF est délibérément presque ennuyeusement simple. Un bundle est un dossier contenant des fichiers Markdown, chacun décrivant un concept — qu’il s’agisse d’une table, d’une métrique, d’une API ou d’un guide opérationnel. Chaque fichier commence par un petit bloc YAML, le frontmatter, entre deux lignes de marqueur. Un seul champ est obligatoire :

---
type: Metric   # required – tells the agent what kind of concept this is
---

Cinq champs optionnels viennent compléter ce formulaire, listés ici avec leur fonction :

| Field         | Purpose                      |
| ------------- | ---------------------------- |
| `title`       | Human-readable name          |
| `description` | Short summary                |
| `resource`    | Link to the underlying asset |
| `tags`        | Keywords for categorization  |

La version 0.2 ajoute des champs optionnels concernant l’origine, la vérification, la fraîcheur, le cycle de vie ainsi que les calculs qui ont été attestés. Vous pouvez ajouter n’importe quelles clés supplémentaires, et il est attendu que les utilisateurs ignorent celles qu’ils ne reconnaissent pas sans que cela ne provoque de problème, ce qui permet d’étendre le format sans endommager l’agent d’autrui. Deux noms de fichiers sont réservés : index.md pour la liste des fichiers d’un répertoire et log.md pour l’historique des modifications, ce qui vous évite d’inventer des conventions déjà définies dans la spécification. La spécification a été lancée sous forme de brouillon v0.1, il est donc normal qu’elle évolue ; vérifiez le répertoire pour obtenir la version actuelle avant de développer quoi que ce soit de sérieux.

Les liens forment le graphe

Puisque les fichiers sont en Markdown pur, les concepts sont reliés par des liens ordinaires [text](autre-fichier.md), et ces liens constituent les arêtes d’un graphe situé dans le dossier, sans base de données supplémentaire. Un fichier de concept valide a cet aspect :

---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---

Revenue is counted after refunds are removed.

See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)

Un agent qui lit revenue.md apprend qu’un concept connexe se trouve dans customer_acquisition_cost.md. La signification du lien provient toujours de celui qui a écrit les fichiers, car le format ne prétend pas la comprendre à votre place.

Essayer en cinq minutes

La spécification est fournie avec des exemples réels composés de données de e-commerce GA4, de données de Stack Overflow et de la blockchain Bitcoin. Un agent de référence qui parcourt les ensembles de données de BigQuery et rédige automatiquement des documents OKF les a générés, et tout est stocké dans un seul répertoire Apache 2.0 :

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF

Chaque ensemble d’échantillons comprend un fichier viz.html. Ouvrez-le dans n’importe quel navigateur pour obtenir un graphique interactif de l’ensemble, avec des nœuds, des liens, des outils de recherche et des filtres, sans nécessiter de backend ni de serveur. Une précaution à prendre : générer un viz.html pour votre propre ensemble signifie exécuter l’outil de référence Python présent dans le répertoire. Cet outil transforme l’ensemble en une seule page HTML autonome basée sur Cytoscape.js et marked.js, toujours sans backend, il ne s’agit que d’un fichier que vous pouvez envoyer par e-mail à un collègue.

Avantages

• Costs réduits : la définition est écrite une seule fois et lue directement, ce qui vous évite de devoir la recalculer cinquante fois par jour.
• Chargement plus rapide : il s’agit de texte brut sur le disque, sans nécessité de communication réseau vers un service de connaissances ni d’étape d’incorporation avant utilisation.
• Portabilité réelle : clonez le dépôt, copiez le dossier ou placez-le dans une image Docker, et il fonctionnera de la même manière sur GCP, Azure, AWS ou sur un ordinateur portable. Rien ne vous oblige à rester prisonnier d’un environnement spécifique.
• Contrôle de version gratuit : les bundles sont stockés dans Git, ce qui permet l’utilisation de pull requests, de diffs, d’analyses de responsabilités et d’avis, transformant ainsi la gestion des connaissances en une tâche d’ingénierie ordinaire.
• Une seule source pour les personnes et les agents : un nouvel employé et un agent de garde ouvrent le même fichier, de sorte que le wiki ne peut pas affirmer une chose tandis que l’agent en croit une autre.
• Échange entre équipes et organisations : un fournisseur peut livrer un catalogue sous forme de bundle OKF que votre agent peut consommer directement, sans aucun travail d’intégration.

La possibilité de faire des revues constitue un avantage supplémentaire. Supposons qu’un agent propose ce changement :

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

C’est un simple diff Git, et l’examinateur voit précisément ce qui a changé. C’est bien plus facile à évaluer qu’une mise à jour silencieuse enfouie dans un système de connaissances propriétaire.

Ses limites

• Il ne corrige pas les définitions erronées. OKF standardise le conteneur et non son contenu ; donc si une équipe ne parvient pas à s’accorder sur la signification de « utilisateur actif », un fichier Markdown ne pourra pas forcer cet accord.
• Quelqu’un doit en assurer la maintenance. Les fichiers deviennent obsolètes, et les champs timestamp ainsi que le fichier log.md ne sont utiles que si des personnes ou des agents les mettent à jour. Des connaissances dépassées peuvent causer plus de dommages qu’aucune connaissance du tout, car les agents croient tout ce qu’ils trouvent.
• Il s’agit d’un projet en phase de développement, explicitement inachevé ; par conséquent, les champs et les conventions peuvent évoluer, et ceux qui l’adoptent tôt doivent s’attendre à des changements fréquents.
• La signification n’est pas imposée. Un lien indique que deux concepts sont liés, mais pas comment, et cette relation est décrite dans du texte, ce qui est flexible mais aussi flou. Les relations à typage strict exigent néanmoins une véritable base de données graphique.
• Peu d’adoptants pour l’instant. Presque tous les producteurs et consommateurs au lancement venaient de Google, et le format ne pourra réussir que si d’autres outils et équipes l’adoptent.

OKF aux côtés de RAG et MCP

Rien dans la pile actuelle n’est éliminé, car OKF s’insère en dessous. Lorsqu’une requête arrive, RAG trouve toujours des passages pertinents, et OKF lui fournit un texte plus propre et pré-structuré, ce qui rend les embeddings plus précis et moins coûteux à générer. MCP, le Model Context Protocol d’Anthropic, transporte le contexte au cours d’une conversation, et OKF peut se trouver en dessous en tant que source à laquelle ces outils se réfèrent. MCP gère le flux tandis qu’OKF conserve les définitions, afin que personne n’ait à les recalculer à chaque fois. Les trois couches se présentent ainsi :

OKF
↓
"What does this concept mean?"

RAG
↓
"Which pieces of knowledge should I retrieve?"

MCP
↓
"How does the agent interact with the tools and context?"

Chaque couche résout un problème différent, il est donc plus judicieux de considérer OKF comme une couche de connaissances partagée sous les deux plutôt que comme un concurrent. Les fichiers Markdown ne ressemblent guère à un lancement de produit, pourtant parfois c’est l’option la plus simple qui fonctionne.

Faut-il l’utiliser ?

Pour tout agent capable de répondre à des questions sur vos données, métriques ou systèmes, la réponse est oui : essayez-le. Essayer coûte presque rien : écrivez trois fichiers, reliez-les, indiquez à l’agent le dossier concerné, et une après-midi vous permettra de savoir s’il est utile. Si vos connaissances se trouvent dans l’esprit d’une seule personne ou dans un wiki désorganisé, OKF offre un endroit simple et versionnable pour les consigner enfin, ce qui peut être utile, qu’il y ait ou non un agent. Si vous avez besoin de schémas stricts, de relations typées ou d’une gouvernance rigoureuse, il est actuellement trop souple, alors conservez votre catalogue et exportez peut-être un ensemble de fichiers plus tard.

Ne commencez pas par l’ensemble de la base de connaissances de l’entreprise. Choisissez un petit domaine, par exemple :

metrics/
  active-user.md
  revenue.md
  conversion-rate.md

systems/
  payments-api.md
  orders-api.md

runbooks/
  payment-failure.md

Associez les fichiers, remettez-les à un seul agent et mesurez les changements. C’est une expérience bien meilleure que de passer trois mois à concevoir une plateforme OKF d’entreprise avant de prouver qu’elle est nécessaire.

Un seul champ obligatoire et un dossier contenant du Markdown ne suffiront pas à résoudre seuls les problèmes de documentation de mauvaise qualité. Ce qu’ils offrent, c’est un espace partagé, simple et portable pour la bonne documentation que l’équipe possède déjà, ce qui vaut bien plus que ce que l’on pourrait en déduire sur papier.