CrewAI OpenAI互換ルーター：マルチエージェントワークフローを1つのキーで

CrewAI OpenAI互換ルーターの設定は、ワークフローのすべてのロールにプロバイダーキー、ベースURL、モデルエイリアスを散在させるのではなく、複数のCrewAIエージェントに1つのゲートウェイ境界を使用させたい場合に便利です。

CrewAIの現在のLLMドキュメントでは、OpenAI互換エンドポイントに対して2つの重要な設定パスが示されています。それは、OPENAI_API_BASEのような環境変数と、model、base_url、api_keyのような明示的なLLM(...)属性です。Flatkeyはその境界に適合します。その公開サイトは、OpenAI互換クライアントをhttps://router.flatkey.ai/v1に向け、製品ダッシュボードで利用状況、コスト、ルーティング、エラーのレビューが可能です。

このガイドでは、マルチエージェントワークフローのための実践的なCrewAI OpenAI互換ルーターのパターンを紹介します。コードはテンプレートです。本番環境のエージェントをルーティングする前に、ご自身のFlatkeyキーを使用して、正確なモデルエイリアス、ツールの動作、ログを検証してください。

CrewAI OpenAI互換ルーターのクイックアンサー

1つのゲートウェイAPIルートと明示的なルート名を使用してください。プロンプトテキストにルーティングを埋め込まないでください。

これがCrewAI OpenAI互換ルーターパターンの核心です。CrewAIにはオーケストレーションを、FlatkeyにはOpenAI互換のゲートウェイ境界を担当させ、運用上のチェックを可視化します。

マルチエージェントワークフローにゲートウェイ境界が必要な理由

CrewAIのワークフローは、多くの場合、1人のマネージャーエージェント、数人のスペシャリストエージェント、そして最終的なタスクというシンプルな形から始まります。これは、ワークフローがデモから他のチームが依存するサービスに移行するまでは機能します。

本番環境のマルチエージェントシステムは通常、単に機能する応答以上のものを必要とします。

関連する設計制御については、Flatkeyのガイド「AIエージェントゲートウェイ制御」を参照してください。CrewAI OpenAI互換ルーターは、これらの制御を各エージェントのロールに対して具体的にする必要があります。

ステップ1：Flatkeyのルート値を作成する

このワークロード用にFlatkeyキーを1つ作成し、ルート値はソース管理外に保管してください。

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_DEFAULT_MODEL=your-default-flatkey-model-alias
FLATKEY_PLANNER_MODEL=your-planner-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias
FLATKEY_VERIFIER_MODEL=your-verifier-model-alias

APIルートはエンドポイントパスとは別にしてください。CrewAIのLLMオブジェクトはベースURLを受け取る必要があります。直接のcurlテストでは/chat/completionsを追加します。

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_DEFAULT_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

この直接リクエストが失敗した場合は、まずFlatkeyキー、モデルエイリアス、エンドポイントファミリー、またはアカウントルートを修正してください。CrewAI OpenAI互換ルーターは、ゲートウェイアカウントが呼び出せないモデルエイリアスを補うことはできません。

ステップ2：CrewAIのLLMオブジェクトを明示的に設定する

CrewAIはbase_urlを介してLLMのベースAPI URLを設定することをサポートしており、そのドキュメントでは、環境変数またはLLMクラス属性のいずれかによるOpenAI互換LLMの設定が示されています。本番環境での作業では、各エージェントのロールが既知のルートを指すため、明示的なLLMオブジェクトの方がレビューが容易です。

import os

from crewai import Agent, Crew, LLM, Process, Task


BASE_URL = os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]


def flatkey_llm(model_env: str, temperature: float = 0.2) -> LLM:
    return LLM(
        model=os.environ[model_env],
        base_url=BASE_URL,
        api_key=API_KEY,
        temperature=temperature,
    )


planner_llm = flatkey_llm("FLATKEY_PLANNER_MODEL", temperature=0.1)
tool_llm = flatkey_llm("FLATKEY_TOOL_MODEL", temperature=0.0)
verifier_llm = flatkey_llm("FLATKEY_VERIFIER_MODEL", temperature=0.0)

これは、CrewAI OpenAI互換ルーターへの移行において最も重要なセットアップの決定です。モデルエイリアスは環境によって変更できますが、CrewAIコードは1つのOpenAI互換APIルートと1つのゲートウェイキー所有者を保持します。

ステップ3：エージェントの責任に応じてルートを割り当てる

各CrewAIエージェントに、そのリスクプロファイルに一致するLLMルートを与えます。小さなルートセットから始めます。最初のポリシーが機能することをログで証明した後、いつでも後から役割をさらに分割できます。

planner = Agent(
    role="ワークフロープランナー",
    goal="リクエストを短い実行計画に分割する。",
    backstory="あなたはクルーの範囲を限定し、不要なモデル呼び出しを避けます。",
    llm=planner_llm,
)

researcher = Agent(
    role="リサーチャー",
    goal="タスクに必要な事実のみを収集する。",
    backstory="あなたは広範な憶測よりも、情報源に裏付けられたメモを好みます。",
    llm=planner_llm,
)

tool_user = Agent(
    role="ツールオペレーター",
    goal="タスクが必要とする場合にのみ、承認されたツールを使用する。",
    backstory="あなたは外部システムを呼び出す前に、ツールの入力を検証します。",
    llm=tool_llm,
)

verifier = Agent(
    role="検証者",
    goal="最終的な回答を要件と証拠と照らし合わせて確認する。",
    backstory="あなたは、欠落している証拠、ツールエラー、ロールバックのリスクを探します。",
    llm=verifier_llm,
)

最初のCrewAI OpenAI互換ルーターの展開では、すべてのエージェントに一意のモデルを割り当てることは避けてください。通常、計画、ツール対応の実行、検証の2つまたは3つのルートタイプで十分です。

ステップ4：小さなクルーを構築し、証拠フィールドを保持する

クルーは通常のものでかまいません。しかし、ルーティングの証拠はそうであってはなりません。リクエストがFlatkeyのログと照合できるように、タスクの説明、出力、または周辺のアプリケーションログに簡単なフィールドを追加します。

