ツール呼び出しは、モデルをエージェントに変えるものです。OpenAI 互換 API でオープンモデルを使う場合も、リクエストの形式は OpenAI と同じです。違うのは、どれくらいの頻度で失敗するかと、それを防ぐためにサーバーが何をしているかです。この記事では、形式、オープンモデルが扱いやすいスキーマの書き方、並列呼び出し、実際に遭遇する 5 つの失敗、そしてそれらを乗り越える Python ループを解説します。
OpenAI 互換 API でツール呼び出しはどう動きますか?
messagesとtoolsのリストを送ります。各ツールには名前、説明、引数の JSON Schema があります。- モデルは
finish_reason: "tool_calls"とtool_callsのリストで返答します。各エントリにはid、関数名、そして JSON 文字列のargumentsがあります。 - コード側で各呼び出しを実行し、呼び出しごとに対応する
tool_call_idを付けたrole: "tool"メッセージを 1 つ追加します。 - もう一度 API を呼びます。モデルは回答するか、さらにツールを求めます。
モデル自身は何も実行しません。何を実行するかはコードが決めます。
ツールのスキーマはどう書くべきですか?
オープンモデルは、シンプルなスキーマほど確実に従います。次のルールは OpenAI のガイドと、壊れやすいポイントの経験から来ています。
- ツールは動作で名付けます。
read_fileやsearch_codeのようにし、説明にはいつ使うかを書きます。 - **リストは短くします。**OpenAI のガイドは、ターン開始時に関数を 20 個未満にすることをソフトな目安としています。しかも、すべてのスキーマが毎回の呼び出しで送られます。エージェントのトークン予算を参照してください。
- **引数はフラットにします。**文字列、数値、真偽値、enum を使い、深いネストや自由形式のオブジェクトは避けます。
- **選択肢が決まっているなら enum を使います。**モデルが値をでっち上げられなくなります。JSON スキーマジェネレーターを使えば、引数のサンプルオブジェクトから、
parametersに貼り付けられるフラットなスキーマを作れます。 - **必須フィールドを明示します。**OpenAI の strict モードでは、
additionalProperties: falseと、すべてのフィールドをrequiredに入れること、省略可能なフィールドの型にnullを加えることが必要です。プロバイダーがstrictを強制するかはまちまちなので、いずれにしても検証してください。
並列ツール呼び出しはどう扱いますか?
モデルは 1 ターンで tool_calls に複数のエントリを返すことがあります。たとえば 3 つのファイルの読み込みです。互いに独立した呼び出しは並行して実行し、tool_call_id ごとに結果を 1 つ、順不同で返します。ツールに互いに依存する副作用がある場合は、parallel_tool_calls: false を設定します。OpenAI のガイドによると、これでモデルの呼び出しは 1 ターンあたり 0 回か 1 回に制限されます。プロバイダーがこれに従うかテストしてください。
ツール呼び出しが失敗するのはなぜですか?
| 失敗 | 見えるもの | 対処 |
|---|---|---|
| 不正な形式の引数 | json.loads が例外を出す |
パースエラーをツールの結果として返し、リトライ |
| スキーマとの不一致 | フィールドの欠落、型の誤り、でっち上げた enum | 検証し、検証エラーを返す |
| 未知のツール | 定義していない名前 | 「unknown tool, available: …」を返す |
| 必要なのに呼び出さない | テキストで回答してしまう | tool_choice: "required" か関数を指定 |
| 途中で切れた呼び出し | finish_reason: "length" |
max_tokens を上げる。推論も同じ上限を使う |
最初の 2 つはまれではなく、想定しておくべきものです。vLLM のツール呼び出しのドキュメントによると、auto モードでは、ツールが strict: true を設定している(またはサーバーが最低限の厳密さを強制している)うえで、モデルのパーサーが制約に対応している場合を除き、“vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.”(訳:vLLM は生のテキストからツール呼び出しを抽出するため、引数がまれに不正な形式になったり、関数のパラメータースキーマに違反したりすることがある。)関数を指定した場合は、vLLM の構造化出力バックエンドが使われます。プロバイダーのモデルの提供方法は違うかもしれないので、検証は必須と考えてください。
最後の行は、推論モデルを使う人がよくはまるところです。GLM 5.3 と Qwen3.8 27B は回答前に考え、その思考は max_tokens に含まれます。どれだけ余裕を残すべきかは、返答が空になる、または途中で切れる理由で説明しています。
検証してリトライするツールループ
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
ここで重要な設計上の選択は 3 つです。
- **エラーはツールの結果としてモデルに返します。**モデルは何が間違っていたかを見て、たいてい次のターンで直します。例外を投げると、その機会を捨てることになります。
- ループには上限があります。
max_stepsは、進展のないままツールを呼び続けるモデルを止めます。 - **通信のリトライは別に扱います。**クライアントの
max_retriesは 429 と 5xx を扱います。不正な引数はループの中で扱います。この 2 つを混ぜないでください。エラーとリトライを参照してください。
メール送信のような副作用のあるツールでは、冪等キーを付けて、リトライしたステップが 2 回実行されないようにします。これは長時間動くエージェントの記事で扱っています。
BroadNet のどのモデルがツール呼び出しに対応していますか?
| モデル | ツールの記載 | コンテキスト | 備考 |
|---|---|---|---|
| GLM 5.3 | あり | 1,048,576 | 構造化出力にも対応 |
| Qwen3.8 27B | あり | 262,144 | 画像入力にも対応 |
| DeepSeek V4.1 Flash | 記載なし | 1,048,576 | 画像入力に対応。ツールに頼る前にテストを |
| Gemma 4 VL 26B | 記載なし | 32,768 | ツールループには不向き |
ツール対応の 2 モデルから選ぶには、GLM 5.3 と Qwen3.8 27B の比較をご覧ください。最終的な回答を決まった形にしたいだけで、関数を実行する必要がないなら、ツールより構造化出力のほうがシンプルです。
BroadNet Inference が向いている場面
BroadNet Inference は、ツール呼び出しの記載がある GLM 5.3 と Qwen3.8 27B を標準の chat completions 形式で提供しているので、上のループは OpenAI Python SDK でそのまま動きます。トークンあたりの料金は料金ページにあります。Web 検索やコード実行のようなサーバー側のツールはホストしておらず、無制限プランのモデルである DeepSeek V4.1 Flash については、ドキュメントにツール呼び出しの記載がありません。ツールを多用するエージェントには、トークン課金で GLM 5.3 か Qwen3.8 27B を使ってください。それでも定額プランを使いたいなら、1 か月分を買う前に、$1 の Meteor 1 時間で DeepSeek V4.1 Flash がツールを確実に呼び出せるか確認してください。
