# Warum schlagen Tool-Aufrufe nach dem Wechsel des Coding-Agent-Modells fehl? > Tool-Aufrufe scheitern nach einem Modellwechsel häufig, weil sich Protokoll, Schema-Erwartungen, Argument-Serialisierung, Streaming-Ereignisse oder Gesprächszustand ändern. Behandeln Sie die Migration als Vertragsänderung und nicht als bloßen Austausch eines Modellnamens. Der erste sinnvolle Test ist kleiner als ein Coding-Benchmark: Lassen Sie das Ersatzmodell eine Read-only-Funktion mit zwei Pflichtargumenten aufrufen. Scheitert das, liegt das Problem unterhalb der Planungsebene. Gelingt es, fügen Sie Streaming, mehrere Tools, Zustand und Schreibaktionen einzeln hinzu, bis der erste Vertragsbruch sichtbar wird. Ein Modellwechsel legt Annahmen offen, die in der bisherigen Integration verborgen waren. Ein Coding-Agent besteht nicht nur aus Prompt und Modell, sondern aus einer Zustandsmaschine, die Modellausgabe, Stream-Parser, Tool-Register, Ausführung und Rückgabe der Tool-Ergebnisse verbindet. Jede Grenze kann inkompatibel werden, obwohl normaler Text weiterhin korrekt aussieht. ## Fähigkeit und Protokoll getrennt prüfen Ein Modell kann hervorragend programmieren und dennoch nicht über das vom Client verwendete Protokoll verfügbar sein. Ein anderes akzeptiert vielleicht die Anfrage, bietet auf dieser Route aber keine Tools an. Prüfen Sie die Fähigkeitsmetadaten, bevor Sie den Modellnamen ändern. Der [Atlas Cloud Leitfaden für LLM-Protokolle](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) nennt OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini und weitere Formate unter einer Base URL. Nicht jedes Modell spricht jedes Protokoll. Verwenden Sie `supported_apis` und die Tool-Fähigkeit als maßgebliche Quelle. | Ebene | Migrationsfrage | Fehlersignal | |---|---|---| | Endpoint | Akzeptiert das Modell dieses Protokoll? | 400-Antwort oder ignorierte Felder | | Fähigkeit | Bietet diese Route Tools an? | Textantwort statt Aufruf | | Schema | Sind Namen und JSON Schema gültig? | Fehlende oder fehlerhafte Argumente | | Stream | Werden Argument-Deltas korrekt zusammengesetzt? | Abgeschnittenes JSON | | Schleife | Werden Ergebnisse in der erwarteten Rolle zurückgegeben? | Wiederholter Aufruf oder Stillstand | ## Das Tool-Schema auf einen Vertrag reduzieren Beginnen Sie mit einem kurzen Funktionsnamen, zwei verpflichtenden Strings, keinen Unions und keiner optionalen Verschachtelung. Komplexe Schemas vermischen Modell- und Validatorverhalten und erschweren die Diagnose. ```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 } } } ``` Erzwingen Sie diese Funktion, wenn das Protokoll dies erlaubt. So lässt sich Unfähigkeit von einer Planungsentscheidung unterscheiden. ## Erst ohne Streaming testen Ohne Streaming erscheint das endgültige Tool-Objekt in einer Antwort. Beim Streaming können Name, ID und JSON-Argumente in getrennten Ereignissen eintreffen. Analysieren Sie Argumente erst nach dem final- oder done-Ereignis des Protokolls. Führen Sie ein Tool nicht aus, nur weil ein Teilpuffer bereits gültiges JSON bildet; spätere Deltas können ihn erweitern. Speichern Sie Puffer nach Aufruf-ID, verhindern Sie doppelte Finalisierung und protokollieren Sie die rohe Ereignisfolge. | Stream-Invariante | Erforderliches Verhalten | |---|---| | Stabile Identität | Alle Deltas landen im selben Puffer | | Geordnete Montage | Fragmente werden in Ereignisreihenfolge angehängt | | Expliziter Abschluss | Ausführung wartet auf das finale Ereignis | | Einmalige Ausführung | Ein fertiger Aufruf läuft höchstens einmal | ## Die Agent-Schleife explizit normalisieren Verteilen Sie anbieterspezifische Felder nicht im gesamten Executor. Wandeln Sie jede Antwort in eine interne Form wie `assistant_text`, `tool_calls`, `usage` und `stop_reason` um und geben Sie Ergebnisse über einen Protokolladapter zurück. Behandeln Sie Aufruf-IDs als undurchsichtige Werte und erhalten Sie sie für die Korrelation. Validieren Sie Argumente vor der Ausführung und geben Sie strukturierte Fehler zurück, statt ungültiges JSON still zu korrigieren. ## Zustand beim ersten Vergleich zurücksetzen Der alte Verlauf kann Reasoning-Blöcke, Tool-Ergebnisrollen, Zustands-IDs oder Nachrichten enthalten, die die neue Route ablehnt. Beginnen Sie mit einer neuen Unterhaltung und denselben Systemanweisungen; spielen Sie danach einen kurzen normalisierten Verlauf ein. Zustandsabkürzungen sind protokollspezifisch. Eine vorherige Response-ID garantiert nicht, dass Entwickleranweisungen übernommen werden. Machen Sie Persistenz zu einem eigenen Test. ## Eine Migrationsleiter aufbauen Führen Sie dieselben Fälle in dieser Reihenfolge aus: * Einfache Textantwort. * Ein erzwungenes Read-only-Tool ohne Streaming. * Eine automatische Auswahl ohne Streaming. * Ein erzwungenes Tool mit Streaming. * Zwei unabhängige Tools. * Ein Tool-Fehler mit Wiederherstellung. * Eine kurze mehrstufige Coding-Aufgabe. Stoppen Sie beim ersten Fehler und untersuchen Sie die Netzwerkdaten. Springen Sie nicht von einem Healthcheck zu einer autonomen Repository-Änderung. ## Entscheiden, ob ein Adapter genügt Ein gemeinsamer Adapter reicht, wenn nur Feld- oder Ereignisnamen variieren. Separate Adapter sind sicherer, wenn Modelle unterschiedliche Protokolle, Verlaufsformen oder Ergebnissemantiken benötigen. Atlas Cloud erleichtert Experimente, weil ein Schlüssel und eine Base URL mehrere Formate und einen sich ändernden [LLM-Modellkatalog](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) bereitstellen. Das ersetzt keine Fähigkeitsprüfung. Speichern Sie Modell, Protokoll, Schemaversion, Streaming-Modus und Testergebnis gemeinsam. ## Fazit Tool-Aufrufe scheitern nach einem Modellwechsel, wenn eine Verhaltens- und Protokollmigration als Textaustausch behandelt wird. Prüfen Sie die Route, vereinfachen Sie das Schema, bestehen Sie einen erzwungenen Aufruf ohne Streaming, validieren Sie die Stream-Montage und fügen Sie Zustand zuletzt hinzu. Bei unterschiedlicher Semantik sind getrennte Adapter die sicherere Lösung. ## FAQ ### Warum antwortet das neue Modell mit Text, statt ein Tool aufzurufen? Möglicherweise unterstützt es im gewählten Protokoll keine Tools, benötigt eine andere Tool-Choice-Einstellung oder interpretiert die Beschreibung anders. Prüfen Sie die Metadaten und erzwingen Sie einen Testaufruf. ### Können zwei OpenAI-kompatible Modelle unterschiedliche Aufrufformate liefern? Ja. Die äußere Anfrage kann kompatibel sein, während Streaming-Deltas, Aufruf-IDs, Argumentabschluss und Stop-Gründe abweichen. ### Sollte ich nach dem Modellwechsel die alte Unterhaltung weiterverwenden? Erst nachdem bestätigt ist, dass das neue Modell und Protokoll dieselben Verlaufselemente akzeptieren. Sicherer ist eine neue Unterhaltung, der Zustand gezielt hinzugefügt wird. ### Was ist der schnellste Diagnosetest? Erzwingen Sie ein deterministisches Read-only-Tool mit kleinem JSON-Schema, führen Sie es ohne Streaming aus und protokollieren Sie Rohdaten von Anfrage und Antwort. ### Normalisiert Atlas Cloud alle Modelle auf eine identische Tool-Schnittstelle? Nein. Atlas Cloud unterstützt mehrere Protokolle; jedes Modell veröffentlicht seine unterstützten APIs und Fähigkeiten. Der Client muss ein tatsächlich unterstütztes Protokoll wählen. ### Wann sollte ich zwei getrennte Adapter behalten? Wenn Zustandsobjekte, Streaming-Ereignisse, Tool-Ergebnisse oder Fehlersemantik nicht sicher durch einen gemeinsamen normalisierten Vertrag abgebildet werden können.