PraisonAI

AI Agents Framework with Self Reflection and MCP support

AI & MLPythonv2.3.42
<div align="center">

PraisonAI 🦞

</div>

PraisonAI 🦞 β€” Automate and solve complex challenges with AI agent teams that plan, research, code, and deliver results to Telegram, Discord, and WhatsApp β€” running 24/7. A low-code, production-ready multi-agent framework with handoffs, guardrails, memory, RAG, and 100+ LLM providers, built around simplicity, customisation, and effective human-agent collaboration.

<div align="center"> <a href="https://docs.praison.ai"> </a> </div>

Quick Paths:


⚑ Performance

PraisonAI is built for speed, with agent instantiation in under 4ΞΌs. This reduces overhead, improves responsiveness, and helps multi-agent systems scale efficiently in real-world production workloads.

Performance MetricPraisonAI
Avg Instantiation Time3.77 ΞΌs

🎯 Use Cases

AI agents solving real-world problems across industries:

Use CaseDescription
πŸ” Research & AnalysisConduct deep research, gather information, and generate insights from multiple sources automatically
πŸ’» Code GenerationWrite, debug, and refactor code with AI agents that understand your codebase and requirements
✍️ Content CreationGenerate blog posts, documentation, marketing copy, and technical writing with multi-agent teams
πŸ“Š Data PipelinesExtract, transform, and analyze data from APIs, databases, and web sources automatically
πŸ€– Customer SupportDeploy 24/7 support bots on Telegram, Discord, Slack with memory and knowledge-backed responses
βš™οΈ Workflow AutomationAutomate multi-step business processes with agents that hand off tasks, verify results, and self-correct

Supported Providers

PraisonAI supports 100+ LLM providers through seamless integration:

<details> <summary><strong>View all 24 providers with examples</strong></summary>
ProviderExample
OpenAIExample
AnthropicExample
Google GeminiExample
OllamaExample
GroqExample
DeepSeekExample
xAI GrokExample
MistralExample
CohereExample
PerplexityExample
FireworksExample
Together AIExample
OpenRouterExample
HuggingFaceExample
Azure OpenAIExample
AWS BedrockExample
Google VertexExample
DatabricksExample
CloudflareExample
AI21Example
ReplicateExample
SageMakerExample
MoonshotExample
vLLMExample
</details>

🌟 Why PraisonAI?

FeatureHow
πŸ”ŒMCP Protocol β€” stdio, HTTP, WebSocket, SSEtools=MCP("npx ...")
🧠Planning Mode β€” plan β†’ execute β†’ reasonplanning=True
πŸ”Deep Research β€” multi-step autonomous researchDocs
πŸ€–External Agents β€” orchestrate Claude Code, Gemini CLI, CodexDocs
πŸ”„Agent Handoffs β€” seamless conversation passinghandoff=True
πŸ›‘οΈGuardrails β€” input/output validationDocs
Web Search + Fetch β€” native browsingweb_search=True
πŸͺžSelf Reflection β€” agent reviews its own outputDocs
πŸ”€Workflow Patterns β€” route, parallel, loop, repeatDocs
🧠Memory (zero deps) β€” works out of the boxmemory=True
<details> <summary><strong>View all 25 features</strong></summary>
FeatureHow
πŸ’‘Prompt Caching β€” reduce latency + costprompt_caching=True
πŸ’ΎSessions + Auto-Save β€” persistent state across restartsauto_save="my-project"
πŸ’­Thinking Budgets β€” control reasoning depththinking_budget=1024
πŸ“šRAG + Quality-Based RAG β€” auto quality scoring retrievalDocs
πŸ“ŠModel Router β€” auto-routes to cheapest capable modelDocs
🧊Shadow Git Checkpoints β€” auto-rollback on failureDocs
πŸ“‘A2A Protocol β€” agent-to-agent interopDocs
πŸ“Context Compaction β€” never hit token limitsDocs
πŸ“‘Telemetry β€” OpenTelemetry traces, spans, metricsDocs
πŸ“œPolicy Engine β€” declarative agent behavior controlDocs
πŸ”„Background Tasks β€” fire-and-forget agentsDocs
πŸ”Doom Loop Detection β€” auto-recovery from stuck agentsDocs
πŸ•ΈοΈGraph Memory β€” Neo4j-style relationship trackingDocs
πŸ–οΈSandbox Execution β€” isolated code executionDocs
πŸ–₯️Bot Gateway β€” multi-agent routing across channelsDocs
</details>

