The Open Standard for Generative UI
import { AssistantMessage, EventType, Message, StreamProtocolAdapter, ToolMessage } from "../types";
import { agUIAdapter } from "./adapters";
/**
* @inline
*/
interface Parameters {
response: Response;
/** A function that creates a new message in the thread (assistant or tool). */
createMessage: (message: Message) => void;
/** A function that updates an existing message in the thread (matched by id). */
updateMessage: (message: Message) => void;
/**
* Marks a tool call as executing (args closed, awaiting result). Wired to the
* store's `executingToolCallIds` set so `pairToolActivity` can report the
* `"executing"` status. Optional — defaults to a no-op for standalone use.
*/
markToolExecuting?: (toolCallId: string) => void;
/** Clears a tool call from the executing set (result landed or errored). */
clearToolExecuting?: (toolCallId: string) => void;
/** The adapter to use for parsing the stream */
adapter?: StreamProtocolAdapter;
}
/**
* @category Utilities
*/
export const processStreamedMessage = async ({
response,
createMessage,
updateMessage,
markToolExecuting = () => {},
clearToolExecuting = () => {},
adapter = agUIAdapter(),
}: Parameters): Promise<AssistantMessage | void> => {
let currentMessage: AssistantMessage = {
id: crypto.randomUUID(),
role: "assistant",
content: "",
toolCalls: [],
};
let isFirst = true;
// The wire message-item id whose text currently streams into currentMessage.
let currentTextItemId: string | null = null;
// Tool messages by toolCallId, so repeated TOOL_CALL_RESULTs for the same
// call UPDATE one message in place instead of duplicating it.
const toolMessagesByCallId = new Map<string, ToolMessage>();
// Tool calls that have started but not yet received a result. On RUN_ERROR
// these are surfaced as errored tool messages instead of being left hanging.
const inFlightToolCallIds = new Set<string>();
let rafId: number | null = null;
const debouncedUpdate = (msg: AssistantMessage) => {
if (rafId !== null) cancelAnimationFrame(rafId);
rafId = requestAnimationFrame(() => {
updateMessage(msg);
rafId = null;
});
};
/** Flush the open assistant and start a fresh one (interleaved segments). */
const startNewAssistantSegment = () => {
if (rafId !== null) {
cancelAnimationFrame(rafId);
rafId = null;
if (!isFirst) updateMessage(currentMessage);
}
currentMessage = {
id: crypto.randomUUID(),
role: "assistant",
content: "",
toolCalls: [],
};
isFirst = true;
currentTextItemId = null;
};
const messageHasBody = (msg: AssistantMessage) =>
(msg.content?.length ?? 0) > 0 || (msg.toolCalls?.length ?? 0) > 0;
/** Publish the open assistant only once it has text or tool calls — never an empty shell. */
const commitCurrentMessage = () => {
if (isFirst) {
if (!messageHasBody(currentMessage)) return;
createMessage(currentMessage);
isFirst = false;
} else {
debouncedUpdate(currentMessage);
}
};
for await (const event of adapter.parse(response)) {
switch (event.type) {
// TEXT_MESSAGE_CHUNK and TEXT_MESSAGE_CONTENT are very similar events but TEXT_MESSAGE_CHUNK
// optionally allows for a role change. Since we don't support role changes in processMessage
// right now, we treat both the same.
case EventType.TEXT_MESSAGE_CHUNK:
case EventType.TEXT_MESSAGE_CONTENT: {
// Ignore empty deltas — a zero-length content event after tools would
// otherwise open a blank assistant segment that shadows the real answer
// (common around parallel tool calls when a new message item is opened).
if (!event.delta) break;
// Some adapters (LangGraph / ChatOpenAI Responses) keep one wire
// messageId for a whole model step even when Responses interleaved
// several message items. Text after tools means a new segment — same
// split Responses adapters express via a new TEXT_MESSAGE_START id.
if ((currentMessage.toolCalls?.length ?? 0) > 0) {
startNewAssistantSegment();
}
currentMessage = {
...currentMessage,
content: (currentMessage.content || "") + event.delta,
};
break;
}
case EventType.TOOL_CALL_START:
inFlightToolCallIds.add(event.toolCallId);
currentMessage = {
...currentMessage,
toolCalls: [
...(currentMessage.toolCalls || []),
{
id: event.toolCallId,
type: "function",
function: {
name: event.toolCallName,
arguments: "",
},
},
],
};
break;
case EventType.TOOL_CALL_END:
// Args have finished arriving → the call is now executing (awaiting its
// result), not "streaming". Previously this event was dropped and
// completion was faked from "did assistant text start".
markToolExecuting(event.toolCallId);
break;
case EventType.TOOL_CALL_ARGS:
if (currentMessage.toolCalls) {
const toolCalls = [...currentMessage.toolCalls];
const toolCallIndex = toolCalls.findIndex((tc) => tc.id === event.toolCallId);
if (toolCallIndex !== -1) {
const currentToolCall = toolCalls[toolCallIndex];
if (currentToolCall) {
toolCalls[toolCallIndex] = {
id: currentToolCall.id,
type: "function",
function: {
name: currentToolCall.function.name,
arguments: currentToolCall.function.arguments + event.delta,
},
};
currentMessage = { ...currentMessage, toolCalls };
}
}
}
break;
case EventType.TOOL_CALL_CHUNK: {
// Combined convenience form of START + ARGS (AG-UI). Some servers emit
// only chunks instead of the explicit START/ARGS/END triad; without
// this case their tool calls would be silently dropped. Lazily START on
// the first chunk carrying an id, fill the name if it arrives on a later
// chunk, and append any `delta` as ARGS. (No END is implied — a
// chunk-only call stays "streaming" until its result lands.)
const id = event.toolCallId;
if (!id) break;
const toolCalls = [...(currentMessage.toolCalls || [])];
let index = toolCalls.findIndex((tc) => tc.id === id);
if (index === -1) {
inFlightToolCallIds.add(id);
toolCalls.push({
id,
type: "function",
function: { name: event.toolCallName ?? "", arguments: "" },
});
index = toolCalls.length - 1;
}
const existing = toolCalls[index];
if (existing) {
toolCalls[index] = {
id: existing.id,
type: "function",
function: {
name: existing.function.name || event.toolCallName || "",
arguments: existing.function.arguments + (event.delta ?? ""),
},
};
currentMessage = { ...currentMessage, toolCalls };
}
break;
}
case EventType.TEXT_MESSAGE_START: {
// A DIFFERENT item id after content/tool calls have accumulated means
// the model opened a new output message item — interleaving prose with
// tool calls (several sections in one run). Split into a fresh assistant
// message so the live structure matches what reload reconstructs from
// storage
const startId = (event as { messageId?: string }).messageId ?? null;
const hasBody =
(currentMessage.content?.length ?? 0) > 0 || (currentMessage.toolCalls?.length ?? 0) > 0;
if (hasBody && startId !== currentTextItemId) {
startNewAssistantSegment();
}
currentTextItemId = startId;
break;
}
case EventType.TOOL_CALL_RESULT: {
// Result landed → no longer executing / in flight.
clearToolExecuting(event.toolCallId);
inFlightToolCallIds.delete(event.toolCallId);
// The call this result answers may still be waiting on the debounced
// assistant update (server-side tools stream their call and result
// back to back). Publish it first, or the result briefly pairs with no
// call and renders as a nameless tool — for as long as the frame is
// deferred, which in a background tab is until it's shown again.
if (rafId !== null) {
cancelAnimationFrame(rafId);
rafId = null;
updateMessage(currentMessage);
}
// Surface a failure onto the @ag-ui/core ToolMessage.error field. The
// TOOL_CALL_RESULT schema is `passthrough`, so adapters may carry an
// `isError` flag and/or `error` string; map either onto `error` so the
// selector can emit `status:"error"` (the previously-dead error branch
// in ToolResult lights up). Absent any failure signal it stays a
// success — no regression vs. today.
const failed = event as unknown as { isError?: boolean; error?: string };
const errorText =
failed.isError === true || (typeof failed.error === "string" && failed.error.length > 0)
? (failed.error ?? event.content)
: undefined;
// Upsert the tool message for this toolCallId. First result → create;
// any subsequent result for the same call → update the same message in
// place (no duplicates).
const existing = toolMessagesByCallId.get(event.toolCallId);
if (existing) {
const updated: ToolMessage = {
...existing,
content: event.content,
...(errorText ? { error: errorText } : {}),
};
toolMessagesByCallId.set(event.toolCallId, updated);
updateMessage(updated);
} else {
const toolMessage: ToolMessage = {
id: crypto.randomUUID(),
role: "tool",
toolCallId: event.toolCallId,
content: event.content,
...(errorText ? { error: errorText } : {}),
};
toolMessagesByCallId.set(event.toolCallId, toolMessage);
createMessage(toolMessage);
}
continue; // skip the trailing isFirst/update logic — this event doesn't touch currentMessage
}
case EventType.RUN_ERROR: {
const raw = (event as any).message || (event as any).error || "Stream error";
const errorText = typeof raw === "string" ? raw : JSON.stringify(raw);
// RUN_ERROR carries no toolCallId. Clear the executing flag for any
// tool call still in flight (started, no result yet) so it doesn't spin
// forever, but do NOT synthesize an empty-content tool message for it —
// an empty result would blank an in-flight renderer (e.g. an artifact
// skeleton). A call that already streamed a result was removed from the
// in-flight set on TOOL_CALL_RESULT, so it keeps its delivered content.
// The failure surfaces as the thread-level error thrown below.
for (const toolCallId of inFlightToolCallIds) {
clearToolExecuting(toolCallId);
}
inFlightToolCallIds.clear();
throw new Error(errorText);
}
}
commitCurrentMessage();
}
if (rafId !== null) {
// flush any update
cancelAnimationFrame(rafId);
updateMessage(currentMessage);
} else if (isFirst && messageHasBody(currentMessage)) {
// Last event was a no-op (e.g. empty delta) after body landed in memory only.
createMessage(currentMessage);
}
return currentMessage;
};