Tool UI

このスキルを使用して、リクエストから動作する Tool UI 統合へ素早く進むことができます。

プロジェクトに既存のチャット UI/ランタイムがない場合は assistant-ui を優先してください。アプリに既に動作するランタイムがある場合は、assistant-ui をオプショナルとして扱ってください。

ステップ 1: 互換性と診断

ユーザーのプロジェクト内の components.json を読み込み、以下を確認します:

• components.json が存在する。

ステップ 2: コンポーネントのインストール

プロジェクトルートからのインストールコマンド

推奨（AI支援統合）:

npx tool-agent "integrate the <component> <component-id>"

カタログからコンポーネント固有のプロンプトを使用してください（例: integrate the plan component for step-by-step task workflows with status tracking）。

代替案（直接レジストリ）:

npx shadcn@latest add @tool-ui/<component-id>

複数のコンポーネント:

npx tool-agent "integrate the plan, progress-tracker, and approval-card components for planning flows"

または shadcn 経由:

npx shadcn@latest add @tool-ui/plan @tool-ui/progress-tracker @tool-ui/approval-card

完全なコンポーネントカタログ

tool-agent プロンプトと shadcn インストールコマンド付きの全 25 個の Tool UI コンポーネント:

進捗

コンポーネント	説明	tool-agent プロンプト	shadcn
plan	ステータス追跡付きのステップバイステップタスク	integrate the plan component for step-by-step task workflows with status tracking	npx shadcn@latest add @tool-ui/plan
progress-tracker	複数ステップ操作の実時間ステータスフィードバック	integrate the progress tracker component for real-time status feedback on multi-step operations	npx shadcn@latest add @tool-ui/progress-tracker

入力

コンポーネント	説明	tool-agent プロンプト	shadcn
option-list	ユーザーが複数の選択肢から選択	integrate the option list component to let users select from multiple choices	npx shadcn@latest add @tool-ui/option-list
parameter-slider	数値パラメータ調整コントロール	integrate the parameter slider component for numeric parameter adjustment controls	npx shadcn@latest add @tool-ui/parameter-slider
preferences-panel	ユーザー設定用のコンパクト設定パネル	integrate the preferences panel component for compact user settings	npx shadcn@latest add @tool-ui/preferences-panel
question-flow	分岐を含むマルチステップガイド質問	integrate the question flow component for multi-step guided questions with branching	npx shadcn@latest add @tool-ui/question-flow

表示

コンポーネント	説明	tool-agent プロンプト	shadcn
citation	引用元参照を表示	integrate the citation component to display source references with attribution	npx shadcn@latest add @tool-ui/citation
item-carousel	コレクション閲覧用の水平カルーセル	integrate the item carousel component for horizontal browsing of collections	npx shadcn@latest add @tool-ui/item-carousel
link-preview	Open Graph データ付きのリッチリンクプレビュー	integrate the link preview component for rich link previews with Open Graph data	npx shadcn@latest add @tool-ui/link-preview
stats-display	ビジュアルグリッドでの主要メトリクス	integrate the stats display component for key metrics and KPIs in a visual grid	npx shadcn@latest add @tool-ui/stats-display
terminal	コマンドラインの出力とログを表示	integrate the terminal component to show command-line output and logs	npx shadcn@latest add @tool-ui/terminal
weather-widget	予報と気象条件付きの天気表示	integrate the weather widget component for weather display with forecasts and conditions	npx shadcn@latest add @tool-ui/weather-widget

アーティファクト

コンポーネント	説明	tool-agent プロンプト	shadcn
chart	インタラクティブチャートでデータ可視化（recharts 必須）	integrate the chart component to visualize data with interactive charts	npx shadcn@latest add @tool-ui/chart
code-block	シンタックスハイライト付きコードスニペット表示	integrate the code block component for syntax-highlighted code snippets	npx shadcn@latest add @tool-ui/code-block
code-diff	シンタックスハイライト付きコード差分比較（@pierre/diffs 必須）	integrate the code diff component to compare code changes with syntax-highlighted diffs	npx shadcn@latest add @tool-ui/code-diff
data-table	ソート可能なテーブルで構造化データを表示	integrate the data table component to present structured data in sortable tables	npx shadcn@latest add @tool-ui/data-table
message-draft	送信前にメッセージを確認して承認	integrate the message draft component to review and approve messages before sending	npx shadcn@latest add @tool-ui/message-draft
instagram-post	Instagram 投稿プレビューをレンダリング	integrate the instagram post component to render Instagram post previews	npx shadcn@latest add @tool-ui/instagram-post
linkedin-post	LinkedIn 投稿プレビューをレンダリング	integrate the linkedin post component to render LinkedIn post previews	npx shadcn@latest add @tool-ui/linkedin-post
x-post	X 投稿プレビューをレンダリング	integrate the x post component to render X/Twitter post previews	npx shadcn@latest add @tool-ui/x-post

