ai message queue.md
AI Message Queue
Installation
npx shadcn@latest add @kokonutui/ai-message-queue
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title? |
string |
"Auth refactor" |
|
initialPrompt? |
string |
The message the agent is working on when the component mounts. The demo's when respond is left out. |
|
initialQueue? |
string[] |
Follow-ups already waiting in the queue. | |
respond? |
(text: string, signal: AbortSignal) => AgentResponse | AsyncIterable<AgentUpdate> |
Runs the agent on a message. Return a stream of updates (steps as they start, reply text as it comes) and the run follows it, ending when the stream does. Stop and Send now abort signal; a throw ends the run with the error's message. Or return fixed steps and a reply, played on stepMs. Demo when omitted. |
|
onQueueChange? |
(queue: QueuedMessage[]) => void |
Called with the queue whenever it changes, to keep it across reloads. | |
stepMs? |
number |
1700 |
Milliseconds per step of a run with fixed steps. |
className? |
string |
Extra classes for the root element. |
AgentResponse
| Field | Type | Description |
|---|---|---|
steps |
string[] |
What the agent shows while it works, one line per step. |
reply |
string |
AgentUpdate
One update from a live run: a step starts a new line of work (the one before it is done), a text adds to the reply.
type AgentUpdate = { step: string } | { text: string };
QueuedMessage
| Field | Type | Description |
|---|---|---|
id |
string |
|
text |
string |
Usage
Pass respond to run your agent. It gets the message and a signal, and returns a stream of updates: { step } when a new piece of work starts and { text } as the reply comes in. The run ends when the stream does, and the next queued message goes in. Stop and Send now abort the signal; a throw ends the run with the error's message. onQueueChange hands you the queue on every edit, so it can survive a reload. Without respond, the demo plays with its own prompt and queue.
"use client";
import type { UIMessageChunk } from "ai";
import AIMessageQueue, { type AgentUpdate } from "@/components/kokonutui/ai-message-queue";
/** Turns your agent route's UI message stream into steps and reply text. */
async function* runAgent(text: string, signal: AbortSignal): AsyncIterable<AgentUpdate> {
const res = await fetch("/api/agent", {
method: "POST",
body: JSON.stringify({ text }),
signal,
});
if (!(res.ok && res.body)) {
throw new Error("The agent didn't start. Try again.");
}
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) return;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split("\n");
buffer = lines.pop() ?? "";
for (const line of lines) {
if (!line.startsWith("data: ") || line === "data: [DONE]") continue;
const chunk = JSON.parse(line.slice(6)) as UIMessageChunk;
if (chunk.type === "tool-input-available") yield { step: chunk.toolName };
if (chunk.type === "text-delta") yield { text: chunk.delta };
if (chunk.type === "error") throw new Error(chunk.errorText);
}
}
}
export function AgentPanel() {
return <AIMessageQueue respond={runAgent} title="Auth refactor" />;
}
Your route returns streamText({ ... }).toUIMessageStreamResponse(). Map tool names to readable lines ("Reading session.ts") in the same loop.