fix: align A2UI schema with v0.9 spec, improve path binding prompts (CopilotKit#3929)

## Summary
- Replace custom `{ name, props }` schema format with A2UI v0.9
spec-aligned inline catalog format (`allOf` + `properties`) — eliminates
LLM "props" nesting confusion
- Restructure generation prompts: inline literal values are the default,
path binding is a narrow schema-driven exception
- Bump `@ag-ui/a2ui-middleware` to `0.0.5` in runtime

## Context
LLMs generating dynamic A2UI sometimes produced invalid output:
1. Nesting properties under a `"props"` key (because our schema used
`props` as a key)
2. Using `{ "path": "..." }` bindings on properties that only accept
literal values (e.g. chart `data`, metric `value`)

Both issues caused silent render failures or runtime crashes.

## Test plan
- [x] Tested with ag-ui dojo — A2UI dynamic schema demo works
- [x] Tested with CopilotKit langgraph-starter — sales dashboard renders
correctly
- [x] `@ag-ui/a2ui-middleware@0.0.5` published to npm

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: mme

examples/integrations/langgraph-python/apps/app/package.json

@@ -8,11 +8,11 @@
     "start": "next start"
   },
   "dependencies": {
-    "@copilotkit/a2ui-renderer": "1.55.2",
-    "@copilotkit/react-core": "1.55.2",
-    "@copilotkit/react-ui": "1.55.2",
-    "@copilotkit/runtime": "1.55.2",
-    "@copilotkit/shared": "1.55.2",
+    "@copilotkit/a2ui-renderer": "https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/a2ui-renderer@cfeb1c68c43e1c0fc00bcef91ea48b065668218b",
+    "@copilotkit/react-core": "https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-core@cfeb1c68c43e1c0fc00bcef91ea48b065668218b",
+    "@copilotkit/react-ui": "https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/react-ui@cfeb1c68c43e1c0fc00bcef91ea48b065668218b",
+    "@copilotkit/runtime": "https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/runtime@cfeb1c68c43e1c0fc00bcef91ea48b065668218b",
+    "@copilotkit/shared": "https://pkg.pr.new/CopilotKit/CopilotKit/@copilotkit/shared@cfeb1c68c43e1c0fc00bcef91ea48b065668218b",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-separator": "^1.1.8",

examples/integrations/langgraph-python/pnpm-lock.yaml

@@ -11,7 +11,7 @@ const BASIC_CATALOG_ID =
  * a frontend-provided schema with a server-side one.
  */
 export const A2UI_SCHEMA_CONTEXT_DESCRIPTION =
-  "A2UI Component Schema — available components for generating UI surfaces. Use these component names and props when creating A2UI operations.";
+  "A2UI Component Schema — available components for generating UI surfaces. Use these component names and properties when creating A2UI operations.";
 
 /**
  * Check whether a catalog is a superset of the basic catalog
@@ -85,28 +85,54 @@ export function buildCatalogContextValue(
 }
 
 /**
- * Extract component schemas from a catalog in the same format used by
- * the A2UI middleware (`A2UIComponentSchema[]`). Each component's Zod
- * schema is converted to JSON Schema via zod-to-json-schema.
+ * A2UI v0.9 inline catalog format — matches the structure defined by the
+ * A2UI specification (basic_catalog.json).  Each component is keyed by
+ * name and uses `allOf` to compose ComponentCommon with component-specific
+ * properties so the schema mirrors the flat wire format the LLM must produce.
+ */
+export interface InlineCatalogSchema {
+  catalogId: string;
+  components: Record<string, Record<string, unknown>>;
+}
+
+/**
+ * Extract component schemas from a catalog in the A2UI v0.9 inline catalog
+ * format.  This mirrors `generateInlineCatalog` from `@a2ui/web_core` so
+ * the schema the LLM sees matches the spec and the flat wire format:
+ *
+ *   { "Column": { "allOf": [
+ *       { "$ref": "common_types.json#/$defs/ComponentCommon" },
+ *       { "properties": { "component": {"const":"Column"}, "gap": ..., "children": ... },
+ *         "required": ["component"] }
+ *   ]}}
  *
  * When sent via `useAgentContext` with `A2UI_SCHEMA_CONTEXT_DESCRIPTION`,
  * the middleware can optionally overwrite it with a server-side schema.
  */
 export function extractCatalogComponentSchemas(
   catalog?: Catalog<ComponentApi>,
-): Array<{ name: string; props: Record<string, unknown> }> {
+): InlineCatalogSchema {
   const resolved = catalog ?? basicCatalog;
-  const schemas: Array<{ name: string; props: Record<string, unknown> }> = [];
+  const components: Record<string, Record<string, unknown>> = {};
 
   for (const [name, comp] of resolved.components) {
-    schemas.push({
-      name,
-      props: zodToJsonSchema(comp.schema, { target: "openApi3" }) as Record<
-        string,
-        unknown
-      >,
-    });
+    const zodSchema = zodToJsonSchema(comp.schema, {
+      target: "jsonSchema2019-09",
+    }) as { properties?: Record<string, unknown>; required?: string[] };
+
+    components[name] = {
+      allOf: [
+        { $ref: "common_types.json#/$defs/ComponentCommon" },
+        {
+          properties: {
+            component: { const: name },
+            ...(zodSchema.properties ?? {}),
+          },
+          required: ["component", ...(zodSchema.required ?? [])],
+        },
+      ],
+    };
   }
 
-  return schemas;
+  return { catalogId: resolved.id, components };
 }

packages/a2ui-renderer/src/react-renderer/catalog-utils.ts

@@ -34,6 +34,7 @@ export {
   buildCatalogContextValue,
   extractCatalogComponentSchemas,
 } from "./catalog-utils";
+export type { InlineCatalogSchema } from "./catalog-utils";
 
 // Catalog creation — new API (definitions + renderers)
 export { createCatalog, extractSchema } from "./create-catalog";

packages/a2ui-renderer/src/react-renderer/index.ts

@@ -88,7 +88,7 @@
     "attw": "attw --pack . --profile node16"
   },
   "dependencies": {
-    "@ag-ui/a2ui-middleware": "0.0.4",
+    "@ag-ui/a2ui-middleware": "0.0.5",
     "@ag-ui/client": "0.0.52",
     "@ag-ui/core": "0.0.52",
     "@ag-ui/encoder": "0.0.52",

packages/runtime/package.json

@@ -47,29 +47,38 @@ CRITICAL: Do NOT use "/name" (absolute) inside templates — use "name" (relativ
 The container's path ("/items") uses a leading slash (absolute), but all
 components INSIDE the template use paths WITHOUT leading slash.
 
-DATA MODEL:
-The "data" key in the tool args is a plain JSON object that initializes the surface
-data model. Components bound to paths (e.g. "value": { "path": "/form/name" })
-read from and write to this data model. Examples:
-  For forms:  "data": { "form": { "name": "Alice", "email": "" } }
-  For lists:  "data": { "items": [{"name": "Product A"}, {"name": "Product B"}] }
-  For mixed:  "data": { "form": { "query": "" }, "results": [...] }
+COMPONENT VALUES — DEFAULT RULE:
+Use inline literal values for ALL component properties. Pass strings, numbers,
+arrays, and objects directly on the component. Do NOT use { "path": "..." }
+objects unless the property's schema explicitly allows it (see exception below).
+CRITICAL: USING { "path": "..." } ON A PROPERTY THAT DOES NOT DECLARE PATH
+SUPPORT IN ITS SCHEMA WILL CAUSE A RUNTIME CRASH AND BREAK THE ENTIRE UI.
+ALWAYS CHECK THE COMPONENT SCHEMA FIRST — IF THE PROPERTY ONLY ACCEPTS A
+PLAIN TYPE, YOU MUST USE A LITERAL VALUE.
+VERY IMPORTANT: THE APPLICATION WILL BREAK IF YOU DO NOT FOLLOW THIS RULE!
 
-FORMS AND TWO-WAY DATA BINDING:
-To create editable forms, bind input components to data model paths using { "path": "..." }.
-The client automatically writes user input back to the data model at the bound path.
-CRITICAL: Using a literal value (e.g. "value": "") makes the field READ-ONLY.
-You MUST use { "path": "..." } to make inputs editable.
+For example, a chart's "data" must always be an inline array:
+  "data": [{"label": "Jan", "value": 100}, {"label": "Feb", "value": 200}]
+A metric's "value" must always be an inline string:
+  "value": "$1,200"
 
-Input components use "value" as the binding property:
-  "value": { "path": "/form/fieldName" }
+PATH BINDING EXCEPTION — SCHEMA-DRIVEN:
+A few properties accept { "path": "/some/path" } as an alternative to a literal
+value. You can identify these in the Available Components schema: the property
+will list BOTH a literal type AND an object-with-path option. If a property only
+shows a single type (string, number, array, etc.), it does NOT support path
+binding — use a literal value only.
 
-To retrieve form values when a button is clicked, include "context" with path references
-in the button's action. Paths are resolved to their current values at click time:
-  "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } }
+Path binding is typically used for editable form inputs so the client can write
+user input back to the data model. When building forms:
+- Bind input "value" to a data model path: "value": { "path": "/form/name" }
+- Pre-fill via the "data" tool argument: "data": { "form": { "name": "Alice" } }
+- Capture values on submit via button action context:
+    "action": { "event": { "name": "submit", "context": { "name": { "path": "/form/name" } } } }
 
-To pre-fill form values, pass initial data via the "data" tool argument:
-  "data": { "form": { "name": "Markus" } }`;
+REPEATING CONTENT uses a structural children format (not the same as value binding):
+  children: { componentId: "card-id", path: "/items" }
+Components inside templates use RELATIVE paths (no leading slash): { "path": "name" }.`;
 
 /**
  * Design guidelines — visual design rules, component hierarchy tips,
@@ -94,8 +103,8 @@ Design principles:
     "action": { "event": { "name": "myAction", "context": { "key": "value" } } }
   The "event" key holds an OBJECT with "name" (required) and "context" (optional).
   Do NOT use a flat format like {"event": "name"} — "event" must be an object.
-- For forms: every input MUST use path binding on the "value" property
-  (e.g. "value": { "path": "/form/name" }) to be editable. The submit button's
-  action context MUST reference the same paths to capture the user's input.
+- For forms: check the component schema — if an input's "value" property
+  supports path binding, use it for editable fields. The submit button's
+  action context should reference the same paths to capture user input.
 
 Use the SAME surfaceId as the main surface. Match action names to button action event names.`;

packages/shared/src/a2ui-prompts.ts

@@ -133,45 +133,38 @@ def render(
 components INSIDE the template card use paths WITHOUT leading slash.
 Do NOT use "/items/0/name" or "/items/{@key}/name" — just "name".
 
-DATA MODEL:
-The "data" key in the tool args is a plain JSON object that initializes the surface
-data model. Components bound to paths (e.g. "value": { "path": "/form/name" })
-read from and write to this data model. Examples:
-  For forms:  "data": { "form": { "name": "Alice", "email": "" } }
-  For lists:  "data": { "items": [{"name": "Product A"}, {"name": "Product B"}] }
-  For mixed:  "data": { "form": { "query": "" }, "results": [...] }
-
-FORMS AND TWO-WAY DATA BINDING:
-To create editable forms, bind input components to data model paths using { "path": "..." }.
-The client automatically writes user input back to the data model at the bound path.
-CRITICAL: Using a literal value (e.g. "value": "") makes the field READ-ONLY.
-You MUST use { "path": "..." } to make inputs editable.
-
-All input components use "value" as the binding property:
-- TextField:     "value": { "path": "/form/fieldName" }
-- CheckBox:      "value": { "path": "/form/isChecked" }
-- Slider:        "value": { "path": "/form/sliderVal" }
-- DateTimeInput: "value": { "path": "/form/date" }
-- ChoicePicker:  "value": { "path": "/form/choices" }
-
-To retrieve form values when a button is clicked, include "context" with path references
-in the button's action. Paths are resolved to their current values at click time:
-  "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } }
-
-To pre-fill form values, pass initial data via the "data" tool argument:
-  "data": { "form": { "name": "Markus" } }
-
-FORM EXAMPLE (editable text field with pre-filled value + submit button):
-  "components": [
-    { "id": "root", "component": "Card", "child": "form-col" },
-    { "id": "form-col", "component": "Column", "children": ["name-field", "submit-row"] },
-    { "id": "name-field", "component": "TextField", "label": "Name", "value": { "path": "/form/name" } },
-    { "id": "submit-row", "component": "Row", "justify": "end", "children": ["submit-btn"] },
-    { "id": "submit-btn", "component": "Button", "child": "btn-text", "variant": "primary",
-      "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } } },
-    { "id": "btn-text", "component": "Text", "text": "Submit" }
-  ],
-  "data": { "form": { "name": "Markus" } }"""
+COMPONENT VALUES — DEFAULT RULE:
+Use inline literal values for ALL component properties. Pass strings, numbers,
+arrays, and objects directly on the component. Do NOT use { "path": "..." }
+objects unless the property's schema explicitly allows it (see exception below).
+CRITICAL: USING { "path": "..." } ON A PROPERTY THAT DOES NOT DECLARE PATH
+SUPPORT IN ITS SCHEMA WILL CAUSE A RUNTIME CRASH AND BREAK THE ENTIRE UI.
+ALWAYS CHECK THE COMPONENT SCHEMA FIRST — IF THE PROPERTY ONLY ACCEPTS A
+PLAIN TYPE, YOU MUST USE A LITERAL VALUE.
+VERY IMPORTANT: THE APPLICATION WILL BREAK IF YOU DO NOT FOLLOW THIS RULE!
+
+For example, a chart's "data" must always be an inline array:
+  "data": [{"label": "Jan", "value": 100}, {"label": "Feb", "value": 200}]
+A metric's "value" must always be an inline string:
+  "value": "$1,200"
+
+PATH BINDING EXCEPTION — SCHEMA-DRIVEN:
+A few properties accept { "path": "/some/path" } as an alternative to a literal
+value. You can identify these in the Available Components schema: the property
+will list BOTH a literal type AND an object-with-path option. If a property only
+shows a single type (string, number, array, etc.), it does NOT support path
+binding — use a literal value only.
+
+Path binding is typically used for editable form inputs so the client can write
+user input back to the data model. When building forms:
+- Bind input "value" to a data model path: "value": { "path": "/form/name" }
+- Pre-fill via the "data" tool argument: "data": { "form": { "name": "Alice" } }
+- Capture values on submit via button action context:
+    "action": { "event": { "name": "submit", "context": { "name": { "path": "/form/name" } } } }
+
+REPEATING CONTENT uses a structural children format (not the same as value binding):
+  children: { componentId: "card-id", path: "/items" }
+Components inside templates use RELATIVE paths (no leading slash): { "path": "name" }."""
 
 DEFAULT_DESIGN_GUIDELINES = """\
 Create polished, visually appealing interfaces: