# PraisonAI: features, protocols, quickstart

## TL;DR

PraisonAI is an MIT-licensed agent framework maintained by Mervin Praison, with a Python core SDK (praisonaiagents), a CLI and a JavaScript SDK. It runs agent teams sequentially or under a manager, supports handoffs, MCP, A2A and AG-UI, and can call Claude Code or Codex. It suits developers who want many features in one package.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python, TypeScript |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Crew / roles |
| GitHub stars | 9,111 (as of 2026-09-30) |
| GitHub forks | 1,459 |
| Last push | 2026-09-30 |
| Latest release | v4.7.11 |
| Repository | [MervinPraison/PraisonAI](https://github.com/MervinPraison/PraisonAI) |
| Website | [praison.ai](https://praison.ai) |
| Documentation | [praison.ai](https://praison.ai/docs) |
| Last verified | 2026-09-30 |

## Key features

- AgentTeam runs agents on Task objects either sequentially (each task gets the previous output) or hierarchically, where a manager LLM assigns tasks and collects reports. ([source](https://praison.ai/docs/concepts/process))
- AgentFlow describes workflows as steps with route(), parallel() and repeat(); the same graph can be written in YAML. ([source](https://praison.ai/docs/concepts/agentflow))
- Handoffs pass a conversation to a specialist agent, with filters such as keeping only the last N messages or removing tools. ([source](https://praison.ai/docs/concepts/handoffs))
- MCP() attaches MCP server tools over stdio, Streamable HTTP, WebSocket or SSE. ([source](https://praison.ai/docs/mcp/transports))
- Agents can be published as A2A servers (agent card plus JSON-RPC) and can call remote A2A agents with A2AClient. ([source](https://praison.ai/docs/features/a2a))
- The AGUI class exposes an agent or team as an AG-UI streaming endpoint for CopilotKit and other AG-UI frontends. ([source](https://praison.ai/docs/deploy/api/agui-api))
- Claude Code, Gemini CLI, Codex CLI and Cursor CLI can be wrapped as agent tools or selected from the praisonai CLI with --external-agent. ([source](https://praison.ai/docs/code/external-agents))
- Risky tool calls can wait for human approval routed to Slack, Discord, Telegram, a webhook or a local dashboard. ([source](https://praison.ai/docs/concepts/approval))

## Architecture and orchestration pattern

Pattern: Crew / roles.

The core unit is an `Agent` (instructions or role/goal, an LLM, tools). For teams, `AgentTeam` takes agents plus `Task` objects: with `process="sequential"` (the default) tasks run in order and each receives the previous output; with `process="hierarchical"` a `manager_llm` decides which agent handles which task and gathers the results, retrying manager parse failures up to three times.

`AgentFlow` is a separate class for explicit workflows: a list of steps where `route()` branches on a classifier result, `parallel()` fans out and joins, and `repeat()` loops an agent until a condition holds. Agents can also hand a conversation to another agent through `handoffs=[...]`, optionally filtering what history the receiver sees.

State and memory are configured per agent: `memory={...}` with a `user_id` keeps memory across runs, a `db(...)` entry persists messages, runs and traces to databases such as PostgreSQL or SQLite, and `context="summarize"` compacts the window before it overflows. Loop limits (`max_iter`, budget caps) and doom-loop detection bound each run, and `tools_run_on=` can move shell, file and code tools into a sandbox such as Docker or E2B.

### Human in the loop

Setting `approval=True` on an agent makes it pause before risky tools run; the approval docs show routing these requests to Slack, Discord, Telegram, a webhook or a local dashboard, and the CLI exposes the same choice with `--approval slack` and similar flags. Plan approval for `planning=True` is a separate mechanism, and a SQLite-backed durable approval store keeps pending bot approvals across restarts. In autonomous runs, `completion_reason` can come back as `needs_help`, handing control back to the caller.

### Harnesses it can drive

- Claude Code ([evidence](https://praison.ai/docs/code/claude-code))
- Codex ([evidence](https://praison.ai/docs/code/codex-cli))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://praison.ai/docs/mcp/transports) | Client: MCP() loads tools from MCP servers over stdio, Streamable HTTP, WebSocket and SSE in the Python SDK; the docs index also has an MCP Server CLI page. |
| A2A | Yes (checked 2026-09-30) | [link](https://praison.ai/docs/features/a2a) | Server and client: agents are published as A2A servers with an agent card over JSON-RPC 2.0, and A2AClient calls remote A2A agents. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://praison.ai/docs/deploy/api/agui-api) | Server: the AGUI class mounts a FastAPI router that streams an agent or team over the AG-UI protocol for CopilotKit-style frontends. PraisonAI is not in the AG-UI README integration list; this is the project's own docs. |

## Best for

- Coding workflows that hand work to Claude Code, Codex CLI, Gemini CLI or Cursor CLI from a PraisonAI agent.
- Chat support bots on Telegram, Discord or Slack with approvals and memory, one of the README's listed use cases.
- Running agents on local models through the ollama/ model prefix.
- Teams that want matching Python and TypeScript SDKs from the same project.
- Projects that need MCP, A2A and AG-UI endpoints without adding separate adapter libraries.

## Not for

- Teams that want a small, minimal library; the project spans several packages (SDK, CLI, bots, code, train, browser).
- Code that must match README snippets exactly over time; APIs are renamed (Agents is now a deprecated alias of AgentTeam) and releases ship weekly.
- JVM or .NET projects.

## Quickstart

```sh
pip install praisonaiagents
```

Install not yet verified by this site.

```python
from praisonaiagents import Agent, AgentTeam, Task

# Uses OPENAI_API_KEY; pass llm="ollama/llama3.2" to an Agent for a local model.
researcher = Agent(name="Researcher", role="Researcher", goal="Collect key facts")
writer = Agent(name="Writer", role="Writer", goal="Write short, clear summaries")

research = Task(
    description="List three facts about the Rhine river.",
    expected_output="Three bullet points",
    agent=researcher,
)
summary = Task(
    description="Turn the facts into one short paragraph.",
    expected_output="One paragraph",
    agent=writer,
    context=[research],
)

team = AgentTeam(agents=[researcher, writer], tasks=[research, summary], process="sequential")
print(team.start())
```

### Common pitfalls

- `praisonaiagents` requires Python 3.10 or newer.
- Package split: `praisonaiagents` is the SDK only, `praisonai` adds the CLI and extras, and `praisonai-code` is the CLI without gateway and bot integrations.
- The default provider is OpenAI (`OPENAI_API_KEY`); local Ollama models need the `ollama/` prefix in `llm`.
- The README's multi-agent snippet imports `Agents`, which is now a deprecated alias of `AgentTeam` and emits a warning.
- `process="hierarchical"` needs `manager_llm`.
- External coding CLIs (Claude Code, Codex, Gemini CLI, Cursor CLI) must be installed and logged in separately; the Claude Code example uses `skip_permissions=True`, which skips that CLI's own permission prompts.

Official quickstart: https://praison.ai/docs/install/quickstart

## Pros

- Covers MCP, A2A and AG-UI in first-party code instead of separate community adapters. ([source](https://praison.ai/docs/features/a2a))
- Human approval can be routed to chat platforms (Slack, Discord, Telegram) rather than only a terminal prompt. ([source](https://praison.ai/docs/concepts/approval))
- Several orchestration styles in one SDK: sequential and hierarchical teams plus routed, parallel and looping workflows. ([source](https://praison.ai/docs/concepts/process))
- Documented persistence adapters for PostgreSQL, MySQL, SQLite, MongoDB, Redis and others. ([source](https://praison.ai/docs/databases/overview))
- A TypeScript SDK and CLI are published on npm as praisonai alongside the Python packages. ([source](https://praison.ai/docs/cli/typescript-cli))

## Cons

- The README's multi-agent example still uses Agents, which the SDK now treats as a deprecated alias of AgentTeam. ([source](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/__init__.py))
- The TypeScript SDK accepts some options only for Python parity and does not act on them yet. ([source](https://praison.ai/docs/features/typescript-parity-notices))
- An open issue reports that guardrails in the praisonai wrapper fail open on any error. ([source](https://github.com/MervinPraison/PraisonAI/issues/5379))
- An open issue reports that the core SDK's default chat history grows without bound. ([source](https://github.com/MervinPraison/PraisonAI/issues/5376))
- Very fast release cadence (eight tagged releases between 28 August and 29 September 2026), so pinning versions matters. ([source](https://github.com/MervinPraison/PraisonAI/releases))

## Alternatives

- [CrewAI](https://multiagentguide.top/tools/crewai.md)
- [Agno](https://multiagentguide.top/tools/agno.md)
- [Swarms](https://multiagentguide.top/tools/swarms.md)
- [AG2](https://multiagentguide.top/tools/ag2.md)
- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)

## FAQ

### Does PraisonAI support MCP, A2A and AG-UI?

Yes, all three in its own docs: MCP() connects to MCP servers over stdio, HTTP, WebSocket or SSE; agents can be A2A servers and use A2AClient; and the AGUI class serves an agent over AG-UI for CopilotKit-style frontends.

### Is PraisonAI free?

It is MIT licensed and no paid plan or pricing page was found on the project site. Model calls are billed by whichever provider you configure.

### Which package should I install?

pip install praisonaiagents gives the Python SDK only; pip install praisonai adds the CLI and optional extras; npm install praisonai installs the TypeScript SDK.

### Can PraisonAI drive Claude Code or Codex?

Yes. Integration classes wrap the Claude Code and Codex CLIs (plus Gemini CLI and Cursor CLI) as tools, and an Agent can use the claude CLI as its model backend. The CLIs must be installed separately.

### How is a hierarchical AgentTeam different from a sequential one?

Sequential runs tasks in list order, passing each output forward. Hierarchical adds a manager LLM (manager_llm is required) that assigns tasks to agents and collects their reports.

## Sources

- [PraisonAI GitHub repository (README)](https://github.com/MervinPraison/PraisonAI)
- [PraisonAI website](https://praison.ai)
- [PraisonAI documentation](https://praison.ai/docs)
- [Quick install](https://praison.ai/docs/install/quickstart)
- [Agent process types](https://praison.ai/docs/concepts/process)
- [AgentFlow](https://praison.ai/docs/concepts/agentflow)
- [Agent handoffs](https://praison.ai/docs/concepts/handoffs)
- [MCP transports](https://praison.ai/docs/mcp/transports)
- [A2A protocol](https://praison.ai/docs/features/a2a)
- [AG-UI API](https://praison.ai/docs/deploy/api/agui-api)
- [External agents (Claude Code, Gemini CLI, Codex CLI, Cursor CLI)](https://praison.ai/docs/code/external-agents)
- [Claude Code integration](https://praison.ai/docs/code/claude-code)
- [Codex CLI integration](https://praison.ai/docs/code/codex-cli)
- [Approval](https://praison.ai/docs/concepts/approval)
- [Databases overview](https://praison.ai/docs/databases/overview)
- [TypeScript CLI (praisonai-ts)](https://praison.ai/docs/cli/typescript-cli)
- [TypeScript parity notices](https://praison.ai/docs/features/typescript-parity-notices)
- [praisonaiagents __init__.py (Agents deprecated alias)](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/__init__.py)
- [Releases](https://github.com/MervinPraison/PraisonAI/releases)
- [Issue #5379: wrapper guardrails fail open](https://github.com/MervinPraison/PraisonAI/issues/5379)
- [Issue #5376: default chat history grows without bound](https://github.com/MervinPraison/PraisonAI/issues/5376)
- [Durable approvals](https://praison.ai/docs/features/durable-approvals)

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/praisonai