PraisonAI Agents

Guide for using PraisonAI Agents framework, a lightweight package for creating and managing AI agents with advanced capabilities

A lightweight package dedicated to creating and managing AI agents with advanced capabilities.

Need a framework that isn’t listed here? See Framework Adapter Plugins to register your own via Python entry points.

Installation

pip install praisonaiagents
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx

Quick Start

Create app.py and add the following code:

Single Agent (Minimal)

from praisonaiagents import Agent

# Instructions IS the task - no prompt needed
agent = Agent(instructions="Research the latest AI trends and summarize them")
result = agent.start()  # Uses instructions as task
print(result)

Single Agent (With Prompt)

from praisonaiagents import Agent

# Agent with role, prompt overrides
agent = Agent(
    name="Assistant",
    instructions="You are a helpful research assistant"
)
result = agent.start("What are the latest AI developments?")
print(result)

Multi-Agent Workflow

from praisonaiagents import Agent, AgentTeam

# Create agents with instructions
research_agent = Agent(instructions="Research about AI trends")
summary_agent = Agent(instructions="Summarize the research findings")

# Run multi-agent workflow
agents = AgentTeam(agents=[research_agent, summary_agent])
result = agents.start()  # Verbose output by default
print(result)

Advanced: With Tasks and Context

from praisonaiagents import Agent, Task, AgentTeam

# Create agents
researcher = Agent(
    name="Researcher",
    role="Senior Research Analyst",
    goal="Uncover cutting-edge developments in AI and data science",
    backstory="""You are an expert at a technology research group, 
    skilled in identifying trends and analyzing complex data.""",
    llm="gpt-4o"
)

writer = Agent(
    name="Writer",
    role="Tech Content Strategist",
    goal="Craft compelling content on tech advancements",
    backstory="""You are a content strategist known for 
    making complex tech topics interesting and easy to understand.""",
    llm="gpt-4o"
)

# Create tasks
research_task = Task(
    description="Research the latest developments in AI and data science",
    expected_output="A comprehensive report on recent AI trends and breakthroughs",
    agent=researcher
)

writing_task = Task(
    description="Create an engaging blog post about the research findings",
    expected_output="A well-structured blog post explaining AI developments",
    agent=writer,
    context=[research_task]  # This task depends on research_task output
)

# Create and run the agents
agents = AgentTeam(
    agents=[researcher, writer],
    tasks=[research_task, writing_task]
)

result = agents.start()
print(result)

Execution Methods

Method	Default Behavior	Use Case
.start()	Verbose in TTY (shows Rich panels)	Interactive/beginner
.run()	Silent (no output)	Production/scripts

Output Control

# Verbose output (default in terminal)
result = agent.start()

# Force silent mode
result = agent.start(output="silent")

# For production scripts, use .run()
result = agent.run()  # Always silent

Agent Configuration

Core Attributes

• name: Agent’s identifier
• role: Agent’s function/expertise
• goal: Individual objective
• backstory: Context and personality
• llm: Language model (default: OpenAI’s GPT-4)
• instructions: Agent instructions/system prompt
• tools: List of tools available to the agent

Optional Attributes

• tools: List of available tools
• memory: Enable memory capabilities
• knowledge: Knowledge base configuration
• planning: Enable planning mode (default: False)
• reflection: Enable self-reflection
• allow_delegation: ⚠️ Deprecated — use handoffs= instead (default: False)
• handoffs: List of agents for handoff

Task Configuration

Core Attributes

• description: Task details
• expected_output: Desired outcome
• agent: Assigned agent

Optional Attributes

• context: Dependencies on other tasks
• tools: Task-specific tools
• async_execution: Run asynchronously (default: False)
• output_file: Save output to file
• callback: Post-task function

Advanced Features

Tool Integration

from duckduckgo_search import DDGS

def search_tool(query: str) -> list:
    """
    Perform a web search using DuckDuckGo and return relevant results.

    Args:
        query (str): The search query string to look up information about.

    Returns:
        list: A list of dictionaries containing search results with the following keys:
            - title (str): The title of the search result
            - url (str): The URL of the search result
            - snippet (str): A brief excerpt or description of the search result
    """
    results = []
    ddgs = DDGS()
    for result in ddgs.text(keywords=query, max_results=10):
        results.append({
            "title": result.get("title", ""),
            "url": result.get("href", ""),
            "snippet": result.get("body", ""),
        })
    return results

agent = Agent(
    name="Researcher",
    tools=[search_tool]
)

Custom Callbacks

def task_completed(output):
    print(f"Task completed: {output.description}")
    print(f"Output: {output.raw}")

task = Task(
    description="Analysis task",
    callback=task_completed
)

Error Handling

The framework includes built-in error handling for:

• API rate limits
• Token limits
• Task timeouts
• Tool execution failures

Best Practices

1. Agent Design

   • Give clear, specific roles and goals
   • Provide detailed backstories
   • Use appropriate tools for tasks

2. Task Management

   • Break complex tasks into subtasks
   • Set clear dependencies
   • Use async execution for independent tasks

3. Resource Optimization

   • Enable caching when appropriate
   • Set reasonable max_iter limits
   • Use rate limiting for API calls

4. Error Handling

   • Implement task callbacks
   • Set appropriate timeouts
   • Monitor execution logs

Parallel Execution (Upcoming)

task1 = Task(
    description="Research task 1",
    async_execution=True
)

task2 = Task(
    description="Research task 2",
    async_execution=True
)

final_task = Task(
    description="Compile results",
    context=[task1, task2]  # Waits for both tasks
)

Memory Management (Upcoming)

agent = Agent(
    name="Analyst",
    memory=True,  # Enable memory
    memory={
        "type": "short_term",
        "max_tokens": 4000
    }
)

Troubleshooting

Unsupported framework error: If you see Unsupported framework: praisonai. Registered: ['ag2', 'autogen', 'autogen_v4', 'crewai', 'praisonai'], check spelling — frameworks are registered via the adapter registry.

Missing installation error: If you see PraisonAI agents is not available. Install with: pip install praisonaiagents, install the package as shown in the installation section above.