Budgets de session

Un budget de session est un plafond de dépenses strict et optionnel que vous définissez lorsque vous créez une session. La plateforme tarifie en continu tout ce que la session consomme aux tarifs publics (le coût tarifaire de la session) et cesse d'émettre de nouvelles requêtes au modèle une fois que ce coût atteint le budget. La requête en cours au moment où le plafond est franchi se termine malgré tout, de sorte que le coût tarifaire 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 plutôt que 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

Passez le champ optionnel budget lorsque vous créez la session :

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

L'objet budget comporte deux champs :

• type est 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 ("2500" correspond à 25,00 $ 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 de nombre flottant 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 budgétée peut être modifié ou supprimé à tout moment.



Comment le coût tarifaire est mesuré

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

• Tokens de modèle, au tarif public de chaque modèle servi
• Recherches web, à 10 $ pour 1 000 recherches
• Temps d'exécution de la session, à 0,08 $ par heure

Ce total cumulé en dollars constitue le coût tarifaire de la session, et c'est à lui que le budget est comparé. Le coût tarifaire 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 tarifaire exact, non arrondi. Les valeurs list_cost rapportées sur la session et ses événements sont des cents entiers, arrondis au cent le plus proche, de sorte qu'une valeur rapportée peut s'écarter jusqu'à un demi-cent de part et d'autre du montant exact utilisé pour l'application.



Lorsqu'une session atteint son budget

Le plafond est appliqué entre les requêtes au modèle, et non en cours de requête. Avant chaque requête au modèle, la plateforme vérifie le coût tarifaire consommé de la session, et une fois que ce total atteint le plafond, chaque thread se met en pause avant sa prochaine requête. La requête qui a fait dépasser le 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 se situe au niveau du max_list_cost ou légèrement au-delà : une session plafonnée à "50" (50 cents) peut se mettre en pause avec un list_cost de "53". Ceci est attendu, il ne s'agit pas d'une erreur de facturation, et le dépassement est limité à une requête au modèle par thread. Considérez le budget comme une limite sur le nouveau travail 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 idle avec un stop_reason de budget_reached ; elle n'est pas terminée, et son historique et son sandbox sont préservés comme ceux de toute autre session idle. 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 tarifaire 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 idle.

Un thread dont la requête finale franchit le plafond et termine son tour rapporte end_turn sur son propre événement session.thread_status_idle tandis que la session rapporte 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 au niveau de son budget ou au-delà, elle n'accepte que les événements qui finalisent 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 nommant cette liste. Les résultats finalisé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 à son budget

Modifiez ou supprimez le budget avec une mise à jour de 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 tarifaire consommé de 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 rapporté de la session, et non sur l'ancien max_list_cost. Définissez-la à un cent ou plus au-dessus de cette valeur : la valeur rapportée est arrondie et peut se situer légèrement en dessous du coût consommé exact utilisé par la vérification.

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "4000", "currency": "USD"}
  }
}
EOF



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 résultant porte budget défini sur null.

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"budget": null}'



Surveiller les dépenses

L'objet session porte son budget et un objet usage avec les dépenses suivies : usage.list_cost est le coût tarifaire consommé de la session, et usage.active_seconds est le temps d'exécution sur lequel son coût d'exécution est tarifé. Sur une session en pause à budget_reached, attendez-vous à ce que usage.list_cost se situe au niveau du max_list_cost ou légèrement au-delà : la requête qui a franchi le plafond s'est terminée avant la pause. Le active_seconds au niveau de la session compte une seule fois l'activité simultanée de threads concurrents. Les réponses de récupération de thread portent les deux mêmes champs sur le propre usage du thread, tarifé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 qu'elles ne totalisent pas exactement le 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 tarifaire suivi de la session. Il porte les totaux de tokens de la session, list_cost, active_seconds, les compteurs de requêtes server_tool_use (web_search_requests, tarifé dans le coût tarifaire par requête, et web_fetch_requests, qui indique 0 car les requêtes de récupération web ne comportent aucun frais par requête et ne sont pas mesurées), et un écho 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 idle, 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 idle de 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 tarifée selon son propre modèle servi, et les threads se mettent en pause indépendamment à mesure que le plafond partagé est atteint. Les consultations de l'advisor sont imputées au même budget, tarifées aux tarifs du modèle advisor. 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 avec un thread en attente sur requires_action et un autre en pause à budget_reached rapporte requires_action au niveau de la session. La requête en attente nécessite toujours une réponse, et y répondre est un événement de finalisation 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 et redéfini 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 peut tarifer. La création d'une session budgétée dont l'agent, ou tout agent ou advisor 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 budgétée 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 :