For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Subagent

Render a delegated task as a live trace of nested tool calls and a final report.

Why does image optimization rerun on every deploy?
scripts/optimize-images.ts:14:  const cacheKey = process.env.COMMIT_SHA
const cacheDir = ".next/cache/images"
const cacheKey = process.env.COMMIT_SHA
const cached = await restoreCache(cacheDir, cacheKey)
1240

The 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.

subagent-demo.tsx
"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

Usage

subagent.tsx
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceDescription,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import {
  CircleAlertIcon,
  CircleCheckIcon,
  LoaderCircleIcon,
} from "lucide-react";

Anatomy

subagent.tsx
<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 Trace with one step row per tool call
  • TraceLine — a single step, marked running while 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.

subagent.ts
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.

Ran grep -rn cacheKey scriptsRunning sed -n 13,15p scripts/optimize-images.ts
subagent-running.tsx
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.

anthropic/claude-sonnet-4.5runCommand

Find out why image optimization reruns on every deploy.

Ran grep -rn cacheKey scriptsRan sed -n 13,15p scripts/optimize-images.ts

The cache is keyed on the commit SHA.

subagent-details.tsx
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 TraceTitle carries 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-motion disables 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.