A lightweight package dedicated to creating and managing AI agents with advanced capabilities.
This is now the default framework. Running praisonai agents.yaml without any framework flag uses this adapter.
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
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 Key | Type | Default | Effect |
|---|
acp | bool | False | Initializes 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. |
lsp | bool | False | Same 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
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.
config.acp and config.lsp only take effect for framework: praisonai. Other adapters (crewai, autogen, ag2, autogen_v4) ignore them.
AgentOps Integration
When agentops is installed, the PraisonAI adapter automatically calls agentops.end_session("Success") after agent execution completes. No configuration required.
pip install agentops
# AgentOps tracking is automatically enabled
Advanced Features
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
-
Agent Design
- Give clear, specific roles and goals
- Provide detailed backstories
- Use appropriate tools for tasks
-
Task Management
- Break complex tasks into subtasks
- Set clear dependencies
- Use async execution for independent tasks
-
Resource Optimization
- Enable caching when appropriate
- Set reasonable max_iter limits
- Use rate limiting for API calls
-
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 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.