A2UI Architecture

The Core Idea

Agents should not know about React.

An agent reasoning about a clinical trial enrollment decision should produce a reasoning tree — not JSX. A2UI is the contract between what an agent knows and what a user sees. The agent declares intent. The renderer handles presentation.

renderSpec() — the full dispatch layer

// Every renderer starts with a discriminated union switch.
// TypeScript narrows the type at each case — zero casting needed.

function renderSpec(spec: AnySpec): React.ReactNode {
  switch (spec.type) {
    case "nodus:mit-card":       return <RenderMitCard spec={spec} />;
    case "nodus:reasoning-tree": return <RenderReasoningTree spec={spec} />;
    case "nodus:learning-ledger":return <RenderLearningLedger spec={spec} />;
    // … 16 more cases
    default:
      console.warn(`[A2UI] Unknown type: ${spec.type}`);
      return null;
  }
}

Agent output — pure JSON, no UI concern

// Agents emit JSON — no UI code, no React, no imports.
// The renderer picks up on the other side.

const spec = {
  type: "nodus:reasoning-tree",
  id: "patient-eligibility-check",
  question: "Should patient MR-8823 enroll in CRYO-3?",
  conclusion: "Borderline — requires specialist review.",
  confidence: 71,
  steps: [
    { label: "Age within inclusion band", weight: "supporting", confidence: 99 },
    { label: "eGFR below minimum (48 < 60)", weight: "opposing", confidence: 100 },
    { label: "PI waiver clause may apply",  weight: "neutral",   confidence: 62 },
  ],
};

// Pass to any renderer — React, Lit, mobile, terminal
await agent.emit(spec);

Extension pattern — same 3 steps every time

// Adding a new spec type takes 3 steps:

// 1. Interface in types.ts
interface StatusPanelSpec extends A2UIComponent {
  type: "nodus:status-panel";
  services: Array<{ name: string; status: "up" | "degraded" | "down" }>;
}

// 2. Type guard
export const isStatusPanel = (c: A2UIComponent): c is StatusPanelSpec =>
  c.type === "nodus:status-panel";

// 3. Renderer + dispatch case
function RenderStatusPanel({ spec }: { spec: StatusPanelSpec }) { ... }

case "nodus:status-panel": return <RenderStatusPanel spec={spec} />;