Budgets

A budget caps how much an agent run can spend, how long it can take and how many steps it can make.

Every field is optional. Without a budget, no limit applies. After each run, result.data.governance tells you whether the run was allowed or blocked, and why.

Try it

Set the limits on agent.budget, save the agent, then run it.

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

agent = aix.Agent(
    name="Governed agent",
    description="Answers questions under a fixed run budget.",
    instructions="You are a helpful assistant. Answer in one sentence.",
)
agent.budget.max_cost = 0.5
agent.budget.max_iterations = 10
agent.save()

result = agent.run("In one sentence, what is an AI agent?")
print(result.data.governance)
print(result.data.output)

Show output

See a blocked run

Limits are checked between steps. When a run crosses one, the agent stops planning and answers from the steps it already finished, and governance reports BLOCKED_BY_BUDGET with the reason. A duration limit of 0 makes this easy to see.

agent.budget.max_duration_seconds = 0

result = agent.run("In one sentence, what is an AI agent?")
print(result.status)
print(result.data.governance)

Show output

A blocked run still returns SUCCESS and an answer. Check result.data.governance["status"] to tell a complete run from a cut-short one. Because the final answer step still runs, result.used_credits can end above max_cost.

Override for one run

A budget saved with .save() is the agent's default. A change made after .save() and before run() applies to that run only. It merges field by field over the saved default, and the run-time value wins.

fetched = aix.Agent.get(agent.id)
print(fetched.budget)

Show output

The previous run used max_duration_seconds = 0, but the saved budget still holds only max_cost and max_iterations.

Reference

Field	Type	Default	Description
max_cost	float	None	Spending cap for one run, in credits. 1 credit = 1 USD.
max_duration_seconds	float	None	Wall-clock seconds before the run is blocked.
max_iterations	int	None	Maximum number of reasoning steps in one run.

Leave a field out for no limit. 0 is a limit of zero, not "unlimited".

result.data.governance has three keys:

Key	Values
status	ALLOWED, BLOCKED_BY_BUDGET, or BLOCKED_BY_INSPECTOR
source	What made the decision: SYSTEM for budgets, INSPECTOR for inspectors, None when allowed
reason	Why the run was blocked, or None

warning

Set limits on agent.budget only. agent.run(budget=...) and agent.max_iterations = N are silently ignored, so the run has no limit.

Troubleshooting

Symptom	Cause	Fix
agent reached the maximum number of iterations	The run hit max_iterations	Raise agent.budget.max_iterations, then agent.save(). Agents with subagents need more steps.
A limit has no effect	It was passed to run() or set on agent.max_iterations	Set it on agent.budget.
The answer looks incomplete	A limit stopped the run early	Check result.data.governance, then raise the limit that reason names.

Next steps

• Inspectors: check inputs, steps and outputs while a run happens.
• Rate limiting: cap requests and tokens per API key.
• Credits and billing: see what each run costs.
• API reference: agent: every parameter and method.