Guide · IA & agents
Mesurer le coût d'un agent, sans chiffre
Appels, tokens, temps, stockage, hébergement, outils. Méthode lue dans les docs. Aucun montant inscrit.
Le coût réel d’un agent ne tient pas sur une ligne de barème recopiée. Ce guide sert à construire un relevé à partir de vos propres volumes et de vos propres tarifs. Il ne fournit aucun tarif par défaut. Aucun appel n’a été lancé, aucun compte fournisseur n’a été ouvert et aucune facture n’a été consultée.
La carte des guides est sur Agents IA : où lire. Le journal d’un run, qui n’est pas la facture, est sur Observer un run d’agent.
Appels
Un tour d’agent n’est pas un seul appel. Track cost and usage sépare l’appel à query(), l’étape et la session. Un query() peut enchaîner plusieurs étapes : le modèle répond, appelle des outils, reçoit leurs résultats, puis répond de nouveau. Quand plusieurs outils partent dans la même étape, les messages d’assistant peuvent reprendre le même identifiant. La documentation demande de les dédupliquer avant de sommer l’usage par étape.
Le champ usage du résultat ne compte que la boucle du niveau supérieur. Les jetons consommés dans un sous-agent n’y sont pas. total_cost_usd et model_usage les incluent. Lire seulement usage sous-compte dès qu’il y a une imbrication. Une session reprise ajoute la dépense antérieure au résultat du nouvel appel. Ce ne sont pas des volumes mesurés ici. Ce sont les périmètres écrits, pour savoir quoi additionner le jour où un run existera.
Côté organisation Claude, l’Usage and Cost API agrège les appels par intervalles de temps, et permet de grouper par modèle, clé, espace de travail, palier. Elle demande une clé d’administration, ou un jeton du même rang. Une clé d’espace de travail ne suffit pas. Les comptes individuels n’ont pas cette API. Les organisations Enterprise passent par une autre clé, décrite sur la même page. Je n’ai pas appelé l’endpoint.
Tokens
Les compteurs nommés ne se résument pas à une entrée et une sortie. L’API d’usage sépare l’entrée non cachée, l’entrée lue dans le cache, la création de cache, et la sortie. La page de suivi du SDK dit la même chose avec d’autres noms de champs : input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens. Le cache en écriture et le cache en lecture ne sont pas tarifés comme l’entrée simple. Les barèmes ne sont pas recopiés.
Le output_tokens d’un message d’assistant, en cours de réponse, est un placeholder. La page dit de lire le compte de sortie sur le message de résultat, ou sur model_usage si vous voulez le détail par modèle. Les compter un par un reprend la même étape plusieurs fois, ou fige un total qui n’est pas celui du résultat. Aucun de ces champs n’a été lu sur un run réel.
total_cost_usd et costUSD sont des estimations calculées dans le client, à partir d’une table de prix embarquée, sauf table modelPricing en vigueur. La page dit qu’elles dérivent de la facture quand les prix changent, quand le SDK installé ne reconnaît pas le modèle, ou quand une règle de facturation n’est pas modélisable côté client. Une règle de résidence est modélisée. D’autres ne le sont pas. La page interdit de facturer un utilisateur final, ou de prendre une décision financière, à partir de ces champs. La facture se lit dans l’API d’usage et de coût, ou sur la page Usage de la console.
Temps
Le temps n’est pas un poste unique. Une trace de l’Agents SDK a, sur chaque span, un début et une fin. Cela date une génération, un outil, un handoff. Ce n’est pas le temps facturé par l’hébergeur du processus.
Le message de résultat du SDK Claude porte une durée d’appel, à côté de l’estimation de coût. La page la nomme pour dire qu’elle inclut l’attente des sous-agents encore en cours à la fin du tour, dans la limite écrite ailleurs. Je n’ai pas lu cette durée sur une session.
L’API d’usage range les jetons dans des seaux de temps. Ce n’est pas la durée d’une tâche métier. C’est la fenêtre dans laquelle les appels sont additionnés. La page dit que les données apparaissent en général peu après la fin de la requête, avec des retards possibles. Aucun délai n’a été chronométré.
Quand Claude Code tourne dans GitHub Actions, la page de l’action nomme une autre horloge : les minutes du runner, à part des jetons. Claude Code dans un workflow GitHub renvoie à cette page. Les barèmes de minutes ne sont pas ici.
Stockage
L’historique que vous gardez a un support. How Claude Code works indique que Claude Code écrit les messages, appels d’outils et résultats dans des fichiers JSONL sous ~/.claude/projects/. Ces fichiers ne sont pas une facture du modèle. Ils occupent le disque de la machine qui héberge la session. Leur taille n’a pas été mesurée ici.
L’Agents SDK peut utiliser le stockage de votre application, des sessions SDK ou un état de conversation côté serveur, selon le runtime choisi. Mémoire d'agent décrit le cas d’un fichier SQLite, sans tarif. Une base qui grossit, des traces exportées et les fichiers indexés par un outil de recherche sont autant de postes de stockage. Leur taille n’a pas été mesurée.
Hébergement
La boucle tourne quelque part. La page Agents sépare un harness hébergé, le SDK dans votre application, et votre propre environnement d’exécution. Le processus que vous hébergez a son propre poste : machine, conteneur, ou runner. Déployer un agent avec Docker et Quel VPS pour un agent tiennent ces choix. Leurs prix, s’ils en ont, ne sont pas recopiés ici.
Un agent qui ne fait qu’appeler une API hébergée n’annule pas ce poste s’il garde un worker, une file, ou une base. Il le déplace. Cette page ne choisit pas l’endroit.
Outils
Les outils ne sont pas tous dans le compteur de jetons. L’API d’usage suit à part les outils serveur, dont la recherche web. L’exécution de code apparaît dans l’endpoint de coût, pas dans l’endpoint d’usage. Un palier prioritaire se filtre dans l’usage, et ses coûts ne sont pas dans l’endpoint de coût. Lire un seul des deux endpoints manque un poste. Je n’ai lu ni l’un ni l’autre sur un compte.
Un outil que votre code exécute, une base, une API tierce, un envoi, a sa facture chez celui qui le fournit. Elle n’entre pas dans usage du modèle. La piste OpenAI le dit en séparant l’appel de fonction, exécuté chez vous, et l’outil hébergé, exécuté sur leur infrastructure. Les deux peuvent coûter. Pas au même endroit.
Les frais par requête, quand la page de suivi du SDK les nomme, ne sont pas multipliés par la règle de résidence qu’elle décrit pour les jetons. Le montant de ces frais n’est pas recopié.
Feuille de calcul sans valeur par défaut
Remplissez uniquement les lignes qui correspondent à votre architecture. Chaque volume et chaque prix unitaire doit venir de votre relevé ou de la grille officielle applicable à votre compte. Une case inconnue reste vide : ne la remplacez pas par une moyenne trouvée ailleurs.
| Entrée à fournir | Unité | Source de votre valeur |
|---|---|---|
| Entrée non cachée | jetons | Rapport d’usage du fournisseur |
| Création de cache | jetons | Rapport d’usage du fournisseur |
| Lecture du cache | jetons | Rapport d’usage du fournisseur |
| Sortie | jetons | Rapport d’usage du fournisseur |
| Outils hébergés | appels ou unités facturées | Rapport d’usage ou facture de l’outil |
| Exécution de code | unité facturée | Rapport de coût du fournisseur |
| Worker ou runner | durée facturée | Relevé de l’hébergeur ou de la CI |
| Stockage | volume et durée facturés | Relevé du stockage |
| API tierces | unité propre au service | Facture du service concerné |
Pour chaque ligne renseignée, calculez volume saisi × prix unitaire saisi. Additionnez ensuite les sous-totaux saisis. N’appliquez pas un prix de jeton aux outils, au stockage ou au temps machine : leurs unités et leurs factures sont différentes. Cette méthode ne produit aucun résultat tant que le lecteur n’a pas fourni les deux facteurs de chaque ligne.
Ce que le relevé devrait contenir
| Poste | Où le lire, d’après les pages | Valeur par défaut |
|---|---|---|
| Appels | Étapes, sous-agents, groupements de l’API d’usage | Aucune |
| Tokens | Entrée, sortie, création de cache, lecture de cache | Aucune |
| Temps | Spans, durée d’appel, minutes de runner | Aucune |
| Stockage | Journal de session, fichier d’historique, checkpoints | Aucune |
| Hébergement | Processus, conteneur, machine, runner | Aucune |
| Outils | Outils serveur, exécution de code, API que vous appelez | Aucune |
Une estimation client n’est pas une ligne de facture. Une facture d’API n’est pas le coût du worker. Additionner les deux sans les nommer produit un total faux. Le total n’est pas calculé ici, parce que les cases sont vides.
Sources
- Anthropic Agent SDK, Track cost and usage : périmètre de
query(), étapes, sous-agents, champs d’usage et limites des estimations client. - Anthropic, Usage and Cost API : jetons, outils serveur, exécution de code, granularité et droits d’accès.
- Claude Code, How Claude Code works : stockage local des sessions en JSONL.
- OpenAI, Agents : répartition de l’exécution, de l’état et des outils entre API, SDK et application.
- OpenAI Agents SDK, Tracing : traces, spans et horodatages de début et de fin.
Sources relues le 2026-10-19. Aucune console Usage, aucune clé d’administration, aucun query() et aucun run d’agent n’ont été utilisés. Les barèmes restent sur les pages tarifaires des fournisseurs ; cette page n’en préremplit aucun.