72はじめる

Agent Todos

エージェントの作業中のプランを表示します。すべてのステップはバックログからToDo、進行中、完了へと移り、リアルタイムの所要時間、失敗、その裏にあるツール呼び出しも確認できます。コンポーザーの上に置くステータスピル、目に見えるプランの変更、実行前にプランを編集できるレビューステップを備えています。

Open in new tab

概要

Claude Code、Codex、Gemini CLIのようなコーディングエージェントは、TodoWrite、update_plan、write_todosといったツールを通じて、作業中に文章化されたプランを保持します。Agent Todosはそのプランを1ステップ1行に変換し、進行中のステップは具体的に(「Running the tests」)、それぞれにかかった時間とともに表示します。

すべてのステップは、バックログからToDo、進行中へ進み、完了、失敗、またはキャンセルになります。エージェントがプランを書き換えると、新しいステップはハイライトされ、削除されたステップは折りたたまれて消え、何が変わったかを短いメモで伝えます。失敗したステップは理由が表示されたままになり、完了したステップが長く続く場合は折りたたまれて、現在の作業が画面に残ります。

AgentTodosStatusは現在のステップと件数をコンポーザーの上の1行に表示します。AgentTodosReviewでは、何かを実行する前にステップの編集、並べ替え、追加、削除ができ、⌘↵で開始できます。アダプターは、まだストリーミング中の入力を含め、各エージェントのツール形式を読み取り、Tool Callsは任意のステップの中の作業を表示できます。

インストール

  1. Proレジストリをcomponents.jsonに追加する

    components.json
    {
  "registries": {
    "@hextaui-pro": {
      "url": "https://hextaui.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${HEXTAUI_PRO_TOKEN}"
      }
    }
  }
}

  2. トークンを追加する

    アカウントページでトークンを作成し、.env.local に HEXTAUI_PRO_TOKEN として設定してください。

  3. ブロックを追加する

    pnpm dlx shadcn@latest add @hextaui-pro/agent-todos

使い方

AI SDKと使う

getTodosFromPartsは、入力がまだストリーミング中でも、メッセージ内の最新のTodoWrite、update_plan、write_todosの呼び出しを読み取ります。リストはメッセージ内に、ステータスピルはコンポーザーの上に表示します。

"use client"

import { useChat } from "@ai-sdk/react"

import { AgentTodos, AgentTodosStatus } from "@/components/blocks/agent-todos/agent-todos"
import { getTodosFromParts } from "@/components/blocks/agent-todos/todos"

export function Chat() {
  const { messages, status } = useChat()
  const busy = status === "submitted" || status === "streaming"
  const last = messages.at(-1)
  const current = last?.role === "assistant" ? getTodosFromParts(last.parts) : null

  return (
    <div className="flex flex-col gap-4">
      {messages.map((message) => {
        const plan = message.role === "assistant" ? getTodosFromParts(message.parts) : null
        return plan ? (
          <AgentTodos
            key={message.id}
            todos={plan.todos}
            explanation={plan.explanation}
            running={busy && message.id === last?.id}
          />
        ) : null
      })}
      {current ? <AgentTodosStatus todos={current.todos} running={busy} /> : null}
    </div>
  )
}

実行前にレビューする

エージェントの開始前に、ステップの編集、並べ替え、追加、削除ができるようにします。Run planまたは⌘↵で、整理されたリストが返されます。

"use client"

import * as React from "react"

import { AgentTodosReview } from "@/components/blocks/agent-todos/todo-review"
import type { Todo } from "@/components/blocks/agent-todos/todos"

export function PlanApproval({
  proposed,
  onRun,
}: {
  proposed: Todo[]
  onRun: (plan: Todo[]) => void
}) {
  const [draft, setDraft] = React.useState(proposed)

  return <AgentTodosReview todos={draft} onChange={setDraft} onApprove={onRun} />
}

増分タスクツールと使う

Claude CodeのTaskCreateやTaskUpdateのように、1回に1つのタスクを作成・更新するツールでは、applyTaskEventで各呼び出しをリストに反映します。

"use client"

import * as React from "react"

import { AgentTodos } from "@/components/blocks/agent-todos/agent-todos"
import { applyTaskEvent, type TaskEvent, type Todo } from "@/components/blocks/agent-todos/todos"

export function useTaskList() {
  const [todos, setTodos] = React.useState<Todo[]>([])
  const apply = React.useCallback(
    (event: TaskEvent) => setTodos((current) => applyTaskEvent(current, event)),
    []
  )
  return { todos, apply }
}

export function Tasks({ todos, running }: { todos: Todo[]; running: boolean }) {
  return <AgentTodos todos={todos} running={running} />
}

構造

外側から内側へ組み合わせるパーツ。

