adk-frontend

ADK フロントエンド統合

ユーザーから、Botpress ADK ボットに接続するフロントエンドアプリケーションの構築について質問された場合に、このスキルを使用します。認証パターン、型安全な API 呼び出し、クライアントの設定、生成された型の統合について説明します。

ADK フロントエンド統合とは？

Botpress ADK でボットを構築する場合、多くの場合、ボットとやり取りするフロントエンドアプリケーションが必要になります。このスキルでは、本番環境で検証済みの次のパターンを紹介します。

• 認証 - OAuth フローを使用した Cookie ベースの PAT 保存
• クライアント管理 - クライアントのキャッシュと再利用のための Zustand ストアパターン
• 型生成 - 完全な型安全性を実現する ADK 生成型の利用
• アクション呼び出し - 適切なエラー処理と楽観的更新を用いたボットアクションの呼び出し

主なテクノロジー

• @botpress/client - Botpress API 用の公式 TypeScript クライアント
• トリプルスラッシュ参照 - 生成された型をインポートする TypeScript のパターン
• React Query - ミューテーションとキャッシュ管理用（任意ですが、推奨）
• Zustand - クライアントの状態管理用

---

このスキルを使用するタイミング

ユーザーから次のようなフロントエンド関連の質問を受けた場合に、このスキルを有効にします。

認証に関する質問

• 「フロントエンドから Botpress に認証するにはどうすればよいですか？」
• 「Personal Access Token（PAT）とは何ですか？」
• 「トークンの保存には Cookie と localStorage のどちらを使うべきですか？」
• 「OAuth ログインフローを実装するにはどうすればよいですか？」
• 「認証状態に応じてルートを保護するにはどうすればよいですか？」
• 「トークンの有効期限切れにはどう対処すればよいですか？」

クライアント設定に関する質問

• 「Botpress クライアントを初期化するにはどうすればよいですか？」
• 「複数のクライアントインスタンスを管理する最適な方法は何ですか？」
• 「クライアントストアを使うのはなぜですか？」
• 「ワークスペーススコープのクライアントとボットスコープのクライアントを作成するにはどうすればよいですか？」
• 「通常のクライアントと Zai クライアントの違いは何ですか？」

型生成に関する質問

• 「ボットのアクションの型を取得するにはどうすればよいですか？」
• 「トリプルスラッシュ参照とは何ですか？」
• 「生成された型をインポートするにはどうすればよいですか？」
• 「.adk 型ファイルはどこにありますか？」
• 「ボットとフロントエンドで型を同期させるにはどうすればよいですか？」
• 「TypeScript でアクションの型が見つからないのはなぜですか？」

アクション呼び出しに関する質問

• 「フロントエンドからボットアクションを呼び出すにはどうすればよいですか？」
• 「client.callAction() の構文を教えてください。」
• 「アクション呼び出し時のエラーを処理するにはどうすればよいですか？」
• 「楽観的更新を実装するにはどうすればよいですか？」
• 「複数のアクション呼び出しを連鎖させるにはどうすればよいですか？」
• 「ボットアクションで React Query を使うにはどうすればよいですか？」

---

利用可能なドキュメント

./references/ にあるドキュメントファイル：

主な統合パターン

• authentication.md - PAT、Cookie、OAuth、ルート保護を含む完全な認証システム
• botpress-client.md - クライアントの初期化、Zustand ストアパターン、Zai クライアントの設定
• calling-actions.md - 型安全なアクション呼び出し、ミューテーション、エラー処理、楽観的更新
• type-generation.md - トリプルスラッシュ参照、生成された型、型安全性の維持

アーキテクチャと設定

• overview.md - アーキテクチャの概要、ADK フロントエンドを使用するタイミング、プロジェクト構成
• project-setup.md - Vite + React のスキャフォールディング、TypeScript 設定、環境設定
• recommended-stack.md - 推奨技術スタックとその理由

データと状態のパターン

• service-layer.md - 型付き API 呼び出しをラップするサービスレイヤーパターン
• data-fetching.md - TanStack Query のパターン、ミューテーション、楽観的更新
• state-management.md - Zustand と TanStack Query の比較、それぞれを使用するタイミング
• realtime-updates.md - ポーリング戦略、間隔の区分、パフォーマンス上の考慮事項

---

フロントエンドに関する質問への回答方法

フロントエンドに関する質問は、通常、次のカテゴリに分類されます。

1. 認証の実装

認証について質問された場合は、authentication.md に記載されている一連のパターンを参照してください。

主な概念：

• Botpress Cloud での PAT の生成
• Cookie ベースの保存（localStorage ではありません）
• React Context API を使用した AuthContext
• cli-login を介した OAuth コールバックフロー
• TanStack Router によるルート保護
• Botpress API とボットのテーブルの両方からのプロフィール取得

回答パターン：

1. 認証戦略（Cookie と localStorage の違い）を説明します
2. AuthProvider の実装を示します
3. OAuth フローを説明します
4. ルート保護の例を提示します
5. セキュリティのベストプラクティスを強調します

2. クライアントのセットアップと管理

クライアントの設定について質問された場合は、botpress-client.md を参照してください。

主な概念：

• apiUrl、workspaceId、token、botId を使用したクライアントの初期化
• クライアントのキャッシュに使用する Zustand ストア
• 再利用のための動的なクライアントキー
• ワークスペーススコープのクライアントとボットスコープのクライアント
• Zai 操作向けのタイムアウト延長

回答パターン：

1. clientsStore.ts のパターンを示します
2. クライアントのキャッシュの仕組みを説明します
3. getApiClient() の使用方法を示します
4. ワークスペーススコープとボットスコープのクライアントを使い分ける場面を示します
5. AI 操作向けの getZaiClient() を説明します

3. 型の生成とインポート

型について質問された場合は、type-generation.md を参照してください。

主な概念：

• ADK は dev/build の実行中に .adk/ ディレクトリ内に型を生成します
• 外部の型を参照するためのトリプルスラッシュディレクティブ
• 生成されるファイル：action-types.d.ts、table-types.d.ts、workflow-types.d.ts
• コードを簡潔にする型エイリアスの作成
• adk dev との型の同期

回答パターン：

1. ADK が型を生成する仕組みを説明します
2. トリプルスラッシュ参照の構文を示します
3. 生成された型のインポート方法を説明します
4. 型エイリアスの作成例を提示します
5. 型が自動的に同期される仕組みを示します

4. ボットのアクションの呼び出し

アクションの呼び出しについて質問された場合は、calling-actions.md を参照してください。

主な概念：

• client.callAction() のシグネチャ
• BotActionDefinitions による型安全な入出力
• 再利用可能なアクション呼び出しのためのサービスレイヤーパターン
• ロード状態とエラー処理に useMutation を使用
• 即時に UI へ反映するオプティミスティック更新
• アクションの連鎖（逐次実行と並列実行）

回答パターン：

1. 基本的な callAction() の構文を示します
2. 型安全なサービス関数の例を説明します
3. useMutation の例を提示します
4. エラー処理のパターンを示します
5. 該当する場合は、オプティミスティック更新を説明します

---

よくあるパターンのリファレンス

認証フロー

// 1. Cookie helpers
function setCookie(name: string, value: string, days = 365)
function getCookie(name: string): string | null
function deleteCookie(name: string)

// 2. AuthContext
interface AuthContextType {
  token: string | null
  isAuthenticated: boolean
  userProfile: UserProfile | null
  isLoadingProfile: boolean
  login: (token: string) => void
  logout: () => void
}

// 3. OAuth Flow
// Redirect: https://app.botpress.cloud/cli-login?redirect=...
// Callback: /auth/callback?pat=bp_pat_...
// Store PAT in cookie and navigate to app

クライアントストアのパターン

// stores/clientsStore.ts
const useClientsStore = create<ClientsState>()((set, get) => ({
  APIClients: {},
  getAPIClient: (props) => {
    const key = props?.botId ? `${props.workspaceId}-${props.botId}` : (props?.workspaceId ?? DEFAULT_API_CLIENT_KEY)

    const cached = get().APIClients[key]
    if (cached) return cached

    const newClient = new APIClient({
      apiUrl: API_BASE_URL,
      workspaceId: props?.workspaceId,
      token: getPat() ?? '',
      botId: props?.botId,
    })

    set((state) => ({
      APIClients: { ...state.APIClients, [key]: newClient },
    }))

    return newClient
  },
}))

export const getApiClient = (props?) => useClientsStore.getState().getAPIClient(props)

型のインポートパターン

// types/index.ts
/// <reference path="../../../bot/.adk/action-types.d.ts" />
/// <reference path="../../../bot/.adk/table-types.d.ts" />

import type { BotActionDefinitions } from '@botpress/runtime/_types/actions'
import type { TableDefinitions } from '@botpress/runtime/_types/tables'

// Create type aliases
export type SendMessageAction = BotActionDefinitions['sendMessage']
export type TicketTableRow = TableDefinitions['TicketsTable']['Output']

アクション呼び出しパターン

// services/bot-service.ts
export async function sendMessage(input: SendMessageAction['input']) {
  const client = getApiClient({ botId, workspaceId })
  const result = await client.callAction({
    type: 'sendMessage',
    input,
  })
  return result.output as SendMessageAction['output']
}

// Component usage with useMutation
const { mutate: send, isPending } = useMutation({
  mutationFn: sendMessage,
  onSuccess: () => {
    toast.success('Message sent')
    queryClient.invalidateQueries({ queryKey: ['messages'] })
  },
  onError: (error) => {
    toast.error('Failed to send message')
  },
})

---

このスキルで回答できる質問の例

初心者向けの質問

• 「React アプリを Botpress ボットに接続するにはどうすればよいですか？」
• 「Personal Access Token とは何ですか？」
• 「ワークスペース ID とボット ID はどこで確認できますか？」
• 「@botpress/client をインストールするにはどうすればよいですか？」

認証に関する質問

• 「認証トークンはどのように保存すればよいですか？」
• 「ログイン／ログアウトを実装するにはどうすればよいですか？」
• 「認証が必要なルートを保護するにはどうすればよいですか？」
• 「Cookie と localStorage のどちらを使うべきですか？」
• 「OAuth コールバックはどのように処理すればよいですか？」

型安全性に関する質問

• 「ボットの TypeScript 型を取得するにはどうすればよいですか？」
• 「トリプルスラッシュ参照とは何ですか？」
• 「TypeScript がアクションの型を見つけられないのはなぜですか？」
• 「型を同期するにはどうすればよいですか？」
• 「生成された型ファイルはどこにありますか？」

実装に関する質問

• 「ボットのアクションを呼び出すにはどうすればよいですか？」
• 「フロントエンドからボットのテーブルをクエリするにはどうすればよいですか？」
• 「ロード状態を処理するにはどうすればよいですか？」
• 「オプティミスティック更新を実装するにはどうすればよいですか？」
• 「複数のアクション呼び出しを連鎖させるにはどうすればよいですか？」

高度な質問

• 「フロントエンドから Zai を使うにはどうすればよいですか？」
• 「ワークスペーススコープのクライアントとボットスコープのクライアントには、どのような違いがありますか？」
• 「クライアントのキャッシュを実装するにはどうすればよいですか？」
• 「トークンの有効期限切れはどのように処理すればよいですか？」
• 「再試行ロジックを実装するにはどうすればよいですか？」

---

回答の形式

回答する際は：

1. 簡潔な説明から始めます（1～2 段落）
2. 参考資料にある実用的なコード例を提示します
3. ファイルの参照箇所を示します（例：「authentication.md:60-85 より」）
4. 関連する場合はセキュリティ上の考慮事項を強調します
5. よくある落とし穴と回避方法を示します
6. 詳しく知るための関連トピックへのリンクを提示します

回答の構成例

Question: "How do I authenticate users in my frontend?"

Answer:
The recommended pattern uses cookie-based PAT storage with OAuth flow.
Here's the complete implementation:

1. Cookie Helpers (authentication.md:89-111)
   [code example]

2. AuthContext Setup (authentication.md:64-76)
   [code example]

3. OAuth Flow (authentication.md:473-533)
   [code example]

Key Security Considerations:
- Use SameSite=Lax for CSRF protection
- Always use HTTPS in production
- Never log PATs to console
- Implement token expiration handling

Related Topics:
- Route protection: authentication.md:369-467
- Profile fetching: authentication.md:304-347
- Client initialization: botpress-client.md:29-51

---

常に参照すべき重要なパターン

質問に回答する際は、ドキュメントで以下のパターンを必ず確認してください。

1. クライアント管理

// ✅ CORRECT - Use client store
const client = getApiClient({ workspaceId, botId })

// ❌ WRONG - Create new client every time
const client = new Client({ apiUrl, workspaceId, token, botId })

2. 型のインポート

// ✅ CORRECT - Triple-slash at top of file
/// <reference path="../../../bot/.adk/action-types.d.ts" />
import type { BotActionDefinitions } from '@botpress/runtime/_types/actions'

// ❌ WRONG - No triple-slash reference
import type { BotActionDefinitions } from '@botpress/runtime/_types/actions'

3. アクションの呼び出し

// ✅ CORRECT - Service layer with types
export async function sendMessage(input: SendMessageAction['input']) {
  const client = getApiClient({ botId, workspaceId })
  const result = await client.callAction({ type: 'sendMessage', input })
  return result.output as SendMessageAction['output']
}

// ❌ WRONG - Direct call in component
const result = await client.callAction({ type: 'sendMessage', input: data })

4. 認証情報の保存

// ✅ CORRECT - Cookie with SameSite
document.cookie = `token=${value};expires=${expires};path=/;SameSite=Lax`

// ❌ WRONG - localStorage without security
localStorage.setItem('token', value)

---

重視すべきベストプラクティス

回答する際は、関連するベストプラクティスに必ず触れてください。

セキュリティ

• 本番環境では必ず HTTPS を使用します
• SameSite 保護を備えた Cookie を使用します
• PAT やトークンをログに記録しないでください
• トークンの有効期限切れを処理します
• 可能な場合は HttpOnly Cookie を使用します（SSR）

型安全性

• ADK で生成された型を必ず使用します
• コードをすっきりさせるために型エイリアスを作成します
• トリプルスラッシュ参照を正しく使用します
• adk dev と型を同期させます
• すべてのアクションの入力と出力に型を指定します

パフォーマンス

• Zustand ストアでクライアントをキャッシュします
• ボット操作が不要な場合は、ワークスペーススコープのクライアントを使用します
• UX を向上させるために楽観的更新を実装します
• キャッシュ管理には React Query を使用します
• 独立したアクションは並列で実行します

エラー処理

• 401（トークンの有効期限切れ）エラーを必ず処理します
• エラー発生時はユーザーにフィードバックを提供します
• 一時的な障害に対する再試行ロジックを実装します
• 適切にエラーを記録します（トークンは決して記録しないでください）
• 非同期処理中はローディング状態を表示します

コードの構成

• アクション呼び出しにはサービスレイヤーを使用します
• 型を単一のファイルに集約します
• 認証ロジックはコンテキストにまとめます
• クライアント設定と使用箇所を分離します
• コンポーネント間でサービス関数を再利用します

---

よくある問題のトラブルシューティング

以下のよくある問題への対応に備えてください。

「Cannot find module '@botpress/runtime/_types/actions'」

• トリプルスラッシュ参照のパスを確認します
• .adk/ ディレクトリが存在することを確認します
• TypeScript サーバーを再起動します
• adk dev/build が実行済みであることを確認します

「ボットの変更後に型が更新されない」

• adk dev を再起動します
• .adk/ を削除して再ビルドします
• TypeScript サーバーを再起動します
• ボットのコンパイルエラーを確認します

「再読み込み後に認証に失敗する」

• 再読み込み時の再試行ロジックを実装します（authentication.md:191-220）
• Cookie の有効期限を確認します
• トークンが正しく取得されていることを確認します
• CORS の問題がないか確認します

「長時間の処理でクライアントがタイムアウトする」

• AI 処理では、タイムアウトを延長して getZaiClient() を使用します
• Zai の処理に通常のクライアントを使用しないでください
• 処理をより小さな単位に分割することを検討します

まとめ

このスキルでは、Botpress ADK のフロントエンド統合に関する全体像を扱います。

主なトピック：

1. PAT と Cookie による認証
2. Zustand によるクライアント管理
3. トリプルスラッシュ参照を使用した型の生成とインポート
4. 完全な型安全性を備えたボットアクションの呼び出し

利用する場面：

• フロントエンド統合に関するあらゆる質問
• 認証とセキュリティのパターン
• 型安全性と生成された型
• クライアントのセットアップと設定
• アクションの呼び出しとエラー処理

重要な原則： 型安全性、セキュリティ、保守性を重視した、本番環境ですぐに使えるパターンを常に提示します。