Tied Workspace

Appearance

ADR 0002: LLM 呼び出しを Cloudflare AI Gateway 経由に統一する (Mastra 不採用) ​

この ADR は置換されました

「AI Gateway 経由に統一」「Mastra 不採用」の決定は ADR 0007 にそのまま引き継がれた。変更点はエージェント実装基盤で、素の Vercel AI SDK ではなく Cloudflare Agents SDK を採用し、専門エージェント網（delegateToTeam + 11 体）は廃止とした。

Context ​

tied-bot は Mastra フレームワーク上に約 12 のエージェント（botAgent + 11 の専門エージェントによる team-coordination network）とメモリシステムを構築し、OpenAI / Anthropic を直接呼んでいた。

  • Mastra（@mastra/*）は Node/Bun ランタイム前提で、Cloudflare Workers では動作しない。
  • tied-workspace は packages/cloudflare の AiGatewayClient を通じて Cloudflare AI Gateway 経由でモデルを呼ぶ既存パターンを持つ（Voyage 埋め込み・Gemini 画像生成）。AI Gateway はレート制御・キャッシュ・ログ・コスト可視化を一元化できる。
  • ユーザー要件として「API は Cloudflare AI Gateway 経由で使いたい」が確定している。

Decision ​

  • すべての LLM / 埋め込み / 画像生成の呼び出しを Cloudflare AI Gateway 経由に統一する。
  • Mastra フレームワークは採用しない。エージェント・ツール呼び出しは Vercel AI SDK (ai + 各プロバイダ) で実装し、プロバイダの baseURL を AI Gateway エンドポイントに向ける。
  • packages/cloudflare の AiGatewayClient を拡張し、chat completions（OpenAI / Anthropic） と テキスト埋め込み を追加する。

Consequences ​

  • 良い点: モデル呼び出しが Cloudflare で一元管理され、キャッシュ・レート制御・ログ・コスト可視化を共通化。Workers / コンテナのどちらからも同一クライアントで利用可能。Mastra 固有ランタイム制約から解放される。
  • 悪い点 / 注意: Mastra が提供していた エージェント網（11 専門エージェント）とメモリシステムを AI SDK で再実装する必要がある（最大の工数）。まずは単機能の botAgent（fetchUrl / fetchWorkspaceGuide）を移植してコア会話を成立させ、専門エージェント網は後続フェーズで判断する（単一エージェント + プロンプト統合での代替も選択肢）。
  • フォローアップ: AI Gateway の Gateway ID / 対応プロバイダ・モデル・キー管理（CLOUDFLARE_ACCOUNT_ID / AI_GATEWAY_ID / 各プロバイダキー）を整理。埋め込みモデル（OpenAI text-embedding-3-small 相当 or Voyage）を確定する。

Alternatives ​

  • Mastra をコンテナ内で維持: Bun コンテナなら動作するが、モデル呼び出しが AI Gateway を経由せず一元管理の利点を失う。ユーザー要件にも反する。却下。
  • 各プロバイダ SDK を直接利用（Gateway なし）: 実装は最短だが、キャッシュ・レート制御・ログを失い、既存 AiGatewayClient 資産と不整合。却下。