Presupuestos de sesión

Un "session budget" (presupuesto de sesión) es un techo de gasto fijo opcional que estableces cuando creas una sesión. La plataforma calcula continuamente el precio de todo lo que la sesión consume a las tarifas de lista públicas (el costo de lista de la sesión) y deja de emitir nuevas solicitudes al modelo una vez que ese costo alcanza el presupuesto. La solicitud en curso cuando se cruza el límite aún termina, por lo que el costo de lista final puede quedar una fracción por encima del presupuesto. Una sesión que alcanza su presupuesto se pausa y pasa a estado idle en lugar de terminar; cambiar o eliminar el presupuesto reanuda el trabajo que el presupuesto pausó. Los despliegues aceptan el mismo presupuesto y lo aplican a cada sesión que inician; consulta Presupuestos en despliegues.

Establecer un presupuesto al crear la sesión

Pasa el campo opcional budget cuando crees la sesión:

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

El objeto budget tiene dos campos:

• type siempre es "limit".
• max_list_cost es el límite en sí: amount es un número entero de centavos de dólar estadounidense escrito como cadena sin ceros a la izquierda ("125" es $1.25 y "50" es 50 centavos) y debe ser mayor que cero. Las formas decimales como "25.00" se rechazan. El monto es una cadena en lugar de un número para que nunca se le aplique redondeo de punto flotante. currency es un código de moneda ISO-4217 en mayúsculas; USD es la única moneda admitida.

Un presupuesto solo puede adjuntarse cuando se crea la sesión. Agregar un presupuesto a una sesión existente que no tiene uno se rechaza con un error 400. El límite de una sesión con presupuesto puede cambiarse o eliminarse en cualquier momento.

Cómo se mide el costo de lista

La plataforma calcula el precio de lo que la sesión consume, de forma continua, a las tarifas de lista públicas:

• Tokens del modelo, al precio de lista de cada modelo servido
• Búsquedas web, a $10 USD por cada 1,000 búsquedas
• Tiempo de ejecución de la sesión, a $0.08 USD por hora

Este total acumulado en dólares es el costo de lista de la sesión, y es contra lo que se compara el presupuesto. El costo de lista no es tu precio contratado: si tu organización ha negociado descuentos, la sesión alcanza su límite cuando lo hace el total a precio de lista, y tu gasto facturado podría ser menor que el límite.

La aplicación del límite usa el costo de lista exacto, sin redondear. Las cifras de list_cost reportadas en la sesión y sus eventos son centavos enteros, redondeados al centavo más cercano, por lo que una cifra reportada puede diferir hasta medio centavo hacia arriba o hacia abajo del monto exacto que usa la aplicación del límite.

Cuando una sesión alcanza su presupuesto

El límite se aplica entre solicitudes al modelo, no a mitad de una solicitud. Antes de cada solicitud al modelo, la plataforma verifica el costo de lista consumido por la sesión, y una vez que ese total alcanza el límite, cada hilo se pausa antes de su siguiente solicitud. La solicitud que llevó el total por encima del límite fue admitida mientras la sesión aún estaba por debajo de él y se ejecuta hasta completarse, por lo que el list_cost registrado de una sesión pausada es igual o una fracción mayor que max_list_cost: una sesión limitada a "50" (50 centavos) puede pausarse con un list_cost de "53". Esto es lo esperado, no un error de facturación. El gasto del modelo por encima del límite es como máximo el costo de una solicitud al modelo por cada hilo. Las llamadas a herramientas en la respuesta de esa solicitud aún se ejecutan, y sus búsquedas web y tiempo de ejecución también cuentan para el costo de lista. Trata el presupuesto como un límite para el trabajo nuevo en lugar de un punto de detención exacto, y dimensiona el límite teniendo en cuenta ese margen.

Una sesión que alcanza su presupuesto pasa a estado inactivo con un stop_reason de budget_reached; no se termina, y su historial y sandbox se conservan como los de cualquier otra sesión inactiva. En el flujo de eventos verás, en orden:

1. Un evento session.thread_status_idle con un stop_reason de budget_reached a medida que cada hilo se pausa.
2. Un evento session.usage con el uso acumulado y el costo de lista de la sesión.
3. Un evento session.status_idle con un stop_reason de budget_reached. El evento de uso siempre precede inmediatamente a este evento de inactividad.

Si hay ejecuciones de flujos de trabajo abiertas, cada una que no esté ya inactiva también recibe un evento workflow_run.status_idle.

Un hilo cuya solicitud final cruza el límite y a la vez completa su turno reporta end_turn en su propio evento session.thread_status_idle mientras la sesión sigue reportando budget_reached; trata el stop_reason a nivel de sesión como la señal de que la sesión se pausó al alcanzar su presupuesto.

Eventos aceptados en el límite

Mientras la sesión está en su presupuesto o por encima de él, solo acepta eventos que resuelven trabajo ya en curso:

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

Cualquier evento que iniciaría trabajo nuevo, como user.message, se rechaza con un error 400 que nombra esta lista. Los resultados resueltos se registran sin desencadenar una nueva solicitud al modelo; la sesión permanece pausada en su presupuesto.

Un user.interrupt enviado mientras la sesión está pausada en su presupuesto (todos los hilos pausados en el límite) se acepta, y no aparece en la lista de eventos. No detiene ningún hilo, porque cada hilo ya está pausado. Cambia o elimina el presupuesto para continuar.

Si la sesión tiene ejecuciones de flujos de trabajo abiertas, la interrupción puede pausarlas, como puede hacerlo una interrupción en cualquier otro momento. Una ejecución que una interrupción pausó no se reanuda cuando cambias o eliminas el presupuesto. Para continuarla, cambia o elimina el presupuesto y luego envía un user.message pidiéndole al agente que continúe sus ejecuciones.

Reanudar una sesión en su presupuesto

Cambia o elimina el presupuesto con una actualización de la sesión. Una actualización aceptada reanuda automáticamente el trabajo que el presupuesto pausó; no se necesita ninguna otra acción del cliente.

Cada ejecución de flujo de trabajo que el presupuesto pausó también recibe un evento workflow_run.status_running. Una ejecución que una interrupción pausó, incluso una interrupción enviada mientras la sesión estaba en su presupuesto, permanece pausada y no recibe ningún evento workflow_run.status_running como resultado de la actualización. Para continuarla, envía un user.message pidiéndole al agente que continúe sus ejecuciones. Consulta Interrumpir una sesión con ejecuciones abiertas.

Cambiar el presupuesto

Actualiza la sesión con un nuevo max_list_cost. El nuevo valor puede ser mayor o menor que el límite actual, pero debe ser estrictamente mayor que el costo de lista consumido por la sesión; de lo contrario, la actualización se rechaza con un error 400: budget.max_list_cost must be greater than the session's consumed list cost. Como el costo consumido suele quedar una fracción por encima del límite anterior cuando la sesión se pausa, basa el nuevo valor en el usage.list_cost reportado de la sesión, no en el max_list_cost anterior. Establécelo un centavo o más por encima de esa cifra: el valor reportado está redondeado y puede quedar una fracción por debajo del costo consumido exacto que usa la verificación.

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

Eliminar el presupuesto

Pasa budget=None para eliminar el límite por completo. El trabajo que el presupuesto pausó se reanuda, y el evento session.updated resultante incluye budget establecido en null.

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

Monitorear el gasto

El objeto de sesión incluye su budget y un objeto usage con el gasto registrado: usage.list_cost es el costo de lista consumido por la sesión, y usage.active_seconds es el tiempo de ejecución sobre el que se calcula su costo de ejecución. En una sesión pausada con budget_reached, espera que usage.list_cost sea igual o una fracción mayor que max_list_cost: la solicitud que cruzó el límite terminó antes de la pausa. El active_seconds a nivel de sesión cuenta una sola vez la actividad superpuesta de hilos concurrentes. Las respuestas de recuperación de hilos incluyen los mismos dos campos en el propio usage del hilo, con precio calculado por hilo. Las cifras por hilo se redondean de forma independiente y excluyen el costo de tiempo de ejecución de la sesión, por lo que no suman exactamente el list_cost de la sesión; la cifra de la sesión es contra la que se aplica el presupuesto.

El evento session.usage es una instantánea del uso acumulado y del costo de lista registrado de la sesión. Incluye los totales de tokens de la sesión, list_cost, active_seconds, los recuentos de solicitudes de server_tool_use (web_search_requests, cuyo precio se incluye en el costo de lista por solicitud, y web_fetch_requests, que marca 0 porque las solicitudes de obtención web no tienen cargo por solicitud y no se miden), y el budget de la sesión si la sesión tiene uno. Aparece en la lista de eventos y en el flujo de la sesión. La sesión emite uno inmediatamente antes de pasar a estado inactivo, sea cual sea el motivo de detención, por lo que una sesión que alcanza su presupuesto siempre emite uno inmediatamente antes del evento de inactividad por presupuesto alcanzado.

Para leer el uso desde el flujo y el objeto de sesión, consulta Hacer seguimiento del uso.

Presupuestos en sesiones multiagente

Una sesión multiagente tiene un único presupuesto compartido entre todos sus hilos; no hay límites por hilo. El consumo de cada hilo se calcula según su propio modelo servido, y los hilos se pausan de forma independiente a medida que se alcanza el límite compartido. Las consultas al asesor cuentan contra el mismo presupuesto, calculadas a las tarifas del modelo asesor. Un hilo puede pausarse en budget_reached mientras otro termina su solicitud en curso.

Una petición pendiente tiene prioridad sobre el límite: una sesión con un hilo esperando en requires_action y otro pausado en budget_reached reporta requires_action a nivel de sesión. La solicitud pendiente aún necesita una respuesta, y responderla es un evento de resolución que el presupuesto no bloquea.

Presupuestos en despliegues

Un despliegue acepta el mismo objeto budget cuando lo creas o actualizas:

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

El límite se copia en cada sesión que inicia el despliegue, por lo que limita cada ejecución por separado en lugar del gasto acumulado del despliegue. Cambiar el presupuesto del despliegue se aplica a las sesiones que el despliegue inicie después, no a las sesiones que ya están en ejecución. A diferencia de una sesión, el presupuesto de un despliegue se puede borrar con budget=None y volver a establecerse más tarde. Consulta Establecer un presupuesto en cada ejecución.

Modelos sin precio de lista

Un presupuesto solo puede registrar el consumo al que la plataforma puede asignar un precio. Crear una sesión con presupuesto cuyo agente, o cualquier agente incluido en la lista predefined_agents de subagents o workflows, o el asesor establecido en su configuración multiagente, use un modelo sin precio de lista público se rechaza con un error 400 que indica que no hay precio de lista disponible para el modelo.

Si el uso de una sesión con presupuesto llega a incluir un modelo sin precio de lista, el presupuesto ya no puede medir el gasto de la sesión: la sesión puede pausarse con un stop_reason de budget_reached, y cambiar el presupuesto se rechaza. Elimina el presupuesto para reanudar la sesión.

Referencia de errores

Las solicitudes relacionadas con presupuestos se rechazan en los siguientes casos: