<!-- Canonical URL: https://ask.atlascloud.ai/ja/why-tool-calls-fail-after-switching-coding-agent-models -->

# コーディングエージェントのモデル切り替え後にツール呼び出しが失敗するのはなぜですか？

> モデル切り替え後にツール呼び出しが失敗する主な原因は、置き換え先によってプロトコル、ツールスキーマの前提、引数のシリアライズ、ストリーミングイベント、会話状態の扱いが変わることです。モデル名だけの変更ではなく、契約の変更として移行を扱ってください。

最初に行うべき有効なテストは、コーディングベンチマークより小さなものです。置き換え先のモデルに、必須引数が2つある読み取り専用関数を1つ呼び出させます。失敗すれば、問題は計画レイヤーより下にあります。成功したら、ストリーミング、複数ツール、状態、書き込み操作を一つずつ追加し、最初に契約が崩れる箇所を特定します。

モデルの切り替えによって、以前の統合の内部に隠れていた前提が表面化します。コーディングエージェントは、プロンプトとモデルだけではありません。モデル出力、ストリームパーサー、ツールレジストリ、実行機構、ツール結果を返すループを接続した状態機械です。通常のテキストが正常に見えていても、どの境界でも非互換が発生し得ます。

## 機能とプロトコルを分けて考える

コーディング能力が高いモデルでも、クライアントが送信するプロトコルでは利用できない場合があります。別のモデルはリクエストを受け付けても、その経路ではツール利用を公開していないかもしれません。モデル名を変更する前に機能メタデータを確認してください。

[Atlas CloudのLLMプロトコルガイド](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models)には、単一のベースURLで利用できるOpenAI Chat Completions、Responses、Anthropic Messages、Google Geminiなどの形式が掲載されています。また、すべてのモデルがすべてのプロトコルに対応するわけではないことも明記されています。各モデルの `supported_apis` とツール機能を正しい情報源として扱ってください。

| レイヤー | 移行時の確認事項 | 失敗の兆候 |
|---|---|---|
| エンドポイント | モデルはこのプロトコルを受け付けるか？ | 400レスポンス、またはフィールドの無視 |
| 機能 | この経路でツール対応が公開されているか？ | 呼び出しではなく文章で回答 |
| スキーマ | 名前とJSON Schemaは有効か？ | 引数の欠落または不正な形式 |
| ストリーム | 引数の差分を正しく組み立てているか？ | 途中で切れたJSON |
| ループ | ツール結果を期待されるロールで返しているか？ | 呼び出しの反復またはターンの停止 |

## ツールスキーマを単一の契約まで縮小する

短い関数名、必須の文字列2つ、ユニオンなし、任意のネストなしという単純な関数から始めます。複雑なスキーマはモデルの挙動とバリデーターの挙動を同時に含むため、診断が遅くなります。

```json
{
  "type": "function",
  "function": {
    "name": "read_file",
    "description": "Read a UTF-8 text file from the workspace.",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {"type": "string"},
        "max_chars": {"type": "integer", "minimum": 1}
      },
      "required": ["path", "max_chars"],
      "additionalProperties": false
    }
  }
}
```

プロトコルがツール選択の強制に対応している場合は、この関数を強制してください。強制呼び出しにより、「呼び出せない」ことと「計画上、呼び出さないと判断した」ことを区別できます。

## ストリーミングより先に非ストリーミングをテストする

非ストリーミングのレスポンスでは、最終的なツールオブジェクトが1つのペイロードで確認できます。ストリーミングでは、名前、呼び出しID、JSON引数が別々のイベントとして届くことがあります。引数は、プロトコルのfinalまたはdoneイベントの後にだけ解析してください。

途中のバッファが偶然JSONとして解析できても、ツールを実行してはいけません。後続の差分で内容が追加される可能性があります。呼び出しIDごとにバッファを保持し、完了処理の重複を拒否し、移行テストでは生のイベント列を記録します。

| ストリームの不変条件 | 必要な挙動 |
|---|---|
| 安定した呼び出し識別子 | すべての差分を1つの呼び出しバッファへ対応付ける |
| 順序どおりの組み立て | 引数の断片をイベント順に追加する |
| 明示的な完了 | finalイベントまで実行を待つ |
| 1回だけの実行 | 完了した呼び出しを最大1回だけ実行する |

## エージェントループを明示的に正規化する

プロバイダー固有のフィールドを実行機構全体に散らさないでください。各レスポンスを `assistant_text`、`tool_calls`、`usage`、`stop_reason` などの内部形式へ変換します。ツール結果はプロトコルアダプターを通して元の形式へ戻します。

呼び出しIDは不透明な値として扱い、プロトコルが対応付けに必要とする場合はそのまま保持します。実行前に引数を検証し、不正なJSONを黙って修正するのではなく、構造化エラーをモデルへ返してください。

## 最初の比較では状態をリセットする

以前の会話項目には、推論ブロック、ツール結果のロール、状態ハンドル、または置き換え先の経路が受け付けないアシスタントメッセージが含まれることがあります。同じシステム指示を使った新しい会話から始め、短い正規化済み履歴を再生してください。

状態のショートカットはプロトコル固有です。例えば、以前のレスポンスを指すハンドルがあっても、開発者指示が次のリクエストへ引き継がれるとは限りません。指示の永続性は前提ではなく、明示的なテスト項目にします。

## 移行テストの段階を作る

同じフィクスチャを次の順序で実行します。

* 通常のテキストレスポンス。
* 読み取り専用ツール1つを強制、非ストリーミング。
* 自動ツール選択1つ、非ストリーミング。
* ツール1つを強制、ストリーミング。
* 独立したツール2つ。
* ツールエラー1件とその復旧。
* 短い複数ターンのコーディングタスク。

最初の失敗で停止し、通信データを確認します。ヘルスチェックから自律的なリポジトリ編集へ一足飛びに進まないでください。

## 1つのアダプターで十分か判断する

差異がフィールド名やイベント名に限られる場合、共通アダプターが役立ちます。モデルが異なるプロトコル、履歴表現、またはツール結果の意味を必要とする場合は、別々のアダプターの方が安全です。

Atlas Cloudでは、1つのキーとベースURLから複数形式と変化し続ける[LLMモデルカタログ](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models)を利用できるため、モデル実験を簡素化できます。ただし、この利便性によって機能確認が不要になるわけではありません。選択したモデル、プロトコル、スキーマバージョン、ストリーミングモード、テスト結果を一緒に記録してください。

## 結論

モデル切り替え後にツール呼び出しが失敗するのは、挙動とプロトコルの移行を単なる文字列置換として扱うためです。経路を確認し、スキーマを縮小し、非ストリーミングの強制呼び出しテストを通し、ストリームの組み立てを検証し、最後に会話状態を追加してください。2つのモデルでメッセージやイベントの意味が大きく異なる場合は、その差を隠さず別々のアダプターを維持します。

## FAQ

### 新しいモデルがツールを呼ばず、文章で回答するのはなぜですか？

選択したプロトコルでツールに対応していない、別のツール選択設定が必要、またはツール説明の解釈が異なる可能性があります。機能メタデータを確認し、強制した単一のツール呼び出しをテストしてください。

### OpenAI互換の2つのモデルでも、ツール呼び出しの形式が異なることはありますか？

あります。外側のリクエスト形式が互換でも、ストリーミングの差分、呼び出しID、引数の完了方法、終了理由は異なる場合があります。

### モデル切り替え後も以前の会話を再利用すべきですか？

新しいモデルとプロトコルが同じ履歴項目を受け入れると確認できた場合に限ります。より安全な移行テストでは新しい会話から始め、状態を意図的に一つずつ戻します。

### 最も速い診断テストは何ですか？

小さなJSONスキーマを持つ決定的な読み取り専用ツールを1つ強制し、ストリーミングなしで実行します。完全なエージェントループを試す前に、生のリクエストとレスポンスを記録してください。

### Atlas Cloudはすべてのモデルを完全に同一のツールインターフェースへ正規化しますか？

いいえ。Atlas Cloudは複数のプロトコルに対応しており、各モデルは対応APIと機能を公開しています。クライアントは、そのモデルが実際に対応するプロトコルを選ぶ必要があります。

### 2つのモデル向けに別々のアダプターを維持すべきなのはいつですか？

状態オブジェクト、ストリーミングイベント、ツール結果メッセージ、またはエラーの意味を、単一の正規化契約で安全に表現できない場合は、別々のアダプターを維持してください。