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 su trabajo automáticamente. 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:

# Mantén el monto entre comillas para que se envíe como cadena, no como número.
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)

El objeto budget tiene dos campos:

• type es siempre "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" son 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 por cada 1,000 búsquedas
• Tiempo de ejecución de la sesión, a $0.08 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 en cualquier dirección 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 de 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 más allá 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 queda en max_list_cost o una fracción por encima: una sesión con límite de "50" (50 centavos) puede pausarse con un list_cost de "53". Esto es esperado, no un error de facturación, y el exceso está acotado a una solicitud al modelo por hilo. Trata el presupuesto como un límite al trabajo nuevo en lugar de un punto de detención exacto, y dimensiona el límite teniendo en cuenta ese margen de una solicitud.

Una sesión que alcanza su presupuesto pasa a idle con un stop_reason de budget_reached; no se termina, y su historial y sandbox se conservan como los de cualquier otra sesión idle. 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 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ó en 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 se ignora: no aparece en la lista de eventos y no cambia nada. Cambia o elimina el presupuesto para continuar.

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 pausado de la sesión; no se necesita ninguna otra acción del cliente.

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 de 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. Dado que el costo consumido normalmente queda 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.

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

Eliminar el presupuesto

Establece budget en null para eliminar el límite por completo. El trabajo pausado de la sesión se reanuda, y el evento session.updated resultante lleva budget establecido en null.

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

Monitorear el gasto

El objeto de sesión lleva su budget y un objeto usage con el gasto rastreado: usage.list_cost es el costo de lista consumido de la sesión, y usage.active_seconds es el tiempo de ejecución sobre el que se calcula su costo de tiempo de ejecución. En una sesión pausada en budget_reached, espera que usage.list_cost quede en max_list_cost o una fracción por encima: 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 llevan los mismos dos campos en el propio usage del hilo, calculados 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 el costo de lista rastreado de la sesión. Lleva los totales de tokens de la sesión, list_cost, active_seconds, los conteos de solicitudes de server_tool_use (web_search_requests, incluidas en el costo de lista por solicitud, y web_fetch_requests, que muestra 0 porque las solicitudes de web fetch no tienen cargo por solicitud y no se miden), y un eco del budget de la sesión, o null cuando la sesión no tiene ninguno. Aparece en la lista de eventos y en el flujo de la sesión. La sesión emite uno inmediatamente antes de pasar a idle, 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 idle de presupuesto alcanzado.

Para leer el uso desde el flujo y el objeto de sesión, consulta 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 acota 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 ya en ejecución. A diferencia de una sesión, el presupuesto de un despliegue puede borrarse con null y establecerse de nuevo más tarde. Consulta Establecer un presupuesto en cada ejecución.

Modelos sin precio de lista

Un presupuesto solo puede rastrear el consumo que la plataforma puede valorar. Crear una sesión con presupuesto cuyo agente, o cualquier agente o asesor en su plantilla 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: