Praison AI

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.

Installation

bash
pip install praisonaiagents
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx

Quick Start

  1. Single agent (minimal)
    python
    from praisonaiagents import Agent

agent = Agent(instructions="Research the latest AI trends and summarise them")
result = agent.start()
print(result)
  2. Single agent (with prompt)
    python
    from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful research assistant",
)
result = agent.start("What are the latest AI developments?")
print(result)
  3. Multi-agent workflow
    python
    from praisonaiagents import Agent, AgentTeam

research_agent = Agent(instructions="Research about AI trends")
summary_agent = Agent(instructions="Summarise the research findings")

agents = AgentTeam(agents=[research_agent, summary_agent])
result = agents.start()
print(result)

Advanced: With Tasks and Context

python
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

MethodDefault BehaviorUse Case
.start()Verbose in TTY (shows Rich panels)Interactive/beginner
.run()Silent (no output)Production/scripts

Output Control

python
# 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

YAML config: Block

The PraisonAI adapter supports a top-level config: block in YAML that automatically wires InteractiveRuntime (ACP + LSP + agent-centric tools) into the agent execution.

YAML KeyTypeDefaultEffect
acpboolFalseInitializes InteractiveRuntime with ACP enabled. Agent-centric tools are loaded and merged into tools_dict before agents start. Runtime is torn down after team.start() returns.
lspboolFalseSame as above but with LSP enabled. Can be combined with acp: true.

The approval mode is read from the PRAISONAI_APPROVAL_MODE environment variable (default: "prompt").

Example: YAML with ACP/LSP

yaml
framework: praisonai
topic: Refactor the auth module

config:
  acp: true
  lsp: true

roles:
  refactorer:
    role: Code Refactorer
    goal: Tighten auth.py for readability and safety
    backstory: Staff engineer, security-minded.
    tasks:
      refactor:
        description: Refactor the auth module in {topic}
        expected_output: Diff applied via the agent-centric tools.

AgentOps Integration

When agentops is installed, the PraisonAI adapter automatically calls agentops.end_session("Success") after agent execution completes. No configuration required.

bash
pip install agentops
# AgentOps tracking is automatically enabled

Advanced Features

Tool Integration

python
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

python
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
  2. Give clear, specific roles and goals
  3. Provide detailed backstories
  4. Use appropriate tools for tasks
  1. Task Management
  2. Break complex tasks into subtasks
  3. Set clear dependencies
  4. Use async execution for independent tasks
  1. Resource Optimization
  2. Enable caching when appropriate
  3. Set reasonable max_iter limits
  4. Use rate limiting for API calls
  1. Error Handling
  2. Implement task callbacks
  3. Set appropriate timeouts
  4. Monitor execution logs

Parallel Execution (Upcoming)

python
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)

python
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 the framework is not installed, PraisonAI now fails fast at CLI entry with:

Framework 'praisonai' was requested but is not installed.
Install it with:
    pip install praisonaiagents

The error appears immediately, before YAML parsing — so a typo in --framework is caught before any expensive setup runs.