fix(showcase/langgraph-python): rename internal A2UI tool so middleware doesn't intercept

The A2UI middleware (`@ag-ui/a2ui-middleware`) defaults `a2uiToolNames` to
`["render_a2ui"]` and synthesises ACTIVITY_SNAPSHOT events from the
streaming tool-call args of any matching call — using the LLM's RAW
catalogId and components verbatim, before the Python tool body has a
chance to validate or normalise.

Both `beautiful_chat.py` and `a2ui_dynamic.py` use a `generate_a2ui` tool
that internally invokes a secondary LLM bound to a structured-output
`render_a2ui` helper. Because the helper's name matched the middleware's
default intercept list, the secondary LLM's hallucinated catalogId
(`declarative-gen-ui-catalog` leaking into the beautiful-chat dashboard)
and malformed root components (no `component` field on KPI dashboard)
were emitted to the frontend bypass, surfacing as:

- "A2UI render error: Catalog not found: declarative-gen-ui-catalog" on
  the beautiful-chat Sales Dashboard pill
- "A2UI render error: Cannot create component root without a type"
  infinite-loop on the declarative-gen-ui KPI Dashboard pill

The earlier force-pin of `catalog_id` and the defensive component sweep
in `generate_a2ui` were correct but ran too late — they execute on the
tool-result, after the middleware has already fired surface events from
the streaming args.

Fix: rename the internal helper to `_design_a2ui_surface` (and update
`tool_choice`, prompt header, and module docstring) so it falls outside
the middleware's intercept list. The explicit `a2ui.render(...)` ops the
outer `generate_a2ui` returns are then the only path to the frontend,
and our Python validation layer is authoritative.

Verified locally: Beautiful Chat → Sales Dashboard pill renders Total
Revenue / New Customers / etc. with no errors.

Author: AlemTuzlak

showcase/integrations/langgraph-python/src/agents/a2ui_dynamic.py

@@ -5,8 +5,10 @@
 `examples/integrations/langgraph-python/agent/src/a2ui_dynamic_schema.py`):
 
 - The agent binds an explicit `generate_a2ui` tool. When called, `generate_a2ui`
-  invokes a secondary LLM bound to `render_a2ui` (tool_choice forced) with the
-  registered client catalog injected as `copilotkit.context`.
+  invokes a secondary LLM bound to `_design_a2ui_surface` (tool_choice forced)
+  with the registered client catalog injected as `copilotkit.context`. The
+  internal tool is intentionally NOT named `render_a2ui` to avoid the A2UI
+  middleware's default tool-call intercept (`a2uiToolNames`).
 - The tool result returns an `a2ui_operations` container which the A2UI
   middleware detects in the tool-call result and forwards to the frontend
   renderer.
@@ -37,14 +39,22 @@
 CUSTOM_CATALOG_ID = "declarative-gen-ui-catalog"
 
 
+# Internal tool bound only to the secondary LLM inside `generate_a2ui` for
+# structured output. Intentionally NOT named `render_a2ui` because the A2UI
+# middleware default-intercepts tool calls by that name from the run's event
+# stream and synthesises ACTIVITY_SNAPSHOT events from the LLM's RAW streaming
+# args (catalogId + components, before our Python code can validate). That
+# bypass is what surfaced the "Cannot create component root without a type"
+# infinite-loop on the deployed declarative-gen-ui demo. Renaming sidesteps
+# the middleware's intercept list (`a2uiToolNames`).
 @lc_tool