パーツ説明
AgentTodosヘッダー、プログレスバー、説明、プラン変更のメモを備えたリスト全体。
AgentTodosStatus現在のステップを表示する1行のピルです。ポップオーバーでリストを開きます。
AgentTodosReviewエージェントの開始前に表示される、編集可能なプラン。
TodoMarkカスタムレイアウト向けの、ステータスマークだけの表示。
getTodosFromParts, fromTodoWrite, fromUpdatePlan, fromWriteTodos, applyTaskEvent各エージェントのツール形式からTodo項目へのアダプターです。

APIリファレンス

AgentTodos

プロパティ型デフォルト
todos順序どおりのステップ。
Todo[]–
explanationプランがその形になっている理由。プログレスバーの下に表示されます。Codexはupdate_planでこれを送信します。
string–
runningエージェントが作業中かどうか。いずれかのステップが進行中の間は、デフォルトでtrueになります。
boolean–
titleヘッダーのラベルとリージョン名。
string"Tasks"
collapsibleヘッダーでリストを折りたためるようにします。
booleantrue
defaultOpen開いた状態で開始します。
booleantrue
foldAfterリストがこの数より長くなったら、先頭の完了済みステップを折りたたみます。
number6

Todo

プロパティ型デフォルト
id安定したid。プランの変更はidで検出されます。
string–
content命令形で書く、実行すること: 「Run the tests」。
string–
activeForm進行中に表示される、実行中の内容: 「Running the tests」。
string–
statusステージ。pendingはTo doとして読み上げられます。
"backlog" | "pending" | "in_progress" | "completed" | "failed" | "cancelled"–
error失敗したステップの下に表示されます。
string–
duration履歴用に保存された秒数。
number–
detailsステップの下に開きます。通常はTool Callsです。
ReactNode–

AgentTodosStatus

プロパティ型デフォルト
todos同じリスト。空の場合は何も描画しません。
Todo[]–
runningtrueの間、マークとシマーをアニメーションさせます。
boolean–
explanationポップオーバー内のリストに渡されます。
string–

AgentTodosReview

プロパティ型デフォルト
todos提案されたプラン。
Todo[]–
onChange編集のたびに呼ばれます。
(todos: Todo[]) => void–
onApproveRun planまたは⌘↵から呼ばれます。空のステップは取り除かれ、テキストは前後の空白が削除されます。
(todos: Todo[]) => void–
onCancelCancelを表示し、Escapeを処理します。
() => void–
title見出し。
string"Review the plan"
approveLabelボタンのラベル。
string"Run plan"

getTodosFromParts(parts)

AI SDKメッセージ内の最新のTodoWrite、update_plan、write_todosの呼び出しから { todos, explanation? } を返します。なければnullを返します。

プロパティ型デフォルト
parts静的なツールパーツでも動的なツールパーツでも動作します。まだストリーミング中の入力にも対応します。
UIMessage["parts"]–

applyTaskEvent(todos, event)

TaskCreateまたはTaskUpdateの呼び出し1回分をリストに反映します。ステータスがdeletedの場合、そのタスクを削除します。

プロパティ型デフォルト
event正規化された呼び出し。
{ type: "create", id, subject, activeForm? } | { type: "update", id, status?, subject?, activeForm? }–

キーボード

キーアクション
EnterSpaceヘッダーまたはステップの詳細から、リストを開閉します。
⌘↵レビュー中にプランを実行します。別のフィールドに入力している場合は実行しません。
Enterレビュー中は、現在のステップの下にステップを追加します。
⌫レビュー中は、空のステップを削除し、1つ上のステップへ移動します。
⌥↑レビュー中は、ステップを上へ移動します。⌥↓で下へ移動します。
↑↓レビュー中は、ステップ間を移動します。
EsconCancelが設定されている場合、レビューをキャンセルします。

アクセシビリティ

  • リストはラベル付きのリージョンで、順序付きリストを持ちます。各ステップの名前には「Running the tests, In progress」のようにステージが含まれます。
  • 非表示のprogressbarが、完了したステップ数を伝えます。
  • ステップの開始、完了、失敗は、プランの変更とともに、politeなライブリージョンを通じて読み上げられます。タイマーの更新は読み上げられません。
  • ステータスピルのラベルは現在のステップと件数を読み上げ、フォーカス管理されたポップオーバーでリストを開きます。
  • レビューのフィールドにはステップ番号のラベルが付き、移動は読み上げられ(「Moved to step 2 of 5」)、入力メソッドで変換中はEnterが待機します。
  • モーション軽減時は、進行中のリングの回転が止まり、チェックは描画されずに表示され、ステップは即座に所定の位置へ移ります。

使用技術

Agent Todos を構成する無料のHextaUIコンポーネントです。それぞれ単独でインストールできます。

コード

4 個のファイルを components/blocks/agent-todos に追加しました。