サーバーツール

サーバーツールは、1 つのリクエストの中で Synthorai が代わりに実行する機能です:モデルが何かを要求し、当社が処理し、結果は同じレスポンスで返ります。tools に 1 エントリ追加するだけ——第 2 のエンドポイントも、実装すべきコールバックもありません。

利用可能なツール

すべてのサーバーツールは synthorai: プレフィックスで識別されるため、お客様自身のツール名と衝突することはありません:

共通の契約

すべてのサーバーツールは同じように振る舞うため、1 つで学んだことが次にも通用します:

• オプトイン専用。tools にツールを入れない限り何も実行されません。入れていないリクエストは通常のリクエストです。
• 1 往復で完結。ツールループは当社が代行し、ツールの活動と回答が最初から含まれた単一のレスポンスを受け取ります。
• お客様のツールもそのまま動作。サーバーツールと function ツールは同時に宣言できます——モデルがお客様のツールを呼んだ場合は、正直に stop_reason: tool_use で制御をお返しします。(唯一の例外は当社が注入するツール名の予約——下記参照。)
• 従量課金で、usage に明示。回数は usage.server_tool_use に、料金は usage.cost に記録されるため、すべてのリクエストを請求と突合できます。
• max_uses は実効的な上限。単一リクエストの支出を制限し、内部リトライをまたいでも維持されます。

トークンが費用のもう半分

会話を続ける

受け取ったままの assistant メッセージを、ツールブロックを含めて messages に追記してください。フォローアップのリクエストでも同じサーバーツールを宣言し続けると、履歴が最も豊かな形のまま保たれます。ツールを外すと過去のツール結果はプレーンテキストに平坦化されますが、内容はモデルに見え続けます。

予約ツール名

synthorai: パラメータの使用中は、対応する裸の名前が予約されます:synthorai:web_search と並べて web_search という自前のツールを宣言する(あるいは synthorai:web_fetch と並べて web_fetch を宣言する)と、ツール名を明示した 400 が返ります。ご自身のツールをリネームするか、synthorai: パラメータを外してください。

理由は、当社がサーバーツールをまさにその名前で注入するためです。2 つのツールが同じ名前でモデルに届くと、どちらの呼び出しが返ってきたのか誰にも判別できません——お客様のツールの引数が当社の検索プロバイダーに送られたり、お客様の呼び出しが失われたりしかねません。リクエストを拒否することが唯一の誠実な回答です。対応する synthorai: パラメータなしでどちらかの名前のツールを宣言することには影響ありません:当社は何も注入しないため、何も衝突しません。

失敗には課金されません

呼び出しごとの料金は、結果を生んだ呼び出しに対して課金されます。当社ネットワークを出る前に拒否した呼び出し——却下された URL、ブロック対象ドメイン、未設定のバックエンド——は無料です。プロバイダーに到達してそこで失敗した呼び出しは、プロバイダーが当社に課金するため課金されます。どちらの場合もラウンドは max_uses の予算にカウントされるため、壊れた URL をリトライし続けるモデルが無料でループすることはできません。

対応エンドポイント

サーバーツールは /v1/messages、/v1/chat/completions、/v1/responses で動作します。対応していないエンドポイント(Gemini エンドポイント)に synthorai: パラメータを送ると、その旨を伝える 400 が返ります。未知のツールを上流に流すより拒否する方を選びます。上流に流した場合、最良でも分かりにくいサードパーティエラー、最悪の場合は黙って無視され、検索は行われず、頼んだより静かに少ないことをした通常リクエストとして課金されるからです。

利用可否

サーバーツールは API キー単位で有効化されます。キーで有効になっていないツールを指定すると、黙って無視されるのではなく、ツール名を明示した 400 が返ります。有効化はお問い合わせください。