Budgets de session

Un budget de session est un plafond de dépenses strict et facultatif que vous définissez lorsque vous créez une session. La plateforme évalue en continu tout ce que la session consomme aux tarifs publics (le coût au tarif public, ou « list cost », de la session) et cesse d'émettre de nouvelles requêtes au modèle dès que ce coût atteint le budget. La requête en cours au moment où le plafond est franchi se termine tout de même, de sorte que le coût au tarif public final peut se situer légèrement au-delà du budget. Une session ayant atteint son budget se met en pause et passe à l'état idle (inactif) au lieu de se terminer ; modifier ou supprimer le budget reprend automatiquement son travail. Les déploiements acceptent le même budget et l'appliquent à chaque session qu'ils démarrent ; consultez Budgets sur les déploiements.

Définir un budget à la création de la session

Transmettez le champ facultatif budget lorsque vous créez la session :

# Gardez le montant entre guillemets pour qu'il soit envoyé comme chaîne, et non comme nombre.
SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}' \
  --transform id --raw-output)

L'objet budget comporte deux champs :

• type vaut toujours "limit".
• max_list_cost est le plafond lui-même : amount est un nombre entier de cents américains écrit sous forme de chaîne sans zéros initiaux ("125" correspond à 1,25 $ et "50" à 50 cents) et doit être supérieur à zéro. Les formes décimales telles que "25.00" sont rejetées. Le montant est une chaîne plutôt qu'un nombre afin qu'aucun arrondi en virgule flottante ne lui soit jamais appliqué. currency est un code de devise ISO-4217 en majuscules ; USD est la seule devise prise en charge.

Un budget ne peut être attaché qu'au moment de la création de la session. L'ajout d'un budget à une session existante qui n'en possède pas est rejeté avec une erreur 400. Le plafond d'une session dotée d'un budget peut être modifié ou supprimé à tout moment.

Comment le coût au tarif public est mesuré

La plateforme évalue ce que la session consomme, en continu, aux tarifs publics :

• Les tokens du modèle, au tarif public de chaque modèle servi
• Les recherches web, à 10 $ pour 1 000 recherches
• Le temps d'exécution de la session, à 0,08 $ par heure

Ce total cumulé en dollars constitue le coût au tarif public de la session, et c'est à lui que le budget est comparé. Le coût au tarif public n'est pas votre prix contractuel : si votre organisation a négocié des remises, la session atteint son plafond lorsque le total au tarif public l'atteint, et vos dépenses facturées peuvent être inférieures au plafond.

L'application du plafond utilise le coût au tarif public exact, non arrondi. Les valeurs list_cost indiquées sur la session et ses événements sont des cents entiers, arrondis au cent le plus proche, de sorte qu'une valeur indiquée peut s'écarter jusqu'à un demi-cent, dans un sens ou dans l'autre, du montant exact utilisé pour l'application du plafond.

Lorsqu'une session atteint son budget

Le plafond est appliqué entre les requêtes au modèle, et non au milieu d'une requête. Avant chaque requête au modèle, la plateforme vérifie le coût au tarif public consommé par la session, et dès que ce total atteint le plafond, chaque thread se met en pause avant sa prochaine requête. La requête qui a fait passer le total au-delà du plafond a été admise alors que la session était encore en dessous et s'exécute jusqu'à son terme, de sorte que le list_cost enregistré d'une session en pause est égal ou légèrement supérieur à max_list_cost : une session plafonnée à "50" (50 cents) peut se mettre en pause avec un list_cost de "53". Ce comportement est attendu, il ne s'agit pas d'une erreur de facturation, et le dépassement est borné à une requête au modèle par thread. Considérez le budget comme une limite sur les nouveaux travaux plutôt que comme un point d'arrêt exact, et dimensionnez le plafond en tenant compte de cette marge d'une requête.

Une session qui atteint son budget passe à l'état inactif avec un stop_reason de budget_reached ; elle n'est pas terminée, et son historique ainsi que son sandbox sont conservés comme ceux de toute autre session inactive. Sur le flux d'événements, vous verrez, dans l'ordre :

1. Un événement session.thread_status_idle avec un stop_reason de budget_reached à mesure que chaque thread se met en pause.
2. Un événement session.usage avec l'utilisation cumulée et le coût au tarif public de la session.
3. Un événement session.status_idle avec un stop_reason de budget_reached. L'événement d'utilisation précède toujours immédiatement cet événement d'inactivité.

Un thread dont la requête finale franchit le plafond et termine son tour en même temps indique end_turn sur son propre événement session.thread_status_idle, tandis que la session indique toujours budget_reached ; considérez le stop_reason au niveau de la session comme le signal que la session s'est mise en pause à son budget.

Événements acceptés au plafond

Tant que la session est à son budget ou au-delà, elle n'accepte que les événements qui règlent un travail déjà en cours :

• user.tool_confirmation
• user.tool_result
• user.custom_tool_result
• user.interrupt

Tout événement qui démarrerait un nouveau travail, tel que user.message, est rejeté avec une erreur 400 mentionnant cette liste. Les résultats réglés sont enregistrés sans déclencher de nouvelle requête au modèle ; la session reste en pause à son budget.

Un user.interrupt envoyé alors que la session est en pause à son budget (tous les threads en pause au plafond) est accepté et ignoré : il n'apparaît pas dans la liste des événements et ne change rien. Modifiez ou supprimez le budget pour continuer.