analysis_task = Task(
    description=(
        "サポートチケットを確認し、短い解決計画を作成してください。 "
        "アカウントの検索が必要な場合を除き、ツールを呼び出さないでください。 "
        "このプロンプトの外部に保持する証拠フィールド：workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="リスク、ツールの必要性、次のアクションを含む簡潔な計画。",
    agent=planner,
)

verification_task = Task(
    description=(
        "計画がチケットの事実を引用し、裏付けのない主張を避け、"
        "まだ承認が必要なツール呼び出しをすべて挙げているかどうかを確認してください。"
    ),
    expected_output="必要な修正を含む合否メモ。",
    agent=verifier,
    context=[analysis_task],
)

crew = Crew(
    agents=[planner, researcher, tool_user, verifier],
    tasks=[analysis_task, verification_task],
    process=Process.sequential,
)

result = crew.kickoff(
    inputs={
        "ticket_id": "TICKET-123",
        "request_id": "support-triage-2026-07-08-001",
    }
)
print(result)

このテンプレートのrequest_idは、それ自体がCrewAIのルーティング機能ではありません。これは可観測性のための習慣です。CrewAI OpenAI互換ルーターのパスをFlatkeyで確認できるように、アプリはリクエストID、ルートポリシー、モデルエイリアス、タイムスタンプ、キーラベルをログに記録する必要があります。

ステップ5：広範な展開の前にツール呼び出しを検証する

ツールの使用は、OpenAI互換ルーティングが危険になる部分です。単純なチャットルートは機能するかもしれませんが、ツールを多用するルートはスキーマ検証に失敗したり、ツール引数を異なる方法でストリーミングしたり、エグゼキュータが拒否する引数を生成したりする可能性があります。

CrewAIのツールルートを信頼する前に、限定的なツールテストを使用してください。より広範なプロバイダーの動作については、このガイドをOpenAI互換のツール呼び出しに関するFlatkeyの記事と併せてお読みください。

これをオプションとして扱わないでください。CrewAI OpenAI互換ルーターは、ツールルートが別の契約としてテストされた場合にのみ、本番環境に対応できます。

ステップ6：プロンプトの外部に予算、リトライ、フォールバックのルールを追加する

エージェントにすべての運用ルールを自然言語で記憶させるように要求しないでください。予算とフォールバックのルールは、レビュー担当者が検査できるコードまたは構成に保持してください。

フォールバックが承認された場合、フォールバックエイリアスは明示的に保ちます。有用な問いは「クルーは完了したか？」ではなく、「どのルートが完了し、なぜ切り替わり、コストはいくらかかったか？」です。それがCrewAI OpenAI互換ルーターの運用上の価値です。

ステップ7：検証パケットを保存する

FlatkeyをCrewAIワークフローのデフォルトゲートウェイにする前に、コンパクトな検証パケットを保存します。

1. https://router.flatkey.ai/v1/chat/completionsへの直接のcurlリクエストが、選択されたモデルエイリアスで成功する。
2. 各CrewAI LLMオブジェクトは、完全なクルーの外で1つの小さなプロンプトを実行する。
3. 完全なクルーは、1つのシンプルなワークフローと1つのツールを多用するワークフローを実行する。
4. 強制的な失敗パスは、永久に再試行するのではなく、クリーンに停止する。
5. Flatkeyのログには、期待されるキー、モデルエイリアス、タイムスタンプ、リクエスト所有者が表示される。
6. トークンまたは使用状況のフィールドは、予算所有者がレビューするのに十分に見えるようになっている。
7. ロールバックは、CrewAIのリファクタリングではなく、1つの環境または設定の変更である。

Flatkeyトークン使用状況ダッシュボードガイドを使用して、最初のスモークテストの後に運用チームがどのフィールドを検査すべきかを決定します。価格設定とアカウントのレビューについては、ライブのFlatkey価格設定ページから始め、次にアカウントで実際のルートを確認します。

CrewAI OpenAI互換ルーターのトラブルシューティング

最初のリクエストが失敗した場合は、デバッグ対象を小さく保ちます：1つのキー、1つのベースURL、1つのモデルエイリアス、1つのCrewAI LLM、1つの直接リクエスト、そして1つのFlatkeyログ検索。

よくある質問

CrewAI OpenAI互換ルーターはモデルのフォールバックと同じですか？

いいえ。CrewAI OpenAI互換ルーターは、CrewAIがモデルルートに到達するために使用するゲートウェイおよび設定の境界です。フォールバックは、選択されたルートが失敗したときに実行される可能性のある1つのポリシーです。ルーティングとフォールバックは別々にテストしてください。

すべてのCrewAIエージェントに異なるモデルを割り当てるべきですか？

いいえ。デフォルトルートから始め、必要に応じてツールを多用する作業や検証作業のために1つの特別ルートを追加します。エイリアスが多すぎると、ログ、コストレビュー、ロールバックが困難になります。

CrewAIは明示的なLLMオブジェクトの代わりに環境変数を使用できますか？

はい。CrewAIのドキュメントには、OPENAI_API_BASEなどの環境変数を使用したOpenAI互換の設定が示されています。明示的なLLMオブジェクトは、各エージェントの役割がmodel、base_url、api_keyを1か所で示すため、本番環境でのレビューが容易になることがよくあります。

すべてのCrewAIワークフローに同じFlatkeyキーを使用できますか？

できますが、ワークロード固有のキーの方が監査が容易です。異なるチーム、環境、予算、またはリスクレベルで個別のレビューが必要な場合は、別々のキーまたはラベルを使用してください。

最終チェックリスト

あなたのCrewAI OpenAI互換ルーターの設定は、次の場合にテンプレートを超えて進む準備ができています：

1. CrewAI LLMオブジェクトは、Flatkey APIルートをbase_urlとして使用している。
2. モデルエイリアスはプロンプトに散在するのではなく、環境または設定に存在する。
3. 各エージェントの役割には意図的なルート決定がある。
4. ツールを多用するルートは、スキーマ、引数、上限、および失敗テストに合格する。
5. 予算、再試行、フォールバックの制限は、エージェントのプロンプトの外で実行される。
6. Flatkeyの使用状況またはリクエストログが、期待されるキーとモデルエイリアスを確認する。
7. ロールバックは1つの設定変更である。

CrewAIのトラフィックを1つのゲートウェイ経由でルーティングする準備ができたら、Flatkeyキーを取得し、リスクの低いクルーを1つテストし、ログでポリシーが機能することが証明された後にのみ拡張してください。