ツールと連携 — firectl・SDK・FireRouter・FireConnect

これは何か

ここまでの章では、app.fireworks.ai のコンソールと、curl・Python SDK での API 呼び出しを中心に見てきた。本章はその「外側」——コンソール画面を開かずに Fireworks を操作したり、他のツールやコーディングエージェントと繋いだりするための道具箱を扱う。第 2 章で触れたとおり、Fireworks には Web コンソール（app.fireworks.ai）・firectl CLI・OpenAI 互換 API・Anthropic 互換 API・Python SDK という 5 つの入口がある。このうち firectl と Python SDK は自動化寄りの入口で、加えて FireRouter・FireConnect という 2 つのマネージドサービス、そして外部フレームワークとの統合が「道具箱」の中身になる。

この 4 つに加えて、ドキュメント自体を検索できる Fireworks Docs MCP、LangChain・LlamaIndex のような エージェントフレームワーク統合、社内共有ゲートウェイとして使う LiteLLM との連携がある。これらは本章の後半でまとめて扱う。

いつ使うのか

4 つの道具はどれも「コンソールを介さずに Fireworks を操作する」という点では共通しているが、狙いは重ならない。firectl はリソース管理（デプロイメント作成・quota確認・課金の内訳取得など）の自動化に向く。Python SDK はアプリのコードの中から推論を呼びつつ、同じクライアントでプラットフォーム操作もしたいときに向く。FireRouter はモデル選定そのものを自動化したい——「簡単な処理は安いモデルに、難しい処理だけ高品質なクローズドモデルに」を自分で条件分岐せずに実現したいときに使う。FireConnect はコーディングエージェントの設定ファイルを手で書き換えずに Fireworks へ向け先を変えたいときに使う。いずれも「同じ Fireworks のリソース」を操作している点は変わらない。たとえば「CI パイプラインからデプロイメントを立てて壊す」なら firectl、「社内の複数アプリから同じ会計・quota でモデルを呼びたい」なら Python SDK か LiteLLM 経由、「コスト重視の下書きと品質重視の最終稿を自動で切り替えたい」なら FireRouter、「普段使いのコーディングエージェントをそのまま Fireworks 上のモデルに向けたい」なら FireConnect、という具合に選ぶとよい。

firectl — コントロールプレーンを操る CLI

firectl は Fireworks の公式 CLI で、デプロイメント・モデル・quota・課金といったコントロールプレーン（推論そのものではなく、アカウント・モデル・デプロイメントといった資源の作成・変更・削除を担う API 層。推論を実行する側はデータプレーンと呼ぶ）の操作を担う。第 9 章で使った firectl deployment create や第 2 章の firectl api-key create も、この firectl のサブコマンドである。配布は GCS の公開バケットから行われ、OS ごとにインストール方法が分かれる。

# Homebrew（macOS）
brew tap fw-ai/firectl
brew install firectl
# SHA256 チェックが失敗したら先に brew update を試す

# macOS (Apple Silicon)
curl https://storage.googleapis.com/fireworks-public/firectl/stable/darwin-arm64.gz -o firectl.gz
gzip -d firectl.gz && chmod a+x firectl
sudo mv firectl /usr/local/bin/firectl
sudo chown root: /usr/local/bin/firectl

Linux は wget + gunzip + install、Windows は wget -L で firectl.exe を直接取得する。認証は 3 通りある。

firectl のサブコマンドは「リソース名 + 動詞」という一貫した文法で揃っている。firectl deployment create/get/list/delete（デプロイメント）、firectl model list/get/create（モデル）、firectl user create/update/delete（ユーザー）、firectl quota list（クォータ確認）、firectl billing get-usage（課金の内訳取得）というように、扱いたい対象と操作を組み合わせるだけで大半のコマンドを推測できる。第 2 章の api-key create、第 9 章の deployment create も同じ文法の一部である。

