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 die Arbeit fort, die das Budget pausiert hat. 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:

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

Das Objekt budget 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" entspricht 1,25 $ und "50" entspricht 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 USD pro 1.000 Suchen
• Sitzungslaufzeit, zu 0,08 USD 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 Werte für list_cost, die für die Sitzung und ihre Events gemeldet werden, 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 Summe die Obergrenze erreicht, pausiert jeder Thread vor seiner nächsten Anfrage. Die Anfrage, die die Summe über die Obergrenze gebracht hat, wurde zugelassen, als die Sitzung noch darunter lag, und läuft bis zum Ende, sodass der erfasste Wert list_cost einer pausierten Sitzung bei oder geringfügig über max_list_cost liegt: Eine Sitzung mit einer Obergrenze von "50" (50 Cent) kann mit einem list_cost von "53" pausieren. Das ist erwartet und kein Abrechnungsfehler. Die Modellkosten über die Obergrenze hinaus betragen höchstens die Kosten einer Modellanfrage pro Thread. Die Tool-Aufrufe in der Antwort dieser Anfrage werden trotzdem ausgeführt, und ihre Websuchen und Laufzeit zählen ebenfalls zu den Listenkosten. Betrachte das Budget als Grenze für neue Arbeit statt als exakten Haltepunkt, und bemiss die Obergrenze mit diesem Spielraum im Hinterkopf.

Eine Sitzung, die ihr Budget erreicht, wechselt in den Status idle mit einem stop_reason von budget_reached; sie wird nicht beendet, und ihr Verlauf und ihre Sandbox bleiben wie bei jeder anderen inaktiven 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 Nutzungs-Event geht diesem Idle-Event immer unmittelbar voraus.

Wenn Workflow-Runs offen sind, erhält jeder, der nicht bereits inaktiv ist, außerdem ein workflow_run.status_idle-Event.

Ein Thread, dessen letzte Anfrage sowohl die Obergrenze überschreitet als auch seinen Turn abschließt, meldet end_turn in seinem eigenen session.thread_status_idle-Event, während die Sitzung weiterhin budget_reached meldet; betrachte den stop_reason auf Sitzungsebene als das Signal, dass die Sitzung bei 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 es erscheint nicht in der Event-Liste. Es stoppt keinen Thread, weil jeder Thread bereits pausiert ist. Ändere oder entferne das Budget, um fortzufahren.

Wenn die Sitzung offene Workflow-Runs hat, kann die Unterbrechung sie pausieren, wie es eine Unterbrechung zu jedem anderen Zeitpunkt auch kann. Ein Run, den eine Unterbrechung pausiert hat, wird nicht fortgesetzt, wenn du das Budget änderst oder entfernst. Um ihn fortzusetzen, ändere oder entferne das Budget und sende dann eine user.message, die den Agenten bittet, seine Runs fortzusetzen.

Eine Sitzung an ihrem Budget fortsetzen

Ändere oder entferne das Budget mit einem Sitzungs-Update. Ein akzeptiertes Update setzt die Arbeit, die das Budget pausiert hat, automatisch fort; es ist keine weitere Aktion des Clients erforderlich.

Jeder Workflow-Run, den das Budget pausiert hat, erhält außerdem ein workflow_run.status_running-Event. Ein Run, den eine Unterbrechung pausiert hat, bleibt pausiert und erhält durch das Update kein workflow_run.status_running-Event, selbst wenn die Unterbrechung gesendet wurde, während die Sitzung an ihrem Budget war. Um ihn fortzusetzen, sende eine user.message, die den Agenten bittet, seine Runs fortzusetzen. Siehe Eine Session mit offenen Runs unterbrechen.

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 meist geringfügig über der alten Obergrenze liegen, orientiere den neuen Wert am gemeldeten usage.list_cost der Sitzung, nicht am alten max_list_cost. Setze ihn einen Cent oder mehr über diesen Wert: Der gemeldete Wert ist gerundet und kann geringfügig unter den exakten verbrauchten Kosten liegen, die die Prüfung verwendet.

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

Das Budget entfernen

Übergib budget=None, um die Obergrenze vollständig zu entfernen. Die Arbeit, die das Budget pausiert hat, wird fortgesetzt, und das resultierende session.updated-Event enthält budget mit dem Wert null.

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

Ausgaben überwachen

Das Sitzungsobjekt enthält 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 die Laufzeitkosten berechnet werden. Bei einer Sitzung, die mit budget_reached pausiert ist, ist zu erwarten, dass usage.list_cost bei oder geringfügig ü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. Antworten beim Abrufen von Threads enthalten dieselben zwei Felder im 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 zum 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 enthält die Token-Summen der Sitzung, list_cost, active_seconds, die Anfragezahlen in server_tool_use (web_search_requests, pro Anfrage in die Listenkosten eingerechnet, und web_fetch_requests, das 0 anzeigt, weil Web-Fetch-Anfragen keine Gebühr pro Anfrage haben und nicht gemessen werden) sowie das budget der Sitzung, falls die Sitzung eines hat. Es erscheint in der Event-Liste und im Sitzungs-Stream. Die Sitzung sendet eines unmittelbar bevor sie in den Status idle wechselt, unabhängig vom Stop-Grund, sodass eine Sitzung, die ihr Budget erreicht, immer eines unmittelbar vor dem Idle-Event für das erreichte Budget sendet.

Wie du die Nutzung aus dem Stream und dem Sitzungsobjekt ausliest, erfährst du unter 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 jede Ausführung einzeln begrenzt und nicht die kumulierten Ausgaben des Deployments. Eine Änderung des Budgets des 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 budget=None gelöscht und später erneut festgelegt werden. Siehe Ein Budget für jede Ausführung festlegen.

Modelle ohne Listenpreis

Ein Budget kann nur Verbrauch erfassen, den die Plattform bepreisen kann. Das Erstellen einer Sitzung mit Budget, deren Agent oder ein beliebiger Agent in der Liste predefined_agents von subagents oder workflows oder der in ihrer Multiagent-Konfiguration festgelegte Advisor 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 Sitzung mit Budget 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: