budget_reached

A budget_reached state means an agent has spent all of the money limit it was given in advance, so it stops and can no longer start new tasks. It's similar to giving a kid a set allowance — once it's gone, they can't buy anything more.

When developers run an agent, they can set a cost ceiling for each session in advance. The agent searches, reads documents, and generates answers within that limit, and the moment it hits the ceiling, it stops right there instead of sending another request. It's a safety mechanism to prevent a task from running indefinitely and racking up an unexpected bill.

This state doesn't mean the agent has broken down. If anything, it's a signal that the agent stopped exactly according to the rule that was set. Developers respond to this state by checking it and either raising the budget or handing the task off to the next session.

The article explains that the budget_reached state — where the agent stops with no further requests once the budget runs out — was added in an update last August. A common misunderstanding is that this isn't an error or failure on the agent's part. It's a normal termination state that occurs when a cost limit set in advance by the developer is reached, and it exists to prevent runaway costs.

Developers who work directly with code can check this concept in the following steps.

1. Look through the documentation for parameters related to setting a budget ceiling when creating an agent session.
2. Set a low budget and run the agent.
3. Observe that once the budget is used up, the session switches to the budget_reached state and no further requests go through.
4. Try responding by raising the budget afterward or creating a new session to continue the task.