サインイン後は firectl whoami でサインイン先を確認でき、firectl version でインストール済みのバージョンが分かる。この確認は儀式ではない。たとえば --preemptible フラグは firectl 1.7.26 未満だとエラーも出さずに無視され、通常の on-demand デプロイとしてそのまま課金される。バージョンが古いと気づかないままトラブルになる典型パターンなので、新しい機能を試す前には firectl version を確認し、必要なら sudo firectl upgrade で更新する習慣をつけておきたい。

Python SDK — alpha 版の自動化クライアント

Fireworks の公式 Python SDK は GitHub で公開されており、PyPI にはパッケージ名 fireworks-ai として配布されている。OpenAI SDK でも Fireworks は呼べる（第 2 章参照）が、公式は Fireworks SDK を使う理由として次の 3 点を挙げている。

• 並列性のデフォルトが良い — 高スループット向けに最適化されたコネクションプーリング
• Fireworks 固有の機能 — OpenAI API に無いパラメータやレスポンスフィールドが使える
• プラットフォーム自動化 — データセット・eval・学習・デプロイメントをコードから操作できる

この SDK は 2026-09 時点で alpha 段階にあり、インストール時に --pre フラグが必須になる。

pip install --pre fireworks-ai
# poetry add --pre fireworks-ai / uv add --pre fireworks-ai も同様

要件は Python 3.9 以上。クライアントは同期の Fireworks と非同期の AsyncFireworks の 2 クラスがあり、Fireworks() を引数なしで呼ぶと環境変数 FIREWORKS_API_KEY から自動でキーを読む。

from fireworks import Fireworks

client = Fireworks()
response = client.chat.completions.create(
    model="accounts/fireworks/models/glm-5p2",
    messages=[{"role": "user", "content": "Say hello in Spanish"}],
)
print(response.choices[0].message.content)

並行してたくさんのリクエストを捌きたい場合は、非同期クライアントの AsyncFireworks を使う。AsyncFireworks(max_retries=5) のように最大リトライ回数を渡せ、asyncio と組み合わせて使う設計になっている。docs 内でコード例が確認できているのは、同期クライアントの chat.completions.create（Fireworks()）と、この非同期クライアントの 2 パターンのみである。

alpha である以上、破壊的変更が入る可能性がある。本番で使うなら requirements にバージョンを固定しておくのが安全である。使い方の詳細（メソッド一覧など）は docs.fireworks.ai には無く、GitHub の README に委ねられている点も覚えておきたい。

FireRouter — オープンモデルとクローズドモデルを自動で使い分ける

FireRouter は、リクエストごとに複雑さを評価し、Fireworks のオープンモデルとクローズドモデル（Claude Opus 5 など）を自動で選び分けるマネージドルーティングサービスである。2026-09 時点で research previewにあり、公式も「API・ルーティングの挙動・組み合わせるモデルは変わり得る」と明記している。以下のモデル名・料金の扱いはすべて取得時点（2026-09-01）の構成として読んでほしい。

FireRouter は BYOK（bring-your-own-key）モデルを取る。Fireworks API キーは FireRouter への認証と Fireworks モデルの支払いに使われ、Anthropic や OpenAI のようなプロバイダキーは対象プロバイダのモデル呼び出し分の支払いに使われる。プロバイダキーはサーバ側に保存されず、毎リクエスト送る必要がある。モデル指定は model フィールドに firerouter（または accounts/fireworks/routers/firerouter）を渡すだけで、リクエストの都度どのモデルが処理したかは FireRouter 側が決める。

curl https://api.fireworks.ai/inference/v1/chat/completions \
  -H "Authorization: Bearer $FIREWORKS_API_KEY" \
  -H "x-anthropic-api-key: $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "firerouter",
    "messages": [{"role": "user", "content": "Say pong in one word."}]
  }'

