fix(showcase): fix llamaindex D5 failures for tool-rendering, gen-ui-headless, hitl-steps

jpr5 · jpr5 · commit f0952e76561f · 2026-04-30T01:47:37.000-07:00
Three D5 probe failures fixed:

tool-rendering: get_weather was a backend tool so the workflow emitted
TOOL_CALL_CHUNK but no TOOL_CALL_RESULT, leaving useRenderTool stuck in
loading state forever. Move get_weather to frontend_tools so CopilotKit
manages the tool call lifecycle. Add ToolCallResultWorkflowEvent (which
subclasses ToolCallEndWorkflowEvent to pass the AG_UI_EVENTS isinstance
filter) and override aggregate_tool_calls to emit TOOL_CALL_RESULT for
render-only tools. The WeatherCard component now always renders with
data-testid="weather-card" even during loading, instead of switching to
a separate div that lacks the testid.

gen-ui-headless: the shared agent was missing a show_card frontend tool
stub, so the workflow never emitted TOOL_CALL_CHUNK for it. Add the
stub and register it in frontend_tools.

hitl-steps: human_in_the_loop was routed to the hitl-in-chat specialized
agent (which only has book_call), not the shared agent (which has
generate_task_steps). Move human_in_the_loop to sharedAgentNames so it
routes through the default agent. Introduce render_only_tool_names set
to distinguish render-only tools (get_weather) from interactive tools
(generate_task_steps, book_call, show_card) — only render-only tools
get premature TOOL_CALL_RESULT; interactive tools let CopilotKit manage
the result lifecycle to keep buttons enabled.
diff --git a/showcase/integrations/llamaindex/src/agents/agent.py b/showcase/integrations/llamaindex/src/agents/agent.py
@@ -71,6 +71,14 @@ def book_call(
     return f"Booking call about {topic} with {attendee}"
 
 
+def show_card(
+    title: Annotated[str, "Short heading for the card."],
+    body: Annotated[str, "Body text for the card."],
+) -> str:
+    """Display a titled card with a short body of text. Rendered on the frontend via useComponent."""
+    return f"Displayed card: {title}"
+
+
 # --- Backend tools (executed server-side, using shared implementations) ---
 
 # @region[weather-tool-backend]
@@ -187,22 +195,27 @@ async def generate_a2ui(
     "- Generate dynamic A2UI dashboards from conversation context (via generate_a2ui tool)\n"
     "- Generate step-by-step plans for user review (human-in-the-loop)\n"
     "- Book calls with people (via book_call frontend tool)\n"
+    "- Show titled cards with a body of text (via show_card frontend tool)\n"
     "When asked about weather, always use the get_weather tool. "
     "When asked about financial data or charts, use query_data first. "
     "When asked to book a call, use the book_call tool with topic and name."
 )
 
 
 async def _agent_workflow_factory():
-    return FixedAGUIChatWorkflow(
+    wf = FixedAGUIChatWorkflow(
         llm=OpenAI(model="gpt-4.1", **_openai_kwargs),
-        frontend_tools=[change_background, generate_haiku, generate_task_steps, book_call],
-        backend_tools=[get_weather, query_data, manage_sales_todos, get_sales_todos_tool, schedule_meeting, search_flights, generate_a2ui],
+        frontend_tools=[change_background, generate_haiku, generate_task_steps, book_call, show_card, get_weather],
+        backend_tools=[query_data, manage_sales_todos, get_sales_todos_tool, schedule_meeting, search_flights, generate_a2ui],
         system_prompt=_AGENT_SYSTEM_PROMPT,
         initial_state={
             "todos": [],
         },
     )
+    # Tools that use useRenderTool on the frontend — emit
+    # TOOL_CALL_RESULT so the render transitions to "complete".
+    wf.render_only_tool_names = {"get_weather"}
+    return wf
 
 
 agent_router = get_ag_ui_workflow_router(
diff --git a/showcase/integrations/llamaindex/src/agents/hitl_in_chat_agent.py b/showcase/integrations/llamaindex/src/agents/hitl_in_chat_agent.py
@@ -52,12 +52,15 @@
     LoopEvent,
     ToolCallEvent,
 )
+from llama_index.protocols.ag_ui.agent import ToolCallResultEvent
 from llama_index.protocols.ag_ui.events import (
     MessagesSnapshotWorkflowEvent,
     StateSnapshotWorkflowEvent,
     TextMessageChunkWorkflowEvent,
     ToolCallChunkWorkflowEvent,
+    ToolCallEndWorkflowEvent,
 )
+from ag_ui.core import EventType
 from llama_index.protocols.ag_ui.router import get_ag_ui_workflow_router
 from llama_index.protocols.ag_ui.utils import (
     ag_ui_message_to_llama_index_message,
@@ -113,12 +116,37 @@ def _fix_tool_messages(chat_history: List[ChatMessage]) -> None:
             msg.role = MessageRole.TOOL
 
 
+class ToolCallResultWorkflowEvent(ToolCallEndWorkflowEvent):
+    """Emit a TOOL_CALL_RESULT AG-UI event for backend tools.
+
+    llama-index-protocols-ag-ui v0.2.2 has no built-in workflow event for
+    TOOL_CALL_RESULT — ToolCallChunkWorkflowEvent emits the call but the
+    result is never forwarded to the frontend. Without this event,
+    CopilotKit's useRenderTool never transitions from "executing" to
+    "complete" and rendered tool cards stay in their loading state.
+
+    Subclasses ToolCallEndWorkflowEvent so it passes the AG_UI_EVENTS
+    isinstance filter in the router's stream_events loop.
+    """
+    message_id: str = ""
+    content: str = ""
+    role: Optional[str] = "tool"
+    type: EventType = EventType.TOOL_CALL_RESULT
+
+
 class FixedAGUIChatWorkflow(AGUIChatWorkflow):
     """AGUIChatWorkflow that fixes duplicate tool-call rendering and
     tool-result message formatting.
 
     See module docstring for the three upstream bugs this addresses.
+
+    render_only_tool_names: set of tool names that use useRenderTool
+    on the frontend. For these tools, aggregate_tool_calls emits a
+    TOOL_CALL_RESULT event so the render callback transitions to
+    status "complete". Interactive tools (useHumanInTheLoop,
+    useComponent) must NOT be in this set.
     """
+    render_only_tool_names: set = set()
 
     def _snapshot_messages(
         self, ctx: Context, chat_history: List[ChatMessage]
@@ -303,6 +331,87 @@ async def chat(
 
         return StopEvent()
 
+    @step
+    async def aggregate_tool_calls(
+        self, ctx: Context, ev: ToolCallResultEvent
+    ) -> Optional[Union[StopEvent, LoopEvent]]:
+        """Override to emit TOOL_CALL_RESULT events for backend tools.
+
+        The upstream aggregate_tool_calls processes backend tool results
+        internally (adding to chat_history + MESSAGES_SNAPSHOT) but never
+        emits a TOOL_CALL_RESULT AG-UI event. Without it, CopilotKit's
+        useRenderTool never transitions to "complete" and tool cards stay
+        in their loading state forever.
+        """
+        num_tool_calls = await ctx.store.get("num_tool_calls")
+        tool_call_results: List[ToolCallResultEvent] = ctx.collect_events(
+            ev, [ToolCallResultEvent] * num_tool_calls
+        )
+        if tool_call_results is None:
+            return None
+
+        frontend_tool_calls = [
+            r for r in tool_call_results
+            if r.tool_name in self.frontend_tools
+        ]
+        backend_tool_calls = [
+            r for r in tool_call_results
+            if r.tool_name in self.backend_tools
+        ]
+
+        new_tool_messages = []
+        for tool_result in backend_tool_calls:
+            new_tool_messages.append(
+                ChatMessage(
+                    role="tool",
+                    content=tool_result.tool_output.content,
+                    additional_kwargs={
+                        "tool_call_id": tool_result.tool_call_id,
+                    },
+                )
+            )
+            # Emit TOOL_CALL_RESULT so useRenderTool transitions to "complete"
+            ctx.write_event_to_stream(
+                ToolCallResultWorkflowEvent(
+                    tool_call_id=tool_result.tool_call_id,
+                    message_id=str(uuid.uuid4()),
+                    content=tool_result.tool_output.content,
+                    role="tool",
+                )
+            )
+
+        chat_history = await ctx.store.get("chat_history")
+        if new_tool_messages:
+            chat_history.extend(new_tool_messages)
+            self._snapshot_messages(ctx, [*chat_history])
+            await ctx.store.set("chat_history", chat_history)
+
+        if len(frontend_tool_calls) > 0:
+            # Emit TOOL_CALL_RESULT for render-only frontend tools (those
+            # registered via useRenderTool, like get_weather). These tools
+            # execute server-side and need the result forwarded so the
+            # render callback transitions to status "complete".
+            #
+            # Do NOT emit for interactive frontend tools (those using
+            # useHumanInTheLoop like generate_task_steps, book_call, or
+            # useComponent like show_card). Those tools need CopilotKit to
+            # manage the result lifecycle — premature TOOL_CALL_RESULT
+            # would skip past the "executing" state and disable interactive
+            # buttons.
+            for tool_result in frontend_tool_calls:
+                if tool_result.tool_name in self.render_only_tool_names:
+                    ctx.write_event_to_stream(
+                        ToolCallResultWorkflowEvent(
+                            tool_call_id=tool_result.tool_call_id,
+                            message_id=str(uuid.uuid4()),
+                            content=tool_result.tool_output.content,
+                            role="tool",
+                        )
+                    )
+            return StopEvent()
+
+        return LoopEvent(messages=chat_history)
+
 
 async def _workflow_factory():
     return FixedAGUIChatWorkflow(
diff --git a/showcase/integrations/llamaindex/src/app/api/copilotkit/route.ts b/showcase/integrations/llamaindex/src/app/api/copilotkit/route.ts
@@ -40,6 +40,7 @@ const sharedAgentNames = [
   "headless_simple",
   "headless_complete",
   "readonly_state_agent_context",
+  "human_in_the_loop",
 ];
 
 // Specialized routers live at dedicated subpaths on the agent_server so the
@@ -53,7 +54,6 @@ const specializedAgents: Record<string, string> = {
   "shared-state-read-write": "/shared-state-read-write",
   "gen-ui-tool-based": "/gen-ui-tool-based",
   "beautiful-chat": "/beautiful-chat",
-  human_in_the_loop: "/hitl-in-chat",
   hitl_in_app: "/hitl-in-app",
   subagents: "/subagents",
 };
diff --git a/showcase/integrations/llamaindex/src/app/demos/tool-rendering/page.tsx b/showcase/integrations/llamaindex/src/app/demos/tool-rendering/page.tsx
@@ -36,14 +36,6 @@ function Chat() {
       }),
       render: ({ parameters, result, status }) => {
         const loading = status !== "complete";
-        if (loading) {
-          return (
-            <div className="bg-[#667eea] text-white p-4 rounded-lg max-w-md">
-              <span className="animate-spin">Retrieving weather...</span>
-            </div>
-          );
-        }
-
         const parsed = parseJsonResult<any>(result);
         const weatherResult: WeatherToolResult = {
           temperature: parsed?.temperature || 0,
@@ -53,10 +45,11 @@ function Chat() {
           feelsLike: parsed?.feels_like || parsed?.temperature || 0,
         };
 
-        const themeColor = getThemeColor(weatherResult.conditions);
+        const themeColor = loading ? "#667eea" : getThemeColor(weatherResult.conditions);
 
         return (
           <WeatherCard
+            loading={loading}
             location={parameters?.location ?? ""}
             themeColor={themeColor}
             result={weatherResult}
@@ -121,10 +114,12 @@ function getThemeColor(conditions: string): string {
 }
 
 function WeatherCard({
+  loading,
   location,
   themeColor,
   result,
 }: {
+  loading?: boolean;
   location?: string;
   themeColor: string;
   result: WeatherToolResult;
@@ -142,42 +137,48 @@ function WeatherCard({
               data-testid="weather-city"
               className="text-xl font-bold text-white capitalize"
             >
-              {location}
+              {location || "Weather"}
             </h3>
-            <p className="text-white">Current Weather</p>
-          </div>
-          <WeatherIcon conditions={result.conditions} />
-        </div>
-
-        <div className="mt-4 flex items-end justify-between">
-          <div className="text-3xl font-bold text-white">
-            <span>{result.temperature}&deg; C</span>
-            <span className="text-sm text-white/50">
-              {" / "}
-              {((result.temperature * 9) / 5 + 32).toFixed(1)}&deg; F
-            </span>
-          </div>
-          <div className="text-sm text-white capitalize">
-            {result.conditions}
+            <p className="text-white">
+              {loading ? "Fetching weather..." : "Current Weather"}
+            </p>
           </div>
+          {!loading && <WeatherIcon conditions={result.conditions} />}
         </div>
 
-        <div className="mt-4 pt-4 border-t border-white">
-          <div className="grid grid-cols-3 gap-2 text-center">
-            <div data-testid="weather-humidity">
-              <p className="text-white text-xs">Humidity</p>
-              <p className="text-white font-medium">{result.humidity}%</p>
-            </div>
-            <div data-testid="weather-wind">
-              <p className="text-white text-xs">Wind</p>
-              <p className="text-white font-medium">{result.windSpeed} mph</p>
+        {!loading && (
+          <>
+            <div className="mt-4 flex items-end justify-between">
+              <div className="text-3xl font-bold text-white">
+                <span>{result.temperature}&deg; C</span>
+                <span className="text-sm text-white/50">
+                  {" / "}
+                  {((result.temperature * 9) / 5 + 32).toFixed(1)}&deg; F
+                </span>
+              </div>
+              <div className="text-sm text-white capitalize">
+                {result.conditions}
+              </div>
             </div>
-            <div data-testid="weather-feels-like">
-              <p className="text-white text-xs">Feels Like</p>
-              <p className="text-white font-medium">{result.feelsLike}&deg;</p>
+
+            <div className="mt-4 pt-4 border-t border-white">
+              <div className="grid grid-cols-3 gap-2 text-center">
+                <div data-testid="weather-humidity">
+                  <p className="text-white text-xs">Humidity</p>
+                  <p className="text-white font-medium">{result.humidity}%</p>
+                </div>
+                <div data-testid="weather-wind">
+                  <p className="text-white text-xs">Wind</p>
+                  <p className="text-white font-medium">{result.windSpeed} mph</p>
+                </div>
+                <div data-testid="weather-feels-like">
+                  <p className="text-white text-xs">Feels Like</p>
+                  <p className="text-white font-medium">{result.feelsLike}&deg;</p>
+                </div>
+              </div>
             </div>
-          </div>
-        </div>
+          </>
+        )}
       </div>
     </div>
   );
