Skip to main content
from praisonaiagents import Agent

agent = Agent(
    name="managed-agent",
    instructions="Use the context manager module for precise control.",
    context_window=16000,
)
agent.start("Process this document while managing context carefully.")
The ContextManager orchestrates budgeting, composition, optimisation, and monitoring through one interface. The user sends a large thread; the context manager budgets tokens and returns an optimised message list for the next LLM call.

​
How It Works

​
Quick Start

1

Create a manager

from praisonaiagents import ContextManager

manager = ContextManager(model="gpt-4o-mini")
2

Process messages

result = manager.process(
    messages=conversation_history,
    system_prompt="You are a helpful assistant.",
    tools=tool_schemas,
)
optimized = result["messages"]
print(f"Tokens saved: {result['tokens_saved']}")
3

Inspect utilisation

stats = manager.get_stats()
print(f"Utilisation: {stats['utilization']*100:.1f}%")

​
Architecture

​
Configuration

​
ManagerConfig

from praisonaiagents import ManagerConfig, EstimationMode

config = ManagerConfig(
    # Auto-compaction
    auto_compact=True,
    compact_threshold=0.8,
    strategy="smart",
    
    # Compression benefit check
    compression_min_gain_pct=5.0,
    compression_max_attempts=3,
    
    # Budget
    output_reserve=8000,
    default_tool_output_max=10000,
    
    # Estimation
    estimation_mode=EstimationMode.HEURISTIC,
    log_estimation_mismatch=False,
    
    # Monitoring
    monitor_enabled=False,
    monitor_path="./context.txt",
    monitor_format="human",
    monitor_write_mode="sync",
    redact_sensitive=True,
)

manager = ContextManager(model="gpt-4o-mini", config=config)

​
Environment Variables

VariableDefaultDescription
PRAISONAI_CONTEXT_AUTO_COMPACTtrueEnable auto-compaction
PRAISONAI_CONTEXT_THRESHOLD0.8Compact threshold (0-1)
PRAISONAI_CONTEXT_STRATEGYsmartOptimization strategy
PRAISONAI_CONTEXT_MONITORfalseEnable monitoring
PRAISONAI_CONTEXT_ESTIMATION_MODEheuristicToken estimation mode

​
Config Precedence

CLI flags > Environment variables > config.yaml > defaults

​
Core Methods

​
process()

Process messages through the full context pipeline: 
result = manager.process(
    messages=messages,
    system_prompt="System prompt",
    tools=tools,
    trigger="turn",  # turn, tool_call, manual, overflow
)

# Result contains:
# - messages: Optimized message list
# - optimized: bool - whether optimization occurred
# - tokens_before: int
# - tokens_after: int
# - tokens_saved: int
# - utilization: float (0-1)
# - warnings: List[str]
# - optimization_result: OptimizationResult or None

​
capture_llm_boundary()

Capture exact state at LLM call boundary for debugging: 
hook_data = manager.capture_llm_boundary(messages, tools)

print(f"Message hash: {hook_data.message_hash}")
print(f"Tools hash: {hook_data.tools_hash}")

​
get_stats()

Get current context statistics: 
stats = manager.get_stats()
print(f"Utilization: {stats['utilization']*100:.1f}%")
print(f"Warnings: {stats['warnings']}")

​
get_resolved_config()

Get fully resolved configuration with source info: 
resolved = manager.get_resolved_config()
print(f"Source: {resolved['config']['source']}")
print(f"Precedence: {resolved['precedence']}")

​
get_history()

Get optimization event history: 
history = manager.get_history()
for event in history:
    print(f"{event['timestamp']}: {event['event_type']}")

​
Per-Tool Budgets

Set custom token budgets per tool: 
# Set budget for specific tool
manager.set_tool_budget("file_read", max_tokens=5000, protected=True)

# Get budget for tool
budget = manager.get_tool_budget("file_read")  # 5000

# Truncate output according to budget
truncated = manager.truncate_tool_output("file_read", large_output)

​
Token Estimation

# Basic estimation
tokens, metrics = manager.estimate_tokens(text)

# With validation (compares heuristic vs accurate)
tokens, metrics = manager.estimate_tokens(text, validate=True)

if metrics:
    print(f"Error: {metrics.error_pct:.1f}%")

​
Snapshot Callbacks

Register callbacks for LLM boundary snapshots: 
def on_snapshot(hook_data):
    print(f"Snapshot at {hook_data.timestamp}")
    print(f"Messages: {len(hook_data.messages)}")

manager.register_snapshot_callback(on_snapshot)

​
CLI Integration

# Show context stats
praisonai chat
> /context

# Show optimization history
> /context history

# Show resolved config
> /context config

# Trigger manual compaction
> /context compact

​
Factory Function

Use create_context_manager for proper config precedence: 
from praisonaiagents import create_context_manager

manager = create_context_manager(
    model="gpt-4o-mini",
    config_file="config.yaml",
    cli_overrides={"auto_compact": False},
)

​
Best Practices

Set auto_compact=True and compact_threshold=0.8 so context stays within model limits without manual /context compact.
Use set_tool_budget() on noisy tools like file reads before they flood the context window.
Enable monitor_enabled and write snapshots to disk when tracing compaction decisions.
Prefer the factory when mixing CLI flags, env vars, and config.yaml overrides.

Context Files

Inject project files into agent context alongside the manager pipeline.

Per-Tool Budgets

Cap individual tool outputs before they reach the manager.

Optimiser

Compression strategies used inside ContextManager.process().

Multi-Agent Policies

Per-agent isolation and handoff sharing rules.