Grokをカスタムアプリケーションに統合する：APIキー設定、モデルパラメータ調整、およびFunction Calling実践ガイド

xAIが提供するGrokモデルを独自ソフトウェアや業務システムに統合することで、高度な論理推論、大容量コンテキストウィンドウ、およびリアルタイムな情報連携機能をアプリケーションへ組み込むことが可能になります。xAIのAPIは https://api.x.ai/v1 をベースURLとし、OpenAI REST仕様と完全な互換性を保持しています。そのため、既存のOpenAI公式SDKをそのまま活用できるほか、公式の xai-sdk や @ai-sdk/xai も利用できます。

実運用においてGrokを安定して活用するためには、API認証キーの安全な管理、ワークロードに応じたモデル推論パラメータの最適化、そして自社データベースや外部マイクロサービスと接続するための関数呼び出し（Function Calling / Tool Calling）の実装という3つの要点を押さえる必要があります。

1. xAI API認証キーの取得と初期設定

Grok APIを呼び出すには、まずxAI開発者ポータルでアカウントを作成し、クレジット残高のチャージとAPIキーの発行を行います。

ステップ1: アカウント開設とAPIキーの発行

1. xAI Console（https://console.x.ai）にアクセスしてログインします。
2. 支払い情報を設定し、API利用のための事前クレジットを購入します。
3. API Keys メニューから新しいAPIキーを発行します。
4. 発行されたキーを環境変数に安全に格納します。ソースコードへのハードコードは避けてください。

export XAI_API_KEY="xai-your-api-key-here"

ローカル開発環境では、Git管理外の .env ファイルに記述して読み込む構成が推奨されます。

XAI_API_KEY=xai-your-api-key-here

ステップ2: クライアントの初期化

OpenAI SDKを使用する場合、ベースURLを https://api.x.ai/v1 に設定するだけで接続が完了します。

Python（OpenAI SDK）

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

TypeScript / Node.js（OpenAI SDK）

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

2. モデルの選定と推論パラメータの調整

システム要件や予算、応答速度の目標値に応じて適切なモデルとパラメータを選択することが重要です。

主要本番モデルの特性

主な推論パラメータ

chat.completions.create または responses.create を実行する際、以下のパラメータを設計します。

• model（文字列、必須）: 利用するモデル名（例: "grok-4.7"）。
• temperature（浮動小数点数、0.0〜2.0）: 生成テキストのランダム性を制御します。
  • 構造化データの抽出、コード生成、関数呼び出しを行う場合は、0.0 または低値（0.1〜0.2）を指定して決定論的な出力を得ます。
  • 自由対話やアイデア出しでは 0.7〜1.0 を設定します。
• top_p（浮動小数点数、0.0〜1.0）: ニュークリアスサンプリングの閾値。通常は temperature または top_p のどちらか一方のみを調整します。
• max_completion_tokens / max_tokens（整数）: 1回のレスポンスで生成される最大トークン数を制限し、予算超過を防ぎます。
• stream（真偽値）: true に設定するとサーバーサイドイベント（SSE）により順次トークンを受信でき、UIの体感応答速度を改善します。
• reasoning_effort（文字列）: 思考プロセス対応モデル（grok-4.7 など）において、思考の深さを "low", "medium", "high", "xhigh" から指定できます。

3. Function Calling（ツール呼び出し）の基本仕様

Function Callingを使用することで、Grokはユーザーの入力内容を分析し、外部システムの操作やデータ取得が必要なタイミングを自律的に検知して、事前に定義したJSONスキーマに従った引数を生成します。

サーバー実行ツールとクライアント実行ツールの違い

xAIでは以下の2種類のツールをサポートしています。

1. サーバーサイド組み込みツール（Built-in Tools）: Web検索（web_search）、Xポスト検索（x_search）、コードサンドボックス実行（code_execution）など。xAIのインフラ上で自動的に実行されます。
2. クライアントサイドカスタム関数（Function Calling）: 開発者のアプリケーション環境で実行する独自関数。モデルがツール呼び出しを決定すると一時停止し、関数名と引数をアプリケーションに返却します。両者は同一のリクエスト内で併用可能です。

引数スキーマの必須要件

関数の引数スキーマ（parameters）はJSON Schemaの厳格な構文に従う必要があります。

• parameters のルートは**必ずオブジェクト型（"type": "object"）**である必要があります。スカラー値や配列をルートに設定すると構文チェックで弾かれ、HTTP 400エラーが返されます。
• 入力項目は properties 配下に定義し、必須項目は required 配列で指定します。

制御パラメータ

• tool_choice:
  • "auto"（デフォルト）: モデルが必要に応じてツールの使用可否を自律判断します。
  • "required": 少なくとも1つのツールの呼び出しを強制します。
  • "none": ツール呼び出しを完全に無効化します。
  • {"type": "function", "function": {"name": "関数名"}}: 指定した単一の関数のみを実行させます。
• parallel_tool_calls（真偽値）: デフォルトは true で、複数のツール呼び出しを一度のレスポンスで同時に要求できます。順次実行が必要な場合は false を指定します。

4. エンドツーエンドの実装コード例（Python）

以下は、自社注文検索関数を定義し、ユーザーからの問い合わせに対してGrokが必要な引数を組み立て、ローカル処理を経て最終回答を返す一連の実装例です。

import json
import os
from openai import OpenAI

# xAIエンドポイントを指定してクライアントを初期化
client = OpenAI(
    api_key=os.environ.get("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 1. ローカル側の業務処理関数
def get_customer_order(order_id: str) -> dict:
    """注文IDに基づき配送状況を取得するモック関数"""
    mock_database = {
        "ORD-9821": {
            "order_id": "ORD-9821",
            "status": "発送完了",
            "items": ["メカニカルキーボード", "USB-C 高速充電ケーブル"],
            "delivery_date": "2026-10-02",
        },
        "ORD-5432": {
            "order_id": "ORD-5432",
            "status": "出荷準備中",
            "items": ["ノイズキャンセリングヘッドホン"],
            "delivery_date": "2026-10-05",
        },
    }
    return mock_database.get(order_id, {"error": "該当する注文が見つかりません"})

# 実行可能な関数マッピング
available_tools = {
    "get_customer_order": get_customer_order,
}

# 2. Grokに渡すツール定義スキーマ
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_customer_order",
            "description": "注文IDを指定して、配送ステータスと商品一覧を取得します。",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "ORD-9821のような英数字の注文ID",
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]

# 3. ユーザーからの問い合わせを作成
messages = [
    {
        "role": "system",
        "content": "あなたは親切なECカスタマーサポートです。ツールを使って正確な配送状況を回答してください。",
    },
    {
        "role": "user",
        "content": "注文番号 ORD-9821 の配送状況と到着予定日を教えてください。",
    },
]

# 4. 初回APIリクエストの送信
response = client.chat.completions.create(
    model="grok-4.7",
    messages=messages,
    tools=tools,
    tool_choice="auto",
    temperature=0.1,  # 安定した引数生成のため低温に設定
)

response_message = response.choices[0].message
tool_calls = response_message.tool_calls

# 5. モデルからのツール呼び出し要求を処理
if tool_calls:
    # ツール呼び出し指示を含むアシスタントのメッセージを履歴に追加
    messages.append(response_message)

    for tool_call in tool_calls:
        function_name = tool_call.function.name
        function_args = json.loads(tool_call.function.arguments)

        if function_name in available_tools:
            tool_func = available_tools[function_name]
            result_data = tool_func(**function_args)

            # tool_call_idを一致させて実行結果を追加
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result_data, ensure_ascii=False),
                }
            )

    # 6. 実行結果を踏まえてGrokから最終回答を取得
    second_response = client.chat.completions.create(
        model="grok-4.7",
        messages=messages,
    )
    final_output = second_response.choices[0].message.content
    print("最終回答:\n", final_output)
else:
    print("通常回答:\n", response_message.content)

5. 本番運用のベストプラクティス

1. スキーマのルート型制限: parameters は必ず "type": "object" で定義してください。スカラー型や配列型をルートに配置するとスキーマコンパイルに失敗し、400エラーとなります。
2. 並列呼び出し時の冪等性確保: parallel_tool_calls が有効な場合、複数の更新系操作が同時に呼び出される可能性があります。自社ハンドラ側で重複実行を防ぐ冪等処理を実装してください。
3. エラーハンドリングのJSON返却: 外部APIのタイムアウトや内部DBエラーが発生した際、例外でプロセスを落とすのではなく、{"error": "データベースが一時的に応答しません"} などの構造化エラーをツール結果として返すと、Grokがユーザーに配慮した案内を自律的に行えます。
4. レートリミット対策: 大量トラフィック下での HTTP 429 エラーに備え、Exponential Backoff（指数バックオフ）による自動リトライロジックを必ず組み込んでください。
5. 認証情報の保護: フロントエンドのブラウザJavaScriptやモバイルネイティブアプリ内に XAI_API_KEY を配置せず、必ず信頼できるバックエンドサーバーを経由して通信を行ってください。

参考資料

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs