Budgets de session

Un « session budget » (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 catalogue (le « list cost » (coût au prix catalogue) 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 prix catalogue final peut se situer légèrement au-delà du budget. Une session qui atteint son budget se met en pause et passe à l’état inactif au lieu de se terminer ; modifier ou supprimer le budget reprend le travail que le budget avait mis en pause. 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 :

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"},
    },
)
print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125

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 non significatifs ("125" correspond à 1,25 $ USD 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 à 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 $ USD pour 1 000 recherches
• Le temps d’exécution de la session, à 0,08 $ USD 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 exprimées en cents entiers, arrondies au cent le plus proche, de sorte qu’une valeur indiquée peut s’écarter d’un demi-cent au plus, 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 prix catalogue consommé par la session, et dès que ce total atteint le plafond, chaque fil d’exécution se met en pause avant sa requête suivante. La requête qui a fait passer le total au-delà du plafond a été admise alors que la session se trouvait encore en dessous, et elle s’exécute jusqu’à son terme. En conséquence, le list_cost enregistré d’une session en pause est égal ou légèrement supérieur à max_list_cost. Par exemple, une session plafonnée à "50" (50 cents) peut se mettre en pause avec un list_cost de "53". Ce comportement est attendu et ne constitue pas une erreur de facturation. Les dépenses liées au modèle au-delà du plafond correspondent au maximum au coût d’une requête au modèle par fil d’exécution. Les appels d’outils contenus dans la réponse à cette requête s’exécutent tout de même, et leurs recherches web ainsi que leur durée d’exécution sont également comptabilisées dans le coût au prix catalogue. 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.

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 pour 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 fil 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é.

Si des exécutions de workflow sont ouvertes, chacune d’elles qui n’est pas déjà inactive reçoit également un événement workflow_run.status_idle.

Un fil dont la dernière requête à la fois franchit le plafond et termine son tour 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 indiquant 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 fils en pause au plafond) est accepté, et il n’apparaît pas dans la liste des événements. Il n’arrête aucun fil, car chaque fil est déjà en pause. Modifiez ou supprimez le budget pour continuer.

Si la session comporte des exécutions de workflow ouvertes, l’interruption peut les mettre en pause, comme le ferait une interruption à tout autre moment. Une exécution mise en pause par une interruption ne reprend pas lorsque vous modifiez ou supprimez le budget. Pour la poursuivre, modifiez ou supprimez le budget, puis envoyez un user.message demandant à l’agent de poursuivre ses exécutions. Consultez Interrompre une session avec des exécutions ouvertes.

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 mis en pause par le budget ; aucune autre action du client n’est nécessaire.

Chaque exécution de workflow mise en pause par le budget reçoit également un événement workflow_run.status_running. Une exécution mise en pause par une interruption, même une interruption envoyée alors que la session était à son budget, reste en pause et ne reçoit aucun événement workflow_run.status_running du fait de la mise à jour. Pour la poursuivre, envoyez un user.message demandant à l’agent de poursuivre ses exécutions. Consultez Interrompre une session avec des exécutions ouvertes.

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é pour la session, et non sur l’ancien max_list_cost. Définissez-la au moins un cent 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.

updated_session = client.beta.sessions.update(
    session.id,
    budget={
        "type": "limit",
        "max_list_cost": {"amount": "500", "currency": "USD"},
    },
)
print(updated_session.budget.max_list_cost.amount)  # 500

Supprimer le budget

Transmettez budget=None pour supprimer entièrement le plafond. Le travail que le budget avait mis en pause reprend, et l’événement session.updated qui en résulte contient budget défini sur null.

unbudgeted_session = client.beta.sessions.update(session.id, budget=None)
print(unbudgeted_session.budget)  # None

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 prix catalogue consommé par la session, et usage.active_seconds est la durée d’exécution sur laquelle est calculé son coût d’exécution. Sur une session en pause avec 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 comptabilise qu’une seule fois l’activité simultanée de fils d’exécution concurrents. Les réponses de récupération d’un fil d’exécution contiennent les deux mêmes champs sur le propre usage du fil d’exécution, calculés pour chaque fil d’exécution. Les valeurs par fil d’exécution sont arrondies indépendamment et excluent le coût de durée d’exécution de la session ; elles ne s’additionnent donc pas exactement au list_cost de la session ; c’est la valeur de la session qui sert de référence pour 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 nombres 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 que le budget de la session si celle-ci en possède un. 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é à l’atteinte du budget.

Pour lire l’utilisation à partir du flux et de l’objet session, consultez Suivre l’utilisation.

Budgets dans les sessions multi-agents

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

Une demande en attente prime sur le plafond : une session dont un fil 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 ; il limite donc 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 ensuite, et non aux sessions déjà en cours d’exécution. Contrairement à une session, le budget d’un déploiement peut être effacé avec budget=None puis redéfini ultérieurement. Consultez Définir un budget pour 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 est rejetée avec une erreur 400 si l’un des éléments suivants utilise un modèle sans prix catalogue public :

• L’agent de la session
• Tout agent figurant dans la liste predefined_agents de subagents ou de workflows
• L’advisor défini dans la configuration multiagent de l’agent

L’erreur indique qu’aucun prix catalogue n’est disponible pour le modèle.

Si l’utilisation d’une session dotée d’un budget en 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 :

Disponibilité