Reprendre une session ayant atteint son budget

Modifiez ou supprimez le budget au moyen d'une mise à jour de la session. Une mise à jour acceptée reprend automatiquement le travail en pause de la session ; aucune autre action du client n'est nécessaire.

Modifier le budget

Mettez à jour la session avec un nouveau max_list_cost. La nouvelle valeur peut être supérieure ou inférieure au plafond actuel, mais elle doit être strictement supérieure au coût au tarif public consommé par la session ; sinon, la mise à jour est rejetée avec une erreur 400 : budget.max_list_cost must be greater than the session's consumed list cost. Comme le coût consommé se situe généralement légèrement au-delà de l'ancien plafond lorsque la session se met en pause, basez la nouvelle valeur sur le usage.list_cost indiqué par la session, et non sur l'ancien max_list_cost. Fixez-la à un cent ou plus au-dessus de cette valeur : la valeur indiquée est arrondie et peut se situer légèrement en dessous du coût consommé exact utilisé par la vérification.

ant beta:sessions update \
  --session-id "$SESSION_ID" \
  --budget '{type: limit, max_list_cost: {amount: "500", currency: USD}}'

Supprimer le budget

Définissez budget sur null pour supprimer entièrement le plafond. Le travail en pause de la session reprend, et l'événement session.updated qui en résulte contient budget défini sur null.

ant beta:sessions update --session-id "$SESSION_ID" --budget null

Surveiller les dépenses

L'objet session contient son budget et un objet usage avec les dépenses suivies : usage.list_cost est le coût au tarif public consommé par la session, et usage.active_seconds est le temps d'exécution sur lequel son coût d'exécution est évalué. Sur une session en pause à budget_reached, attendez-vous à ce que usage.list_cost soit égal ou légèrement supérieur à max_list_cost : la requête qui a franchi le plafond s'est terminée avant la pause. Le active_seconds au niveau de la session ne compte qu'une seule fois l'activité simultanée de threads concurrents. Les réponses de récupération de thread contiennent les deux mêmes champs dans le usage propre au thread, évalués par thread. Les valeurs par thread sont arrondies indépendamment et excluent le coût du temps d'exécution de la session, de sorte que leur somme ne correspond pas exactement au list_cost de la session ; c'est la valeur de la session qui sert à l'application du budget.

L'événement session.usage est un instantané de l'utilisation cumulée et du coût au tarif public suivi de la session. Il contient les totaux de tokens de la session, list_cost, active_seconds, les compteurs de requêtes server_tool_use (web_search_requests, intégré au coût au tarif public par requête, et web_fetch_requests, qui vaut 0 car les requêtes de récupération web n'entraînent aucun frais par requête et ne sont pas mesurées), ainsi qu'une copie du budget de la session, ou null lorsque la session n'en a pas. Il apparaît dans la liste des événements et dans le flux de la session. La session en émet un immédiatement avant de passer à l'état inactif, quelle que soit la raison d'arrêt, de sorte qu'une session qui atteint son budget en émet toujours un immédiatement avant l'événement d'inactivité lié au budget atteint.

Pour lire l'utilisation depuis le flux et l'objet session, consultez Suivi de l'utilisation.

Budgets dans les sessions multi-agents

Une session multi-agents dispose d'un budget unique partagé entre tous ses threads ; il n'existe pas de plafonds par thread. La consommation de chaque thread est évaluée au tarif de son propre modèle servi, et les threads se mettent en pause indépendamment à mesure que le plafond partagé est atteint. Les consultations du conseiller sont imputées au même budget, évaluées aux tarifs du modèle conseiller. Un thread peut se mettre en pause à budget_reached pendant qu'un autre termine sa requête en cours.

Une demande en attente prime sur le plafond : une session dont un thread attend sur requires_action et un autre est en pause à budget_reached indique requires_action au niveau de la session. La demande en attente nécessite toujours une réponse, et y répondre constitue un événement de règlement que le budget ne bloque pas.

Budgets sur les déploiements

Un déploiement accepte le même objet budget lorsque vous le créez ou le mettez à jour :

{
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "2000", "currency": "USD" }
  }
}

Le plafond est copié sur chaque session que le déploiement démarre, de sorte qu'il limite chaque exécution séparément plutôt que les dépenses cumulées du déploiement. La modification du budget du déploiement s'applique aux sessions que le déploiement démarre par la suite, et non aux sessions déjà en cours d'exécution. Contrairement à une session, le budget d'un déploiement peut être effacé avec null puis défini à nouveau ultérieurement. Consultez Définir un budget sur chaque exécution.

Modèles sans tarif public

Un budget ne peut suivre que la consommation que la plateforme est en mesure d'évaluer. La création d'une session dotée d'un budget dont l'agent, ou tout agent ou conseiller de sa liste multi-agents, utilise un modèle sans tarif public est rejetée avec une erreur 400 indiquant qu'aucun tarif public n'est disponible pour le modèle.

Si l'utilisation d'une session dotée d'un budget vient à inclure un modèle sans tarif public, le budget ne peut plus mesurer les dépenses de la session : la session peut se mettre en pause avec un stop_reason de budget_reached, et la modification du budget est rejetée. Supprimez le budget pour reprendre la session.

Référence des erreurs

Les requêtes liées au budget sont rejetées dans les cas suivants :