fix(langgraph-threads): restore A2UI tool docstrings dropped in compaction rewrite (CopilotKit#4216)

## Summary

The Apr 21 commit
[\`25f6f1541\`](CopilotKit@25f6f1541)
(\"refactor(runtime): Support durable compaction of threads\") re-added
\`a2ui_dynamic_schema.py\` and \`a2ui_fixed_schema.py\` to the
\`langgraph-python-threads\` example (they had been deleted in the
earlier \"fix(examples): Pin version number and simplify example\"
commit). The re-add stripped two docstrings whose content was
load-bearing for the sub-LLM, not cosmetic:

- **\`render_a2ui\`** — its Args block said *\"The root component must
have id 'root'\"*. Without it, the secondary LLM emits a valid flat
component list with no entry point. The A2UI renderer always starts at
\`id=\"root\"\`
([\`A2uiSurface.tsx:152\`](packages/a2ui-renderer/src/react-renderer/a2ui-react/A2uiSurface.tsx)),
falls through to its shimmer placeholder, and the *Sales Dashboard (A2UI
Dynamic)* demo renders as an empty ~30px white square with 13 unused
components queued on the surface.
- **\`search_flights\`** — its Args block spelled out airline logo URLs,
date format, and status-icon colors, keeping flight cards visually
consistent across runs.

## What this PR does

Copies both files verbatim from
\`examples/integrations/langgraph-python/agent/src/\` (the non-threads
example, which is the known-good template). After this PR, \`diff -r\`
between the two examples' \`agent/src/\` dirs is clean.

Verified end-to-end locally against a demo scaffolded from this
template: \"Sales Dashboard (A2UI Dynamic)\" now renders the full
dashboard (title, three metric cards, pie + bar charts) instead of the
shimmer placeholder.

## Notes

- The restore brings back \`[A2UI-DEBUG]\` print statements and the
fuller module headers. If the \`-threads\` version was meant to be
terser than the non-threads version, happy to strip those in a follow-up
— but verbatim parity seemed like the safer default since the two
templates are otherwise meant to match.
- A separate, complementary fix would be to make the \`id: \"root\"\`
requirement explicit in \`A2UI_DEFAULT_GENERATION_GUIDELINES\`
(\`packages/shared/src/a2ui-prompts.ts\` +
\`sdk-python/copilotkit/a2ui.py\`), so the invariant doesn't depend on
per-demo tool docstrings. Not in scope here.

## Test plan

- [x] Run the template locally, click *Sales Dashboard (A2UI Dynamic)*,
confirm the dashboard renders.
- [ ] Sanity-check *Search Flights (A2UI Fixed Schema)* in CI or locally
— should continue to work (this file's behavior is unchanged; only
docstring content differs).
- [ ] Reviewer to decide whether to keep or strip debug prints.

Author: maxkorp

examples/integrations/langgraph-python-threads/apps/agent/src/a2ui_dynamic_schema.py

@@ -1,18 +1,23 @@
 """
 Dynamic A2UI tool: LLM-generated UI from conversation context.
+
+A secondary LLM generates v0.9 A2UI components via a structured tool call.
+The generate_a2ui tool wraps the output as a2ui_operations, which the
+middleware detects in the TOOL_CALL_RESULT and renders automatically.
 """
 
 from __future__ import annotations
 
 import json
 from typing import Any
 
-from copilotkit import a2ui
-from langchain.tools import ToolRuntime, tool
+from langchain.tools import tool, ToolRuntime
 from langchain_core.messages import SystemMessage
 from langchain_core.tools import tool as lc_tool
 from langchain_openai import ChatOpenAI
 
+from copilotkit import a2ui
+
 CUSTOM_CATALOG_ID = "copilotkit://app-dashboard-catalog"
 
 
@@ -23,39 +28,76 @@ def render_a2ui(
     components: list[dict],
     data: dict | None = None,
 ) -> str:
-    """Render a dynamic A2UI v0.9 surface."""
+    """Render a dynamic A2UI v0.9 surface.
+
+    Args:
+        surfaceId: Unique surface identifier.
+        catalogId: The catalog ID (use "copilotkit://app-dashboard-catalog").
+        components: A2UI v0.9 component array (flat format). The root
+            component must have id "root".
+        data: Optional initial data model for the surface (e.g. form values,
+            list items for data-bound components).
+    """
     return "rendered"
 
 
 @tool()
 def generate_a2ui(runtime: ToolRuntime[Any]) -> str:
-    """Generate dynamic A2UI components based on the conversation."""
+    """Generate dynamic A2UI components based on the conversation.
+
+    A secondary LLM designs the UI schema and data. The result is
+    returned as an a2ui_operations container for the middleware to detect.
+    """
+    import time
+    t0 = time.time()
+    print(f"[A2UI-DEBUG] generate_a2ui STARTED at t=0")
+
     messages = runtime.state["messages"][:-1]
+    print(f"[A2UI-DEBUG]   messages count: {len(messages)}")
+
+    # Get context entries from copilotkit state (catalog capabilities + component schema)
     context_entries = runtime.state.get("copilotkit", {}).get("context", [])
     context_text = "\n\n".join(
-        entry.get("value", "")
-        for entry in context_entries
+        entry.get("value", "") for entry in context_entries
         if isinstance(entry, dict) and entry.get("value")
     )
+    print(f"[A2UI-DEBUG]   context entries: {len(context_entries)}, context_text_len: {len(context_text)}")
+
+    prompt = context_text
 
     model = ChatOpenAI(model="gpt-4.1")
-    model_with_tool = model.bind_tools([render_a2ui], tool_choice="render_a2ui")
-    response = model_with_tool.invoke([SystemMessage(content=context_text), *messages])
+    model_with_tool = model.bind_tools(
+        [render_a2ui],
+        tool_choice="render_a2ui",
+    )
+
+    print(f"[A2UI-DEBUG]   calling secondary LLM at t={time.time()-t0:.1f}s")
+    response = model_with_tool.invoke(
+        [SystemMessage(content=prompt), *messages],
+    )
+    print(f"[A2UI-RESPONSE] {response}")
+    print(f"[A2UI-DEBUG]   secondary LLM responded at t={time.time()-t0:.1f}s")
 
     if not response.tool_calls:
+        print(f"[A2UI-DEBUG]   ERROR: no tool calls in response")
         return json.dumps({"error": "LLM did not call render_a2ui"})
 
-    args = response.tool_calls[0]["args"]
+    tool_call = response.tool_calls[0]
+    args = tool_call["args"]
+
     surface_id = args.get("surfaceId", "dynamic-surface")
     catalog_id = args.get("catalogId", CUSTOM_CATALOG_ID)
     components = args.get("components", [])
     data = args.get("data", {})
+    print(f"[A2UI-DEBUG]   components={len(components)} data_keys={list(data.keys()) if data else []} surface={surface_id}")
 
-    operations = [
-      a2ui.create_surface(surface_id, catalog_id=catalog_id),
-      a2ui.update_components(surface_id, components),
+    ops = [
+        a2ui.create_surface(surface_id, catalog_id=catalog_id),
+        a2ui.update_components(surface_id, components),
     ]
     if data:
-        operations.append(a2ui.update_data_model(surface_id, data))
+        ops.append(a2ui.update_data_model(surface_id, data))
 
-    return a2ui.render(operations=operations)
+    result = a2ui.render(operations=ops)
+    print(f"[A2UI-DEBUG] generate_a2ui DONE at t={time.time()-t0:.1f}s result_len={len(result)}")
+    return result

examples/integrations/langgraph-python-threads/apps/agent/src/a2ui_fixed_schema.py

@@ -1,5 +1,7 @@
 """
 Fixed-schema A2UI tool: flight search results.
+
+Schema is loaded from a JSON file. Only the data changes per invocation.
 """
 
 from __future__ import annotations
@@ -37,9 +39,20 @@ class Flight(TypedDict):
 def search_flights(flights: list[Flight]) -> str:
     """Search for flights and display the results as rich cards. Return exactly 2 flights.
 
-    Each flight must have: id, airline, airlineLogo, flightNumber, origin,
-    destination, date, departureTime, arrivalTime, duration, status, statusIcon,
-    and price.
+    Each flight must have: id, airline (e.g. "United Airlines"),
+    airlineLogo (use Google favicon API: https://www.google.com/s2/favicons?domain={airline_domain}&sz=128
+    e.g. "https://www.google.com/s2/favicons?domain=united.com&sz=128" for United,
+    "https://www.google.com/s2/favicons?domain=delta.com&sz=128" for Delta,
+    "https://www.google.com/s2/favicons?domain=aa.com&sz=128" for American,
+    "https://www.google.com/s2/favicons?domain=alaskaair.com&sz=128" for Alaska),
+    flightNumber, origin, destination,
+    date (short readable format like "Tue, Mar 18" — use near-future dates),
+    departureTime, arrivalTime,
+    duration (e.g. "4h 25m"), status (e.g. "On Time" or "Delayed"),
+    statusIcon (colored dot: use "https://placehold.co/12/22c55e/22c55e.png"
+    for On Time, "https://placehold.co/12/eab308/eab308.png" for Delayed,
+    "https://placehold.co/12/ef4444/ef4444.png" for Cancelled),
+    and price (e.g. "$289").
     """
     return a2ui.render(
         operations=[

packages/shared/src/a2ui-prompts.ts

@@ -27,6 +27,11 @@ CRITICAL: You MUST call the render_a2ui tool with ALL of these arguments:
   component names or use names not in the schema.
 
 COMPONENT ID RULES:
+- Exactly one component MUST have id="root". This is the surface's entry
+  point — the renderer begins at "root" and walks the child/children tree
+  from there. Every other component must be reachable from "root". If no
+  component has id="root", the surface renders an empty loading placeholder
+  and none of your components will be shown.
 - Every component ID must be unique within the surface.
 - A component MUST NOT reference itself as child/children. This causes a
   circular dependency error. For example, if a component has id="avatar",

sdk-python/copilotkit/a2ui.py

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