Set token budgets

Use this when a workflow calls a model, possibly in a loop of agent rounds, and you want a ceiling on tokens, money or tool calls. Prerequisites: Call an LLM works for you. Add -H "X-API-Key: $YUKTA_API_KEY" if your server has keys.

Steps

Add a budget to each model node

budget is a map on LLM_CALL: maxTokens (input plus output), maxCost (needs prices), maxCalls counts tool calls (for MCP_TOOL_CALL), agent names a shared ledger and hardStop decides what happens when it is used up.

{
  "nodeId": "plan",
  "type": "LLM_CALL",
  "config": {
    "provider": "anthropic", "model": "claude-sonnet-5-5", "apiKey": "decrypted:anthropic",
    "prompt": "${payload.text}",
    "maxTokens": 1024,
    "prices": { "input": 3.0, "output": 15.0 },
    "budget": { "maxTokens": 20000, "maxCost": 0.5, "agent": "triage", "hardStop": true }
  }
}

prices are per million tokens, in your own currency; use your provider’s current rates. With prices set, the node’s output also carries a cost.

Share one ledger across nodes

Every model and tool node of a run shares the budget. Give the same agent name to the nodes that belong together, and each agent is counted apart. Without agent, a run has one budget for all its nodes. MCP_TOOL_CALL supports maxCalls, agent and hardStop (no tokens or cost):

{ "nodeId": "act", "type": "MCP_TOOL_CALL",
  "config": { "url": "https://issues.example.com/mcp", "tool": "${payload.tool}",
              "budget": { "maxCalls": 4, "agent": "triage", "hardStop": true } } }

Choose soft or hard

Without hardStop, the next call after the budget is used up fails like any failed call, so retries, failureMode, fallback ports and error routing still apply. With hardStop: true the next call ends the whole run: it is not retried, dropped, routed or absorbed by failureMode. Use hardStop when overspend must never be absorbed.

Test the ceiling with a tiny budget

Set "budget": {"maxTokens": 1, "hardStop": true} on a second LLM_CALL chained after the first, start the workflow and watch the run end at the second call. Then restore your real numbers.

Verify it worked

curl -s localhost:9858/api/executions/$EXEC
curl -s "localhost:9858/api/executions/$EXEC/nodes/plan/output?tail=20"

With the tiny test budget, the first call succeeds and the second does not run: the run ends in a failed status with a budget error in the log, and no further model call is billed. Without hardStop, the second node ends FAILURE and the rest of the graph reacts as for any failure. With your real budget the node output includes usage and, with prices, cost. The Control dashboard shows tokens and spend per provider: Use the Control dashboard.

Variations

Know what counts. The check runs before a call and the usage is added after it, so one call can overshoot, and calls running at the same time can each pass the check. maxCalls counts tool calls only.
Budgets are in memory. They start again from zero after a restart or a resume.
Other guardrails. A per-provider rate limit, prompt and answer filters and tool allow-lists are server and node settings: Call an LLM, Use tools and MCP servers.
Cheaper decisions. Small routing and gating choices cost far fewer tokens with a decision model: Classify, gate and score.

AI plugins reference for the budget and prices fields.
Configuration for yukta.llm.*.

Build workflows

Work with AI

Supervise runs

Run and operate

Extend

Set token budgets

Steps

Verify it worked

Variations

Steps

Verify it worked

Variations

Related