Agent Configuration

Complete reference for agent configuration parameters

Agent Configuration

This page provides detailed documentation for all agent configuration parameters, including execution controls, context management, and output formatting options.

Core Parameters

Execution Control Parameters

max_iter

• Type: int
• Default: 15
• Description: Maximum number of iterations an agent will attempt to complete a task
• Range: 1-100 (recommended: 10-25)

The max_iter parameter controls how many times an agent can iterate through its execution loop when working on a task. This prevents infinite loops and ensures tasks complete within reasonable bounds.

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    execution=ExecutionConfig(max_iter=20),  # Allow up to 20 iterations
)

Best Practices:

• Set lower values (5-10) for simple tasks
• Use higher values (20-30) for complex research or analysis tasks
• Monitor iteration count to optimize performance

max_retry_limit

• Type: int
• Default: 2
• Description: Maximum number of times to retry a failed operation
• Range: 0-10 (recommended: 2-5)

Controls how many times an agent will retry operations that fail due to transient errors like network issues or API rate limits.

agent = Agent(
    name="DataAnalyst",
    max_retry_limit=3,  # Retry failed operations up to 3 times
    # other parameters...
)

Use Cases:

• API calls that may face rate limits
• Network operations that may timeout
• Tool executions that may fail intermittently

max_budget

• Type: float | None
• Default: None
• Description: Hard USD cap on the agent run. Set via execution=ExecutionConfig(max_budget=...). Budget enforcement runs after each LLM call returns — in stop mode BudgetExceededError is raised, in warn mode a warning is logged and the agent continues.

Set a dollar limit via ExecutionConfig:

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="BudgetedAgent",
    instructions="Complete task within budget",
    execution=ExecutionConfig(max_budget=0.50),  # Stop at $0.50
)

result = agent.start("Research AI trends")

Benefits:

• Prevents runaway costs in production — the guard fires before each LLM call in stop mode (default), so the over-budget call is never dispatched
• Clean error handling in CLI mode
• Zero overhead when not set

Mode behaviour: stop (default) enforces a pre-call hard ceiling; warn and callable modes check post-call and always let the call run. Pass on_budget_exceeded via ExecutionConfig to change the mode.

Context Management

context_length

• Type: int
• Default: None (uses model default)
• Description: Maximum context window size in tokens
• Common Values:
  • GPT-4: 128000
  • GPT-3.5: 16385
  • Claude 3: 200000

Defines the maximum amount of context (in tokens) that can be included in a single LLM request.

from praisonaiagents import ManagerConfig

agent = Agent(
    name="Analyzer",
    context=ManagerConfig(
        auto_compact=True,  # Automatically manage context window
        compact_threshold=0.8,  # Trigger at 80% usage
    ),
    # other parameters...
)

Important Considerations:

• Larger context windows allow more information but increase costs
• Some models perform better with focused context
• Always validate against your LLM’s maximum context size

Output Formatting

markdown

• Type: bool
• Default: True
• Description: Enable markdown formatting in agent outputs

Controls whether the agent formats its responses using markdown syntax for better readability.

agent = Agent(
    name="Reporter",
    instructions="Format your responses using markdown with headers, lists, and code blocks",
    templates={
        "response": """
        ## Analysis Report
        
        {content}
        
        ### Key Findings
        {findings}
        """
    }
)

Features When Enabled:

• Headers using #, ##, etc.
• Bold text with **text**
• Code blocks with ```
• Lists and tables
• Links and images

Advanced Execution Controls

Performance Optimization

agent = Agent(
    name="HighPerformanceAgent",
    instructions="Complete tasks efficiently",
    
    # Context optimization
    context=True,  # Enable context management
    
    # Caching configuration
    caching={"enabled": True},
    
    # Rate limiting (via ExecutionConfig)
    execution=ExecutionConfig(max_rpm=60)
)

Error Handling Configuration

from praisonaiagents.config.feature_configs import ExecutionConfig

agent = Agent(
    name="ResilientAgent",
    instructions="Handle tasks with error recovery",
    
    # Code execution via ExecutionConfig
    execution=ExecutionConfig(
        code_execution=True,
        code_mode="safe",  # Safe mode with restrictions
        # Enable tool bridge so model-generated code can call registered tools
        code_tools=True,
        code_tools_allow=["fetch", "parse"],  # Explicit per-run allow-list
    ),
    
    # LLM configuration
    model="gpt-4o-mini"
)

Configuration Patterns

Research Agent Configuration

research_agent = Agent(
    name="ResearchSpecialist",
    role="Senior Research Analyst",
    goal="Conduct thorough research and provide comprehensive reports",
    backstory="Expert researcher with 10 years of experience",
    
    # Enable reflection for quality
    reflection=True,
    
    # Enable planning for complex tasks
    planning=True,
    
    # LLM with large context
    llm="gpt-4o"  # Supports 128k context
)

Quick Task Agent Configuration

quick_agent = Agent(
    name="QuickResponder",
    role="Rapid Task Handler",
    
    # Optimized for speed using execution= config
    execution="fast",  # Uses ExecutionConfig(max_iter=5, max_retry_limit=1)
    
    # Minimal output using output= config
    output="silent"  # Disables verbose, markdown, stream
)

Environment Variable Overrides

Agent parameters can be overridden using environment variables:

# Override default iteration limit
export PRAISONAI_AGENT_MAX_ITER=20

# Override retry limit
export PRAISONAI_AGENT_MAX_RETRY_LIMIT=5

# Set context length
export PRAISONAI_AGENT_CONTEXT_LENGTH=100000

# Disable markdown
export PRAISONAI_AGENT_MARKDOWN=false

Validation and Constraints

Parameter Validation Rules

Parameter	Validation	Error Handling
max_iter	Must be > 0	Defaults to 15 if invalid
max_retry_limit	Must be >= 0	Defaults to 2 if invalid
context_length	Must be greater than 0 and less than or equal to model max	Uses model default if invalid
markdown	Must be boolean	Defaults to True if invalid

Interaction Between Parameters

1. Context Length and Max Iterations

   • Higher max_iter may require larger context_length
   • Each iteration adds to context usage

2. Retry Limit and Execution Time

   • Higher max_retry_limit extends total execution time
   • Consider both when setting timeouts

3. Markdown and Response Templates

   • “ enables template formatting
   • Templates should use markdown syntax when enabled

Troubleshooting

Common Issues

1. Task taking too long

   # Solution: Use a faster model or simplify the task
   agent = Agent(
       instructions="Complete tasks concisely",
       llm="gpt-4o-mini"  # Faster model
   )
   

2. Context window exceeded

   # Solution: Enable context management
   agent = Agent(
       instructions="...",
       context=True  # Enable context management
   )
   

3. Need better quality responses

   # Solution: Enable reflection
   agent = Agent(
       instructions="...",
       reflection=True,
       planning=True
   )
   

See Also

• Task Configuration - Configure task execution
• LLM Configuration - LLM-specific settings
• Best Practices - Configuration guidelines