Skip to content

Commit bec1fd0

Browse files
committed
fix(a2ui): document id="root" entry-point requirement in generation guidelines
The A2UI React renderer (packages/a2ui-renderer/src/react-renderer/a2ui-react/A2uiSurface.tsx:152) always begins rendering at the component with id="root": export const A2uiSurface: React.FC<{...}> = ({ surface }) => { // The root component always has ID 'root' and base path '/' return <DeferredChild surface={surface} id="root" basePath="/" />; }; If no component has that ID, DeferredChild falls through to its loading- shimmer placeholder, so the surface silently renders as an empty ~30px rectangle regardless of how many other components are on the surface. The generation guidelines shipped to the sub-LLM (in @copilotkit/shared and copilotkit sdk-python) never stated this requirement. Fixed-schema demos hard-code a component with id="root" in their JSON and work; dynamic demos relied on the LLM guessing, which it sometimes did and sometimes didn't. The failure mode is particularly nasty: no error, no warning, just a loading spinner that never resolves. Adds the requirement to COMPONENT ID RULES in both the TS and Python guideline strings. Both strings are injected into the sub-LLM's context by A2UICatalogContext (packages/react-core) and copilotkit.a2ui.a2ui_prompt() respectively, so every A2UI-enabled app picks it up automatically — no per-demo change needed. Stacked on CopilotKit#4216, which restores the same instruction to the langgraph-python-threads demo's tool docstring (belt-and-braces until consumers update their shared package version).
1 parent be835b0 commit bec1fd0

2 files changed

Lines changed: 10 additions & 0 deletions

File tree

packages/shared/src/a2ui-prompts.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,11 @@ CRITICAL: You MUST call the render_a2ui tool with ALL of these arguments:
2727
component names or use names not in the schema.
2828
2929
COMPONENT ID RULES:
30+
- Exactly one component MUST have id="root". This is the surface's entry
31+
point — the renderer begins at "root" and walks the child/children tree
32+
from there. Every other component must be reachable from "root". If no
33+
component has id="root", the surface renders an empty loading placeholder
34+
and none of your components will be shown.
3035
- Every component ID must be unique within the surface.
3136
- A component MUST NOT reference itself as child/children. This causes a
3237
circular dependency error. For example, if a component has id="avatar",

sdk-python/copilotkit/a2ui.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,11 @@ def render(
117117
- every component must have the "component" field specifying the component type (e.g. "Text", "Image", "Row", "Column", "List", "Button", etc.)
118118
119119
COMPONENT ID RULES:
120+
- Exactly one component MUST have id="root". This is the surface's entry
121+
point — the renderer begins at "root" and walks the child/children tree
122+
from there. Every other component must be reachable from "root". If no
123+
component has id="root", the surface renders an empty loading placeholder
124+
and none of your components will be shown.
120125
- Every component ID must be unique within the surface.
121126
- A component MUST NOT reference itself as child/children. This causes a
122127
circular dependency error. For example, if a component has id="avatar",

0 commit comments

Comments
 (0)