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

Task

Render a multi-step agent task as a live trace with running, done, and error states.

Add Open Graph metadata to the home page.
Searched for generateMetadataRead app/layout.tsxRead app/page.tsx
Edited app/layout.tsxEdited app/page.tsx

Added Open Graph defaults to app/layout.tsx and a title, description and image for the home page in app/page.tsx.

task-demo.tsx
"use client";

import { useChat } from "@ai-sdk/react";
import type { UIMessage } from "ai";
import {
  CircleAlertIcon,
  CircleCheckIcon,
  LoaderCircleIcon,
} from "lucide-react";
import * as React from "react";
import { Button } from "@/components/ui/button";
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 ChatMessage = UIMessage<
  unknown,
  {
    task: {
      title: string;
      steps: { title: string; status: "done" | "running" | "error" }[];
    };
  }
>;

type TaskPart = Extract<ChatMessage["parts"][number], { type: "data-task" }>;

type Status = "running" | "error" | undefined;

const TASKS = [
  {
    id: "find",
    steps: [
      ["Searching for generateMetadata", "Searched for generateMetadata"],
      ["Reading app/layout.tsx", "Read app/layout.tsx"],
      ["Reading app/page.tsx", "Read app/page.tsx"],
    ],
    title: ["Finding the project files", "Found the project files"],
  },
  {
    id: "update",
    steps: [
      ["Editing app/layout.tsx", "Edited app/layout.tsx"],
      ["Editing app/page.tsx", "Edited app/page.tsx"],
    ],
    title: ["Updating the page metadata", "Updated the page metadata"],
  },
];

function taskAt(task: (typeof TASKS)[number], done: number) {
  return {
    steps: task.steps.slice(0, done + 1).map(([running, finished], index) => ({
      status: index < done ? "done" : "running",
      title: index < done ? finished : running,
    })),
    title: task.title[done < task.steps.length ? 0 : 1],
  } satisfies TaskPart["data"];
}

const chat = createChat<ChatMessage>()
  .user("Add Open Graph metadata to the home page.")
  .assistant(({ writer }) => {
    TASKS.forEach((task) => {
      for (let done = 0; done <= task.steps.length; done++) {
        writer
          .data({ data: taskAt(task, done), id: task.id, type: "data-task" })
          .sleep(900);
      }
    });
    writer.text(
      "Added Open Graph defaults to app/layout.tsx and a title, description and image for the home page in app/page.tsx."
    );
  });

const transcript = chat.get();
const [question] = chat.get(1);
const transport = chat.transport({ delayMs: 20 });

function getStepStatus(
  status: TaskPart["data"]["steps"][number]["status"],
  streaming: boolean
): Status {
  if (status === "done") {
    return undefined;
  }
  return status === "running" && streaming ? "running" : "error";
}

function StatusIcon({ status }: { status: Status }) {
  if (status === "running") {
    return <LoaderCircleIcon className="animate-spin" />;
  }
  return status === "error" ? <CircleAlertIcon /> : <CircleCheckIcon />;
}

function TaskRow({
  task,
  streaming,
}: {
  task: TaskPart["data"];
  streaming: boolean;
}) {
  const [open, setOpen] = React.useState<boolean>();
  const steps = task.steps.map((step) => ({
    status: getStepStatus(step.status, streaming),
    title: step.title,
  }));
  const status = steps.some((step) => step.status === "error")
    ? "error"
    : steps.some((step) => step.status === "running")
      ? "running"
      : undefined;

  return (
    <TraceCollapsible
      onOpenChange={setOpen}
      open={open ?? status === "running"}
    >
      <TraceCollapsibleTrigger>
        <TraceLine status={status}>
          <TraceIcon>
            <StatusIcon status={status} />
          </TraceIcon>
          <TraceTitle>{task.title}</TraceTitle>
        </TraceLine>
      </TraceCollapsibleTrigger>
      <TraceCollapsibleContent keepMounted>
        <Trace>
          {steps.map((step) => (
            <TraceLine key={step.title} status={step.status}>
              <TraceTitle>{step.title}</TraceTitle>
            </TraceLine>
          ))}
        </Trace>
      </TraceCollapsibleContent>
    </TraceCollapsible>
  );
}

export function TaskDemo() {
  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 tasks = message.parts.filter((part) => part.type === "data-task");
        const text = getMessageText(message);

        return (
          <Message key={message.id}>
            <MessageContent className="gap-4">
              {tasks.length > 0 && (
                <Trace>
                  {tasks.map((part) => (
                    <TaskRow
                      key={part.id}
                      streaming={streaming}
                      task={part.data}
                    />
                  ))}
                </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>
  );
}

Task renders a multi-step agent operation as a collapsible trace. The header shows the task title and a status icon. The body lists each step with its own status. Every step updates in place as the task advances.

Task is a composition, not a primitive. It composes Trace and drives its own step state through a chat transport.

Installation

Usage

task.tsx
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
task.tsx
<TraceCollapsible open={open} onOpenChange={setOpen}>
  <TraceCollapsibleTrigger>
    <TraceLine status={status}>
      <TraceIcon>
        <StatusIcon status={status} />
      </TraceIcon>
      <TraceTitle>{task.title}</TraceTitle>
    </TraceLine>
  </TraceCollapsibleTrigger>
  <TraceCollapsibleContent>
    <Trace>
      {steps.map((step) => (
        <TraceLine key={step.title} status={step.status}>
          <TraceTitle>{step.title}</TraceTitle>
        </TraceLine>
      ))}
    </Trace>
  </TraceCollapsibleContent>
</TraceCollapsible>

Anatomy

task.tsx
<TraceCollapsible>
  <TraceCollapsibleTrigger>
    <TraceLine>
      <TraceIcon />
      <TraceTitle />
    </TraceLine>
  </TraceCollapsibleTrigger>
  <TraceCollapsibleContent>
    <Trace>
      <TraceLine>
        <TraceTitle />
      </TraceLine>
    </Trace>
  </TraceCollapsibleContent>
</TraceCollapsible>
  • TraceCollapsible — the task run, one per task
  • TraceCollapsibleTrigger — header with status icon and task title
  • TraceCollapsibleContent — nested Trace with one step row per action
  • TraceLine — a single step, status drives the color

Step status

Each step is done, running, or error. The parent task status derives from its steps: any error makes the task error, any running makes it running, otherwise it is done.

task.ts
const status = steps.some((step) => step.status === "error")
  ? "error"
  : steps.some((step) => step.status === "running")
    ? "running"
    : undefined

Controlled open

The demo keeps the task open while it is running and collapses it once it finishes. Pass open and onOpenChange when the parent wants to control visibility, or use defaultOpen for a fixed block that starts expanded.

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

  • One task per collapsible. Do not merge unrelated work into one block.
  • Keep step titles verb-first. "Reading app/layout.tsx", not "app/layout.tsx".
  • Open while running, collapse when done. A live task signals progress.
  • Pair with a plain-text summary. The task is evidence, not the answer.