確認

コンポーネント	説明	tool-agent プロンプト	shadcn
approval-card	エージェントアクションのバイナリ確認	integrate the approval card component for binary confirmation of agent actions	npx shadcn@latest add @tool-ui/approval-card
order-summary	購入を明細価格付きで表示	integrate the order summary component to display purchases with itemized pricing	npx shadcn@latest add @tool-ui/order-summary

メディア

コンポーネント	説明	tool-agent プロンプト	shadcn
audio	アートワークとメタデータ付きの音声再生	integrate the audio component for audio playback with artwork and metadata	npx shadcn@latest add @tool-ui/audio
image	メタデータと帰属付きの画像表示	integrate the image component to display images with metadata and attribution	npx shadcn@latest add @tool-ui/image
image-gallery	フルスクリーンライトボックスビューア付きメーソンリーグリッド	integrate the image gallery component with masonry grid and lightbox viewer	npx shadcn@latest add @tool-ui/image-gallery
video	コントロールとポスター付きの動画再生	integrate the video component for video playback with controls and poster	npx shadcn@latest add @tool-ui/video

表示（ジオマップ）

コンポーネント	説明	tool-agent プロンプト	shadcn
geo-map	ジオロケーション付きエンティティとフリート位置表示	integrate the geo map component to display geolocated entities and fleet positions	npx shadcn@latest add @tool-ui/geo-map

ユースケース別のインストール例

tool-agent（推奨）:

npx tool-agent "integrate the plan, progress-tracker, and approval-card components for planning flows"
npx tool-agent "integrate citation, link-preview, code-block, and code-diff for research output"
npx tool-agent "integrate data-table, chart, and stats-display for data visualization"
npx tool-agent "integrate image, image-gallery, video, and audio for media display"

shadcn（直接）:

npx shadcn@latest add @tool-ui/plan @tool-ui/progress-tracker @tool-ui/approval-card
npx shadcn@latest add @tool-ui/citation @tool-ui/link-preview @tool-ui/code-block @tool-ui/code-diff
npx shadcn@latest add @tool-ui/data-table @tool-ui/chart @tool-ui/stats-display
# npm i recharts  # chart のピア依存
npx shadcn@latest add @tool-ui/image @tool-ui/image-gallery @tool-ui/video @tool-ui/audio

コードベースのツールキット設定

コンポーネントをインストール後、それらを assistant-ui 経由の Toolkit でワイヤリングします。このセクションは完全なセットアップを扱います: プロバイダー、ランタイム、ツールキットファイル、ID ハンドリング。

1. プロバイダーとランタイム

ランタイム、トランスポート、ツールを提供するアシスタントラッパーを作成します:

"use client";

import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
import { AssistantRuntimeProvider, Tools, useAui } from "@assistant-ui/react";
import {
  AssistantChatTransport,
  useChatRuntime,
} from "@assistant-ui/react-ai-sdk";
import { Thread } from "@/components/assistant-ui/thread";
import { toolkit } from "@/components/toolkit";

export const Assistant = () => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({ api: "/api/chat" }),
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
  });
  const aui = useAui({ tools: Tools({ toolkit }) });

  return (
    <AssistantRuntimeProvider runtime={runtime} aui={aui}>
      <div className="h-dvh">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
};

重要なポイント:

• useChatRuntime + AssistantChatTransport: チャット API に接続します。
• Tools({ toolkit }): ツール定義とレンダラーをモデルに転送します。
• sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls: ツール呼び出し後に自動継続します（オプションですがツール集約的フローでは一般的）。

2. ツールキットファイル構造

toolkit.ts（または toolkit.tsx）を単一ファイルとして作成し、Toolkit オブジェクトをエクスポートします。各キーはツール名で、各値は type、description、parameters、render を持ちます。

