Agent plan

npx shadcn@latest add "@assistant-ui/elements-agent-plan"

npx assistant-ui@latest init

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/ai-sdk";

export default function App() {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {/* your components */}
    </AssistantRuntimeProvider>
  );
}

npx shadcn@latest add "@assistant-ui/elements-agent-plan"

A checklist with a title, header count, accessible progress bar, and each step marked done, active, or still ahead. With a runtime the plan comes from a tool call the model drives; standalone you hold the step list and the active index yourself.

Getting started

"use client";

import { defineToolkit } from "@assistant-ui/react";
import { AgentPlan } from "@/components/assistant-ui/elements/agent-plan";

export const toolkit = defineToolkit({
  update_plan: {
    type: "backend",
    render: ({ args }) => (
      <AgentPlan
        title={args.title}
        steps={args.steps}
        activeIndex={args.activeIndex}
      />
    ),
  },
});

import { AssistantRuntimeProvider, AuiConfig, Tools } from "@assistant-ui/react";
import { toolkit } from "./toolkit";

const config = AuiConfig({ tools: Tools({ toolkit }) });

export function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  return (
    <AssistantRuntimeProvider runtime={runtime} config={config}>
      {children}
    </AssistantRuntimeProvider>
  );
}

"use client";

import { useState } from "react";
import { AgentPlan } from "@/components/assistant-ui/elements/agent-plan";

const STEPS = [
  { id: "read", label: "Read existing composer state" },
  {
    id: "design",
    label: "Design the draft store",
    description: "Keep pending changes local until they are ready.",
  },
  { id: "wire", label: "Wire runtime persistence" },
  { id: "test", label: "Add regression tests" },
  { id: "docs", label: "Update the docs" },
];

export function Plan() {
  const [activeIndex, setActiveIndex] = useState(0);
  return <AgentPlan title="Composer draft" steps={STEPS} activeIndex={activeIndex} />;
}

function completeStep() {
  setActiveIndex((i) => i + 1);
}

Anatomy

<div data-slot="agent-plan">
  <div>
    <span>{/* title */}</span>
    <span>{/* n of m */}</span>
  </div>
  <div role="progressbar">{/* accessible progress */}</div>
  <ul>
    <li>
      <span>{/* check, spinner, or dot */}</span>
      <span>{/* step label, active description, and screen-reader status */}</span>
    </li>
  </ul>
</div>

activeIndex is clamped into 0…steps.length before anything is drawn from it, so an out-of-range value never breaks the layout: a value at or past steps.length marks every step done, and NaN falls back to 0. A step is done when its index is before the clamped active index or every step is already done, active when it sits exactly at that index, and otherwise still ahead. Object steps may add a stable id and a description; only the active step shows its description. Every row includes screen-reader status text, while the progress bar announces both percentage and the completed-step count. With an empty steps array the header reads 0 of 0, the bar sits at 0%, and the list renders nothing.

Examples

Add detail to the active step

Object steps use id for stable keys, label for the visible row, and an optional description beneath the active label. A custom title names both the heading and the progress bar for screen readers.

<AgentPlan
  title="Release checklist"
  steps={[
    { id: "review", label: "Review the release notes" },
    {
      id: "publish",
      label: "Publish the package",
      description: "Wait for the release job to finish.",
    },
    { id: "announce", label: "Share the release" },
  ]}
  activeIndex={1}
/>

Restarting a plan

render: ({ args }) => (
  <AgentPlan title={args.title} steps={args.steps} activeIndex={args.activeIndex} />
),

function restart() {
  setActiveIndex(0);
}

API reference