-def render_a2ui(
+def _design_a2ui_surface(
     surfaceId: str,
     catalogId: str,
     components: list[dict],
     data: dict | None = None,
 ) -> str:
-    """Render a dynamic A2UI v0.9 surface.
+    """Design a dynamic A2UI v0.9 surface.
 
     Args:
         surfaceId: Unique surface identifier.
@@ -53,12 +63,12 @@ def render_a2ui(
             component must have id "root".
         data: Optional initial data model for the surface.
     """
-    return "rendered"
+    return "designed"
 
 
 _GENERATE_A2UI_PROMPT_HEADER = f"""\
-You are designing a dynamic A2UI v0.9 surface. Call the `render_a2ui` tool with
-a flat component array.
+You are designing a dynamic A2UI v0.9 surface. Call the `_design_a2ui_surface`
+tool with a flat component array.
 
 Hard requirements (failing any of these breaks the renderer — be strict):
 - `catalogId` MUST be exactly: "{CUSTOM_CATALOG_ID}"
@@ -103,16 +113,16 @@ def generate_a2ui(runtime: ToolRuntime[Any]) -> str:
 
     model = ChatOpenAI(model="gpt-4.1")
     model_with_tool = model.bind_tools(
-        [render_a2ui],
-        tool_choice="render_a2ui",
+        [_design_a2ui_surface],
+        tool_choice="_design_a2ui_surface",
     )
 
     response = model_with_tool.invoke(
         [SystemMessage(content=prompt), *messages],
     )
 
     if not response.tool_calls:
-        return json.dumps({"error": "LLM did not call render_a2ui"})
+        return json.dumps({"error": "LLM did not call _design_a2ui_surface"})
 
     tool_call = response.tool_calls[0]
     args = tool_call["args"]

showcase/integrations/langgraph-python/src/agents/beautiful_chat.py

@@ -197,14 +197,23 @@ def search_flights(flights: list[Flight]) -> str:
 CUSTOM_CATALOG_ID = "copilotkit://app-dashboard-catalog"
 
 
+# Internal tool bound only to the secondary LLM inside `generate_a2ui` for
+# structured-output. Intentionally NOT named `render_a2ui` because the A2UI
+# middleware default-intercepts any tool call by that name from the run's
+# event stream and synthesises ACTIVITY_SNAPSHOT events from the LLM's RAW
+# streaming args (catalogId + components, before our Python code can validate
+# or normalise). That bypass is what surfaced the "Catalog not found:
+# declarative-gen-ui-catalog" hallucination on beautiful-chat and the
+# "Cannot create component root without a type" loop on declarative-gen-ui.
+# Renaming sidesteps the middleware's intercept list (`a2uiToolNames`).
 @lc_tool
-def render_a2ui(
+def _design_a2ui_surface(
     surfaceId: str,
     catalogId: str,
     components: list[dict],
     data: dict | None = None,
 ) -> str:
-    """Render a dynamic A2UI v0.9 surface.
+    """Design a dynamic A2UI v0.9 surface.
 
     Args:
         surfaceId: Unique surface identifier.
@@ -214,12 +223,12 @@ def render_a2ui(
         data: Optional initial data model for the surface (e.g. form values,
             list items for data-bound components).
     """
-    return "rendered"
+    return "designed"
 
 
 _GENERATE_A2UI_PROMPT_HEADER = f"""\
-You are designing a dynamic A2UI v0.9 surface. Call the `render_a2ui` tool with
-a flat component array.
+You are designing a dynamic A2UI v0.9 surface. Call the `_design_a2ui_surface`
+tool with a flat component array.
 
 Hard requirements (failing any of these breaks the renderer — be strict):
 - `catalogId` MUST be exactly: "{CUSTOM_CATALOG_ID}"
@@ -260,16 +269,16 @@ def generate_a2ui(runtime: ToolRuntime[Any]) -> str:
 
     model = ChatOpenAI(model="gpt-4.1")
     model_with_tool = model.bind_tools(
-        [render_a2ui],
-        tool_choice="render_a2ui",
+        [_design_a2ui_surface],
+        tool_choice="_design_a2ui_surface",
     )
 
     response = model_with_tool.invoke(
         [SystemMessage(content=prompt), *messages],
     )
 
     if not response.tool_calls:
-        return json.dumps({"error": "LLM did not call render_a2ui"})
+        return json.dumps({"error": "LLM did not call _design_a2ui_surface"})
 
     tool_call = response.tool_calls[0]
     args = tool_call["args"]