AI Agents Framework with Self Reflection and MCP support
PraisonAI is an AI Agents Framework with Self Reflection and MCP support, designed to coordinate multi-agent systems. It exposes a structured server for Model Context Protocol (MCP) interactions and emphasizes agent collaboration, self-reflection, and extensibility within AI agent frameworks.
π οΈ Key Features
MCP (Model Context Protocol) support for standardized context exchange
Self-reflection capabilities to adapt agent behavior over time
AI agent framework with multi-agent coordination
Rich topic tagging for discoverability and integration
Open-source repository with documentation and examples
π Use Cases
Building and managing multi-agent workflows
Implementing self-reflective agent strategies
Integrating MCP-based context sharing in AI agents
Extending a modular AI-agent framework for experiments
β‘ Developer Benefits
Clear MCP integration guidance and context schemas
Extensible framework for AI agents and tooling
Topics-driven discoverability for ecosystem tooling
Accessible README excerpts and repository references
β οΈ Limitations
Specific MCP implementation details are inferred from repository metadata
ReadmeExcerpt in data may be truncated; consult full docs for complete guidance
PraisonAI π¦ β Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous, self-improving agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.
from praisonaiagents import Agent
# Give your agent a goal, and watch it work.
agent = Agent(instructions="You are a senior data analyst.")
agent.start("Analyze the top 3 tech trends of 2026 and format as a markdown table.")
𧬠The Five-Layer Agent Stack
Most frameworks hand you one or two layers and leave the rest as homework. PraisonAI covers all five β plus the outer layer that decides where your agent actually runs.
Each layer wraps the one inside it. When an agent misbehaves, the layer tells you where to look.
code
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ⬑ MANAGED AGENTS β Where does it actually run? β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 5 Β· GRAPH β Who runs when, and who checks whom? β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β β β 4 Β· LOOP β When do we stop? β β β
β β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β β
β β β β 3 Β· HARNESS β Can it act, and be checked? β β β β
β β β β βββββββββββββββββββββββββββββββββββββββββββββββββββ β β β β
β β β β β 2 Β· CONTEXT β Is the right thing in the window? β β β β β
β β β β β βββββββββββββββββββββββββββββββββββββββββββββββ β β β β β
β β β β β β 1 Β· PROMPT β Did I say it clearly? β β β β β β
β β β β β βββββββββββββββββββββββββββββββββββββββββββββββ β β β β β
β β β β βββββββββββββββββββββββββββββββββββββββββββββββββββ β β β β
β β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
backend=ManagedAgent(compute="e2b") β remote sandbox, or a fully hosted loop
Layer 1 Β· Prompt β Did I say it clearly?
Role, instructions, examples, output format.
python
from praisonaiagents import Agent
agent = Agent(
role="Senior Data Analyst",
goal="Turn raw numbers into decisions",
output="verbose", # markdown-formatted output
)
agent.start("Summarise Q3 revenue trends")
Layer 2 Β· Context β Is the right thing in the window?
Write, select, compress, isolate β the four context operations, one parameter each.
python
from praisonaiagents import Agent
agent = Agent(
instructions="You are a support engineer.",
memory={"user_id": "u-42"}, # write β persists across runs (needs a user_id)
knowledge=["docs/"], # select β retrieves only what's relevant
context="summarize", # compress β auto-compacts before the limit
)
Isolate is handoffs=[specialist] β a sub-agent inherits the last few messages and the intersection of your tools, not your whole transcript. π Handoffs
Layer 3 Β· Harness β Can it act, and be checked?
Agent = Model + Harness. Tool dispatch, plus the guides that steer before acting and the sensors that observe after.
python
from praisonaiagents import Agent, MCP, tool
@tooldefdeploy(env: str) -> str:
"""Deploy the current build to an environment."""returnf"Deployed to {env}"
agent = Agent(
name="ReleaseEngineer",
instructions="You are a release engineer.",
tools=[deploy, MCP("npx -y @modelcontextprotocol/server-filesystem /tmp")],
approval=True, # guide β human gate before risky tools run
)
agent.start("Deploy to staging, then list the files you can read")
Layer 4 Β· Loop β When do we stop?
Hard iteration caps, budget ceilings, no-progress detection and completion checks β every brake is explicit.
python
from praisonaiagents import Agent, ExecutionConfig
agent = Agent(
instructions="Fix the failing tests.",
execution=ExecutionConfig(max_iter=30, max_budget=0.50, on_budget_exceeded="stop"),
reflection=True, # completion check β the agent grades its own answer
autonomy=True, # required to drive the loop with run_autonomous()
)
result = agent.run_autonomous("Refactor the auth module", max_iterations=5)
print(result.completion_reason)
# goal | no_tool_calls | max_iterations | timeout | doom_loop | needs_help | error# (with on_budget_exceeded="stop", hitting the cap raises BudgetExceededError,# surfaced here as completion_reason="error")
Doom-loop detection is on by default. Repeated identical tool calls and AβBβAβB oscillation get caught β while a poller whose output keeps changing does not. π Doom Loop Detection
Layer 5 Β· Graph β Who runs when, and who checks whom?
Topology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.
The same graph is expressible in YAML with no Python at all. π AgentFlow
⬑ Outside the stack: Managed Agents β Where does it actually run?
The harness is commoditising; where the agent executes is the next multiplier. Rather than burning your laptop's CPU, hand an agent a short-lived cloud sandbox β repo, tools and tests run there.
bash
pip install praisonai
python
from praisonai import Agent, ManagedAgent, LocalManagedConfig
# A. Tools run in a remote sandbox; the agent loop stays local
sandboxed = ManagedAgent(
provider="local", compute="e2b", # or modal | daytona | flyio | docker | tenki
config=LocalManagedConfig(model="gpt-4o-mini", name="RemoteTools"),
)
agent = Agent(name="builder", backend=sandboxed)
# B. The entire agent loop runs in the cloud (needs ANTHROPIC_API_KEY;# with no key set, ManagedAgent() falls back to a local loop)
agent = Agent(name="teacher", backend=ManagedAgent())
agent.start("Write a Python script that prints the first 10 primes, then run it")
Sandboxes shut themselves down when idle (auto_shutdown, idle_timeout_s), and a post-setup snapshot is reused so the next run skips the image pull and dependency install. Commit a .praisonai/environment.yaml and the environment travels with the repo.
π 20 runnable examples Β· manage sessions with praisonai managed sessions list <agent-id> or praisonai managed sessions resume <session-id> "<prompt>"
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()
π Full MCP docs β stdio, HTTP, WebSocket, SSE transports
4. Custom Tools
python
from praisonaiagents import Agent, tool
@tooldefsearch(query: str) -> str:
"""Search the web for information."""returnf"Results for: {query}"@tooldefcalculate(expression: str) -> float:
"""Safely evaluate a numeric arithmetic expression."""import ast
import operator
# Define allowed operations
_OPS = {
ast.Add: operator.add,
ast.Sub: operator.sub,
ast.Mult: operator.mul,
ast.Div: operator.truediv,
ast.Pow: operator.pow,
ast.USub: operator.neg,
ast.UAdd: operator.pos,
}
def_safe_eval(node):
ifisinstance(node, ast.Constant) andisinstance(node.value, (int, float)):
return node.value
elifisinstance(node, ast.BinOp) andtype(node.op) in _OPS:
return _OPS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))
elifisinstance(node, ast.UnaryOp) andtype(node.op) in _OPS:
return _OPS[type(node.op)](_safe_eval(node.operand))
else:
raise ValueError("Unsupported expression")
try:
return _safe_eval(ast.parse(expression, mode="eval").body)
except (ValueError, SyntaxError, TypeError, ZeroDivisionError, OverflowError):
raise ValueError("Invalid arithmetic expression")
agent = Agent(
instructions="You are a helpful assistant",
tools=[search, calculate]
)
agent.start("Search for AI news and calculate 15*4")
β οΈ Security Note: Never use eval(), exec(), or subprocess in tool functions that process LLM-generated or user-supplied input. Always validate and sanitize inputs to prevent code injection attacks.
π Full tools docs β BaseTool, tool packages, 100+ built-in tools
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
Build multi-agent workflows visually with drag-and-drop components in Langflow.
bash
pip install "praisonai[flow]"
praisonai flow
Open http://localhost:7861 β use the Agent and Agent Team components to create sequential or parallel workflows. Connect Chat Input β Agent Team β Chat Output for instant multi-agent pipelines.
π Full Flow docs β visual agent building, component reference, and deployment
8. PraisonAI UI π€ (Clean Chat)
Lightweight chat interface for your AI agents.
bash
pip install "praisonai[ui]"
praisonai ui
π Using YAML (No Code)
Example 1: Two Agents Working Together
Create agents.yaml:
yaml
framework:praisonaitopic:"Write a blog post about AI"agents:researcher:role:ResearchAnalystgoal:ResearchAItrendsandgatherinformationinstructions:"Find accurate information about AI trends"writer:role:ContentWritergoal:Writeengagingblogpostsinstructions:"Write clear, engaging content based on research"
Run with:
bash
praisonai agents.yaml
The agents automatically work together sequentially
Example 2: Agent with Custom Tool
Create two files in the same folder:
agents.yaml:
yaml
framework:praisonaitopic:"Calculate the sum of 25 and 15"agents:calculator_agent:role:Calculatorgoal:Performcalculationsinstructions:"Use the add_numbers tool to help with calculations"tools:-add_numbers
tools.py:
python
defadd_numbers(a: float, b: float) -> float:
"""
Add two numbers together.
Args:
a: First number
b: Second number
Returns:
The sum of a and b
"""return a + b
Run with:
bash
praisonai agents.yaml
π‘ Tips:
Use the function name (e.g., add_numbers) in the tools list, not the file name
Tools in tools.py are automatically discovered
The function's docstring helps the AI understand how to use it
const { Agent } = require('praisonai');
const agent = newAgent({ instructions: 'You are a helpful AI assistant' });
agent.start('Write a movie script about a robot in Mars');
β‘ Performance
PraisonAI is built for speed, with agent instantiation in around 14ΞΌs. This reduces overhead, improves responsiveness, and helps multi-agent systems scale efficiently in real-world production workloads.
