fix(shell-client): handle multiple A2A response formats in orchestrator

[juantello-bit]

Fix A2UI Shell Client Response Parsing for Orchestrator Agent

Problem

The A2UI shell client (samples/client/lit/shell/client.ts) was not displaying responses from the orchestrator agent. When users submitted queries, the backend would process requests successfully and return A2UI components, but the UI would remain on the input form without rendering the results.

Root Cause

The client's response parsing logic only checked for parts in result.status.message.parts, which is used for streaming/task-based responses. However, the orchestrator agent returns responses in a different format using:

• result.artifacts[].parts - for blocking responses
• result.history[] - containing message history including agent responses

This mismatch meant that valid A2UI responses were being discarded, resulting in an empty messages array and no UI rendering.

Solution

Updated the send() method in samples/client/lit/shell/client.ts to handle multiple A2A response formats:

1. Task Status Messages (existing): Check result.status.message.parts for streaming responses
2. Artifacts (new): Check result.artifacts[].parts for blocking responses
3. History (new): Check result.history[] for agent responses in message history

The fix also adds comprehensive logging to help debug response parsing issues in development.

Changes Made

File: samples/client/lit/shell/client.ts

The response parsing now checks three locations for A2UI message parts:

• Task status messages (maintains backwards compatibility)
• Artifacts array (for blocking responses from orchestrator)
• History array (for agent responses in message history)

Debug console.log statements have been added to aid troubleshooting during development.

Testing

Setup

1. Start all required agents:

   # Terminal 1: Restaurant Agent
   cd samples/agent/adk/restaurant_finder
   export GEMINI_API_KEY=your_key_here
   uv run . --port=10003
   
   # Terminal 2: Contact Lookup Agent
   cd samples/agent/adk/contact_lookup
   export GEMINI_API_KEY=your_key_here
   uv run . --port=10004
   
   # Terminal 3: Ecommerce Dashboard Agent
   cd samples/agent/adk/rizzcharts
   export GEMINI_API_KEY=your_key_here
   uv run . --port=10005
   
   # Terminal 4: Orchestrator Agent
   cd samples/agent/adk/orchestrator
   export GEMINI_API_KEY=your_key_here
   uv run . --port=10002 --subagent_urls=http://localhost:10003 --subagent_urls=http://localhost:10004 --subagent_urls=http://localhost:10005
   

2. Start the shell client:

   cd samples/client/lit/shell
   npm install
   npm run dev
   

3. Open browser to http://localhost:5173/

Test Cases

✅ Restaurant Query

• Input: "Top 5 Chinese restaurants in New York"
• Expected: UI displays a list of 5 restaurants with images, ratings, details, and "Book Now" buttons

✅ Contact Query

• Input: "Who is David Chen in marketing?"
• Expected: UI displays contact information

✅ Dashboard Query

• Input: "Show my sales breakdown by product category for Q3"
• Expected: UI displays a pie chart with sales data

Impact

• Scope: Shell client only (samples/client/lit/shell/client.ts)
• Breaking Changes: None
• Backwards Compatibility: ✅ Maintains support for existing streaming/task-based responses
• New Functionality: ✅ Adds support for blocking responses and history-based responses

Additional Notes

Debug Logging

The fix includes console.log statements for development debugging. These are useful for troubleshooting response parsing issues and can be:

• Left as-is for development builds (Vite strips them in production)
• Wrapped in if (import.meta.env.DEV) conditionals if preferred
• Removed entirely if the team prefers

Response Format Documentation

This fix highlights the need for clearer documentation on A2A response formats. The protocol supports multiple response structures depending on agent implementation and configuration (blocking vs streaming, task-based vs direct).

Checklist

• [x] Code changes implemented
• [x] Tested with orchestrator agent
• [x] Tested with restaurant finder agent (via orchestrator)
• [x] Tested with contact lookup agent (via orchestrator)
• [x] Tested with ecommerce dashboard agent (via orchestrator)
• [x] Console logs added for debugging
• [x] Backwards compatibility maintained

Related Issues

This fix addresses the issue where the orchestrator agent sample would process requests successfully (as shown in backend logs) but the UI would not render the A2UI components returned by the subagents.

---

Fixes: Orchestrator agent UI rendering issue