ツール説明 — すべてのツールに description を含めてください。可視コンテンツではなく、いつ ツールを呼び出すか、どの役割を果たすかを説明します。Tool UI コンポーネントは既にペイロード（オプション、プラン、チャートなど）をユーザーに対してレンダリングするため、そのコンテンツを繰り返す説明は冗長です。コンテンツを繰り返す（例: 「ラベルと説明付きのオプションリストを表示」）のではなく、モデル指向のガイダンスを優先してください（例: 「ユーザーが従うべきプランを提示」または「ユーザーが 1 つのオプションを選択させる」）。

フロントエンド vs バックエンドツール

-	-	フロントエンド	バックエンド
-	実装	ブラウザで実行; ユーザーインタラクションが addResult 経由でコミット	ツール実装はサーバーに配置; モデルが結果を返す
-	execute	必須 — クライアント側のツール UI フローを実行	不要
-	parameters	必須（モデル引数のスキーマ）	使用しない、バックエンド llm が aisdk 経由で完了した場合は inputSchema を使用
-	render	必須（引数、ステータス、結果、addResult の UI）	必須（result の UI）

バックエンドツール（モデルが結果を返す; ユーザー入力なし）:

import { type Toolkit } from "@assistant-ui/react";
import { Plan } from "@/components/tool-ui/plan";
import { safeParseSerializablePlan } from "@/components/tool-ui/plan/schema";

export const toolkit: Toolkit = {
  showPlan: {
    type: "backend",
    render: ({ result }) => {
      const parsed = safeParseSerializablePlan(result);
      if (!parsed) return null;
      return <Plan {...parsed} />;
    },
  },
};

フロントエンドツール（モデルが引数を送信; ユーザーインタラクションが addResult 経由でコミット）:

import { type Toolkit } from "@assistant-ui/react";
import { OptionList } from "@/components/tool-ui/option-list";
import {
  SerializableOptionListSchema,
  safeParseSerializableOptionList,
} from "@/components/tool-ui/option-list/schema";

const optionListTool: Toolkit[string] = {
  description: "Render selectable options with confirm and clear actions.",
  parameters: SerializableOptionListSchema,
  render: ({ args, toolCallId, result, addResult }) => {
    const parsed = safeParseSerializableOptionList({
      ...args,
      id: args?.id ?? `option-list-${toolCallId}`,
    });
    if (!parsed) return null;

    if (result) {
      return <OptionList {...parsed} choice={result} />;
    }
    return (
      <OptionList
        {...parsed}
        onAction={async (actionId, selection) => {
          if (actionId === "confirm" || actionId === "cancel") {
            await addResult?.(selection);
          }
        }}
      />
    );
  },
};

export const toolkit: Toolkit = {
  option_list: optionListTool,
  approval_card: {
    /* ... */
  },
};

3. API ルート（AI SDK）

チャット API が AI SDK（streamText）を使用する場合、ai から tool() を使用してバックエンドツールを定義します:

• inputSchema を使用
• バックエンドツールはサーバー上で execute を使用; 結果がストリーミングされ、ツールキットの render 関数経由でレンダリング

