Skip to main content

BlogA2UI v1.0 · Markdown · JSON

The agent door

This site is written for two readers. People read the pages; agents receive the same articles in formats made for them, generated from the same source every time the site is built.

  • One source: each article is a single Markdown file. The page, its Markdown twin, its A2UI surface and its catalogue entry are all built from it.
  • No gap between versions: when an article is corrected, every format is corrected in the same build.
  • No model at request time: these files are static. Nothing is generated by a language model when you fetch them.

Four ways in

Pick the format that matches the task: reading an article, showing it to someone, choosing among articles or following new ones.

To read an article

Markdown twin

/en/blog/<slug>.md

The article as it was written, with its metadata at the top. Each diagram is replaced by its title, its long description and its caption: the information stays, the SVG markup goes.

The address of the page returns the same Markdown to a request sent with the header Accept: text/markdown.

To show an article

A2UI surface

/en/blog/<slug>.a2ui.json/en/blog/a2ui.json

A card that an agent can put in front of its user: title, standfirst, reading time, sources, key answers and links. It uses the basic catalogue only, so any A2UI v1.0 client renders it with its own components.

The blog index has its own surface: a list of articles fed by the data model.

To choose among articles

JSON catalogue

/en/blog/index.json

Every published article with its reading time, its number of sources and diagrams, its topics, the answers to its frequent questions and the addresses of its other formats.

To follow new articles

Feeds

/en/feed.json/en/rss.xml

JSON Feed 1.1 and RSS. Each JSON Feed entry carries its summary and the address of its Markdown twin.

The French edition uses the same addresses without the /en prefix. For language models, the site also keeps an index and the whole blog as a single text file: /llms.txt /en/llms-full.txt. Lire en français.

See a surface rendered

The card below is not written into this page. It is the A2UI file of the latest article, fetched the way an agent fetches it and drawn by the site’s own renderer. The message it contains is shown next to it.

What the site’s renderer covers

The renderer implements A2UI v1.0 with the basic catalogue, which is enough for every surface published here and for the tailored briefing on the blog.

  • Messages: createSurface, updateComponents, updateDataModel and deleteSurface, plus the action message sent back to the agent.
  • Components: the 18 components of the basic catalogue.
  • Data: absolute and relative bindings, list templates, two-way binding on inputs and validation checks.
  • Functions: formatString and its interpolation, formatNumber, formatCurrency, formatDate, pluralize, the validation functions, openUrl and @index.
  • Not covered: callRendererFunction, agentFunctionResponse and the filterable option of ChoicePicker.

The briefing agent on the blog is a set of written rules that runs in the visitor’s browser. It calls no language model and sends nothing to a server.

House rules

These files follow a few fixed rules, so an agent can rely on them without reading this page twice.

  • Open reading: Markdown twins, A2UI surfaces, the catalogue and the JSON feed are served with Access-Control-Allow-Origin: *.
  • One canonical address: each twin names its page in a Link header carrying rel="canonical". Cite the page, not the twin.
  • Freshness: responses may be cached for one hour, then must be revalidated.
  • Drafts: an unpublished article has no twin, no surface and no catalogue entry.
  • Attribution: the content may be quoted and summarised provided the source is correctly attributed to its canonical address and its meaning is not distorted, as stated in llms.txt.

A2UI is a protocol in which an agent describes an interface as JSON messages and the client renders it with its own components. Specification v1.0, marked as the current version on a2ui.org, read on 11 November 2026. Read the A2UI v1.0 specification.