GPT、Claude、Gemini、DeepSeek、Grok を使って1つの AI アプリを作りたい場合、共通のリクエスト経路には統一 API を使い、ルーティングポリシーはアプリケーション内に保持してください。CometAPI(https://www.cometapi.com/) は OpenAI 互換のベース URL と共有モデルカタログを提供するため、Python サービスは1つのクライアントから異なるモデル ID を呼び分けられます。どのモデルを実行するか、どのツールを許可するか、いつフォールバックが安全かは、引き続きあなたのコードが決めます。
このチュートリアルでは、2つの読み取り専用ビジネスツールを要求でき、未知のツールや不正な引数を実行前に拒否し、選別した一時的障害のときにのみ契約テスト済みの別モデルへ切り替える Grok 4.7 エージェントを構築します。目標は魔法のような自律システムではなく、本番運用・テストが可能な、小さく検査しやすいループです。
何を構築するか
このエージェントは5つの明示的な要素から成ります。
- 一つの CometAPI クライアント。OpenAI Python SDK は下記セットアップの CometAPI API ベース URL を使用します。
- プライマリモデルとしての Grok 4.7。現行の CometAPI モデル ID は
grok-4.7です。 - ツールレジストリ。モデルは関数呼び出しを提案できますが、許可リストにある関数のみをアプリケーションコードが実行します。
- 有界なエージェントループ。無制限に走らせず、所定のモデルターン数で停止します。
- 順序付きフォールバックポリシー。再試行可能なモデル/API 障害の後にのみ、互換の GPT、Claude、Gemini、DeepSeek のモデル ID を試行します。
Grok 4.7 は関数呼び出しをサポートし、CometAPI は現在、モデルに対して /v1/chat/completions と /v1/responses の両ルートをドキュメント化しています。このチュートリアルは Chat Completions を使用します。理由は、OpenAI 互換の tools、アシスタントのツール呼び出し、対応する tool 結果メッセージが、コンパクトで検査しやすい Python ループに直接対応するためです。トランスポートの互換性は、すべてのモデルで機能同等性を証明するものではありません。したがって、設定するフォールバックは、本番投入前に同一の契約テストを必ず通過させてください。
マルチターン Grok 4.7 エージェントにおける推論状態
Grok 4.7 は推論の負荷として low、medium、high、xhigh を受け付け、デフォルトは high です。xAI の Responses API では、すべての Grok 4.7 レスポンスに reasoning.encrypted_content が含まれます。クライアントが管理するマルチターンループでは、返された推論アイテムを次のリクエストにそのまま渡すべきです。長いループでは context compaction も利用できます。返されたコンパクションアイテムを不透明な状態として保持し、その後に新しいターンを追加します。これらはステートフルでプロバイダ固有のレスポンスフィールドであるため、本番依存にする前に、選択した CometAPI ルートがエンドツーエンドでそれらを返すことを確認してください。
エージェントアーキテクチャ: モデルが提案し、アプリが決める
安全なツール呼び出しフローは単純です。
ユーザー要求 → モデル応答 → ツール呼び出しの検証 → 許可ツールの実行 → ツール結果の追加 → モデル応答
モデルがデータベース認証情報を受け取ることも、Python を直接実行することもありません。「この注文 ID で get_order_status を呼び出せ」のような構造化リクエストを生成します。アプリケーションはツール名をチェックし、引数を解析し、認可とビジネスルールを適用して関数を実行し、シリアライズした結果を返します。
この分離はモデル選択以上に重要です。フォールバックモデルは同じツール境界を継承すべきで、それ以上に広げてはいけません。また、外部コンテンツを含む場合は、ツール結果を信頼できないデータとして扱ってください。
Python で Grok 4.7 AI エージェントを構築する方法
ステップ 1: OpenAI Python SDK を CometAPI 用に設定する
OpenAI SDK をインストールします。
pip install openai
環境変数で設定します。
export COMETAPI_KEY="your-cometapi-key"
export PRIMARY_MODEL="grok-4.7"
export FALLBACK_MODEL_1="your-compatible-gpt-model-id"
export FALLBACK_MODEL_2="your-compatible-claude-model-id"
export FALLBACK_MODEL_3="your-compatible-gemini-model-id"
export FALLBACK_MODEL_4="your-compatible-deepseek-model-id"
このチュートリアルは Chat Completions を使用します。アシスタントの明示的なツール呼び出しと対応するツール結果メッセージにより、制御フローをコンパクトな Python 例で容易に検査できるためです。より長いステートフルなループでは、上述のとおり Responses API の評価を検討してください。また、古いブログ投稿のモデル ID を本番にコピペしないでください。デプロイ時または起動時に CometAPI の公開 GET /api/models カタログを取得し、その後 model directory で機能と価格を確認してください。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
timeout=30.0,
)
明示的なタイムアウトと SDK の再試行無効化には意図があります。アプリケーション側で障害を分類し、リクエストの再実行か次のモデルへの移行かを判断します。隠れた再試行はレイテンシや副作用の重複、フォールバック挙動を理解しづらくします。
ステップ 2: まずは狭い読み取り専用ツールを定義する
データを変更しない読み取りツールから始めます。以下の定義により、エージェントは注文を確認し、在庫を検索できます。実装はデモデータを返します。自身のサービスへの認証済み呼び出しに置き換えてください。
import json
TOOLS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Read the current status of one order.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
},
{
"type": "function",
"function": {
"name": "check_inventory",
"description": "Read available inventory for one SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {"type": "string"}
},
"required": ["sku"],
"additionalProperties": False,
},
},
},
]
def get_order_status(order_id: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"order_id": order_id, "status": "in_transit"}
def check_inventory(sku: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"sku": sku, "available_units": 12}
TOOL_REGISTRY = {
"get_order_status": get_order_status,
"check_inventory": check_inventory,
}
JSON スキーマはリクエストの形を改善しますが、認可ではありません。引数の長さや形式を検証し、現在のユーザーが要求された注文や SKU にアクセスできることを確認し、ツール結果のサイズを制限した上でモデルに返してください。
ステップ 3: 狭いマルチモデル・フォールバックポリシーを追加する
フォールバックは一時的なルート障害から回復するためのものであり、壊れたリクエストを隠すためのものではありません。CometAPI の公式ガイドでは、接続エラー、タイムアウト、HTTP 408、HTTP 429、一時的な 5xx レスポンスで次の設定ルートに移ることを推奨しています。無効な認証情報、未対応パラメータ、無効なリクエストは即時失敗で構いません。
from openai import APIConnectionError, APIStatusError, APITimeoutError
def configured_models() -> list[str]:
names = [
os.getenv("PRIMARY_MODEL", "grok-4.7"),
os.getenv("FALLBACK_MODEL_1"),
os.getenv("FALLBACK_MODEL_2"),
os.getenv("FALLBACK_MODEL_3"),
os.getenv("FALLBACK_MODEL_4"),
]
return [name for name in names if name]
def is_retryable(error: Exception) -> bool:
if isinstance(error, (APIConnectionError, APITimeoutError)):
return True
if isinstance(error, APIStatusError):
return error.status_code in {408, 429} or error.status_code >= 500
return False
def complete_with_fallback(messages: list[dict], tools: list[dict]):
models = configured_models()
last_error = None
for index, model in enumerate(models):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tools,
tool_choice="auto",
)
return response, model
except Exception as error:
last_error = error
final_route = index == len(models) - 1
if final_route or not is_retryable(error):
raise
raise RuntimeError("No configured model completed the request") from last_error
モデルリストは設定であり、品質ランキングではありません。このエージェントに必要なメッセージロール、ツールスキーマ、入力モダリティ、コンテキスト要件、レスポンス挙動を同等にサポートするフォールバックを選んでください。選択されたルートと、遷移を引き起こした障害を必ず記録しましょう。
ステップ 4: 有界な Grok 4.7 エージェントループを実行する
以下のループは会話を送信し、許可リストにあるツール呼び出しを実行し、対応する tool_call_id とともに結果を追加し、選択されたモデルに最終回答を求めます。
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
if name not in TOOL_REGISTRY:
return json.dumps({"error": f"Tool not allowed: {name}"})
try:
arguments = json.loads(tool_call.function.arguments)
result = TOOL_REGISTRY[name](**arguments)
return json.dumps(result)
except (json.JSONDecodeError, TypeError, ValueError) as error:
return json.dumps({"error": f"Invalid tool arguments: {error}"})
def run_agent(user_text: str, max_turns: int = 4) -> dict:
messages = [
{
"role": "system",
"content": (
"You are a support agent. Use tools only when needed. "
"Never invent order or inventory data."
),
},
{"role": "user", "content": user_text},
]
route_log = []
for turn in range(max_turns):
response, model = complete_with_fallback(messages, TOOLS)
route_log.append({"turn": turn + 1, "model": model})
assistant = response.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
if not assistant.tool_calls:
return {
"answer": assistant.content,
"routes": route_log,
"usage": response.usage.model_dump() if response.usage else None,
}
for tool_call in assistant.tool_calls:
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": execute_tool_call(tool_call),
}
)
raise RuntimeError("Agent stopped after reaching max_turns")
result = run_agent("Where is order A-104, and is SKU BLUE-42 in stock?")
print(result["answer"])
print(result["routes"])
このコードは、1 回のモデル応答に複数のツール呼び出しが含まれるケースをサポートします。状態を変更するツール（メール送信、注文作成、返金発行など）の場合は、冪等性キーと人間による確認ステップを追加してください。副作用がすでに起きている可能性があるなら、タイムアウト後にエージェントの同一ターン全体を安易に再実行してはいけません。
GPT、Claude、Gemini、DeepSeek を同じアプリに収める方法
CometAPI は接続層の重複を減らせます。1 つのアカウント、共通パス向けに OpenAI 互換のベース URL、そしてアプリケーションコードで選ぶモデル ID。これにより GPT、Claude、Gemini、DeepSeek、Grok を 1 つの内部インターフェースの背後に置く候補にできます。
ただし、モデルが互換というわけではありません。フォールバックに追加する前に、次を検証してください。
- 現行のモデル ID が CometAPI のカタログから返されること
- 必要なツールスキーマとメッセージロールをルートがサポートすること
- ツール呼び出し引数と複数呼び出しの挙動がエージェント契約に一致すること
- コンテキストウィンドウと入力モダリティがリクエストに適合すること
- レスポンスがユーザー到達前に検証可能であること
- レイテンシとコストが製品の予算内に収まること
プロバイダ固有機能は、ネイティブエンドポイントや別アダプタを必要とする場合があります。それらの例外は明示的に扱い、共通インターフェースにすべての機能を無理やり押し込まないでください。
Grok 4.7 のマルチモデル・フォールバックはマルチエージェントと同じではない
マルチモデル・フォールバックチェーンは、ルートが失敗したときに別のモデルを選びます。マルチエージェントシステムは、プランナ、リサーチャ、レビュアといった役割を別々のエージェントに割り当てます。両者は異なる問題を解きます。
この Grok 4.7 エージェントをマルチエージェントワークフローへ拡張する場合は、各ワーカーに狭い役割、個別のツール許可リスト、有界な予算、構造化ハンドオフを与えてください。すべてのエージェントにすべてのツールを呼ばせたり、無制限のトランスクリプトを転送させたりしないでください。まずは単一エージェントで開始し、役割分離が結果を改善することを評価データで確認してから拡張します。
本番のための Grok 4.7 エージェントのガードレール
実行前に検証する
ツール名、引数スキーマ、テナントの所有権、ユーザー権限、レート制限をアプリケーションコードでチェックします。ツールの説明はモデルへのガイダンスであり、セキュリティ制御ではありません。
読み取りツールと書き込みツールを分離する
読み取り専用ツールは、認可後に自動実行できることが多いです。書き込みツールは、重大なアクションに対してより強いチェック、冪等性、確認が必要です。
すべてのループに境界を設ける
最大モデルターン数、ツール呼び出し回数、ウォールクロック時間、プロンプトサイズ、トークン予算を設定します。境界に達したら、制御可能なエラーやエスカレーション経路を返します。
意思決定の痕跡を記録する
要求タスク、ポリシーバージョン、選択モデル ID、フォールバック理由、ツール名、ツールレイテンシ、検証結果、トークン使用量、最終ステータスを記録します。秘密や不要な顧客コンテンツは記録しないでください。
想定ではなく契約テストを使う
構成したすべてのモデルに対して同一のフィクスチャを実行します。最低限、通常回答、単一ツール呼び出し、複数ツール呼び出し、不正引数、未知ツール、ツールのタイムアウト、プライマリモデルの 429、フォールバックしてはならない無効 API キーを網羅してください。
デプロイチェックリスト
- 現行のモデル ID を取得し、デプロイ前に Grok 4.7 ルートを検証する
- CometAPI キーをソースコードやプロンプトに埋め込まず、シークレットマネージャに保管する
- 読み取り専用ツールと明示的な JSON スキーマから始める
- 各ツール呼び出し前に認証とテナント認可を適用する
- 選別した一時的エラーにのみフォールバックを許可する
- すべてのフォールバックを同一のツール呼び出し契約でテストする
- 書き込みツールを有効化する前に冪等性と確認を追加する
- ループ、レイテンシ、コンテキスト、コストの上限を設定する
- API 可用性だけでなく、タスク成功率を計測する
なぜ CometAPI 経由でこのエージェントを作るのか？
CometAPI は共通の統合部分を小さく保てるからです。OpenAI Python SDK は 1 つのベース URL を指し、Grok 4.7 はモデル ID で選択し、他プロバイダの互換モデルも同じアプリ内のルートポリシーの背後に置けます。
これにより、GPT、Claude、Gemini、DeepSeek を製品中にプロバイダ固有の接続コードを散らさずに評価する余地が生まれます。また重要な境界も保てます。CometAPI はアクセスを提供し、能力チェック、ツール実行、フォールバックポリシー、評価、ユーザー向け挙動はあなたのアプリケーションが管理します。
最新の Grok 4.7 モデルページ を確認し、CometAPI クイックスタート でクライアントを設定し、本番フォールバックを選ぶ前に最新のモデル ID を取得してください。
FAQ
GPT、Claude、Gemini、DeepSeek を使うアプリではどの API を使うべき？
共通のチャットとツール呼び出し経路には、CometAPI のような OpenAI 互換の統一 API が統合作業を減らせます。モデル選択とフォールバックポリシーはアプリケーションに保持し、共有契約に合わない必要機能にはプロバイダネイティブのアダプタを使ってください。
Grok 4.7 は Python 関数を直接呼べますか？
Grok 4.7 は構造化された関数呼び出し要求を返せます。Python アプリケーションが要求を解析・検証し、許可リストの関数を実行し、結果をモデルに返します。モデル自体がローカルの Python を実行するわけではありません。
すべてのエラーで別モデルに切り替えるべきですか？
いいえ。接続障害、タイムアウト、408、429、一時的な 5xx に対してフォールバックを使用してください。無効なリクエスト、認証失敗、未対応パラメータは、別モデルに送るのではなく修正すべきです。
1 つのツールスキーマをすべてのモデルで使えますか？
テスト後であれば可能です。共有トランスポートは、ツール挙動、引数品質、並列呼び出し挙動、スキーマ強制が同一であることを保証しません。エージェントの契約テストを通過したモデルのみチェーンに加えてください。
マルチモデル・フォールバックはマルチエージェントですか？
違います。フォールバックはルート障害後に、そのリクエストで使用するモデルを切り替えます。マルチエージェントは異なるタスクを別のエージェントに割り当てます。別レイヤーとして切り離し、独立したテストとコントロールを用意してください。
出典
- CometAPI — Grok 4.7 モデルページ(https://www.cometapi.com/models/xai/grok-4-7/)
- CometAPI — OpenAI SDK クイックスタート(https://www.cometapi.com/quickstart/)
- CometAPI — Chat Completions、tools、function calling(https://apidoc.cometapi.com/api/text/chat)
- CometAPI — モデルとプロバイダのフォールバック(https://apidoc.cometapi.com/guides/model-fallback-with-cometapi)
- CometAPI — 現行モデルカタログの取得ワークフロー(https://apidoc.cometapi.com/guides/how-to-list-available-models)
- xAI — Grok 4.7 開発者ガイド(https://docs.x.ai/developers/grok-4-7)
- xAI — Function calling(https://docs.x.ai/developers/tools/function-calling)