import { streamText, tool, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

// フロントエンドツール の場合: ...frontendTools(clientTools) — clientTools は AssistantChatTransport 経由のリクエストボディから来ます
const result = streamText({
  model: openai("gpt-4o"),
  messages: await convertToModelMessages(messages),
  tools: {
    get_weather: tool({
      description:
        "Get the current weather and forecast for a location. Returns data to display in a weather widget.",
      inputSchema: z.object({
        location: z.string().describe("City name, e.g. 'San Francisco'"),
        units: z
          .enum(["celsius", "fahrenheit"])
          .default("fahrenheit")
          .describe("Temperature unit"),
      }),
      execute: async ({ location, units }) => {
        // 天気データを取得、ウィジェットスキーマと一致する形状を返す
        return { location, units /* ... */ };
      },
    }),
  },
});

4. アクション中心 vs 複合コンポーネント

パターン	コンポーネント	使用方法
アクション中心	OptionList、ParameterSlider、PreferencesPanel、ApprovalCard	onAction または onConfirm/onCancel を直接ワイヤリング; ToolUI ラッパーなし。領収状態の場合は choice={result} を渡します。
複合	OrderSummary、DataTable など	ToolUI + ToolUI.Surface + ToolUI.Actions でラップ; DecisionActions または LocalActions を使用。

アクション中心の例（OptionList）:

return (
  <OptionList
    {...parsed}
    onAction={async (actionId, selection) => {
      if (actionId === "confirm" || actionId === "cancel") {
        await addResult?.(selection);
      }
    }}
  />
);

複合の例（DecisionActions 付き OrderSummary）:

return (
  <ToolUI id={parsed.id}>
    <ToolUI.Surface>
      <OrderSummary {...parsed} />
    </ToolUI.Surface>
    <ToolUI.Actions>
      <ToolUI.DecisionActions
        actions={[
          { id: "cancel", label: "Cancel", variant: "outline" },
          { id: "confirm", label: "Purchase" },
        ]}
        onAction={(action) =>
          createDecisionResult({ decisionId: parsed.id, action })
        }
        onCommit={(decision) => addResult?.(decision)}
      />
    </ToolUI.Actions>
  </ToolUI>
);

ApprovalCard は組み込みアクションを使用します; onConfirm/onCancel を直接ワイヤリング:

return (
  <ApprovalCard
    {...parsed}
    choice={
      result === "approved" || result === "denied" ? result : parsed.choice
    }
    onConfirm={async () => addResult?.("approved")}
    onCancel={async () => addResult?.("denied")}
  />
);

アクションモデル

Tool UI は、表示コンポーネント外の複合兄弟としてレンダリングされた 2 つのアクションサーフェスを使用します:

• ToolUI.LocalActions: 非結果的副作用（エクスポート、コピー、リンク開く）。ハンドラーは addResult(...) を呼び出してはいけません。
• ToolUI.DecisionActions: createDecisionResult(...) 経由で DecisionResult エンベロップを生成する結果的選択。コミットコールバックは addResult(...) を呼び出します。

アクション付き表示コンポーネント用の複合ラッパーパターン:

<ToolUI id={surfaceId}>
  <ToolUI.Surface>
    <DataTable {...props} />
  </ToolUI.Surface>
  <ToolUI.Actions>
    <ToolUI.LocalActions
      actions={[{ id: "export-csv", label: "Export CSV" }]}
      onAction={(actionId) => {
        /* 副作用のみ */
      }}
    />
  </ToolUI.Actions>
</ToolUI>

3 つのコンポーネントはアクション中心の例外です — それらは兄弟サーフェスの代わりに組み込みアクションプロップを保持します。3 つすべてが統一インターフェースを共有:

• actions: コンポーネントによってレンダリングされるアクションボタン。
• onAction(actionId, state): アクション後に実行され、アクション後の状態を受け取ります。
• onBeforeAction(actionId, state): アクション実行前に評価されるガード。

コンポーネント	ハンドラーに渡される状態型
OptionList	OptionListSelection
ParameterSlider	SliderValue[]
PreferencesPanel	PreferencesValue

複合パターンを使用するコンポーネント: CodeBlock、CodeDiff、Terminal、ProgressTracker。

コンテキストは createContext + use()（React 19）を経由して共有されます。サブコンポーネントは Root の外で使用された場合はスローします。

領収と選択の慣例

結果を持つコンポーネントは、確認/完了状態をレンダリングするために choice プロップを使用します:

コンポーネント	choice 型	値 / 形状
ApprovalCard	"approved" | "denied"	文字列リテラル
OptionList	string | string[]	選択されたオプション ID
OrderSummary	OrderDecision	{ action: "confirm", orderId?, confirmedAt? }
ProgressTracker	ToolUIReceipt	{ outcome, summary, identifiers?, at }（共有型）

choice が存在する場合、コンポーネントは領収モードでレンダリングされます — 読み取り専用、アクションなし。

運用規則

• リクエストを解決する最小限のコンポーネントセットをインストールします。
• すべてのツールに description が必要; モデル向けに書いてください（いつ呼び出すか、どの役割か）— コンポーネントがレンダリングするコンテンツを繰り返さないこと。

注釈:

• フロントエンドツールは execute 関数が必要

• バックエンドツールはサーバー側にツール実装があります。

• バックエンドツールはどちらも必要ありません

• 生成されたファイルは無視してください

• セットアップ後:

• 変更後の実行の最初の経験が魔法的になるよう、必要なパッケージ依存関係がインストールされていることを確認してください

• 実装されたばかりの機能の成功した実行に必要な env 変数（ほとんどの場合は api チャットエンドポイントに必要な変数）が設定されていない場合は、ユーザーに通知してください。