- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
scripts/optimize-images.ts:14: const cacheKey = process.env.COMMIT_SHAconst cacheDir = ".next/cache/images"
const cacheKey = process.env.COMMIT_SHA
const cached = await restoreCache(cacheDir, cacheKey)1240The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again.
Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped.
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
CircleAlertIcon,
CircleCheckIcon,
LoaderCircleIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type SubagentMessage = UIMessage<
unknown,
UIDataTypes,
{
runCommand: {
input: { command: string };
output: { stdout: string };
};
}
>;
type SubagentPart = SubagentMessage["parts"][number];
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
researchAgent: {
input: { task: string };
output: SubagentMessage;
};
}
>;
type Part = ChatMessage["parts"][number];
const steps = [
{
command: "grep -rn cacheKey scripts",
stdout:
"scripts/optimize-images.ts:14: const cacheKey = process.env.COMMIT_SHA",
},
{
command: "sed -n 13,15p scripts/optimize-images.ts",
stdout:
'const cacheDir = ".next/cache/images"\nconst cacheKey = process.env.COMMIT_SHA\nconst cached = await restoreCache(cacheDir, cacheKey)',
},
{
command: "ls public/images | wc -l",
stdout: "1240",
},
];
function getSubagentMessage(done: number, report?: string): SubagentMessage {
const parts = steps.slice(0, done).map(
(step, index): SubagentPart => ({
input: { command: step.command },
output: { stdout: step.stdout },
state: "output-available",
toolCallId: `step-${index}`,
type: "tool-runCommand",
})
);
if (done < steps.length) {
parts.push({
input: { command: steps[done].command },
state: "input-available",
toolCallId: `step-${done}`,
type: "tool-runCommand",
});
}
if (report) {
parts.push({ text: report, type: "text" });
}
return { id: "research-agent", parts, role: "assistant" };
}
const chat = createChat<ChatMessage>()
.user("Why does image optimization rerun on every deploy?")
.assistant(({ writer }) => {
const subagent = writer.tool("researchAgent", {
input: {
task: "Find out why image optimization reruns on every deploy.",
},
});
writer.sleep(600);
steps.forEach((_, index) => {
subagent.output(getSubagentMessage(index), { preliminary: true });
writer.sleep(1000);
});
subagent.output(
getSubagentMessage(
steps.length,
"The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again."
)
);
writer.sleep(400);
writer.text(
"Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function StepRow({
part,
running,
}: {
part: Extract<SubagentPart, { type: "tool-runCommand" }>;
running: boolean;
}) {
const command = part.input?.command;
if (part.state === "output-available") {
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>{`Ran ${command}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{part.output.stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine status={running ? "running" : "error"}>
<TraceIcon>
{running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{running ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
function SubagentRow({
part,
streaming,
}: {
part: Extract<Part, { type: "tool-researchAgent" }>;
streaming: boolean;
}) {
const done = part.state === "output-available" && !part.preliminary;
const running = !done && part.state !== "output-error" && streaming;
const parts = part.state === "output-available" ? part.output.parts : [];
const report = parts
.map((agentPart) => (agentPart.type === "text" ? agentPart.text : ""))
.join("");
const line = (
<TraceLine status={done ? undefined : running ? "running" : "error"}>
<TraceIcon>
{done ? (
<CircleCheckIcon />
) : running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{done ? "Ran" : running ? "Running" : "Failed to run"} the research
subagent
</TraceTitle>
</TraceLine>
);
if (parts.length === 0) {
return line;
}
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-3" keepMounted>
<Trace>
{parts.map((agentPart) =>
agentPart.type === "tool-runCommand" ? (
<StepRow
key={agentPart.toolCallId}
part={agentPart}
running={running}
/>
) : null
)}
</Trace>
{report && <p>{report}</p>}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function SubagentDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const agents = message.parts.filter(
(part) => part.type === "tool-researchAgent"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{agents.length > 0 && (
<Trace>
{agents.map((part) => (
<SubagentRow
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Subagent renders a delegated task as a live trace. The parent message holds a researchAgent tool call, the subagent streams its own tool calls as partial output, and the final report lands at the bottom. Every step updates in place.
Subagent is a composition, not a primitive. It composes Trace and Code Block and streams nested tool calls through a chat transport.
Installation
$ bunx --bun frakment add trace code-block message bubble button$ npx frakment add trace code-block message bubble button$ pnpm dlx frakment add trace code-block message bubble button$ yarn dlx frakment add trace code-block message bubble button
Install the primitives:
$ bunx --bun frakment add trace code-block message bubble button$ npx frakment add trace code-block message bubble button$ pnpm dlx frakment add trace code-block message bubble button$ yarn dlx frakment add trace code-block message bubble button
Copy the demo into your project:
"use client";
import { useChat } from "@ai-sdk/react";
import type { UIDataTypes, UIMessage } from "ai";
import {
CircleAlertIcon,
CircleCheckIcon,
LoaderCircleIcon,
} from "lucide-react";
import { Button } from "@/components/ui/button";
import { CodeBlock, CodeBlockContent } from "@/components/ui/code-block";
import {
Bubble,
BubbleContent,
Message,
MessageContent,
} from "@/components/ui/message";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import { createChat, getMessageText } from "@/lib/ai";
type SubagentMessage = UIMessage<
unknown,
UIDataTypes,
{
runCommand: {
input: { command: string };
output: { stdout: string };
};
}
>;
type SubagentPart = SubagentMessage["parts"][number];
type ChatMessage = UIMessage<
unknown,
UIDataTypes,
{
researchAgent: {
input: { task: string };
output: SubagentMessage;
};
}
>;
type Part = ChatMessage["parts"][number];
const steps = [
{
command: "grep -rn cacheKey scripts",
stdout:
"scripts/optimize-images.ts:14: const cacheKey = process.env.COMMIT_SHA",
},
{
command: "sed -n 13,15p scripts/optimize-images.ts",
stdout:
'const cacheDir = ".next/cache/images"\nconst cacheKey = process.env.COMMIT_SHA\nconst cached = await restoreCache(cacheDir, cacheKey)',
},
{
command: "ls public/images | wc -l",
stdout: "1240",
},
];
function getSubagentMessage(done: number, report?: string): SubagentMessage {
const parts = steps.slice(0, done).map(
(step, index): SubagentPart => ({
input: { command: step.command },
output: { stdout: step.stdout },
state: "output-available",
toolCallId: `step-${index}`,
type: "tool-runCommand",
})
);
if (done < steps.length) {
parts.push({
input: { command: steps[done].command },
state: "input-available",
toolCallId: `step-${done}`,
type: "tool-runCommand",
});
}
if (report) {
parts.push({ text: report, type: "text" });
}
return { id: "research-agent", parts, role: "assistant" };
}
const chat = createChat<ChatMessage>()
.user("Why does image optimization rerun on every deploy?")
.assistant(({ writer }) => {
const subagent = writer.tool("researchAgent", {
input: {
task: "Find out why image optimization reruns on every deploy.",
},
});
writer.sleep(600);
steps.forEach((_, index) => {
subagent.output(getSubagentMessage(index), { preliminary: true });
writer.sleep(1000);
});
subagent.output(
getSubagentMessage(
steps.length,
"The cache is keyed on the commit SHA, so every deploy misses it and optimizes all 1,240 images again."
)
);
writer.sleep(400);
writer.text(
"Image optimization reruns because its cache is keyed on the commit SHA, which changes on every deploy. Key the cache on a hash of public/images instead, and unchanged images will be skipped."
);
});
const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });
function StepRow({
part,
running,
}: {
part: Extract<SubagentPart, { type: "tool-runCommand" }>;
running: boolean;
}) {
const command = part.input?.command;
if (part.state === "output-available") {
return (
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>{`Ran ${command}`}</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock size="sm">
<CodeBlockContent className="max-h-64" wrap>
{part.output.stdout}
</CodeBlockContent>
</CodeBlock>
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
return (
<TraceLine status={running ? "running" : "error"}>
<TraceIcon>
{running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{running ? "Running" : "Failed to run"} {command}
</TraceTitle>
</TraceLine>
);
}
function SubagentRow({
part,
streaming,
}: {
part: Extract<Part, { type: "tool-researchAgent" }>;
streaming: boolean;
}) {
const done = part.state === "output-available" && !part.preliminary;
const running = !done && part.state !== "output-error" && streaming;
const parts = part.state === "output-available" ? part.output.parts : [];
const report = parts
.map((agentPart) => (agentPart.type === "text" ? agentPart.text : ""))
.join("");
const line = (
<TraceLine status={done ? undefined : running ? "running" : "error"}>
<TraceIcon>
{done ? (
<CircleCheckIcon />
) : running ? (
<LoaderCircleIcon className="animate-spin" />
) : (
<CircleAlertIcon />
)}
</TraceIcon>
<TraceTitle>
{done ? "Ran" : running ? "Running" : "Failed to run"} the research
subagent
</TraceTitle>
</TraceLine>
);
if (parts.length === 0) {
return line;
}
return (
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>{line}</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-3" keepMounted>
<Trace>
{parts.map((agentPart) =>
agentPart.type === "tool-runCommand" ? (
<StepRow
key={agentPart.toolCallId}
part={agentPart}
running={running}
/>
) : null
)}
</Trace>
{report && <p>{report}</p>}
</TraceCollapsibleContent>
</TraceCollapsible>
);
}
export function SubagentDemo() {
const { messages, sendMessage, setMessages, status } = useChat<ChatMessage>({
messages: transcript,
transport,
});
const busy = status === "submitted" || status === "streaming";
return (
<div className="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
{messages.map((message) => {
if (message.role === "user") {
return (
<Message align="end" key={message.id}>
<MessageContent>
<Bubble align="end" variant="muted">
<BubbleContent>{getMessageText(message)}</BubbleContent>
</Bubble>
</MessageContent>
</Message>
);
}
const streaming = busy && message === messages.at(-1);
const agents = message.parts.filter(
(part) => part.type === "tool-researchAgent"
);
const text = getMessageText(message);
return (
<Message key={message.id}>
<MessageContent className="gap-4">
{agents.length > 0 && (
<Trace>
{agents.map((part) => (
<SubagentRow
key={part.toolCallId}
part={part}
streaming={streaming}
/>
))}
</Trace>
)}
{text && <p>{text}</p>}
</MessageContent>
</Message>
);
})}
{!busy && question && (
<Button
className="mt-auto self-start"
onClick={() => {
if (!question) {
return;
}
setMessages([]);
sendMessage(question);
}}
size="sm"
variant="outline"
>
Replay
</Button>
)}
</div>
);
}Update the import paths to match your project setup.
Usage
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
import {
CircleAlertIcon,
CircleCheckIcon,
LoaderCircleIcon,
} from "lucide-react";Anatomy
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<Trace>
<TraceCollapsible>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon />
<TraceTitle />
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent>
<CodeBlock />
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
<p />
</TraceCollapsibleContent>
</TraceCollapsible>- TraceCollapsible — the subagent run, one per delegation
- TraceCollapsibleTrigger — header row with a status icon and "Ran the research subagent"
- TraceCollapsibleContent — nested
Tracewith one step row per tool call - TraceLine — a single step, marked
runningwhile the subagent is still working
Streaming partial output
The parent calls writer.tool("researchAgent", ...) and then emits partial outputs with { preliminary: true }. Each partial output is a full subagent message with one more step completed. The preliminary flag keeps the call open until the final output lands.
const subagent = writer.tool("researchAgent", { input: { task } })
steps.forEach((_, index) => {
subagent.output(getSubagentMessage(index), { preliminary: true })
writer.sleep(1000)
})
subagent.output(getSubagentMessage(steps.length, report))Running
While the subagent is still working, the header shimmers and the active step spins. The parent message stays open so the user can follow along.
import { CircleCheckIcon, LoaderCircleIcon } from "lucide-react";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function SubagentRunning() {
return (
<Trace className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine status="running">
<TraceIcon>
<LoaderCircleIcon className="animate-spin" />
</TraceIcon>
<TraceTitle>Running the research agent</TraceTitle>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent keepMounted>
<Trace>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Ran grep -rn cacheKey scripts</TraceTitle>
</TraceLine>
<TraceLine status="running">
<TraceIcon>
<LoaderCircleIcon className="animate-spin" />
</TraceIcon>
<TraceTitle>
Running sed -n 13,15p scripts/optimize-images.ts
</TraceTitle>
</TraceLine>
</Trace>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
);
}Details
A finished run can surface metadata: the model that ran the subagent, the tools it had access to, the task description, and the final report. Use TraceDescription for duration and Badge for the model and tool set.
Find out why image optimization reruns on every deploy.
The cache is keyed on the commit SHA.
import { CircleCheckIcon } from "lucide-react";
import { Badge } from "@/components/ui/badge";
import {
Trace,
TraceCollapsible,
TraceCollapsibleContent,
TraceCollapsibleTrigger,
TraceDescription,
TraceIcon,
TraceLine,
TraceTitle,
} from "@/components/ui/trace";
export function SubagentDetails() {
return (
<Trace className="max-w-sm">
<TraceCollapsible defaultOpen>
<TraceCollapsibleTrigger>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Ran the research agent</TraceTitle>
<TraceDescription>48s</TraceDescription>
</TraceLine>
</TraceCollapsibleTrigger>
<TraceCollapsibleContent className="flex flex-col gap-3" keepMounted>
<div className="flex flex-wrap gap-1.5">
<Badge variant="secondary">anthropic/claude-sonnet-4.5</Badge>
<Badge className="font-mono" variant="outline">
runCommand
</Badge>
</div>
<p>Find out why image optimization reruns on every deploy.</p>
<Trace>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>Ran grep -rn cacheKey scripts</TraceTitle>
</TraceLine>
<TraceLine>
<TraceIcon>
<CircleCheckIcon />
</TraceIcon>
<TraceTitle>
Ran sed -n 13,15p scripts/optimize-images.ts
</TraceTitle>
</TraceLine>
</Trace>
<p>The cache is keyed on the commit SHA.</p>
</TraceCollapsibleContent>
</TraceCollapsible>
</Trace>
);
}Accessibility
- The status icon is decorative. The
TraceTitlecarries the state. - While running,
aria-live="polite"on the content region announces step changes. - Each step row is text, not an icon. Color is a secondary signal.
prefers-reduced-motiondisables the spinner and collapse animation.
Best Practices
- Stream partial output. Users want to see the subagent think, not wait for the final message.
- Collapse the subagent after it finishes. Long runs crowd the transcript.
- Surface the model and tools. A badge row makes the subagent auditable.
- Keep the report short. One paragraph, not a summary of every step.