スラッシュ区切りの slug（モデルの組み合わせを表す識別子。例: firerouter/kimi-k3/glm-5p2-fast）を使うと、ルーティング対象のモデルを最大 8 個まで自分で組み替えられる。先頭が primary で、そのクレデンシャルは必須。2 番目以降はキーがあれば候補に入り、無ければ黙って外れる。Claude 系のキーは x-anthropic-api-key、OpenAI 系は x-openai-api-key ヘッダで渡す。既定の firerouter は primary が Claude Opus 5 なので Anthropic キーが必須で、無い場合はエラーになる（GLM だけに黙って絞られることはない）。

コストと品質のどちらに寄せるかは、x-routing-preference ヘッダで調整できる。FireConnect 経由なら --routing-preference フラグとして渡す（対応は Claude Code・OpenCode・Pi・VS Code のみで、Codex・Cursor・DeepSeek Harness は非対応）。値は 1〜5、既定は 3 で、1（max-intelligence）に近いほど品質寄り（クローズドモデルへ回りやすい）、5（max-savings）に近いほどコスト寄り（オープンモデルへ回りやすい）になる。ヘッダが未指定・不正・範囲外の場合は既定の 3（balanced）が使われる。

fireconnect claude on --model firerouter --routing-preference 4

この例の 4（more-savings）は、既定の 3 からコスト寄りに 1 段倒す設定である。

ここで名前が紛らわしいものがもう 1 つある。第 9 章で触れた Router（firectl router create で作る、自分の Deployment 間でトラフィックを分割する仕組み）と FireRouter は別物である。

FireConnect — コーディングハーネスを Fireworks 経由に切り替える

FireConnect は、Claude Code・Codex・Cursor・OpenCode などのコーディングエージェント（公式は「ハーネス」と呼ぶ）の設定ファイルを手で書き換えずに、Fireworks 経由の推論へ切り替えるオープンソースの CLI である。インストールは 1 行、サインインも 1 回で済み、あとはハーネスごとに on / off を切り替えるだけになる。

curl -fsSL https://raw.githubusercontent.com/fw-ai/fireconnect/main/install.sh | bash
fireconnect login

要件は Node.js 18 以上。インストーラは ~/.fireconnect/cli に CLI を clone し、~/.local/bin/fireconnect を追加するだけで、サインインやハーネス設定の書き込みは行わない。Windows では Git Bash から実行する必要がある。PowerShell にパイプすると改行コードが壊れ、set: pipefail\r: invalid option name というエラーになる。

対応ハーネスは 7 種類あり、機能ごとに対応状況が異なる。

Fireworks ゲートウェイ自体は全ハーネスで使えるが、FireConnect 経由では Fire Pass は Codex だけ使えず、Microsoft Foundry は Claude Code と DeepSeek Harness だけ使えない。FireRouter を使うには標準の Fireworks キー（fw_...）が必須で、Fire Pass キー（fpk_...）は全ハーネスで拒否される。Cursor と DeepSeek Harness だけは、ローカルの Anthropic キーを直接添付できないため「Workspace BYOK」という別経路になる。

Claude Code を例に、実際に何が起きるかを見てみる。

fireconnect login
fireconnect claude on

実行すると ~/.claude/settings.json に次のような設定が書き込まれる。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.fireworks.ai/inference",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "firerouter[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-flash-latest[1m]",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Fireworks-Api-Key: YOUR_FIREWORKS_API_KEY"
  }
}

ANTHROPIC_BASE_URL が /v1 を含まない点に注意したい。Claude Code 側が /v1/messages を付け足すためで、curl で直接叩くときの https://api.fireworks.ai/inference/v1/messages とは書き方が異なる。認証は apiKeyHelper ではなく ANTHROPIC_CUSTOM_HEADERS 経由の X-Fireworks-Api-Key ヘッダで行われ、キーは settings.json にパーミッション 0600 の平文で書き込まれる。以前の設定は ~/.fireconnect/claude/ にバックアップされており、fireconnect claude off でいつでも元に戻せる。

スロットは main / opus / sonnet / haiku / fable / subagent の 6 つあり、--opus や --sonnet で個別に上書きできる。fireconnect claude on --model firerouter と --anthropic-api-key を組み合わせれば、Claude Code から直接 FireRouter のルーティングを使うこともできる。使用量は Claude Code の /model 画面には出ない（そこに出るのは Anthropic の定価であって Fireworks の料金ではない）ため、実際の支出は fireconnect claude usage でセッションログから見積もる。

もう 1 つ、実際に踏みやすい罠がある。Claude Code はモデルを「画像非対応」としてマークする仕組みを持たないため、glm-fast-latest や deepseek-flash-latest のようなテキスト専用モデルを割り当てたスロットに画像を貼り付けると、セッションが壊れることがある。壊れた場合は /rewind で復旧し、そのスロットには画像を貼らないか、kimi-fast-latest のような画像対応モデルに割り当て直す。fireconnect claude status は各スロットを vision / text-only のラベル付きで表示するので、事前に確認しておくと事故を避けられる。

Fire Pass — 個人のコーディング用途向け無料パス

Fire Pass は、Claude Code・OpenCode・Codex・Pi などのエージェンティックなコーディングハーネスで、特定のオープンウェイトモデルをトークン課金ゼロで使える実験的なパスである（これは利用規約が許可するハーネスの一覧であり、前節の FireConnect 対応表とは別の話である。FireConnect の対応表は Codex の Fire Pass を非対応としているが、Fire Pass ページ側は Codex にも FireConnect の利用を案内しており記述が割れているため、Codex で使うなら Fire Pass ページの手動設定値も確認するとよい）。2026-09 時点で招待制（invite only）であり、機能・提供状況・価格は変わり得ると公式が明記している。

有効化はコンソールの Fire Pass ページ（app.fireworks.ai/fire-pass）でプロモコードを入力するだけで即時反映される。手動でエンドポイントを設定する場合の専用モデル ID は router リソースの accounts/fireworks/routers/kimi-k3-fast（ピン留め ID）で、通常の models/ ではない点に注意したい。FireConnect が設定ファイルに書き込むのはこのピン留め ID ではなくエイリアスの方で、Fire Pass キー（fpk_...）を検出すると全スロットをエイリアス kimi-fast-latest に割り当てる。

最も重要なのは利用規約である。Fire Pass は本番ワークロードでの利用が禁止されている。許されるのは個人の開発・実験・コーディングハーネスでの利用に限られ、違反はパスの取消しにつながる。ダッシュボードには利用量そのものは記録されるが、コストは対象モデルである限り $0.00 と表示される。

Docs MCP と外部エコシステム

Fireworks はドキュメント自体を MCP サーバとして公開しており、Claude Code や Cursor から自然文でドキュメントを検索できる。エンドポイントは https://docs.fireworks.ai/mcp（HTTP transport）で、公式が案内する設定は URL 1 行だけであり、API キーやトークンの入力欄は無い。

claude mcp add --transport http fireworks-docs https://docs.fireworks.ai/mcp

設定後は「デプロイメントのオートスケールはどう設定する？」のような質問をエージェントに投げると、ドキュメントを検索して答えてくれる。同じ仕組みで、docs.fireworks.ai は llms.txt に全ページのインデックスを持ち、任意のページ URL の末尾に .md を付けると生の Markdown が返る。MCP を使わなくても curl だけでドキュメント全体を機械的に読めるということでもある。

エージェントフレームワークとの統合は LangChain・LlamaIndex・CrewAI・PydanticAI・Strands Agents・AWS AgentCore の 6 つが案内されている。ただし Fireworks 側のページはほぼリンク集で、実装手順の大半は各フレームワークの公式ドキュメントに委ねられている（AWS AgentCore のみ Fireworks 内に専用ページがある）。可観測性は用途で 2 つに分かれる。Weights & Biases は学習実験のトラッキング、MLflow は推論のプロンプト・出力・レイテンシのトレーシングに使う。専有デプロイのメトリクス監視自体は第 9 章で触れた Prometheus 形式のエクスポートの方が詳しい。

社内で複数の開発者に Fireworks を安全に使わせたい場合は LiteLLM Proxy（2026-09 時点で公式が案内するバージョンは 1.95.0）を共有ゲートウェイとして立てるパターンがある。Fireworks のサービスアカウントキーをプロキシ側に 1 本だけ置き、開発者にはプロキシの仮想キーを配ることで、アクセス制御と支出の按分ができる。設定ファイルでは 必ずフルリソースパス（accounts/fireworks/models/... や accounts/fireworks/routers/...）を書く必要がある。この落とし穴は次の「つまずきポイント」でまとめて扱う。鍵の持ち方は「Fireworks API キーはプロキシサーバの環境変数、開発者ごとの認証は LiteLLM の仮想キー」という 2 段構えが公式の推奨パターンで、プロキシは既定でポート 4000 に立ち上がる。仮想キーはプロキシへの認証と支出の按分に使われ、Fireworks 側のキーそのものを開発者に配らずに済む。

curl https://storage.googleapis.com/fireworks-public/firectl/stable/darwin-arm64.gz -o firectl.gz
gzip -d firectl.gz && chmod a+x firectl
sudo mv firectl /usr/local/bin/firectl
sudo chown root: /usr/local/bin/firectl

firectl signin

firectl whoami

firectl version

firectl model list

claude mcp add --transport http fireworks-docs https://docs.fireworks.ai/mcp

{
  "mcpServers": {
    "fireworks-docs": {
      "url": "https://docs.fireworks.ai/mcp"
    }
  }
}

つまずきポイント

理解度チェック

まとめ

• firectl はコントロールプレーンの CLI、Python SDK（alpha）は推論とプラットフォーム自動化を両方コードから呼ぶためのクライアント
• FireRouter（research preview）はリクエストの複雑さでオープンモデルとクローズドモデルを自動選択する。自分の Deployment を束ねる Router とは別物
• FireConnect はコーディングハーネスの設定ファイルを書き換えて Fireworks 経由に挟み替える。書き込まれる内容とバックアップの仕組みを知っておくと事故を避けやすい
• Fire Pass は招待制・本番利用禁止の無料パス。Docs MCP は URL 1 行の設定だけでドキュメントをそのまま検索できる
• LiteLLM・エージェントフレームワークとの連携は「フルリソースパスを書く」「Fireworks 側は入口の紹介にとどまる」という 2 点を覚えておけば実務で困らない

この後、どこから深めるか — 全 14 章ガイドマップ

これで全 14 章を読み終えたことになる。もう一度どこかを読み返したくなったら、次の地図を使ってほしい。

• 第 I 部　全体像をつかむ — 第 1 章　Fireworks AI とは何か・第 2 章　はじめの一歩
• 第 II 部　モデルを探して試す — 第 3 章　Model Library・第 4 章　Playground
• 第 III 部　API で使いこなす — 第 5 章　Serverless 推論・第 6 章　画像・音声・Embeddings・第 7 章　開発を助ける機能・第 8 章　Batch API
• 第 IV 部　自分のモデルを作って運用する — 第 9 章　Deployments・第 10 章　Datasets・第 11 章　Fine-Tuning・第 12 章　Evaluations
• 第 V 部　チームで運用する — 第 13 章　アカウント運用・本章（第 14 章　ツールと連携）

公式ドキュメントを自分で歩きたくなったら、docs.fireworks.ai/llms.txt が全ページのインデックスになっている。任意のページ URL の末尾に .md を付ければ生の Markdown が返るので、本章で設定した Fireworks Docs MCP（docs.fireworks.ai/mcp）からも、curl からも同じ内容にたどり着ける。コード例をまとめて見たいときは Cookbook、疑問を人に聞きたいときは公式サイトから辿れる Discord コミュニティが助けになる。

参考リンク

• firectl — Getting started
• firectl — Authentication
• Python SDK
• FireRouter — Overview
• FireRouter — Quickstart
• FireConnect — Overview
• FireConnect — Claude Code
• Development Setup with Fireworks Docs MCP
• LiteLLM
• Fire Pass Setup