A2UI vs. Open-JSON-UI: Bridging the Gap

Working with Agentic User Interfaces you will realize that there is a fundamental tension between Developer Precision and Agent Efficiency.

• Developers want explicit control, predictable rendering, and debuggable UI trees.
• Agents (LLMs) need simple, token-efficient schemas that they can emit reliably under structured output constraints.

A2UI and Open-JSON-UI sit on opposite ends of this spectrum. This article explains how they differ, why neither is sufficient on its own, and how SimpleA2UI bridges the gap—without compromising correctness, performance, or UX.

The Core Tension: Precision vs. Efficiency

Agent-generated UIs fail for two common reasons:

1. Too much freedom: Hallucinated layouts, broken components.
2. Too much structure: Bloated prompts, high token cost, brittle generation.

A2UI and Open-JSON-UI solve opposite halves of this problem.

The Two Standards

1. A2UI: The Developer-Heavy Protocol

A2UI is a low-level, explicit UI protocol. It is designed to be rendered directly by a client with minimal interpretation.

Key characteristics:

• Deeply nested component trees.
• Explicit layout, state, and rendering boundaries.
• Strong separation between data, layout, and actions.

Pros:

• Maximum expressive power.
• Deterministic rendering.
• Fine-grained control over complex UIs (graphs, dashboards, workflows).
• Ideal for high-stakes or regulated environments.

Cons:

• Verbose and token-heavy.
• Hard for LLMs to generate correctly.
• Requires detailed schema knowledge (e.g., literalString, surfaceUpdate, component IDs).

In practice, A2UI is excellent for rendering—but painful for agents to author directly.

2. Open-JSON-UI: The Agent-Heavy Standard

Open-JSON-UI takes the opposite approach. It is intentionally flattened, content-first, and optimized for LLM structured output (JSON Schema).

Instead of deep trees, it uses:

• screen → content[]
• Top-level properties.
• Minimal nesting.

This aligns with how LLMs naturally emit structured data.

Pros:

• Token-efficient.
• Easy for agents to generate.
• Low failure rate under JSON schema constraints.
• Human-readable and debuggable.

Cons:

• Not directly renderable.
• Limited layout semantics.
• Requires a smart client to interpret intent.
• Lacks explicit UI lifecycle semantics.

Open-JSON-UI is easy to generate—but incomplete as a rendering protocol.

Side-by-Side Comparison

Feature	A2UI (Protocol)	Open-JSON-UI (Standard)
Primary Goal	Precise rendering	Easy generation
Structure	Deep, hierarchical	Flattened, content-first
Verbosity	High	Low
LLM-friendliness	Poor	Excellent
Rendering	Direct	Requires translation
State Model	Explicit	Implicit
Best Used By	Clients & renderers	Agents & planners

The Missing Piece: Translation

On their own:

• A2UI is too rigid for agents.
• Open-JSON-UI is too vague for renderers.

What’s missing is a deterministic translation layer that preserves agent intent, enforces UI correctness, and produces valid A2UI every time. This is where SimpleA2UI comes in.

How SimpleA2UI Bridges the Gap

SimpleA2UI acts as a universal adapter between agent-friendly JSON and a production-grade UI protocol.

• Agents emit Open-JSON-UI v1.
• Clients render A2UI.
• SimpleA2UI connects the two.

The Translation Layer (mapOpenJsonToA2UI)

When an agent emits an Open-JSON-UI payload:

1. Ingestion: SimpleA2UI detects { "type": "screen", "content": [...] }. This signals Open-JSON-UI v1, not A2UI.
2. Inflation: The mapper recursively walks the flattened content[] array and reconstructs a hierarchical UI tree. Flattened intent becomes structured layout.
3. Protocol Generation: The mapper automatically generates valid A2UI messages, including:
   • Wrapping raw strings into literalString.
   • Generating stable, unique component IDs.
   • Creating Column and Row layouts.
   • Expanding high-level constructs: form → TextField + Button, card → container + children.
   • Binding actions to A2UI event semantics.
   • This step is lossless—no UI intent is discarded.
4. Execution: The resulting A2UI payload is passed to the standard surfaceUpdate, beginRendering, and MessageProcessor.

From this point onward, the system behaves exactly like a native A2UI app.

Why This Matters (Practically)

This architecture enables:

• Cheap agents (low token usage).
• Reliable UIs (strict rendering guarantees).
• Clean separation of concerns:
  • Agents decide what.
  • SimpleA2UI decides how.
  • Clients decide where.

You no longer need to choose between agent performance and UI quality. You get both.

Final Takeaway

Think of it this way:

• Open-JSON-UI is how agents think about UI.
• A2UI is how clients render UI.
• SimpleA2UI is the compiler in between.

Together, they form a complete, future-proof pipeline for agent-driven applications—from reasoning to interaction to execution.

This is not a compromise. It’s a layered architecture, done correctly.