Agent Playground Streaming#

The Agent Playground delivers LLM responses via two response channels managed by AgentChatTransport — a custom transport class wired into the Vercel AI SDK useChat hook. The default channel is stream mode (Server-Sent Events, token-by-token); batch mode (single JSON response) is available as a fallback or manual override. The playground also keeps live streams alive across revision switches, so in-progress turns survive config updates.

Key source files (in the private web/oss + web/packages tree):

AgentChatTransport and Response Channels#

AgentChatTransport subclasses DefaultChatTransport from the Vercel AI SDK and overrides processResponseStream to handle both SSE and batch paths 1.

Channel selection is controlled by agentChannelModeAtom (a Jotai atom, default "stream"). The buildAgentRequest function reads this atom and sets the Accept header accordingly 1:

• "stream" → Accept: text/event-stream — response is an SSE stream conforming to Vercel AI SDK's uiMessageChunkSchema; processResponseStream delegates to the default SSE parser.
• "batch" → Accept: application/json — response is a WorkflowBatchResponse; AgentChatTransport calls batchJsonToUiMessageStream to replay it as a synthetic one-shot chunk sequence: start → start-step → text/reasoning/tool parts → finish-step → finish.

The batch replay path handles flexible data.outputs shapes: {role, content} where content may be a string or an array of content blocks (tool use, reasoning). Tool blocks are normalized to tool-input-available / tool-output-available chunk types 1.

A kebab-menu toggle in PlaygroundVariantHeaderMenu lets users manually switch channels 1.

Automatic Stream→Batch Negotiation#

PR #4875 introduced createNegotiatingFetch — a fetch middleware that makes the channel switch transparent when a backend handler can't stream 3.

Fallback flow:

1. Request sent with Accept: text/event-stream.
2. If the backend responds HTTP 406 Not Acceptable, createNegotiatingFetch re-issues the request with Accept: application/json.
3. AgentChatTransport detects the resolved mode and routes to the batch replay parser.
4. The user sees a single-frame response with no error — the fallback is fully transparent.

Non-406 errors are passed through untouched so useChat's onError handler surfaces them (e.g., "insufficient credit") rather than swallowing them 3.

Concurrency safety: the resolved mode is tracked in a WeakMap keyed to the response body stream, so overlapping requests each carry their own mode and cannot interfere 3. AgentChatTransport owns the NegotiatingFetch instance directly 3.

Stream Persistence Across Revision Switches#

Before PR #4997, switching the displayed revision (via self-commit or the config header) unmounted the agent chat component, aborting any live stream and losing in-progress turns 2.

Three coordinated fixes address this:

1. Stable key in MainLayout
The agent generation panel is assigned the static key "agent-generation-host" instead of using variantId as the key. A revision switch becomes a prop update (entityId change) rather than a remount, keeping useChat state and the active SSE connection intact 2.

2. entityIdRef in AgentChatPanel
A useRef captures the current entityId and is read at send time inside prepareSendMessagesRequest. This means subsequent turns in the same session are dispatched against the live revision's config, not the revision that was active when the session mounted — fixing the stale closure capture from the previous implementation 2.

3. Latch refs for async flag gaps
Workflow flags (the isAgent boolean) reload a beat after a revision swap, causing a brief window where the component might unmount:

• agentHostRef in PlaygroundMainView — latches true while the new revision loads; releases only once the entity definitively loads as non-agent 2.
• agentSurfaceRef in ExecutionItems — prevents teardown of the agent surface during this gap 2.

localStorage note: The useChat hook skips mid-stream persistence to localStorage, so only completed turns are persisted. In-progress turns survive revision switches in memory only 2.