πŸš€ Quick Start

Get started with PraisonAI in under 1 minute:

bash
# Install
pip install praisonaiagents

# Set API key
export OPENAI_API_KEY=your_key_here

# Create a simple agent
python -c "from praisonaiagents import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"

Next Steps: Single Agent Example | Multi Agents | Full Docs


πŸ“¦ Installation

Python SDK

Lightweight package dedicated for coding:

bash
pip install praisonaiagents

For the full framework with CLI support:

bash
pip install praisonai

🦞 AgentClaw β€” full UI with bots, memory, knowledge, and gateway:

bash
pip install "praisonai[claw]"
praisonai claw

JavaScript SDK

bash
npm install praisonai

πŸ“˜ Using Python Code

1. Single Agent

python
from praisonaiagents import Agent
agent = Agent(instructions="You are a helpful AI assistant")
agent.start("Write a movie script about a robot in Mars")

2. Multi Agents

python
from praisonaiagents import Agent, Agents

research_agent = Agent(instructions="Research about AI")
summarise_agent = Agent(instructions="Summarise research agent's findings")
agents = Agents(agents=[research_agent, summarise_agent])
agents.start()

3. MCP (Model Context Protocol)

python
from praisonaiagents import Agent, MCP

# stdio - Local NPX/Python servers
agent = Agent(tools=MCP("npx @modelcontextprotocol/server-memory"))

# Streamable HTTP - Production servers
agent = Agent(tools=MCP("https://api.example.com/mcp"))

# WebSocket - Real-time bidirectional
agent = Agent(tools=MCP("wss://api.example.com/mcp", auth_token="token"))

# With environment variables
agent = Agent(
    tools=MCP(
        command="npx",
        args=["-y", "@modelcontextprotocol/server-brave-search"],
        env={"BRAVE_API_KEY": "your-key"}
    )
)

πŸ“– Full MCP docs β€” stdio, HTTP, WebSocket, SSE transports

4. Custom Tools

python
from praisonaiagents import Agent, tool

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

@tool
def calculate(expression: str) -> float:
    """Evaluate a math expression."""
    return eval(expression)

agent = Agent(
    instructions="You are a helpful assistant",
    tools=[search, calculate]
)
agent.start("Search for AI news and calculate 15*4")

πŸ“– Full tools docs β€” BaseTool, tool packages, 100+ built-in tools

5. Persistence (Databases)

python
from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    db=db(database_url="postgresql://localhost/mydb"),
    session_id="my-session"
)
agent.chat("Hello!")  # Auto-persists messages, runs, traces

πŸ“– Full persistence docs β€” PostgreSQL, MySQL, SQLite, MongoDB, Redis, and 20+ more

6. AgentClaw 🦞 (Dashboard UI)

Connect your AI agents to Telegram, Discord, Slack, WhatsApp and more β€” all from a single command.

bash
pip install "praisonai[claw]"
praisonai claw

Open http://localhost:8082 β€” the dashboard comes with 13 built-in pages: Chat, Agents, Memory, Knowledge, Channels, Guardrails, Cron, and more. Add messaging channels directly from the UI.

πŸ“– Full Claw docs β€” platform tokens, CLI options, Docker, and YAML agent mode


🎯 CLI Quick Reference

CategoryCommands
Executionpraisonai, --auto, --interactive, --chat
Researchresearch, --query-rewrite, --deep-research
Planning--planning, --planning-tools, --planning-reasoning
Workflowsworkflow run, workflow list, workflow auto
Memorymemory show, memory add, memory search, memory clear
Knowledgeknowledge add, knowledge query, knowledge list
Sessionssession list, session resume, session delete
Toolstools list, tools info, tools search
MCPmcp list, mcp create, mcp enable
Developmentcommit, docs, checkpoint, hooks
Schedulingschedule start, schedule list, schedule stop

πŸ“– Full CLI reference


✨ Key Features

<details open> <summary><strong>πŸ€– Core Agents</strong></summary>
FeatureCodeDocs
Single AgentExampleπŸ“–
Multi AgentsExampleπŸ“–
Auto AgentsExampleπŸ“–
Self Reflection AI AgentsExampleπŸ“–
Reasoning AI AgentsExampleπŸ“–
Multi Modal AI AgentsExampleπŸ“–
</details> <details> <summary><strong>πŸ”„ Workflows</strong></summary>
FeatureCodeDocs
Simple WorkflowExampleπŸ“–
Workflow with AgentsExampleπŸ“–
Agentic Routing (route())ExampleπŸ“–
Parallel Execution (parallel())ExampleπŸ“–
Loop over List/CSV (loop())ExampleπŸ“–
Evaluator-Optimizer (repeat())ExampleπŸ“–
Conditional StepsExampleπŸ“–
Workflow BranchingExampleπŸ“–
Workflow Early StopExampleπŸ“–
Workflow CheckpointsExampleπŸ“–
</details> <details> <summary><strong>πŸ’» Code & Development</strong></summary>
FeatureCodeDocs
Code Interpreter AgentsExampleπŸ“–
AI Code Editing ToolsExampleπŸ“–
External Agents (All)ExampleπŸ“–
Claude Code CLIExampleπŸ“–
Gemini CLIExampleπŸ“–
Codex CLIExampleπŸ“–
Cursor CLIExampleπŸ“–
</details> <details> <summary><strong>🧠 Memory & Knowledge</strong></summary>
FeatureCodeDocs
Memory (Short & Long Term)ExampleπŸ“–
File-Based MemoryExampleπŸ“–
Claude Memory ToolExampleπŸ“–
Add Custom KnowledgeExampleπŸ“–
RAG AgentsExampleπŸ“–
Chat with PDF AgentsExampleπŸ“–
Data Readers (PDF, DOCX, etc.)CLIπŸ“–
Vector Store SelectionCLIπŸ“–
Retrieval StrategiesCLIπŸ“–
RerankersCLIπŸ“–
Index Types (Vector/Keyword/Hybrid)CLIπŸ“–
Query Engines (Sub-Question, etc.)CLIπŸ“–
</details> <details> <summary><strong>πŸ”¬ Research & Intelligence</strong></summary>
FeatureCodeDocs
Deep Research AgentsExampleπŸ“–
Query Rewriter AgentExampleπŸ“–
Native Web SearchExampleπŸ“–
Built-in Search ToolsExampleπŸ“–
Unified Web SearchExampleπŸ“–
Web Fetch (Anthropic)ExampleπŸ“–
</details> <details> <summary><strong>πŸ“‹ Planning & Execution</strong></summary>
FeatureCodeDocs
Planning ModeExampleπŸ“–
Planning ToolsExampleπŸ“–
Planning ReasoningExampleπŸ“–
Prompt ChainingExampleπŸ“–
Evaluator OptimiserExampleπŸ“–
Orchestrator WorkersExampleπŸ“–
</details> <details> <summary><strong>πŸ‘₯ Specialized Agents</strong></summary>
FeatureCodeDocs
Data Analyst AgentExampleπŸ“–
Finance AgentExampleπŸ“–
Shopping AgentExampleπŸ“–
Recommendation AgentExampleπŸ“–
Wikipedia AgentExampleπŸ“–
Programming AgentExampleπŸ“–
Math AgentsExampleπŸ“–
Markdown AgentExampleπŸ“–
Prompt Expander AgentExampleπŸ“–
</details> <details> <summary><strong>🎨 Media & Multimodal</strong></summary>
FeatureCodeDocs
Image Generation AgentExampleπŸ“–
Image to Text AgentExampleπŸ“–
Video AgentExampleπŸ“–
Camera IntegrationExampleπŸ“–
</details> <details> <summary><strong>πŸ”Œ Protocols & Integration</strong></summary>
FeatureCodeDocs
MCP TransportsExampleπŸ“–
WebSocket MCPExampleπŸ“–
MCP SecurityExampleπŸ“–
MCP ResumabilityExampleπŸ“–
MCP Config ManagementDocsπŸ“–
LangChain Integrated AgentsExampleπŸ“–
</details> <details> <summary><strong>πŸ›‘οΈ Safety & Control</strong></summary>
FeatureCodeDocs
GuardrailsExampleπŸ“–
Human ApprovalExampleπŸ“–
Rules & InstructionsDocsπŸ“–
</details> <details> <summary><strong>βš™οΈ Advanced Features</strong></summary>
FeatureCodeDocs
Async & Parallel ProcessingExampleπŸ“–
ParallelisationExampleπŸ“–
Repetitive AgentsExampleπŸ“–
Agent HandoffsExampleπŸ“–
Stateful AgentsExampleπŸ“–
Autonomous WorkflowExampleπŸ“–
Structured Output AgentsExampleπŸ“–
Model RouterExampleπŸ“–
Prompt CachingExampleπŸ“–
Fast ContextExampleπŸ“–
</details> <details> <summary><strong>πŸ› οΈ Tools & Configuration</strong></summary>
FeatureCodeDocs
100+ Custom ToolsExampleπŸ“–
YAML ConfigurationExampleπŸ“–
100+ LLM SupportExampleπŸ“–
Callback AgentsExampleπŸ“–
HooksExampleπŸ“–
Middleware SystemExampleπŸ“–
Configurable ModelExampleπŸ“–
Rate LimiterExampleπŸ“–
Injected Tool StateExampleπŸ“–
Shadow Git CheckpointsExampleπŸ“–
Background TasksExampleπŸ“–
Policy EngineExampleπŸ“–
Thinking BudgetsExampleπŸ“–
Output StylesExampleπŸ“–
Context CompactionExampleπŸ“–
</details> <details> <summary><strong>πŸ“Š Monitoring & Management</strong></summary>
FeatureCodeDocs
Sessions ManagementExampleπŸ“–
Auto-Save SessionsDocsπŸ“–
History in ContextDocsπŸ“–
TelemetryExampleπŸ“–
Project Docs (.praison/docs/)DocsπŸ“–
AI Commit MessagesDocsπŸ“–
@Mentions in PromptsDocsπŸ“–
</details> <details> <summary><strong>πŸ–₯️ CLI Features</strong></summary>
FeatureCodeDocs
Slash CommandsExampleπŸ“–
Autonomy ModesExampleπŸ“–
Cost TrackingExampleπŸ“–
Repository MapExampleπŸ“–
Interactive TUIExampleπŸ“–
Git IntegrationExampleπŸ“–
Sandbox ExecutionExampleπŸ“–
CLI CompareExampleπŸ“–
Profile/BenchmarkDocsπŸ“–
Auto ModeDocsπŸ“–
InitDocsπŸ“–
File InputDocsπŸ“–
Final AgentDocsπŸ“–
Max TokensDocsπŸ“–
</details> <details> <summary><strong>πŸ§ͺ Evaluation</strong></summary>
FeatureCodeDocs
Accuracy EvaluationExampleπŸ“–
Performance EvaluationExampleπŸ“–
Reliability EvaluationExampleπŸ“–
Criteria EvaluationExampleπŸ“–
</details> <details> <summary><strong>🎯 Agent Skills</strong></summary>
FeatureCodeDocs
Skills ManagementExampleπŸ“–
Custom SkillsExampleπŸ“–
</details> <details> <summary><strong>⏰ 24/7 Scheduling</strong></summary>
FeatureCodeDocs
Agent SchedulerExampleπŸ“–
</details>

