従来の実装と Agent-Native な実装の差分

Kuma Dashboard は当初、Gmail / Slack / Calendar / Backlog / HubSpot を 1 つに集約する業務統合ダッシュボードとして始まった。 AI チャットは右の折りたたみパネルとして「補助的に」存在する、典型的な AI-enabled 構成だった。

プロジェクトの途中で、Builder.io の Vishwas Gopinath による Agent-Native: The Next Architecture for Software を読み、判別基準が刺さった：

「AI を取り除いてもプロダクトは動くか？」
Yes → AI-enabled（後付け）
No、UI なし → AI-native
No、UI あり → Agent-native — Builder.io ブログ

当時の Kuma は完全な AI-enabled だった。AI を切り離してもダッシュボードは動く。逆に言えば AI は本当の意味でアプリの中核ではなかった。

そこでスコープを変更した：

• 連携先は Gmail のみ に絞る
• 目的を「機能の集約」から「Agent-Native パターンの体験」に切り替える
• 既存の Slack / Calendar / Backlog 関連コードは凍結（削除せず残置）

defineAction の例

export const replyAction = defineAction({
  name: "gmail_reply",
  description: "メールスレッドに返信（draft / send 選択）",
  input: z.object({
    action: z.enum(["draft", "send"]),
    to: z.string().min(1),
    subject: z.string().min(1),
    body: z.string().min(1),
    thread_id: z.string().optional(),
    in_reply_to: z.string().optional(),
    cc: z.string().optional(),
  }),
  output: z.discriminatedUnion("status", [/* … */]),
  scope: "gmail.write",
  requiresConfirmation: true,
  run: async (input, ctx) => {
    // 唯一の実装ポイント
  },
});

これ 1 つから派生するもの：

        ┌──────────────────────────────────┐
        │   defineAction("gmail_reply")    │
        └──────┬───────────────────────────┘
               │
   ┌───────────┼─────────────────┬──────────────┬─────────────┐
   ▼           ▼                 ▼              ▼             ▼
Anthropic   HTTP route       MCP tool     audit_log     UI 確認
Tool 定義   /api/actions/    JSON-RPC    記録          フック
            gmail_reply      tools/call

同期パターン

  ┌─────────────────┐         ┌─────────────────┐
  │      UI         │         │     Agent       │
  └────────┬────────┘         └────────┬────────┘
           │                           │
   push    │ ui_state_update           │ view_screen
   route/  │                           │ → 読む
   選択    ▼                           │
       ┌───────────┐                   │
       │  ui_state │◄──── pendingNav ──┘
       │   (DB)    │           ─── navigate({route})
       └─────┬─────┘
             │
   pull      │ poll 2s
             ▼
       UI が pendingNav を検出 → router.push() → クリア

記事の言葉を借りれば「データベースが人間 UI とエージェントの調整レイヤー」になっている。 AgentがUIに直接 RPC せず、宣言的に DB へ書く → UI が観測して反応する設計。

// ~/.claude.json
{
  "mcpServers": {
    "kuma": { "url": "http://localhost:3000/api/mcp" }
  }
}

記事のコア：

アクションが共有単位になっていれば、プロトコル公開はルーティング問題に過ぎない。 — Builder.io ブログ

実際、MCP 公開のために書いたコードは route 1 ファイル（約 130 行）だけで、Action registry を読むコード以外は JSON-RPC のフレーミングだった。

権限スコープ

各アクションは scope: "gmail.read" | "gmail.write" | "ui.read" | "ui.write" を持ち、呼び出し元（ agent / ui / http / mcp）×スコープのマトリクスで許可される。

拒否されると、reason が action_log に "denied: …" として記録され、/audit ページで人間が確認できる。

監査ログ

すべてのアクション実行は action_log テーブルに自動記録される（読み取りスコープのポーリング由来はフィルタ済み）。/audit ページで時系列にフィルタ・展開できる。

コスト・レイテンシ計測

Bedrock 呼び出しは chat_log テーブルに model / input_tokens / output_tokens / cost_usd / duration_ms / tool_rounds で記録。Sonnet 4.6 価格（$3 / $15 per M tokens）でリアルタイム計算。/audit ページ上部に「直近 24h サマリ」を 5 カードで表示。

ワークスペース設定の DB 化

システムプロンプト・ユーザー追加指示は workspace_settings シングルトン行に保存。/settings ページから編集可能で、次のチャットから即反映される。ファイルでなく DBに置くことで、複数ユーザー・複数ワークスペースへの拡張が容易になる。

Smart Action Bar の例

「取引先 A 社の担当者から、打ち合わせ確認＋サンプルデータ提供依頼への回答」というメールを開くと、Bedrock が以下のチップを生成：

  ✨  A 社担当者より、5/13(水)11:00〜の打ち合わせ承諾と
      Web会議設定依頼、サンプルデータ提供は困難との回答。

  [↩ Web会議URLを送付]  [↩ サンプルデータ受領了承]

認証コードメールなら「195541 をコピー」、会議招待なら「日程調整を依頼」など、メールの種類に応じて UI 自体が変わる。 記事の「Runtime tools — エージェントがその場で作る私的ダッシュボード」の最小版として機能している。

Agent-Native チェックリスト 10 項目

△＝部分達成 / ○＝部分達成（10 は requiresConfirmation フラグは Action に存在するが UI 側の確認モーダルと別実装のため）。

1. 「DB が調整レイヤー」は強い

UI と Agent の状態同期を、メッセージング・WebSocket・直接 RPC ではなく DB を介した宣言的な状態にしたことで、ポーリング 1 つで双方向に流れる単純な系になった。 レースコンディションは「最後に書いた人勝ち」で許容できる粒度に収まる。

2. 「単一定義」の威力は派生数に比例する

Action を 1 か所に書く価値は、それを消費する surface の数に比例する。UI だけなら過剰、UI + Agent なら割に合う、UI + Agent + MCP なら劇的。MCP 公開を「ルーティング問題」に縮めたのが象徴的。

3. 監査ログは早めに入れたほうがよかった

後付けで action_log を入れたが、ポーリングや内部 push がノイズになりやすい。 最初から shouldAudit(action, ctx) ルールを設計しておけばよかった。

4. Agent に見せない設定は agentVisible: false で十分

ui_state_update や workspace_settings_update は registry には入っているが、Anthropic Tool 派生時にフィルタしている。 「全部がツール」ではなく「誰に見せるかは別軸」というシンプルな2軸設計で運用できた。

5. AI-native の "experience" は UI が薄くなることで生まれる

Smart Action Bar はメール詳細から「Gmail バッジ」「カレンダー widget」「Chat ボタン」を削った後にようやく機能した。 AI が前に出るには UI が引かないと、ノイズになる。