Outils serveur

Les outils serveur sont des capacités que Synthorai exécute pour vous au sein d'une même requête : le modèle demande quelque chose, nous faisons le travail, et le résultat revient dans la même réponse. Vous ajoutez une entrée à tools — pas de second endpoint, pas de callback à implémenter.

Outils disponibles

Chaque outil serveur est identifié par le préfixe synthorai:, il n'entre donc jamais en collision avec vos propres noms d'outils :

Paramètre	Description	Prix
`synthorai:web_search`	Chercher sur le web et lire les résultats.	$0.01
`synthorai:web_fetch`	Lire le texte intégral d'une page dont vous avez déjà l'URL.	$0.01

Le contrat commun

Chaque outil serveur se comporte de la même façon : ce que vous apprenez sur l'un s'applique au suivant :

Opt-in uniquement. Rien ne s'exécute si vous ne mettez pas l'outil dans tools. Une requête sans lui est une requête ordinaire.
Un seul aller-retour. Nous pilotons la boucle d'outils pour vous ; vous recevez une réponse unique contenant déjà l'activité de l'outil et la réponse.
Vos propres outils fonctionnent toujours. Outils serveur et outils function peuvent être déclarés ensemble — quand le modèle appelle l'un des vôtres, nous vous rendons la main avec un honnête stop_reason: tool_use. (Une exception : les noms que nous injectons sont réservés — voir plus bas.)
Tarification à l'appel, visible dans usage. Les compteurs atterrissent dans usage.server_tool_use et le montant dans usage.cost, chaque requête peut donc être rapprochée de sa facture.
max_uses est un vrai plafond. Il limite ce qu'une requête peut dépenser, et il tient à travers les réessais internes.

Les tokens sont l'autre moitié du coût

Le tarif à l'appel d'un outil serveur n'est qu'une partie du coût d'une requête. Ce que l'outil rapporte — extraits de recherche, corps de page — entre dans la conversation comme tokens d'entrée, facturés au tarif normal du modèle. Pour les pages longues, ce coût en tokens est généralement le plus gros chiffre. Et comme la passerelle exécute la boucle d'outils en interne, usage.input_tokens est la somme de tous les tours internes : il sera nettement supérieur au prompt envoyé. C'est le vrai coût de la réinjection des résultats dans le modèle, pas une double facturation.

Poursuivre la conversation

Réinjectez le message assistant dans messages exactement comme vous l'avez reçu, blocs d'outils compris. Continuez à déclarer le même outil serveur dans les requêtes suivantes pour garder l'historique sous sa forme la plus riche ; si vous retirez l'outil, les résultats antérieurs sont aplatis en texte brut mais le modèle voit toujours le contenu.

Noms d'outils réservés

Tant que vous utilisez un paramètre synthorai:, le nom nu correspondant est réservé : déclarer votre propre outil nommé web_search à côté de synthorai:web_search (ou web_fetch à côté de synthorai:web_fetch) renvoie un 400 nommant l'outil. Renommez le vôtre, ou retirez le paramètre synthorai:.

La raison : nous injectons l'outil serveur sous ce nom exact. Deux outils arriveraient au modèle sous un seul nom et personne ne saurait à qui appartient l'appel qui revient — les arguments de votre outil pourraient partir vers notre fournisseur de recherche, et votre appel pourrait se perdre. Refuser la requête est la seule réponse honnête. Déclarer votre propre outil sous l'un ou l'autre nom sans le paramètre synthorai: correspondant n'est pas affecté : nous n'injectons rien, donc rien n'entre en collision.

Les échecs ne sont pas facturés

Le tarif à l'appel s'applique aux appels ayant produit un résultat. Un appel refusé avant de quitter notre réseau — URL rejetée, domaine bloqué, backend non configuré — ne vous coûte rien. Un appel arrivé chez le fournisseur et qui y a échoué est facturé, parce que le fournisseur nous a facturés. Dans les deux cas le tour compte dans votre budget max_uses : un modèle qui réessaie une URL cassée ne peut pas boucler gratuitement.

Endpoints pris en charge

Les outils serveur fonctionnent sur /v1/messages, /v1/chat/completions et /v1/responses. Envoyer un paramètre synthorai: à un endpoint qui ne les prend pas en charge — un endpoint Gemini — renvoie un 400 qui vous le dit. Nous préférons refuser plutôt que transmettre un outil inconnu en amont : au mieux une erreur tierce déroutante, au pire il est ignoré en silence, la recherche n'a jamais lieu, et vous payez une requête normale qui a discrètement fait moins que demandé.

Disponibilité

Les outils serveur s'activent par clé API. Si un outil n'est pas activé pour votre clé, vous recevez un 400 explicite le nommant, plutôt qu'un paramètre ignoré en silence. Contactez-nous pour l'activer.