Claude API でジェネレーティブ UI を本番投入する — JSON Schema と Tool Use で動的コンポーネントをストリーミング描画する実装パターン

// src/genui/registry.ts
import { z } from "zod";
import zodToJsonSchema from "zod-to-json-schema";
import type { ReactNode } from "react";
import { Heading } from "@/components/genui/Heading";
import { BarChart } from "@/components/genui/BarChart";
import { DataTable } from "@/components/genui/DataTable";
import { ActionButton } from "@/components/genui/ActionButton";
import { Callout } from "@/components/genui/Callout";
 
// コンポーネントごとに props スキーマと描画関数を 1 か所にまとめる
export const componentRegistry = {
  heading: {
    description: "セクションの見出し。h2 として描画する。",
    schema: z.object({
      text: z.string().min(1).max(120),
      level: z.union([z.literal(2), z.literal(3)]).default(2),
    }),
    render: (props: { text: string; level?: 2 | 3 }): ReactNode => (
      <Heading {...props} />
    ),
  },
  bar_chart: {
    description: "数値データの棒グラフ。x は最大 24 件まで。",
    schema: z.object({
      title: z.string().max(80),
      x: z.array(z.string()).min(1).max(24),
      y: z.array(z.number()).min(1).max(24),
    }),
    render: (props: { title: string; x: string[]; y: number[] }) => (
      <BarChart {...props} />
    ),
  },
  data_table: {
    description: "シンプルな表。最大 6 列・100 行まで。",
    schema: z.object({
      columns: z.array(z.string()).min(1).max(6),
      rows: z.array(z.array(z.union([z.string(), z.number()]))).max(100),
    }),
    render: (props: any) => <DataTable {...props} />,
  },
  action_button: {
    description: "ユーザーが押せる次のアクション。最大 3 個まで。",
    schema: z.object({
      label: z.string().min(1).max(40),
      action_id: z.string().regex(/^[a-z][a-z0-9_]{1,40}$/),
    }),
    render: (props: { label: string; action_id: string }) => (
      <ActionButton {...props} />
    ),
  },
  callout: {
    description: "補足や注意点を強調表示する。",
    schema: z.object({
      tone: z.enum(["info", "warn", "success"]),
      body: z.string().max(240),
    }),
    render: (props: any) => <Callout {...props} />,
  },
} as const;
 
export type ComponentId = keyof typeof componentRegistry;
 
// Claude に渡す Tool 定義を自動生成する
export function buildRenderTool() {
  const blockSchemas = Object.entries(componentRegistry).map(([id, def]) => ({
    type: "object" as const,
    required: ["component", "props"],
    properties: {
      component: { const: id },
      props: zodToJsonSchema(def.schema, { target: "openApi3" }),
    },
  }));
  return {
    name: "render_component",
    description:
      "ユーザー向け UI を 1 ブロック描画する。許可されたコンポーネントだけ使用すること。",
    input_schema: {
      type: "object",
      required: ["block"],
      properties: { block: { oneOf: blockSchemas } },
    },
  } as const;
}

// src/genui/stream.ts
import Anthropic from "@anthropic-ai/sdk";
import { parse as partialParse } from "best-effort-json-parser"; // 部分 JSON 用
import { componentRegistry, buildRenderTool, type ComponentId } from "./registry";
 
export type GenUIBlock = {
  index: number;
  component: ComponentId | null;
  props: unknown;
  status: "streaming" | "ready" | "invalid";
  error?: string;
};
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
 
export async function* streamGenerativeUI(userQuery: string): AsyncGenerator<GenUIBlock> {
  const tool = buildRenderTool();
  const blocks: Map<number, GenUIBlock> = new Map();
  // タイムアウトと中断は production では必須。AbortController で 30 秒上限を強制する。
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 30_000);
 
  try {
    const stream = client.messages.stream(
      {
        model: "claude-sonnet-4-6",
        max_tokens: 4096,
        tools: [tool],
        tool_choice: { type: "any" },
        system:
          "あなたはレンダラーです。ユーザーの質問を理解したら、render_component を必要な数だけ順番に呼び出してください。順番がそのまま表示順です。",
        messages: [{ role: "user", content: userQuery }],
      },
      { signal: controller.signal },
    );
 
    let buffers: Map<number, string> = new Map();
 
    for await (const event of stream) {
      if (
        event.type === "content_block_start" &&
        event.content_block.type === "tool_use"
      ) {
        buffers.set(event.index, "");
        const block: GenUIBlock = {
          index: event.index,
          component: null,
          props: null,
          status: "streaming",
        };
        blocks.set(event.index, block);
        yield block;
      } else if (
        event.type === "content_block_delta" &&
        event.delta.type === "input_json_delta"
      ) {
        const prev = buffers.get(event.index) ?? "";
        const next = prev + event.delta.partial_json;
        buffers.set(event.index, next);
 
        // 部分 JSON を best-effort で parse して即時描画する
        try {
          const parsed = partialParse(next);
          const blockData = parsed?.block;
          const current = blocks.get(event.index);
          if (current && blockData?.component) {
            current.component = blockData.component as ComponentId;
            current.props = blockData.props ?? {};
            yield current;
          }
        } catch {
          // 部分パース失敗は無視して次のデルタを待つ
        }
      } else if (event.type === "content_block_stop") {
        const finalText = buffers.get(event.index);
        if (!finalText) continue;
        const current = blocks.get(event.index);
        if (!current) continue;
        try {
          const finalJson = JSON.parse(finalText);
          const block = finalJson.block;
          const def = componentRegistry[block.component as ComponentId];
          if (!def) {
            current.status = "invalid";
            current.error = `unknown component: ${block.component}`;
            yield current;
            continue;
          }
          // ⭐ ここが核心 — Zod で props を最終バリデーションして型を確定させる
          const result = def.schema.safeParse(block.props);
          if (!result.success) {
            current.status = "invalid";
            current.error = result.error.issues
              .map((i) => `${i.path.join(".")}:${i.message}`)
              .join(", ");
            yield current;
            continue;
          }
          current.component = block.component as ComponentId;
          current.props = result.data;
          current.status = "ready";
          yield current;
        } catch (err) {
          current.status = "invalid";
          current.error = err instanceof Error ? err.message : String(err);
          yield current;
        }
      }
    }
  } finally {
    clearTimeout(timer);
  }
}

// src/genui/server.ts
import { streamGenerativeUI } from "./stream";
 
type SessionState = {
  history: { role: "user" | "assistant"; content: string }[];
  blocks: Awaited<ReturnType<typeof toArray>>;
};
 
const sessions = new Map<string, SessionState>();
 
async function toArray<T>(gen: AsyncIterable<T>) {
  const out: T[] = [];
  for await (const v of gen) out.push(v);
  return out;
}
 
export async function handleUserMessage(sessionId: string, query: string) {
  const session = sessions.get(sessionId) ?? { history: [], blocks: [] };
  session.history.push({ role: "user", content: query });
  // 履歴の末尾 8 件のみ送る（コンテキストとコスト両方の上限を担保）
  const recent = session.history.slice(-8);
  const blocks = await toArray(streamGenerativeUI(recent.map((m) => m.content).join("\n\n")));
  session.blocks = blocks.filter((b) => b.status === "ready");
  sessions.set(sessionId, session);
  return session.blocks;
}
 
export async function handleAction(sessionId: string, actionId: string) {
  const session = sessions.get(sessionId);
  if (!session) throw new Error("session_not_found");
  // アクション ID から「このボタンが押されたら〜」のミニプロンプトを再注入する
  const prompt = `ユーザーがアクション "${actionId}" を選びました。直前のレスポンスのうち、関連する 1 ブロックだけを差し替える形で再描画してください。`;
  const blocks = await toArray(streamGenerativeUI(prompt));
  // ⭐ 重要 — ID 衝突した既存ブロックを置き換える
  const replaced = session.blocks.map((b) => {
    const swap = blocks.find((nb) => nb.component === b.component && nb.status === "ready");
    return swap ?? b;
  });
  session.blocks = replaced;
  return session.blocks;
}