πŸ’» Using JavaScript Code

bash
npm install praisonai
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
javascript
const { Agent } = require('praisonai');
const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
agent.start('Write a movie script about a robot in Mars');

⭐ Star History

Star History Chart


πŸŽ“ Video Tutorials

Learn PraisonAI through our comprehensive video series:

<details> <summary><strong>View all 22 video tutorials</strong></summary>
TopicVideo
AI Agents with Self ReflectionSelf Reflection
Reasoning Data Generating AgentReasoning Data
AI Agents with ReasoningReasoning
Multimodal AI AgentsMultimodal
AI Agents WorkflowWorkflow
Async AI AgentsAsync
Mini AI AgentsMini
AI Agents with MemoryMemory
Repetitive AgentsRepetitive
IntroductionIntroduction
Tools OverviewTools Overview
Custom ToolsCustom Tools
Firecrawl IntegrationFirecrawl
User InterfaceUI
Crawl4AI IntegrationCrawl4AI
Chat InterfaceChat
Code InterfaceCode
Mem0 IntegrationMem0
TrainingTraining
Realtime Voice InterfaceRealtime
Call InterfaceCall
Reasoning Extract AgentsReasoning Extract
</details>

πŸ‘₯ Contributing

We welcome contributions! Fork the repo, create a branch, and submit a PR β†’ Contributing Guide.


❓ FAQ & Troubleshooting

<details> <summary><strong>ModuleNotFoundError: No module named 'praisonaiagents'</strong></summary>

Install the package:

bash
pip install praisonaiagents
</details> <details> <summary><strong>API key not found / Authentication error</strong></summary>

Ensure your API key is set:

bash
export OPENAI_API_KEY=your_key_here

For other providers, see Models docs.

</details> <details> <summary><strong>How do I use a local model (Ollama)?</strong></summary>
bash
# Start Ollama server first
ollama serve

# Set environment variable
export OPENAI_BASE_URL=http://localhost:11434/v1

See Models docs for more details.

</details> <details> <summary><strong>How do I persist conversations to a database?</strong></summary>

Use the db parameter:

python
from praisonaiagents import Agent, db

agent = Agent(
    name="Assistant",
    db=db(database_url="postgresql://localhost/mydb"),
    session_id="my-session"
)

See Persistence docs for supported databases.

</details> <details> <summary><strong>How do I enable agent memory?</strong></summary>
python
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    memory=True,  # Enables file-based memory (no extra deps!)
    user_id="user123"
)

See Memory docs for more options.

</details> <details> <summary><strong>How do I run multiple agents together?</strong></summary>
python
from praisonaiagents import Agent, Agents

agent1 = Agent(instructions="Research topics")
agent2 = Agent(instructions="Summarize findings")
agents = Agents(agents=[agent1, agent2])
agents.start()

See Agents docs for more examples.

</details> <details> <summary><strong>How do I use MCP tools?</strong></summary>
python
from praisonaiagents import Agent, MCP

agent = Agent(
    tools=MCP("npx @modelcontextprotocol/server-memory")
)

See MCP docs for all transport options.

</details>

Getting Help


<div align="center"> <p><strong>Made with ❀️ by the PraisonAI Team</strong></p> <p> <a href="https://docs.praison.ai">πŸ“š Documentation</a> β€’ <a href="https://github.com/MervinPraison/PraisonAI">GitHub</a> β€’ <a href="https://youtube.com/@MervinPraison">▢️ YouTube</a> β€’ <a href="https://x.com/MervinPraison">𝕏 X</a> β€’ <a href="https://linkedin.com/in/mervinpraison">πŸ’Ό LinkedIn</a> </p> </div>

Learn More