Per-Tool Token Budgets
Configure token limits per tool for fine-grained output control
from praisonaiagents import Agent
agent = Agent(
name="budgeted-agent",
instructions="Use tools without flooding context.",
)
agent.start("Search the web and keep only the most relevant snippets.")Per-tool budgets cap how much of each tool’s output enters agent context — noisy tools get tighter limits, critical tools stay protected.
The user caps noisy tool output; per-tool budgets truncate oversized results before they fill the context window.
How It Works
Quick Start
- Enable context on the agent
python from praisonaiagents import Agent, ManagerConfig agent = Agent( name="researcher", instructions="Research topics efficiently", context=ManagerConfig(default_tool_output_max=10000), ) - Set per-tool budgets
python agent.context_manager.set_tool_budget("web_search", max_tokens=2000) agent.context_manager.set_tool_budget("file_read", max_tokens=5000, protected=True) agent.context_manager.set_tool_budget("code_execute", max_tokens=10000) agent.start("Summarise the latest WebAssembly news") - Truncate output manually
python truncated = agent.context_manager.truncate_tool_output( "file_read", large_file_content ) # Appends "...[output truncated]..." when over budget
How It Works
Each tool call checks get_tool_budget(tool_name) — falling back to default_tool_output_max when no per-tool rule exists. Protected tools skip pruning during context optimisation.
Configuration
Via ManagerConfig
from praisonaiagents import Agent, ManagerConfig
agent = Agent(
name="researcher",
context=ManagerConfig(
default_tool_output_max=10000,
protected_tools=["file_read"],
),
)
agent.context_manager.set_tool_budget("web_search", max_tokens=2000)Via environment
export PRAISONAI_CONTEXT_TOOL_OUTPUT_MAX=10000Methods
| Method | Purpose |
|---|---|
set_tool_budget(name, max_tokens, protected=False) | Set limit for one tool |
get_tool_budget(name) | Read limit (falls back to default) |
truncate_tool_output(name, output) | Truncate to the tool’s budget |
CLI Usage
praisonai chat
> /context config
# Shows:
# default_tool_max: 10,000
# tool_budgets:
# file_read: 5,000 (protected)
# web_search: 2,000Best Practices
Set lower limits for verbose tools
Web search and file reads return large payloads — cap them at 2,000–5,000 tokens so they do not crowd out conversation history.
Give code execution higher limits
Code tools often need full stack traces or build logs — 10,000+ tokens prevents losing error context mid-debug.
Mark critical tools as protected
protected=True keeps a tool’s output from being pruned during context optimisation, even when the window is tight.
Monitor usage via the ledger
Run /context in chat or call get_stats() on the context manager to see which tools consume the most tokens.