docs(showcase): a2ui-fixed-schema backend siblings across 6 frameworks

samjulien · samjulien · commit afe66be2fbca · 2026-04-29T13:25:34.000-07:00
The shell-docs `/generative-ui/a2ui/fixed-schema` page references the
regions `backend-schema-json-load` and `backend-render-operations` to
teach how the backend loads (or inlines) the A2UI schema and emits
render operations. 5 frameworks (ag2, agno, claude-sdk-python,
claude-sdk-typescript, langroid) ship working schema-loading demos but
hadn't tagged those region markers, so cells rendered a yellow
"missing snippet" box. built-in-agent has the same issue with its
schema-inline variant.

Per the established sibling convention (matching
`tool-rendering/render-flight-tool.snippet.tsx`), each framework now
ships a docs-only `a2ui-backend.snippet.{py,ts}` exposing both regions
with the canonical pattern. Zero changes to the actual demo source.

Files:
- 4 × `.snippet.py` (Python backends): ag2, agno, claude-sdk-python, langroid
- 1 × `.snippet.ts` (TypeScript backend, schema-loading): claude-sdk-typescript
- 1 × `.snippet.ts` (TypeScript backend, schema-inline): built-in-agent

Closes 12 B-docs-gap region refs (6 frameworks × 2 regions).
diff --git a/showcase/integrations/ag2/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py b/showcase/integrations/ag2/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py
@@ -0,0 +1,65 @@
+# Docs-only snippet — not imported or run. The shell-docs page at
+# `/generative-ui/a2ui/fixed-schema` references the regions
+# `backend-schema-json-load` and `backend-render-operations` to teach
+# the schema-loading pattern. This file exposes those regions as
+# canonical teaching code so the docs render real samples instead of a
+# missing-snippet box. The actual demo backend already loads the schema
+# and emits operations end-to-end; this sibling just isolates the two
+# teaching lines.
+#
+# Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+from pathlib import Path
+import json
+
+_SCHEMAS_DIR = Path(__file__).parent / "a2ui_schemas"
+
+# Stand-in for the real a2ui SDK helpers. In a real backend, import
+# `a2ui` from your runtime SDK; the calls below match its shape.
+class _A2UI:
+    @staticmethod
+    def load_schema(path):
+        with open(path) as fh:
+            return json.load(fh)
+    @staticmethod
+    def create_surface(*args, **kwargs): ...
+    @staticmethod
+    def update_components(*args, **kwargs): ...
+    @staticmethod
+    def update_data_model(*args, **kwargs): ...
+    @staticmethod
+    def render(*args, **kwargs): ...
+a2ui = _A2UI()
+SURFACE_ID = "flight-fixed-schema"
+CATALOG_ID = "flight-catalog"
+
+
+# @region[backend-schema-json-load]
+# Schemas are JSON so they can be authored and reviewed independently of
+# the backend code. `a2ui.load_schema` is just a thin `json.load` wrapper
+# that resolves the path against the schemas directory.
+FLIGHT_SCHEMA = a2ui.load_schema(_SCHEMAS_DIR / "flight_schema.json")
+# @endregion[backend-schema-json-load]
+
+
+def emit_render_operations(origin: str, destination: str, airline: str, price: float):
+    # @region[backend-render-operations]
+    # The a2ui middleware detects the `a2ui_operations` container in this
+    # tool result and forwards the ops to the frontend renderer. The
+    # frontend catalog resolves component names to local React components.
+    return a2ui.render(
+        operations=[
+            a2ui.create_surface(SURFACE_ID, catalog_id=CATALOG_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(
+                SURFACE_ID,
+                {
+                    "origin": origin,
+                    "destination": destination,
+                    "airline": airline,
+                    "price": price,
+                },
+            ),
+        ],
+    )
+    # @endregion[backend-render-operations]
diff --git a/showcase/integrations/agno/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py b/showcase/integrations/agno/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py
@@ -0,0 +1,65 @@
+# Docs-only snippet — not imported or run. The shell-docs page at
+# `/generative-ui/a2ui/fixed-schema` references the regions
+# `backend-schema-json-load` and `backend-render-operations` to teach
+# the schema-loading pattern. This file exposes those regions as
+# canonical teaching code so the docs render real samples instead of a
+# missing-snippet box. The actual demo backend already loads the schema
+# and emits operations end-to-end; this sibling just isolates the two
+# teaching lines.
+#
+# Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+from pathlib import Path
+import json
+
+_SCHEMAS_DIR = Path(__file__).parent / "a2ui_schemas"
+
+# Stand-in for the real a2ui SDK helpers. In a real backend, import
+# `a2ui` from your runtime SDK; the calls below match its shape.
+class _A2UI:
+    @staticmethod
+    def load_schema(path):
+        with open(path) as fh:
+            return json.load(fh)
+    @staticmethod
+    def create_surface(*args, **kwargs): ...
+    @staticmethod
+    def update_components(*args, **kwargs): ...
+    @staticmethod
+    def update_data_model(*args, **kwargs): ...
+    @staticmethod
+    def render(*args, **kwargs): ...
+a2ui = _A2UI()
+SURFACE_ID = "flight-fixed-schema"
+CATALOG_ID = "flight-catalog"
+
+
+# @region[backend-schema-json-load]
+# Schemas are JSON so they can be authored and reviewed independently of
+# the backend code. `a2ui.load_schema` is just a thin `json.load` wrapper
+# that resolves the path against the schemas directory.
+FLIGHT_SCHEMA = a2ui.load_schema(_SCHEMAS_DIR / "flight_schema.json")
+# @endregion[backend-schema-json-load]
+
+
+def emit_render_operations(origin: str, destination: str, airline: str, price: float):
+    # @region[backend-render-operations]
+    # The a2ui middleware detects the `a2ui_operations` container in this
+    # tool result and forwards the ops to the frontend renderer. The
+    # frontend catalog resolves component names to local React components.
+    return a2ui.render(
+        operations=[
+            a2ui.create_surface(SURFACE_ID, catalog_id=CATALOG_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(
+                SURFACE_ID,
+                {
+                    "origin": origin,
+                    "destination": destination,
+                    "airline": airline,
+                    "price": price,
+                },
+            ),
+        ],
+    )
+    # @endregion[backend-render-operations]
diff --git a/showcase/integrations/built-in-agent/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts b/showcase/integrations/built-in-agent/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts
@@ -0,0 +1,65 @@
+// Docs-only snippet — not imported or run. The shell-docs page at
+// `/generative-ui/a2ui/fixed-schema` references the regions
+// `backend-schema-json-load` and `backend-render-operations` to teach
+// the *schema-inline* pattern for built-in-agent (the schema is declared
+// as a typed literal in source rather than loaded from JSON at startup).
+// This file exposes those regions as canonical teaching code so the docs
+// render real samples instead of a missing-snippet box.
+//
+// Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+declare const a2ui: {
+  createSurface: (id: string, opts: { catalogId: string }) => unknown;
+  updateComponents: (id: string, schema: unknown) => unknown;
+  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
+  render: (args: { operations: unknown[] }) => unknown;
+};
+const SURFACE_ID = "flight-fixed-schema";
+const CATALOG_ID = "flight-catalog";
+
+// @region[backend-schema-json-load]
+// In the schema-inline pattern, the schema is declared as a typed literal
+// in source rather than loaded from JSON at startup. Same shape as the
+// schema-loading variant; just no file I/O.
+const FLIGHT_SCHEMA = [
+  {
+    type: "Card",
+    children: [
+      { type: "Title", text: "Flight" },
+      { type: "Row", children: [
+        { type: "Label", bind: "origin" },
+        { type: "Label", bind: "destination" },
+      ]},
+      { type: "Row", children: [
+        { type: "Label", bind: "airline" },
+        { type: "Label", bind: "price" },
+      ]},
+    ],
+  },
+];
+// @endregion[backend-schema-json-load]
+
+export function emitRenderOperations(args: {
+  origin: string;
+  destination: string;
+  airline: string;
+  price: number;
+}) {
+  // @region[backend-render-operations]
+  // The a2ui middleware detects the `a2ui_operations` container in this
+  // tool result and forwards the ops to the frontend renderer. The
+  // frontend catalog resolves component names to local React components.
+  return a2ui.render({
+    operations: [
+      a2ui.createSurface(SURFACE_ID, { catalogId: CATALOG_ID }),
+      a2ui.updateComponents(SURFACE_ID, FLIGHT_SCHEMA),
+      a2ui.updateDataModel(SURFACE_ID, {
+        origin: args.origin,
+        destination: args.destination,
+        airline: args.airline,
+        price: args.price,
+      }),
+    ],
+  });
+  // @endregion[backend-render-operations]
+}
diff --git a/showcase/integrations/claude-sdk-python/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py b/showcase/integrations/claude-sdk-python/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py
@@ -0,0 +1,65 @@
+# Docs-only snippet — not imported or run. The shell-docs page at
+# `/generative-ui/a2ui/fixed-schema` references the regions
+# `backend-schema-json-load` and `backend-render-operations` to teach
+# the schema-loading pattern. This file exposes those regions as
+# canonical teaching code so the docs render real samples instead of a
+# missing-snippet box. The actual demo backend already loads the schema
+# and emits operations end-to-end; this sibling just isolates the two
+# teaching lines.
+#
+# Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+from pathlib import Path
+import json
+
+_SCHEMAS_DIR = Path(__file__).parent / "a2ui_schemas"
+
+# Stand-in for the real a2ui SDK helpers. In a real backend, import
+# `a2ui` from your runtime SDK; the calls below match its shape.
+class _A2UI:
+    @staticmethod
+    def load_schema(path):
+        with open(path) as fh:
+            return json.load(fh)
+    @staticmethod
+    def create_surface(*args, **kwargs): ...
+    @staticmethod
+    def update_components(*args, **kwargs): ...
+    @staticmethod
+    def update_data_model(*args, **kwargs): ...
+    @staticmethod
+    def render(*args, **kwargs): ...
+a2ui = _A2UI()
+SURFACE_ID = "flight-fixed-schema"
+CATALOG_ID = "flight-catalog"
+
+
+# @region[backend-schema-json-load]
+# Schemas are JSON so they can be authored and reviewed independently of
+# the backend code. `a2ui.load_schema` is just a thin `json.load` wrapper
+# that resolves the path against the schemas directory.
+FLIGHT_SCHEMA = a2ui.load_schema(_SCHEMAS_DIR / "flight_schema.json")
+# @endregion[backend-schema-json-load]
+
+
+def emit_render_operations(origin: str, destination: str, airline: str, price: float):
+    # @region[backend-render-operations]
+    # The a2ui middleware detects the `a2ui_operations` container in this
+    # tool result and forwards the ops to the frontend renderer. The
+    # frontend catalog resolves component names to local React components.
+    return a2ui.render(
+        operations=[
+            a2ui.create_surface(SURFACE_ID, catalog_id=CATALOG_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(
+                SURFACE_ID,
+                {
+                    "origin": origin,
+                    "destination": destination,
+                    "airline": airline,
+                    "price": price,
+                },
+            ),
+        ],
+    )
+    # @endregion[backend-render-operations]
diff --git a/showcase/integrations/claude-sdk-typescript/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts b/showcase/integrations/claude-sdk-typescript/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.ts
@@ -0,0 +1,60 @@
+// Docs-only snippet — not imported or run. The shell-docs page at
+// `/generative-ui/a2ui/fixed-schema` references the regions
+// `backend-schema-json-load` and `backend-render-operations` to teach
+// the schema-loading pattern. This file exposes those regions as
+// canonical teaching code so the docs render real samples instead of a
+// missing-snippet box.
+//
+// Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+import path from "path";
+import fs from "fs";
+
+const SCHEMAS_DIR = path.join(__dirname, "a2ui_schemas");
+
+// Stand-in for the real a2ui SDK helpers. In a real backend, import
+// `a2ui` from your runtime SDK.
+declare const a2ui: {
+  loadSchema: (path: string) => unknown;
+  createSurface: (id: string, opts: { catalogId: string }) => unknown;
+  updateComponents: (id: string, schema: unknown) => unknown;
+  updateDataModel: (id: string, data: Record<string, unknown>) => unknown;
+  render: (args: { operations: unknown[] }) => unknown;
+};
+const SURFACE_ID = "flight-fixed-schema";
+const CATALOG_ID = "flight-catalog";
+
+// @region[backend-schema-json-load]
+// Schemas are JSON so they can be authored and reviewed independently of
+// the backend code. `a2ui.loadSchema` is a thin wrapper around
+// `JSON.parse(fs.readFileSync(...))` that resolves the path against the
+// schemas directory.
+const FLIGHT_SCHEMA = a2ui.loadSchema(
+  path.join(SCHEMAS_DIR, "flight_schema.json"),
+);
+// @endregion[backend-schema-json-load]
+
+export function emitRenderOperations(args: {
+  origin: string;
+  destination: string;
+  airline: string;
+  price: number;
+}) {
+  // @region[backend-render-operations]
+  // The a2ui middleware detects the `a2ui_operations` container in this
+  // tool result and forwards the ops to the frontend renderer. The
+  // frontend catalog resolves component names to local React components.
+  return a2ui.render({
+    operations: [
+      a2ui.createSurface(SURFACE_ID, { catalogId: CATALOG_ID }),
+      a2ui.updateComponents(SURFACE_ID, FLIGHT_SCHEMA),
+      a2ui.updateDataModel(SURFACE_ID, {
+        origin: args.origin,
+        destination: args.destination,
+        airline: args.airline,
+        price: args.price,
+      }),
+    ],
+  });
+  // @endregion[backend-render-operations]
+}
diff --git a/showcase/integrations/langroid/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py b/showcase/integrations/langroid/src/app/demos/a2ui-fixed-schema/a2ui-backend.snippet.py
@@ -0,0 +1,65 @@
+# Docs-only snippet — not imported or run. The shell-docs page at
+# `/generative-ui/a2ui/fixed-schema` references the regions
+# `backend-schema-json-load` and `backend-render-operations` to teach
+# the schema-loading pattern. This file exposes those regions as
+# canonical teaching code so the docs render real samples instead of a
+# missing-snippet box. The actual demo backend already loads the schema
+# and emits operations end-to-end; this sibling just isolates the two
+# teaching lines.
+#
+# Mirrors the convention from `tool-rendering/render-flight-tool.snippet.tsx`.
+
+from pathlib import Path
+import json
+
+_SCHEMAS_DIR = Path(__file__).parent / "a2ui_schemas"
+
+# Stand-in for the real a2ui SDK helpers. In a real backend, import
+# `a2ui` from your runtime SDK; the calls below match its shape.
+class _A2UI:
+    @staticmethod
+    def load_schema(path):
+        with open(path) as fh:
+            return json.load(fh)
+    @staticmethod
+    def create_surface(*args, **kwargs): ...
+    @staticmethod
+    def update_components(*args, **kwargs): ...
+    @staticmethod
+    def update_data_model(*args, **kwargs): ...
+    @staticmethod
+    def render(*args, **kwargs): ...
+a2ui = _A2UI()
+SURFACE_ID = "flight-fixed-schema"
+CATALOG_ID = "flight-catalog"
+
+
+# @region[backend-schema-json-load]
+# Schemas are JSON so they can be authored and reviewed independently of
+# the backend code. `a2ui.load_schema` is just a thin `json.load` wrapper
+# that resolves the path against the schemas directory.
+FLIGHT_SCHEMA = a2ui.load_schema(_SCHEMAS_DIR / "flight_schema.json")
+# @endregion[backend-schema-json-load]
+
+
+def emit_render_operations(origin: str, destination: str, airline: str, price: float):
+    # @region[backend-render-operations]
+    # The a2ui middleware detects the `a2ui_operations` container in this
+    # tool result and forwards the ops to the frontend renderer. The
+    # frontend catalog resolves component names to local React components.
+    return a2ui.render(
+        operations=[
+            a2ui.create_surface(SURFACE_ID, catalog_id=CATALOG_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(
+                SURFACE_ID,
+                {
+                    "origin": origin,
+                    "destination": destination,
+                    "airline": airline,
+                    "price": price,
+                },
+            ),
+        ],
+    )
+    # @endregion[backend-render-operations]
