L’appel d’outils est ce qui transforme un modèle en agent. Avec des modèles ouverts sur une API compatible OpenAI, le format de requête est celui que vous utiliseriez avec OpenAI. Ce qui change, c’est la fréquence des ratés et ce que fait le serveur pour les éviter. Cet article couvre le format, la façon d’écrire des schémas que les modèles ouverts gèrent bien, les appels parallèles, les cinq échecs que vous rencontrerez vraiment et une boucle Python qui y résiste.
Comment fonctionne l’appel d’outils sur une API compatible OpenAI ?
- Vous envoyez
messageset une listetools. Chaque outil a un nom, une description et un JSON Schema pour ses arguments. - Le modèle répond avec
finish_reason: "tool_calls"et une listetool_calls. Chaque entrée comporte unid, un nom de fonction et desargumentssous forme de chaîne JSON. - Votre code exécute chaque appel et ajoute un message
role: "tool"par appel, avec letool_call_idcorrespondant. - Vous rappelez l’API. Le modèle répond ou demande d’autres outils.
Le modèle n’exécute jamais rien. C’est votre code qui décide de ce qui s’exécute.
Comment écrire des schémas d’outils ?
Les modèles ouverts suivent plus fiablement des schémas simples. Ces règles viennent du guide d’OpenAI et de ce qui casse en pratique :
- Nommez les outils par action, comme
read_fileousearch_code, et dites dans la description quand utiliser chacun. - Gardez la liste courte. Le guide d’OpenAI présente le seuil de moins de 20 fonctions au début d’un tour comme une suggestion souple. Chaque schéma est en outre envoyé à chaque appel ; voir le budget de tokens d’un agent.
- Préférez des arguments plats. Chaînes, nombres, booléens et enums. Évitez l’imbrication profonde et les objets libres.
- Utilisez des enums pour les choix fixes, afin que le modèle ne puisse pas inventer de valeur. Le générateur de JSON Schema transforme un objet d’arguments d’exemple en schéma plat à coller dans
parameters. - Marquez les champs obligatoires. Le mode strict d’OpenAI exige
additionalProperties: falseet tous les champs dansrequired, avecnullcomme type pour les champs facultatifs. L’application destrictvarie selon les fournisseurs : validez de toute façon.
Et les appels d’outils parallèles ?
Un modèle peut renvoyer plusieurs entrées dans tool_calls en un seul tour, par exemple trois lectures de fichiers. Exécutez les appels indépendants en parallèle et renvoyez un résultat par tool_call_id, dans n’importe quel ordre. Si vos outils ont des effets de bord qui dépendent les uns des autres, réglez parallel_tool_calls: false ; selon le guide d’OpenAI, cela limite le modèle à zéro ou un appel par tour. Vérifiez que votre fournisseur le respecte.
Pourquoi les appels d’outils échouent-ils ?
| Échec | Ce que vous voyez | Correctif |
|---|---|---|
| Arguments mal formés | json.loads lève une exception |
Renvoyer l’erreur de parsing comme résultat d’outil ; relancer |
| Non-conformité au schéma | Champ manquant, mauvais type, enum inventé | Valider ; renvoyer l’erreur de validation |
| Outil inconnu | Un nom que vous n’avez jamais défini | Renvoyer « unknown tool, available: … » |
| Pas d’appel alors qu’il en faut un | Une réponse en texte à la place | tool_choice: "required" ou une fonction nommée |
| Appel coupé | finish_reason: "length" |
Augmenter max_tokens ; le raisonnement le partage |
Les deux premiers sont attendus, pas rares. La documentation de vLLM sur l’appel d’outils indique qu’en mode auto, sauf si un outil définit strict: true (ou si le serveur impose un niveau minimal de rigueur) et que le parseur du modèle prend en charge les contraintes, « vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema. » (traduction : « vLLM extrait les appels d’outils du texte brut, si bien que les arguments peuvent parfois être mal formés ou enfreindre le schéma de paramètres de la fonction. ») Une fonction nommée passe par le backend de structured outputs de vLLM. Votre fournisseur peut servir les modèles autrement : considérez la validation comme obligatoire.
La dernière ligne piège ceux qui utilisent des modèles de raisonnement. GLM 5.3 et Qwen3.8 27B réfléchissent avant de répondre, et la réflexion compte dans max_tokens. Pourquoi les réponses reviennent vides ou coupées explique quelle marge laisser.
Une boucle d’outils qui valide et relance
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")
Trois choix de conception comptent ici :
- Les erreurs reviennent au modèle comme résultats d’outil. Le modèle voit ce qui n’allait pas et le corrige généralement au tour suivant. Lever une exception gâche cette occasion.
- La boucle est bornée.
max_stepsarrête un modèle qui enchaîne les appels d’outils sans progresser. - Les relances réseau sont séparées.
max_retriessur le client gère les 429 et les 5xx. Les mauvais arguments sont gérés dans la boucle. Ne mélangez pas les deux ; voir erreurs et relances.
Pour les outils à effets de bord, comme l’envoi d’un e-mail, ajoutez une clé d’idempotence pour qu’une étape relancée n’agisse pas deux fois. Les agents de longue durée traitent ce point.
Quels modèles BroadNet prennent en charge l’appel d’outils ?
| Modèle | Outils indiqués | Contexte | Remarques |
|---|---|---|---|
| GLM 5.3 | Oui | 1 048 576 | Aussi sortie structurée |
| Qwen3.8 27B | Oui | 262 144 | Aussi entrée image |
| DeepSeek V4.1 Flash | Non indiqué | 1 048 576 | Entrée image ; testez les outils avant d’en dépendre |
| Gemma 4 VL 26B | Non indiqué | 32 768 | Pas pour des boucles d’outils |
Pour choisir entre les deux modèles qui gèrent les outils, voir GLM 5.3 vs Qwen3.8 27B. Quand la réponse finale doit respecter une forme sans qu’aucune fonction n’ait besoin de s’exécuter, la sortie structurée est plus simple qu’un outil.
La place de BroadNet Inference
BroadNet Inference sert GLM 5.3 et Qwen3.8 27B, pour lesquels l’appel d’outils est indiqué, via le format standard des chat completions : la boucle ci-dessus tourne sans modification avec le SDK Python d’OpenAI. Les prix au token figurent sur la page des prix. BroadNet n’héberge pas d’outils côté serveur comme la recherche web ou l’exécution de code, et sa documentation n’indique pas l’appel d’outils pour DeepSeek V4.1 Flash, le modèle des forfaits illimités. Pour un agent très dépendant des outils, utilisez GLM 5.3 ou Qwen3.8 27B au token. Si vous voulez quand même le forfait, vérifiez sur une heure Meteor à $1 que DeepSeek V4.1 Flash appelle vos outils de façon fiable avant d’acheter un mois.
