fix(multi-agent-chat): fix sub-agent rendering, hydration, and added documentation

[vishxrad]

Fixes three runtime bugs in the multi-agent-chat example that caused sub-agent responses to never render, a hydration mismatch on page load, and an infinite re-render loop during streaming. Also improves the orchestrator prompt for more reliable sub-agent delegation and rewrites the README for the multi-agent architecture.

Bug Fixes

1. Sub-agent responses stuck on loading spinner

The ai package resolved to two different versions in the workspace: the server used ai@6.0.141 (from ^6.0.116) while @ai-sdk/react internally depended on ai@6.0.116. The newer version added a providerMetadata field to tool-output-available stream chunks, but the older client used z.strictObject() for validation — rejecting the unknown field and silently breaking the stream. Tool parts never transitioned to output-available, so the UI stayed on the loading spinner.

Fix: Pin ai to 6.0.116 in package.json to match @ai-sdk/react's internal dependency.

2. Hydration mismatch in Sidebar

useThreads initialized threads state by calling getThreads() (which reads localStorage) during the useState initializer. On the server, localStorage is unavailable so it returned []. On the client, it returned actual threads — causing a hydration mismatch.

Fix: Initialize threads as [] and defer the localStorage read to a useEffect.

3. Maximum update depth exceeded during streaming

persistMessages called refreshThreads() → setThreads(getThreads()) inside a useEffect that depended on messages. During streaming, each re-render saw a new messages reference from useSyncExternalStore, causing the effect to fire repeatedly in a tight loop.

Fix: persistMessages now only writes to localStorage without triggering state updates. A separate effect calls refreshThreads() only when status transitions to "ready" (streaming complete).

Improvements

• Orchestrator prompt — Rewritten to be more forceful about delegating visual tasks to analytics_subagent immediately, without text preamble.
• Conversation starters — All 4 starters now explicitly target the analytics sub-agent (sales dashboard, signup form, expense pie chart, team directory table).
• README — Full rewrite covering the multi-agent architecture, the async generator sub-agent pattern, streaming OpenUI rendering, and the request/response flow.

Changed Files

File	Change
package.json	Pin ai to exact 6.0.116
src/hooks/use-threads.ts	Hydration fix + decouple refreshThreads from persistMessages
src/app/page.tsx	Refresh sidebar only on stream completion
src/app/api/chat/route.ts	Stronger orchestrator system prompt
src/components/conversation-starters.tsx	All starters use analytics sub-agent
README.md	Full rewrite for multi-agent architecture
pnpm-lock.yaml	Lockfile update for pinned ai version

[Copilot]

Pull request overview

Fixes runtime issues in the multi-agent-chat example related to sub-agent tool streaming/rendering, React hydration, and streaming-induced render loops, and updates the orchestrator prompt + documentation accordingly.

Changes:

• Pin ai to 6.0.116 to prevent incompatible client/server stream chunk validation and unblock sub-agent rendering.
• Fix hydration mismatch by deferring localStorage thread reads to an effect, and prevent streaming render loops by decoupling persistence from sidebar refresh.
• Update orchestrator system prompt, conversation starters, and rewrite README to document the multi-agent streaming architecture.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Reflects dependency graph updates from pinning ai and lock regeneration.
examples/multi-agent-chat/package.json	Pins ai to 6.0.116 to eliminate version skew with @ai-sdk/react.
examples/multi-agent-chat/src/hooks/use-threads.ts	Avoids SSR hydration mismatch and separates persistence from thread list refresh.
examples/multi-agent-chat/src/app/page.tsx	Persists messages without state churn and refreshes threads only when streaming completes.
examples/multi-agent-chat/src/app/api/chat/route.ts	Tightens orchestrator prompt to delegate UI/visual tasks to analytics_subagent immediately.
examples/multi-agent-chat/src/components/conversation-starters.tsx	Reorients starters toward analytics sub-agent driven UI generation.
examples/multi-agent-chat/src/components/chat-header.tsx	Updates UI title to match the example’s new positioning.
examples/multi-agent-chat/src/app/layout.tsx	Updates app metadata title.
examples/multi-agent-chat/README.md	Rewrites docs to explain the multi-agent, async-generator sub-agent streaming flow.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The link text is malformed (unbalanced backticks), so it won’t render as intended in Markdown. Update the link text to either wrap the package name in balanced backticks or remove the stray backtick.

Suggested change

	- `[@openuidev/react-lang` package](../../packages/react-lang)
	- [`@openuidev/react-lang` package](../../packages/react-lang)

[Copilot]

The title uses "Multi Agent" without a hyphen, but the README uses "Multi-Agent". Please standardize the naming across metadata/header/README to avoid inconsistent branding and searchability.

Suggested change

	title: "Multi Agent Chat",
	title: "Multi-Agent Chat",