Tool Calling macht aus einem Modell einen Agenten. Mit offenen Modellen auf einer OpenAI-kompatiblen API ist das Anfrageformat dasselbe, das Sie auch bei OpenAI verwenden würden. Unterschiedlich ist, wie oft etwas schiefgeht und was der Server tut, um es zu verhindern. Dieser Beitrag behandelt das Format, wie Sie Schemas schreiben, mit denen offene Modelle gut zurechtkommen, parallele Aufrufe, die fünf Fehler, die Ihnen tatsächlich begegnen, und eine Python-Schleife, die sie übersteht.
Wie funktioniert Tool Calling auf einer OpenAI-kompatiblen API?
- Sie senden
messagesplus einetools-Liste. Jedes Tool hat einen Namen, eine Beschreibung und ein JSON Schema für seine Argumente. - Das Modell antwortet mit
finish_reason: "tool_calls"und einertool_calls-Liste. Jeder Eintrag hat eineid, einen Funktionsnamen undargumentsals JSON-String. - Ihr Code führt jeden Aufruf aus und hängt pro Aufruf eine Nachricht mit
role: "tool"und der passendentool_call_idan. - Sie rufen die API erneut auf. Das Modell antwortet oder fordert weitere Tools an.
Das Modell führt nie etwas aus. Ihr Code entscheidet, was ausgeführt wird.
Wie sollten Sie Tool-Schemas schreiben?
Offene Modelle halten sich zuverlässiger an einfache Schemas. Diese Regeln stammen aus dem Leitfaden von OpenAI und aus dem, was erfahrungsgemäß bricht:
- Benennen Sie Tools nach der Aktion, etwa
read_fileodersearch_code, und sagen Sie in der Beschreibung, wann jedes zu nutzen ist. - Halten Sie die Liste kurz. Der Leitfaden von OpenAI nennt weniger als 20 Funktionen zu Beginn eines Zugs als weiche Empfehlung. Jedes Schema wird außerdem bei jedem Aufruf mitgesendet; siehe das Token-Budget von Agenten.
- Bevorzugen Sie flache Argumente. Strings, Zahlen, Booleans und Enums. Vermeiden Sie tiefe Verschachtelung und freie Objekte.
- Nutzen Sie Enums für feste Auswahlwerte, damit das Modell keinen Wert erfinden kann. Der JSON-Schema-Generator macht aus einem Beispielobjekt mit Argumenten ein flaches Schema, das Sie in
parameterseinfügen können. - Markieren Sie Pflichtfelder. Der Strict Mode von OpenAI verlangt
additionalProperties: falseund jedes Feld inrequired, mitnullals zusätzlichem Typ für optionale Felder. Ob ein Anbieterstrictdurchsetzt, ist unterschiedlich, validieren Sie also trotzdem.
Was ist mit parallelen Tool Calls?
Ein Modell kann in einem Zug mehrere Einträge in tool_calls zurückgeben, zum Beispiel drei Dateizugriffe. Führen Sie unabhängige Aufrufe parallel aus und geben Sie ein Ergebnis pro tool_call_id zurück, in beliebiger Reihenfolge. Haben Ihre Tools Seiteneffekte, die voneinander abhängen, setzen Sie parallel_tool_calls: false; laut dem Leitfaden von OpenAI beschränkt das das Modell auf keinen oder einen Aufruf pro Zug. Testen Sie, ob Ihr Anbieter das beachtet.
Warum scheitern Tool Calls?
| Fehler | Was Sie sehen | Lösung |
|---|---|---|
| Fehlerhafte Argumente | json.loads wirft eine Ausnahme |
Parse-Fehler als Tool-Ergebnis zurückgeben; Retry |
| Schema-Abweichung | Fehlendes Feld, falscher Typ, erfundener Enum-Wert | Validieren; Validierungsfehler zurückgeben |
| Unbekanntes Tool | Ein Name, den Sie nie definiert haben | „unknown tool, available: …“ zurückgeben |
| Kein Aufruf, obwohl nötig | Stattdessen eine Textantwort | tool_choice: "required" oder eine benannte Funktion |
| Abgeschnittener Aufruf | finish_reason: "length" |
max_tokens erhöhen; Reasoning teilt sich das Limit |
Die ersten beiden sind zu erwarten, nicht selten. Die Tool-Calling-Doku von vLLM sagt, dass im Modus auto, sofern kein Tool strict: true setzt (oder der Server eine Mindest-Strenge erzwingt) und der Parser des Modells Constraints unterstützt, gilt: „vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.“ (Übersetzung: „vLLM extrahiert Tool Calls aus Rohtext, daher können Argumente gelegentlich fehlerhaft sein oder das Parameter-Schema der Funktion verletzen.“) Eine benannte Funktion nutzt das Structured-Outputs-Backend von vLLM. Ihr Anbieter kann Modelle anders bereitstellen, behandeln Sie die Validierung also als Pflicht.
Die letzte Zeile erwischt alle, die Reasoning-Modelle nutzen. GLM 5.3 und Qwen3.8 27B denken nach, bevor sie antworten, und das Thinking zählt zu max_tokens. Warum Antworten leer oder abgeschnitten zurückkommen erklärt, wie viel Platz Sie lassen sollten.
Eine Tool-Schleife mit Validierung und Retry
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")
Drei Designentscheidungen sind hier wichtig:
- Fehler gehen als Tool-Ergebnis an das Modell zurück. Das Modell sieht, was falsch war, und behebt es meist im nächsten Zug. Eine Ausnahme zu werfen verschenkt diese Chance.
- Die Schleife ist begrenzt.
max_stepsstoppt ein Modell, das ohne Fortschritt immer weiter Tools aufruft. - Transport-Retries sind getrennt.
max_retriesam Client behandelt 429 und 5xx. Falsche Argumente werden in der Schleife behandelt. Vermischen Sie beides nicht; siehe Fehler und Retries.
Für Tools mit Seiteneffekten, etwa dem Versand einer E-Mail, ergänzen Sie einen Idempotenzschlüssel, damit ein wiederholter Schritt nicht doppelt handelt. Lang laufende Agenten behandelt das.
Welche BroadNet-Modelle unterstützen Tool Calling?
| Modell | Tools gelistet | Kontext | Hinweise |
|---|---|---|---|
| GLM 5.3 | Ja | 1.048.576 | Auch strukturierte Ausgabe |
| Qwen3.8 27B | Ja | 262.144 | Auch Bildeingabe |
| DeepSeek V4.1 Flash | Nicht gelistet | 1.048.576 | Bildeingabe; Tools vor dem Einsatz testen |
| Gemma 4 VL 26B | Nicht gelistet | 32.768 | Nicht für Tool-Schleifen |
Für die Wahl zwischen den beiden Modellen mit Tool-Unterstützung siehe GLM 5.3 vs. Qwen3.8 27B. Muss die endgültige Antwort einer Form entsprechen, ohne dass eine Funktion laufen muss, ist strukturierte Ausgabe einfacher als ein Tool.
Wo BroadNet Inference ins Bild passt
BroadNet Inference stellt GLM 5.3 und Qwen3.8 27B mit gelistetem Tool Calling über das Standardformat für Chat Completions bereit, sodass die Schleife oben unverändert mit dem OpenAI Python SDK läuft. Die Preise pro Token stehen auf der Preisseite. BroadNet hostet keine serverseitigen Tools wie Websuche oder Codeausführung, und die Doku listet kein Tool Calling für DeepSeek V4.1 Flash, das Modell der unbegrenzten Pläne. Für einen Agenten mit vielen Tool-Aufrufen nutzen Sie GLM 5.3 oder Qwen3.8 27B pro Token. Wenn Sie trotzdem die Flatrate wollen, prüfen Sie mit einer Meteor-Stunde für $1, ob DeepSeek V4.1 Flash Ihre Tools zuverlässig aufruft, bevor Sie einen Monat kaufen.
