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.
```bash
curl -fsSL https://praison.ai/install.sh | bash
```
---
## π― Use Cases
AI agents solving real-world problems across industries:
| Use Case | Description |
|----------|-------------|
| π **Research & Analysis** | Conduct deep research, gather information, and generate insights from multiple sources automatically |
| π» **Code Generation** | Write, debug, and refactor code with AI agents that understand your codebase and requirements |
| βοΈ **Content Creation** | Generate blog posts, documentation, marketing copy, and technical writing with multi-agent teams |
| π **Data Pipelines** | Extract, transform, and analyze data from APIs, databases, and web sources automatically |
| π€ **Customer Support** | Deploy 24/7 support bots on Telegram, Discord, Slack with memory and knowledge-backed responses |
| βοΈ **Workflow Automation** | Automate multi-step business processes with agents that hand off tasks, verify results, and self-correct |
---
## π Meet your first Agent (Under 1 Minute)
1. Install the lightweight core SDK:
```bash
pip install praisonaiagents
export OPENAI_API_KEY="your-api-key"
```
2. Run your first autonomous agent:
```python
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.
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ⬑ 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? β β β β β β
β β β β β βββββββββββββββββββββββββββββββββββββββββββββββ β β β β β
β β β β βββββββββββββββββββββββββββββββββββββββββββββββββββ β β β β
β β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β β
β β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
| Layer | The question it answers | PraisonAI |
|:--|:--|:--|
| **1 Β· Prompt** | Did I say it clearly? | `instructions=`, `role`/`goal`/`backstory`, `output=`, `templates=` |
| **2 Β· Context** | Is the right thing in the window? | `memory=`, `knowledge=`, `context=`, handoff `ContextPolicy` |
| **3 Β· Harness** | Can it act, and be checked? | `tools=`, `MCP()`, `guardrails=`, `approval=`, `hooks=`, `sandbox=` |
| **4 Β· Loop** | When do we stop? | `execution=ExecutionConfig(...)`, `reflection=`, `autonomy=`, doom-loop detection |
| **5 Β· Graph** | Who runs when, and who checks whom? | `AgentFlow`, `route()`, `parallel()`, `loop()`, `repeat()` |
| **⬑ Managed** | *Where does it actually run?* | `tools_run_on="docker"` β one shared sandbox for the tools, or `run_on="anthropic"` for the whole agent |
### 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](https://docs.praison.ai/docs/concepts/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
@tool
def deploy(env: str) -> str:
"""Deploy the current build to an environment."""
return f"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"),
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](https://docs.praison.ai/docs/features/doom-loop-detection)
### Layer 5 Β· Graph β *Who runs when, and who checks whom?*
Topology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.
```python
from praisonaiagents import AgentFlow
from praisonaiagents.workflows import route, parallel, repeat
flow = AgentFlow(steps=[
classifier,
route({"bug": [bug_agent], "feature": [feature_agent], "default": [triage]}),
parallel([reviewer, tester]), # fan out, join automatically
repeat(editor, until=lambda ctx: "approved" in ctx.previous_result.lower(),
max_iterations=3), # evaluatorβoptimizer
])
flow.run("Ticket #123: login fails on Safari")
```
> The same graph is expressible in YAML with no Python at all. [π AgentFlow](https://docs.praison.ai/docs/concepts/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
```
The simplest way in is `tools_run_on=` β one whole team or workflow shares **one** sandbox, so a file written by step 1 is there for step 2. Thinking stays on your machine:
```python
from praisonaiagents import Agent, AgentFlow
writer = Agent(name="Writer", instructions="You write files.")
reader = Agent(name="Reader", instructions="You read files.")
flow = AgentFlow(tools_run_on="docker", steps=[writer, reader]) # or e2b | modal | daytona | flyio
flow.run("Write 'hello' to /workspace/note.txt, then read it back")
```
Same thing with no Python at all:
```yaml
name: remote-demo
tools_run_on: docker # every step shares one sandbox
agents:
writer: {role: Writer, goal: Write files}
reader: {role: Reader, goal: Read files}
steps:
- agent: writer
action: "Write 'hello' to /workspace/note.txt"
- agent: reader
action: "Read /workspace/note.txt"
```
For a single agent, two words cover it β and they answer different questions:
```python
from praisonaiagents import Agent
# A. Only the TOOLS move. Thinking stays on your machine.
agent = Agent(name="builder", instructions="You build things.",
tools_run_on="docker") # docker | e2b | modal | daytona | flyio
# tenki | sandlock | ssh | novita | subprocess
# B. The WHOLE agent moves β model calls, loop and tools
agent = Agent(name="teacher", instructions="You teach.", run_on="anthropic") # hosted
agent = Agent(name="builder", instructions="You build.", run_on="docker") # self-hosted
agent.start("Write a Python script that prints the first 10 primes, then run it")
```
Ask any object where it runs, and it will tell you:
```python
>>> Agent(name="builder", instructions="x", tools_run_on="docker")
Agent(name='builder', thinks_on='this machine', tools_run_on='a Docker container')
>>> agent.where_does_it_run()
Thinking (the AI model calls) happens on this machine.
Tools run on a Docker container.
Your own tools (check_db) still run on this machine -- only shell, file and
code tools move. They read and write this machine's files.
```
Naming a place that cannot do the job is a typo, not a preference, so it says so:
```python
>>> Agent(name="x", instructions="i", run_on="e2b")
TypeError: Agent(run_on='e2b') is not valid: run_on= places the whole agent
-- model calls, loop and tools -- on a managed runtime, and 'e2b' runs
commands but cannot host an agent loop.
To run only the tools there: Agent(tools_run_on='e2b')
```
To run one block of code somewhere else, name the place on that call:
```python
agent.execute_code_sync("print(6 * 7)", run_in="sandlock") # kernel-enforced
```
See what is running and reclaim strays:
```bash
praisonai managed ps # list running sandboxes
praisonai managed stop --all # reclaim them
```
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](examples/python/managed-agents/) Β· manage sessions with `praisonai managed sessions list ` or `praisonai managed sessions resume ""`
Stack framing adapted from [The Five-Layer Agent Stack](https://mer.vin/2026/07/five-layer-agent-stack-match-bug-to-right-layer/) and [Agent Harnesses vs Orbs](https://mer.vin/2026/08/agent-harnesses-vs-orbs-why-remote-sandboxes-beat-local-agent-loops/).
---
## π The PraisonAI Ecosystem
Start simple with the core SDK, or expand to full visual builders and dashboards when you're ready.
* **Core SDK (`praisonaiagents`)**: For pure Python development. `pip install praisonaiagents`
* π» **PraisonAI CLI (`praisonai`)**: For terminal-based developers. `pip install praisonai`
* π¦ **Claw Dashboard**: Connect agents directly to Telegram, Slack, or Discord. `pip install "praisonai[claw]"`
* π **Flow Visual Builder**: Drag-and-drop workflow creation. `pip install "praisonai[flow]"`
* π€ **PraisonAI UI**: Clean chat interface. `pip install "praisonai[ui]"`
### JavaScript SDK
```bash
npm install praisonai
```
## π§ Supported Providers & Features
Powered by 100+ LLMs (OpenAI, Anthropic, Gemini & local models).
---
## π Video Tutorials
Learn PraisonAI through our comprehensive video series:
View all 22 video tutorials
| Topic | Video |
|-------|--------|
| AI Agents with Self Reflection | [](https://www.youtube.com/watch?v=vLXobEN2Vc8) |
| Reasoning Data Generating Agent | [](https://www.youtube.com/watch?v=fUT332Y2zA8) |
| AI Agents with Reasoning | [](https://www.youtube.com/watch?v=KNDVWGN3TpM) |
| Multimodal AI Agents | [](https://www.youtube.com/watch?v=hjAWmUT1qqY) |
| AI Agents Workflow | [](https://www.youtube.com/watch?v=yWTH44QPl2A) |
| Async AI Agents | [](https://www.youtube.com/watch?v=VhVQfgo00LE) |
| Mini AI Agents | [](https://www.youtube.com/watch?v=OkvYp5aAGSg) |
| AI Agents with Memory | [](https://www.youtube.com/watch?v=1hVfVxvPnnQ) |
| Repetitive Agents | [](https://www.youtube.com/watch?v=dAYGxsjDOPg) |
| Introduction | [](https://www.youtube.com/watch?v=Fn1lQjC0GO0) |
| Tools Overview | [](https://www.youtube.com/watch?v=XaQRgRpV7jo) |
| Custom Tools | [](https://www.youtube.com/watch?v=JSU2Rndh06c) |
| Firecrawl Integration | [](https://www.youtube.com/watch?v=UoqUDcLcOYo) |
| User Interface | [](https://www.youtube.com/watch?v=tg-ZjNl3OCg) |
| Crawl4AI Integration | [](https://www.youtube.com/watch?v=KAvuVUh0XU8) |
| Chat Interface | [](https://www.youtube.com/watch?v=sw3uDqn2h1Y) |
| Code Interface | [](https://www.youtube.com/watch?v=_5jQayO-MQY) |
| Mem0 Integration | [](https://www.youtube.com/watch?v=KIGSgRxf1cY) |
| Training | [](https://www.youtube.com/watch?v=aLawE8kwCrI) |
| Realtime Voice Interface | [](https://www.youtube.com/watch?v=frRHfevTCSw) |
| Call Interface | [](https://www.youtube.com/watch?v=m1cwrUG2iAk) |
| Reasoning Extract Agents | [](https://www.youtube.com/watch?v=2PPamsADjJA) |
---
## π₯ Contributing
We welcome contributions! Fork the repo, create a branch, and submit a PR β [Contributing Guide](https://github.com/MervinPraison/PraisonAI/blob/main/CONTRIBUTING.md).
---
## β FAQ & Troubleshooting
ModuleNotFoundError: No module named 'praisonaiagents'
Install the package:
```bash
pip install praisonaiagents
```
API key not found / Authentication error
Ensure your API key is set:
```bash
export OPENAI_API_KEY=your_key_here
```
For other providers, see [Models docs](https://docs.praison.ai/docs/models).
How do I use a local model (Ollama)?
```bash
# Start Ollama and pull a model
ollama serve
ollama pull llama3.2
```
```python
from praisonaiagents import Agent
agent = Agent(instructions="You are a helpful assistant", llm="ollama/llama3.2")
agent.start("Why is the sky blue?")
```
The `ollama/` prefix is what selects Ollama's handling β tool-call repair,
tool-result formatting and the streaming rules small local models need. Or set
it by environment instead:
```bash
export OPENAI_MODEL_NAME=ollama/llama3.2
```
Setting only `OPENAI_BASE_URL` is not enough: with no model named, the OpenAI
default (`gpt-4o-mini`) is sent to Ollama, which answers
`404 model 'gpt-4o-mini' not found`. Always name the model.
Point at a non-default host with `base_url=` or `OLLAMA_HOST`:
```python
agent = Agent(instructions="...", llm="ollama/llama3.2", base_url="http://192.168.1.10:11434")
```
The same shape works for other local runtimes β `lm_studio/`, `vllm/` and
`hosted_vllm/` with their server's `base_url`.
See [Models docs](https://docs.praison.ai/docs/models) for more details.
How do I persist conversations to a database?
Use the `db` parameter:
```python
from praisonaiagents import Agent, db
agent = Agent(
name="Assistant",
memory={
"db": db(database_url="postgresql://localhost/mydb"),
"session_id": "my-session",
},
)
```
See [Persistence docs](https://docs.praison.ai/docs/databases/overview) for supported databases.
How do I enable agent memory?
```python
from praisonaiagents import Agent
agent = Agent(
name="Assistant",
# Enables file-based memory (no extra deps!)
memory={"user_id": "user123"},
)
```
See [Memory docs](https://docs.praison.ai/docs/concepts/memory) for more options.
How do I run multiple agents together?
```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](https://docs.praison.ai/docs/concepts/agents) for more examples.
How do I use MCP tools?
```python
from praisonaiagents import Agent, MCP
agent = Agent(
tools=MCP("npx @modelcontextprotocol/server-memory")
)
```
See [MCP docs](https://docs.praison.ai/docs/mcp/transports) for all transport options.
### Getting Help
- π [Full Documentation](https://docs.praison.ai)
- π [Report Issues](https://github.com/MervinPraison/PraisonAI/issues)
- π¬ [Discussions](https://github.com/MervinPraison/PraisonAI/discussions)
---
