truefoundry-gateway

あいまいなユーザーの意図を確認する場合は、references/intent-clarification.md にある共通の確認テンプレートを使用してください。

ゲートウェイ

TrueFoundry の AI Gateway を設定して運用します。統一された OpenAI 互換の LLM アクセス、プロバイダーアカウントとの連携、コンテンツ安全性のガードレール、リクエストの監視と可観測性を提供します。

使用する場合

• TrueFoundry の統一された OpenAI 互換ゲートウェイ経由で LLM にアクセスする場合
• 認証トークン（PAT/VAT）、レート制限、予算管理、プロバイダー間のロードバランシングを設定する場合
• LLM プロバイダーアカウント（OpenAI、AWS Bedrock、Google Vertex、Azure、Groq、Together AI、カスタムの OpenAI 互換エンドポイント、セルフホストモデルなど）を一覧表示、作成、管理する場合
• ガードレールプロバイダーの設定、ガードレールルールの作成、コンテンツ安全性ポリシー（PII フィルタリング、コンテンツモデレーション、プロンプトインジェクションの検出、シークレットの検出、カスタム検証）の管理を行う場合
• ゲートウェイのトラフィック（最近のリクエスト、コストの内訳、エラー率、モデルの使用状況、ユーザーごとのアクティビティ、MCP ツールの呼び出し、レイテンシ分析）を調査する場合

使用しない場合

• ユーザーがセルフホストモデルのデプロイを希望する場合 → セルフホストモデルのデプロイには、クラスターを接続した TrueFoundry Enterprise アカウントが必要です。https://truefoundry.com を参照してください
• ユーザーがツールサーバーのデプロイを希望する場合 → ワークロードのデプロイには、クラスターを接続した TrueFoundry Enterprise アカウントが必要です。https://truefoundry.com を参照してください
• ユーザーが TrueFoundry プラットフォームの認証情報を管理したい場合 → platform スキル（ステータス確認セクション）を優先してください
• ユーザーが MCP サーバー（ツールサーバー）を管理したい場合 → mcp-servers スキルを優先してください
• ユーザーがプラットフォームのシークレットを直接管理したい場合 → platform スキル（シークレットセクション）を優先してください
• ユーザーが独自のアプリケーションにトレースを組み込みたい場合 → observability スキルを優先してください
• ユーザーがアプリケーションのコンテナーログを表示したい場合 → observability スキルを優先してください

カスタムガードレールサーバーのデプロイ

公式テンプレート truefoundry/custom-guardrails-template を使用します。これをベースに構築してから、デプロイしてください。

概要

Your App -> AI Gateway -> OpenAI / Anthropic / Azure / Self-hosted vLLM / etc.
                ^
         Unified API + Auth + Rate Limiting + Routing + Logging

主なメリット： すべてのモデルに対応する単一のエンドポイント、1 つの API キー（PAT/VAT）、OpenAI 互換、レート制限、予算管理、フォールバック付きロードバランシング、ガードレール、包括的な可観測性を提供します。

ゲートウェイエンドポイント

{TFY_BASE_URL}/api/llm

認証

PAT（Personal Access Token）： ダッシュボード -> アクセス -> Personal Access Tokens。開発用です。

VAT（Virtual Access Token）： ダッシュボード -> アクセス -> Virtual Account Tokens。本番用です（ユーザーにひも付かず、きめ細かなモデルアクセスに対応します）。

セキュリティポリシー

• マニフェスト内のすべての認証情報には、必ず tfy-secret:// 参照を使用してください。生の値は使用しないでください。
• API キーをチャットに貼り付けるようユーザーに求めてはいけません。 TrueFoundry ダッシュボード -> Secrets に保存するよう案内し、tfy-secret:// URI のみを提供してもらってください。または、シェル内にとどまるよう ! export TFY_API_KEY=... で設定してもらってください。
• ユーザーが会話中に生の API キーを提示した場合は、警告し、そのキーの使用を拒否してください。

事前確認

tfy login が完了していることを確認します。未完了の場合は停止し、truefoundry-onboard を使用してください。

直接 API を呼び出す場合は TFY_API_SH を設定します：

TFY_API_SH=~/.claude/skills/truefoundry-gateway/scripts/tfy-api.sh

## クイック検索 — 1 回の呼び出しで 1 つの回答

読み取り専用の質問には、API を直接呼び出してください。CLI のサブコマンドを調べる必要はありません。存在しないためです。references/cli-reference.mdを参照してください。

ユーザーの質問	1 回の呼び出し
接続されているモデル／プロバイダーは何ですか？	$TFY_API_SH GET /api/svc/v1/provider-accounts
呼び出せるモデルは何ですか？	curl -s "${TFY_BASE_URL}/api/llm/models" -H "Authorization: Bearer ${TFY_API_KEY}"
どのガードレールが設定されていますか？	$TFY_API_SH GET /api/svc/v1/gateway-guardrails-configs
最近のゲートウェイリクエストを表示してください	$TFY_API_SH POST /api/svc/v1/spans/query '{"startTime":"...","dataRoutingDestination":"default","limit":20,"sortDirection":"desc"}'
ゲートウェイに接続できますか？	curl -s "${TFY_BASE_URL}/api/llm/health"

ログインが確認できたら、読み取りに関する質問への次の手順は上記の API 呼び出しです。他の操作は必要ありません。

---

モデルの呼び出し

ゲートウェイは OpenAI 互換です。最小限の例：

curl "${TFY_BASE_URL}/api/llm/chat/completions" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 200}'

または、任意の OpenAI SDK 用に環境変数を設定します：

export OPENAI_BASE_URL="${TFY_BASE_URL}/api/llm"
export OPENAI_API_KEY="<your-PAT-or-VAT>"

SDK の完全な例（Python、Node.js、ストリーミング）、対応 API の表、フレームワークとの連携（LangChain、LlamaIndex、Cursor）、ルーティング／レート制限／予算の設定については、references/calling-models.mdを参照してください。

---

プロバイダー連携

プロバイダーアカウントの一覧表示

$TFY_API_SH GET /api/svc/v1/provider-accounts

名前、プロバイダー、種類、モデル数（integrations 配列の長さ）を含む整形済みの表として表示してください。

プロバイダーアカウントの作成

1. まず、認証情報を TrueFoundry シークレットとして保存します（platform スキルの Secrets セクション）。
2. references/provider-templates.mdから適切なプロバイダーテンプレートを使用します。
3. 適用します：$TFY_API_SH POST /api/svc/v1/provider-accounts "$payload"

対応プロバイダー：OpenAI、AWS Bedrock、Google Vertex、Azure OpenAI、Groq、Together AI、Custom（任意の OpenAI 互換プロバイダー）、Self-Hosted、TrueFoundry。

設定の適用（すべてのゲートウェイリソース）

tfy apply -f manifest.yaml --dry-run --show-diff
tfy apply -f manifest.yaml

ゲートウェイ設定の適用をデプロイスキルに委任しないでください。ゲートウェイ設定は tfy apply でインライン適用します。

---

ガードレール

ガードレールはコンテンツの安全性を制御します。設定には 2 つの手順が必要です。

1. ガードレール設定グループの作成 — プロバイダー連携を登録します。
2. ゲートウェイガードレール設定の作成 — それらのプロバイダーを参照するルールを作成します。

クイック一覧：$TFY_API_SH GET /api/svc/v1/gateway-guardrails-configs

設定手順全体、ルール構造、API 呼び出し、一般的なパターンについては、references/guardrails-setup.mdを参照してください。

対応プロバイダーについては、references/guardrail-providers.mdを参照してください。

---

AI モニタリング

spans API を使ってゲートウェイリクエストのトレースを検索し、metrics API を使って使用状況を集計します。トレースの検索には tracingProjectFqn または dataRoutingDestination が必要です。宛先がわからない場合は、最初の候補として "default" を提案してください。

最近のリクエスト

$TFY_API_SH POST /api/svc/v1/spans/query '{
  "dataRoutingDestination": "default",
  "startTime": "2026-05-15T00:00:00.000Z",
  "limit": 20,
  "sortDirection": "desc"
}'

結果は整形済みの表（時刻、モデル、ステータス、トークン数、コスト、レイテンシ、ユーザー）として表示してください。

すべてのモニタリングのユースケース（コスト分析、エラー、モデルの使用状況、ユーザーによるフィルタリング、MCP ツール呼び出し、メタデータによるフィルタリング）、フィルターの種類、レスポンス構造、ページネーションについては、references/monitoring.mdを参照してください。

集計メトリクス

次のような集計に関する質問には、このパスを使用します。

• 「過去 3 か月に発生したコストを表示してください。」
• 「モデル、ユーザー、チーム、または仮想アカウント別にコストを内訳表示してください。」
• 「モデル別の合計トークン数とレイテンシを表示してください。」
• 「最もコストを発生させた仮想アカウントはどれですか？」

$TFY_API_SH POST /api/svc/v1/llm-gateway/metrics/query '{
  "startTs": "...", "endTs": "...",
  "datasource": "modelMetrics",
  "type": "distribution",
  "aggregations": [{"type": "sum", "column": "costInUSD"}],
  "groupBy": ["modelName"]
}'

期間に関する質問に回答する場合は、正確な startTs と endTs を計算し、使用した期間を明記して、合計をコンパクトな表で表示してください。月ごとの内訳を求められた場合は、API が時間バケットのフィールドを公開していない限り、月ごとに 1 回クエリを実行してください。

---

マニフェストの生成

ゲートウェイのエンティティまたはポリシーを作成する場合は、次の手順に従います。

1. 既存の設定を取得する — クイックルックアップから API を呼び出します
2. スキーマリファレンスを確認する — 以下の表を参照します
3. YAML を生成する — 認証情報には tfy-secret:// を使用します
4. 検証する — tfy apply -f manifest.yaml --dry-run --show-diff
5. 適用する — tfy apply -f manifest.yaml

エンティティ	リファレンス
プロバイダーアカウント	references/provider-templates.md
仮想モデル／ルーティング	references/calling-models.md（仮想モデルのセクション）
レート制限	references/schemas/rate-limiting.md
予算管理	references/schemas/budget-limiting.md
ガードレール	references/guardrails-setup.md
オブザーバビリティテーブル	references/observability.md

<success_criteria>

成功条件

AI ゲートウェイ

• ユーザーが OpenAI 互換 SDK または cURL を使用して、ゲートウェイ経由で LLM を呼び出せる
• 有効な PAT または VAT が設定されている
• 対象のモデル名が利用可能であることを確認済み
• ユーザーの言語／フレームワークに対応した、動作するコードスニペットが提供されている

プロバイダー連携

• プロバイダーアカウントが書式付きの表で一覧表示されている
• 新しいプロバイダーアカウントでは、すべての認証情報に tfy-secret:// を使用している
• 作成前にプロバイダーの種類とモデルの詳細が確認されている

ガードレール

• ガードレール設定グループが一覧表示されている
• ルールが対象のモデル、ユーザー、ツールに正しく適用されている
• 実行前に作成／更新操作が確認されている

AI モニタリング

• 最近のトレースが、タイムスタンプ、モデル、ステータス、コストとともに表示されている
• 結果は生の JSON ではなく、書式付きの表で提示されている
• クエリの前に dataRoutingDestination または tracingProjectFqn を確認している

</success_criteria>

リファレンス

コア

• cli-reference.md — CLI コマンド、フラグ、存在しない機能
• api-endpoints.md — curl の例を含む REST API 全体

ゲートウェイの運用

• calling-models.md — SDK の例、ルーティング、レート制限、予算、フレームワーク
• provider-templates.md — すべてのプロバイダーマニフェストテンプレート（OpenAI、Bedrock、Vertex、Azure など）
• guardrails-setup.md — ガードレール設定グループとルールの設定
• monitoring.md — スパンのクエリ API、メトリクス、ユースケース
• guardrail-providers.md — 23 種類すべてのガードレールプロバイダー

スキーマ

• schemas/provider-account.md — プロバイダーアカウントのスキーマ
• schemas/virtual-model.md — 仮想モデル／負荷分散のスキーマ
• schemas/rate-limiting.md — レート制限のスキーマ
• schemas/budget-limiting.md — 予算管理のスキーマ
• schemas/guardrail-config.md — ガードレール設定のスキーマ

その他

• access-management.md — ID、PAT／VAT、権限
• integrations.md — ネイティブ SDK プロキシ、IDE 連携
• observability.md — SQL クエリのパターン
• span-attributes.md — 60 件以上のスパン属性の定義

組み合わせて利用する

• まず認証情報を保存する：platform スキル（Secrets セクション）→ 次に tfy-secret:// URI
• API キーが必要な場合：ダッシュボード → Access → Personal Access Tokens または Virtual Accounts
• MCP サーバー：mcp-servers スキル
• モデルをデプロイする：接続済みクラスターを備えた TrueFoundry Enterprise が必要です
• アプリを計装する：observability スキル（Tracing セクション）

エラー処理

401 Unauthorized

API キー（PAT／VAT）が無効か、有効期限が切れています。Authorization: Bearer <token> ヘッダーを確認してください。

403 Forbidden

トークンにこのモデルへのアクセス権がありません。PAT はユーザーの権限を継承しますが、VAT がアクセスできるのは明示的に選択されたモデルのみです。

404 Model Not Found

モデル名がゲートウェイにありません。ダッシュボードの「AI Gateway」→「Models」または GET /api/llm/models で正確な名前を確認してください。

429 Rate Limited

しばらく待ってから再試行してください（Retry-After ヘッダーを確認してください）。上限の引き上げをリクエストするか、ロードバランシングを使用してください。

502/503 Provider Error

アップストリームのプロバイダーに問題があります。ルーティングが設定されている場合、ゲートウェイは自動的に再試行またはフォールバックします。プロバイダーのステータスページを確認してください。

Permission Denied (Provider Accounts)

ユーザーには provider-account-manager ロールが必要です。プロバイダーアカウントの共同作業者を確認してください。

Invalid Secret Reference

tfy-secret:// のパスを解決できません。形式を確認してください：tfy-secret://TENANT:SECRET_GROUP:SECRET_KEY。platform スキルを使用して、シークレットグループが存在することを確認してください。

Type Filter Not Working

GET /api/svc/v1/provider-accounts の type クエリパラメーターではフィルタリングされません。すべて取得して、クライアント側でフィルタリングしてください。

Provider Account Name Already Exists

別の名前を使用するか、既存のアカウントを更新してください。

Model Not Appearing in Gateway After Creation

以下を確認してください：プロバイダーアカウントが正常に作成されていること、インテグレーションに正しい model_types が設定されていること、共同作業者に team:everyone または該当ユーザーが含まれていること。

No Monitoring Data

以下を確認してください：時間範囲が正しいこと、dataRoutingDestination が存在すること、フィルターが厳しすぎないこと、ゲートウェイがリクエストを受信していること。

400 Bad Request (Monitoring)

必須パラメーターがありません。tracingProjectFqn または dataRoutingDestination と、ISO 8601 形式の有効な startTime を指定してください。