Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Un presupuesto de sesión es un límite máximo de gasto opcional que estableces cuando creas una sesión. La plataforma calcula continuamente el precio de todo lo que consume la sesión según las tarifas públicas de lista (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 se completa de todos modos, 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 inactivo en lugar de terminar; cambiar o eliminar el presupuesto reanuda su trabajo automáticamente. Los deployments aceptan el mismo presupuesto y lo aplican a cada sesión que inician; consulta Presupuestos en deployments.
Pasa el campo opcional budget cuando crees la sesión:
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")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 ("2500" equivale a $25.00 y "50" equivale a 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.
La plataforma calcula el precio de lo que consume la sesión, de forma continua, según las tarifas públicas de lista:
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 estar hasta medio centavo por encima o por debajo del monto exacto que usa la aplicación del límite.
El límite se aplica entre solicitudes al modelo, no en medio 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 se lee igual o una fracción por encima de max_list_cost: una sesión con un 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 excedente está acotado por una solicitud al modelo por hilo. Trata el presupuesto como un límite para trabajo nuevo en lugar de un punto de parada exacto, y dimensiona el límite teniendo en cuenta ese margen de una solicitud.
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 preservan como los de cualquier otra sesión inactiva. En el flujo de eventos verás, en orden:
session.thread_status_idle con un stop_reason de budget_reached a medida que cada hilo se pausa.session.usage con el uso acumulado y el costo de lista de la sesión.session.status_idle con un stop_reason de budget_reached. El evento de uso siempre precede inmediatamente a este evento de inactividad.Un hilo cuya solicitud final cruza el límite y además completa su turno reporta end_turn en su propio evento session.thread_status_idle, mientras que 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.
Mientras la sesión está en su presupuesto o por encima de él, solo acepta eventos que resuelven trabajo ya en curso:
user.tool_confirmationuser.tool_resultuser.custom_tool_resultuser.interruptCualquier 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.
Cambia o elimina el presupuesto con una actualización de sesión. Una actualización aceptada reanuda automáticamente el trabajo pausado de la sesión; no se necesita ninguna acción adicional del cliente.
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 generalmente 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 estar una fracción por debajo del costo consumido exacto que usa la verificación.
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"}
}
}
EOFEstablece 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.
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}'El objeto de sesión lleva su budget y un objeto usage con el gasto registrado: 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 cual se calcula su costo de tiempo de ejecución. En una sesión pausada en budget_reached, espera que usage.list_cost se lea igual o una fracción por encima de 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 llevan los mismos dos campos en el usage propio 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 registrado 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, que se incluye en el costo de lista por solicitud, y web_fetch_requests, que se lee como 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 inactiva, sea cual sea el motivo de parada, 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 Seguimiento del uso.
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 al precio de su propio modelo servido, y los hilos se pausan de forma independiente a medida que se alcanza el límite compartido. Las consultas al advisor cuentan contra el mismo presupuesto, calculadas a las tarifas del modelo del advisor. Un hilo puede pausarse en budget_reached mientras otro termina su solicitud en curso.
Una solicitud 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.
Un deployment 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 deployment, por lo que acota cada ejecución por separado en lugar del gasto acumulado del deployment. Cambiar el presupuesto del deployment se aplica a las sesiones que el deployment inicie después, no a las sesiones que ya están en ejecución. A diferencia de una sesión, el presupuesto de un deployment puede eliminarse con null y establecerse de nuevo más tarde. Consulta Establecer un presupuesto en cada ejecución.
Un presupuesto solo puede registrar el consumo que la plataforma puede valorar. Crear una sesión con presupuesto cuyo agente, o cualquier agente o advisor en su lista multiagente, usa un modelo sin precio público de lista 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.
Las solicitudes relacionadas con presupuestos se rechazan en los siguientes casos:
| Condición | Estado |
|---|---|
Se envía un evento que inicia trabajo (por ejemplo, user.message) mientras la sesión está en su presupuesto o por encima de él; el error nombra los eventos de resolución aceptados | 400 |
| El presupuesto se establece en un valor igual o inferior al costo de lista consumido de la sesión | 400 |
| Se agrega un presupuesto a una sesión creada sin uno, o se vuelve a agregar después de eliminarlo | 400 |
amount no es un número entero de centavos (por ejemplo, "25.00"), es cero o negativo, o currency no es USD | 400 |
| Una creación con presupuesto hace referencia a un modelo sin precio público de lista | 400 |
Was this page helpful?