Sitzungsbudgets

Ein „session budget“ (Sitzungsbudget) ist eine optionale harte Ausgabenobergrenze, die du festlegst, wenn du eine Sitzung erstellst. Die Plattform bepreist fortlaufend alles, was die Sitzung verbraucht, zu öffentlichen Listenpreisen (die Listenkosten bzw. „list cost“ der Sitzung) und stellt keine neuen Modellanfragen mehr aus, sobald diese Kosten das Budget erreichen. Die Anfrage, die gerade läuft, wenn die Obergrenze überschritten wird, wird noch abgeschlossen, sodass die endgültigen Listenkosten einen Bruchteil über dem Budget landen können. Eine Sitzung, die ihr Budget erreicht hat, pausiert und wird idle, anstatt beendet zu werden; das Ändern oder Entfernen des Budgets setzt ihre Arbeit automatisch fort. Deployments akzeptieren dasselbe Budget und wenden es auf jede Sitzung an, die sie starten; siehe Budgets bei Deployments.

Ein Budget bei der Sitzungserstellung festlegen

Übergib das optionale Feld budget, wenn du die Sitzung erstellst:

# Lass den Betrag in Anführungszeichen, damit er als String und nicht als Zahl gesendet wird.
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)

Das budget-Objekt hat zwei Felder:

• type ist immer "limit".
• max_list_cost ist die Obergrenze selbst: amount ist eine ganze Zahl von US-Cent, geschrieben als String ohne führende Nullen ("125" sind 1,25 $ und "50" sind 50 Cent), und muss größer als null sein. Dezimalformen wie "25.00" werden abgelehnt. Der Betrag ist ein String statt einer Zahl, damit niemals eine Gleitkomma-Rundung darauf angewendet wird. currency ist ein ISO-4217-Währungscode in Großbuchstaben; USD ist die einzige unterstützte Währung.

Ein Budget kann nur beim Erstellen der Sitzung angehängt werden. Das Hinzufügen eines Budgets zu einer bestehenden Sitzung, die keines hat, wird mit einem 400-Fehler abgelehnt. Die Obergrenze einer budgetierten Sitzung kann jederzeit geändert oder entfernt werden.

Wie Listenkosten gemessen werden

Die Plattform bepreist fortlaufend, was die Sitzung verbraucht, zu öffentlichen Listenpreisen:

• Modell-Token, zum Listenpreis des jeweils bereitgestellten Modells
• Websuchen, zu 10 $ pro 1.000 Suchen
• Sitzungslaufzeit, zu 0,08 $ pro Stunde

Diese laufende Dollar-Gesamtsumme sind die Listenkosten der Sitzung, und mit ihnen wird das Budget verglichen. Listenkosten sind nicht dein vertraglich vereinbarter Preis: Wenn deine Organisation Rabatte ausgehandelt hat, erreicht die Sitzung ihre Obergrenze, wenn die Listenpreis-Gesamtsumme sie erreicht, und deine abgerechneten Ausgaben können niedriger als die Obergrenze sein.

Die Durchsetzung verwendet die exakten, ungerundeten Listenkosten. Die auf der Sitzung und ihren Events gemeldeten list_cost-Werte sind ganze Cent, auf den nächsten Cent gerundet, sodass ein gemeldeter Wert bis zu einem halben Cent über oder unter dem exakten Betrag liegen kann, den die Durchsetzung verwendet.

Wenn eine Sitzung ihr Budget erreicht

Die Obergrenze wird zwischen Modellanfragen durchgesetzt, nicht mitten in einer Anfrage. Vor jeder Modellanfrage prüft die Plattform die verbrauchten Listenkosten der Sitzung, und sobald diese Gesamtsumme die Obergrenze erreicht, pausiert jeder Thread vor seiner nächsten Anfrage. Die Anfrage, die die Gesamtsumme über die Obergrenze getragen hat, wurde zugelassen, als die Sitzung noch darunter lag, und läuft bis zum Abschluss, sodass die aufgezeichneten list_cost einer pausierten Sitzung bei oder einen Bruchteil über max_list_cost liegen: Eine auf "50" (50 Cent) begrenzte Sitzung kann mit list_cost von "53" pausieren. Das ist erwartet und kein Abrechnungsfehler, und die Überschreitung ist auf eine Modellanfrage pro Thread begrenzt. Behandle das Budget als Grenze für neue Arbeit statt als exakten Haltepunkt und dimensioniere die Obergrenze mit diesem Spielraum von einer Anfrage im Hinterkopf.

Eine Sitzung, die ihr Budget erreicht, wird idle mit einem stop_reason von budget_reached; sie wird nicht beendet, und ihr Verlauf und ihre Sandbox bleiben wie bei jeder anderen idle Sitzung erhalten. Im Event-Stream siehst du der Reihe nach:

1. Ein session.thread_status_idle-Event mit einem stop_reason von budget_reached, wenn jeder Thread pausiert.
2. Ein session.usage-Event mit der kumulierten Nutzung und den Listenkosten der Sitzung.
3. Ein session.status_idle-Event mit einem stop_reason von budget_reached. Das Usage-Event geht diesem Idle-Event immer unmittelbar voraus.

Ein Thread, dessen letzte Anfrage sowohl die Obergrenze überschreitet als auch seinen Turn abschließt, meldet end_turn auf seinem eigenen session.thread_status_idle-Event, während die Sitzung weiterhin budget_reached meldet; behandle den stop_reason auf Sitzungsebene als das Signal, dass die Sitzung an ihrem Budget pausiert hat.

An der Obergrenze akzeptierte Events

Solange die Sitzung bei oder über ihrem Budget liegt, akzeptiert sie nur Events, die bereits laufende Arbeit abschließen:

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

Jedes Event, das neue Arbeit starten würde, wie user.message, wird mit einem 400-Fehler abgelehnt, der diese Liste nennt. Abgeschlossene Ergebnisse werden aufgezeichnet, ohne eine neue Modellanfrage auszulösen; die Sitzung bleibt an ihrem Budget pausiert.

Ein user.interrupt, das gesendet wird, während die Sitzung an ihrem Budget pausiert ist (alle Threads an der Obergrenze pausiert), wird akzeptiert und ignoriert: Es erscheint nicht in der Event-Liste und ändert nichts. Ändere oder entferne das Budget, um fortzufahren.

Eine Sitzung an ihrem Budget fortsetzen

Ändere oder entferne das Budget mit einem Sitzungs-Update. Ein akzeptiertes Update setzt die pausierte Arbeit der Sitzung automatisch fort; es ist keine weitere Client-Aktion nötig.

Das Budget ändern

Aktualisiere die Sitzung mit einem neuen max_list_cost. Der neue Wert kann höher oder niedriger als die aktuelle Obergrenze sein, muss aber strikt größer als die verbrauchten Listenkosten der Sitzung sein; andernfalls wird das Update mit einem 400-Fehler abgelehnt: budget.max_list_cost must be greater than the session's consumed list cost. Da die verbrauchten Kosten beim Pausieren der Sitzung üblicherweise einen Bruchteil über der alten Obergrenze liegen, stütze den neuen Wert auf die gemeldeten usage.list_cost der Sitzung, nicht auf das alte max_list_cost. Setze ihn einen Cent oder mehr über diesen Wert: Der gemeldete Wert ist gerundet und kann einen Bruchteil unter den exakten verbrauchten Kosten liegen, die die Prüfung verwendet.

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

Das Budget entfernen

Setze budget auf null, um die Obergrenze vollständig zu entfernen. Die pausierte Arbeit der Sitzung wird fortgesetzt, und das resultierende session.updated-Event trägt budget auf null gesetzt.

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

Ausgaben überwachen

Das Sitzungsobjekt trägt sein budget und ein usage-Objekt mit den erfassten Ausgaben: usage.list_cost sind die verbrauchten Listenkosten der Sitzung, und usage.active_seconds ist die Laufzeit, auf deren Basis ihre Laufzeitkosten bepreist werden. Bei einer Sitzung, die bei budget_reached pausiert ist, erwarte, dass usage.list_cost bei oder einen Bruchteil über max_list_cost liegt: Die Anfrage, die die Obergrenze überschritten hat, wurde vor der Pause abgeschlossen. active_seconds auf Sitzungsebene zählt überlappende Aktivität gleichzeitiger Threads nur einmal. Thread-Abrufantworten tragen dieselben zwei Felder auf dem eigenen usage des Threads, pro Thread bepreist. Werte pro Thread werden unabhängig gerundet und schließen die Laufzeitkosten der Sitzung aus, sodass sie sich nicht exakt zu den list_cost der Sitzung summieren; der Sitzungswert ist derjenige, gegen den das Budget durchgesetzt wird.

Das session.usage-Event ist eine Momentaufnahme der kumulierten Nutzung und der erfassten Listenkosten der Sitzung. Es trägt die Token-Gesamtsummen der Sitzung, list_cost, active_seconds, server_tool_use-Anfragezähler (web_search_requests, pro Anfrage in die Listenkosten eingepreist, und web_fetch_requests, das 0 anzeigt, weil Web-Fetch-Anfragen keine Gebühr pro Anfrage tragen und nicht gemessen werden) sowie ein Echo des budget der Sitzung oder null, wenn die Sitzung keines hat. Es erscheint in der Event-Liste und im Sitzungs-Stream. Die Sitzung sendet eines unmittelbar bevor sie idle wird, unabhängig vom Stop-Grund, sodass eine Sitzung, die ihr Budget erreicht, immer eines unmittelbar vor dem Budget-erreicht-Idle-Event sendet.

Um die Nutzung aus dem Stream und dem Sitzungsobjekt zu lesen, siehe Nutzung verfolgen.

Budgets in Multiagent-Sitzungen

Eine Multiagent-Sitzung hat ein einziges Budget, das über alle ihre Threads geteilt wird; es gibt keine Obergrenzen pro Thread. Der Verbrauch jedes Threads wird zu seinem eigenen bereitgestellten Modell bepreist, und Threads pausieren unabhängig voneinander, wenn die gemeinsame Obergrenze erreicht wird. Advisor-Konsultationen zählen gegen dasselbe Budget, bepreist zu den Preisen des Advisor-Modells. Ein Thread kann bei budget_reached pausieren, während ein anderer seine laufende Anfrage abschließt.

Eine ausstehende Rückfrage hat Vorrang vor der Obergrenze: Eine Sitzung mit einem Thread, der auf requires_action wartet, und einem anderen, der bei budget_reached pausiert ist, meldet requires_action auf Sitzungsebene. Die ausstehende Anfrage braucht weiterhin eine Antwort, und sie zu beantworten ist ein Abschluss-Event, das das Budget nicht blockiert.

Budgets bei Deployments

Ein Deployment akzeptiert dasselbe budget-Objekt, wenn du es erstellst oder aktualisierst:

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

Die Obergrenze wird auf jede Sitzung kopiert, die das Deployment startet, sodass sie jeden Lauf separat begrenzt und nicht die kumulierten Ausgaben des Deployments. Das Ändern des Budgets eines Deployments gilt für Sitzungen, die das Deployment danach startet, nicht für bereits laufende Sitzungen. Anders als bei einer Sitzung kann das Budget eines Deployments mit null gelöscht und später erneut gesetzt werden. Siehe Ein Budget für jeden Lauf festlegen.

Modelle ohne Listenpreis

Ein Budget kann nur Verbrauch erfassen, den die Plattform bepreisen kann. Das Erstellen einer budgetierten Sitzung, deren Agent oder irgendein Agent oder Advisor auf ihrem Multiagent-Roster ein Modell ohne öffentlichen Listenpreis verwendet, wird mit einem 400-Fehler abgelehnt, der angibt, dass für das Modell kein Listenpreis verfügbar ist.

Wenn die Nutzung einer budgetierten Sitzung ein Modell ohne Listenpreis einschließt, kann das Budget die Ausgaben der Sitzung nicht mehr messen: Die Sitzung kann mit einem stop_reason von budget_reached pausieren, und das Ändern des Budgets wird abgelehnt. Entferne das Budget, um die Sitzung fortzusetzen.

Fehlerreferenz

Budgetbezogene Anfragen werden in den folgenden Fällen abgelehnt: