Chat UI Patterns

Chat UI Patterns

Overview

A streaming chat has two state machines the UI must not confuse: the run (idle → running → finished | errored | cancelled) and the message under construction (which the client already buffers for you). Wire the UI to the client's buffers and lifecycle callbacks, and keep the in-progress reply out of the live region until it's final. Visual direction is the frontend-design skill's job; protocol semantics are ag-ui-protocol's. This skill is the interaction contract between them.

Quick reference — concern → contract

Worked example — subscriber → state → render

const agent = useMemo(() => new HttpAgent({ url, headers, threadId }), [url, threadId]);
const [draft, setDraft] = useState<{ id: string; text: string } | null>(null); // in-progress reply
const [run, setRun] = useState<"idle" | "running" | "stopped" | "error">("idle");

useEffect(() => agent.subscribe({
  onRunStartedEvent: () => setRun("running"),
  onTextMessageContentEvent: ({ event, textMessageBuffer }) =>
    setDraft({ id: event.messageId, text: textMessageBuffer }),
  onTextMessageEndEvent: () => setDraft(null),          // agent.messages now holds it; log re-renders it
  onToolCallStartEvent: ({ event }) => setTool(event.toolCallId, event.toolCallName, "running"),
  onToolCallResultEvent: ({ event }) => setTool(event.toolCallId, undefined, "done"),
  onRunErrorEvent: ({ event }) => setRun(event.code === "abort" ? "stopped" : "error"),
  onRunFailed: () => setRun("error"),
  onRunFinishedEvent: () => setRun("idle"),
  onMessagesChanged: ({ messages }) => setLog([...messages]),   // agent.messages is mutated in place — copy it
}).unsubscribe, [agent]);

const send = (text: string) => {
  agent.addMessage({ id: randomUUID(), role: "user", content: text });
  stickToBottom.current = true;
  void agent.runAgent();
};
const stop = () => agent.abortRun();

// render — the streaming message is already in agent.messages (pushed on TEXT_MESSAGE_START),
// so exclude it from the live region until it's final
const committed = draft ? log.filter(m => m.id !== draft.id) : log;
<Log role="log" aria-live="polite" aria-relevant="additions" ref={logRef}>
  {committed.map(m => <Bubble key={m.id} message={m} />)}
</Log>
{draft && <Bubble key={draft.id} streaming message={{ id: draft.id, role: "assistant", content: draft.text }} />}
<VisuallyHidden role="status" aria-live="polite">{statusText(run)}</VisuallyHidden>

agent.messages is the single source of truth; onMessagesChanged fires on every applied frame (per token during streaming), so memoize Bubble on id + content. The draft bubble renders outside the region while streaming; when onTextMessageEndEvent clears draft, the same message mounts inside the log as a new node and is announced once.

Common mistakes

• Concatenating deltas yourself. The client already accumulates textMessageBuffer; a second accumulator drifts on reconnect or replay.
• Marking a tool "done" on TOOL_CALL_END. That's the end of the arguments stream. The tool hasn't run yet.
• Treating the abort RUN_ERROR as an error. Users see "Something went wrong" every time they press Stop.
• Streaming inside the live region. Per-token announcement with aria-relevant="text", or silence forever with "additions". Neither is what you want.
• Putting the draft inside the log "because it's the same node that will exist after commit." That sameness is the bug: nothing new mounts at the end, so the finished reply is never read. The draft is a sibling; the commit is a mount.
• Building an AbortController the agent never sees. HttpAgent owns its own; abortRun() is the API. Passing abortController via runAgent({ abortController }) is allowed but unnecessary.
• Rendering model markdown as plain text to avoid the question. The question is which sanitizer the project already uses, not whether to render. In a project with no renderer yet, name that as the open decision and leave one render slot — don't present white-space: pre-wrap as the answer.