# https://github.com/MervinPraison/PraisonAI Project Manual Generated at: 2026-06-23 03:25:42 UTC ## Table of Contents - [PraisonAI Overview and System Architecture](#page-1) - [Core SDK: Agent, Agents, Memory, and Workflows](#page-2) - [Tools, MCP Protocol, and LLM Provider Integration](#page-3) - [CLI, UI Surfaces, Workflows, and Deployment](#page-4) ## PraisonAI Overview and System Architecture ### Related Pages Related topics: [Core SDK: Agent, Agents, Memory, and Workflows](#page-2), [Tools, MCP Protocol, and LLM Provider Integration](#page-3), [CLI, UI Surfaces, Workflows, and Deployment](#page-4)
Related Source Files The following source files were used to generate this page: - [examples/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md) - [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) - [src/praisonai-ts/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/README.md) - [examples/rag/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/rag/README.md) - [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md) - [examples/security/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/security/README.md) - [examples/cookbooks/Industry_Templates/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/cookbooks/Industry_Templates/README.md) - [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) - [examples/serve/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/serve/README.md) - [examples/python/monitoring/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/monitoring/README.md) - [examples/python/profiling/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/profiling/README.md) - [examples/python/plugin_template/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/plugin_template/README.md) - [examples/recipes/creator_suite/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/recipes/creator_suite/README.md) - [examples/yaml/pr-reviewer/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/yaml/pr-reviewer/README.md)
# PraisonAI Overview and System Architecture PraisonAI is a multi-agent AI framework delivered as a multi-language SDK and CLI toolkit. The current latest release is **v4.6.71** (per community release notes). The repository organizes code into several top-level packages, with `src/praisonai` containing the Python SDK and CLI entry points and `src/praisonai-ts` providing a TypeScript counterpart (Source: [examples/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md)). ## High-Level Architecture PraisonAI follows an **agent-centric** design where the `Agent` is the core primitive and additional abstractions (Tasks, Teams, Workflows, Tools, Memory, Knowledge) are layered on top. The framework exposes both Python and TypeScript surfaces, and ships a CLI (`praisonai`) for running recipes, serving endpoints, and managing MCP servers (Source: [examples/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md)). ```mermaid flowchart TB User[Developer / CLI User] --> CLI[praisonai CLI] User --> SDK[Python / TypeScript SDK] CLI --> Recipes[Recipes / YAML Agents] SDK --> Agent[Agent Core] Recipes --> Agent Agent --> Tools[Tools & Plugins] Agent --> Memory[Memory & Knowledge] Agent --> MCP[MCP Server] Agent --> Telemetry[Monitoring & Profiling] Tools --> External[External APIs: ArXiv, Exa, Web] MCP --> Registry[MCPToolRegistry] Telemetry --> Metrics[Metrics Endpoint] Recipes --> Serve[Recipe Serve / OpenAPI] ``` ### Core Packages - **`praisonaiagents`** — The Python agent runtime exposing `Agent`, `Task`, `AgentTeam`, `BaseTool`, the `@tool` decorator, telemetry (`@monitor_function`, `track_api_call`), and a plugin discovery system (Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md)). - **`praisonai`** — The umbrella Python package that ships the CLI and higher-level features: `recipe serve`, `recipe sbom`, `recipe audit`, MCP server registry, and consolidated parameter shortcuts (Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md)). - **`praisonai-ts`** — A TypeScript SDK mirroring the Python API with `Agent`, `Task`, and `AgentTeam` for Node.js users (Source: [src/praisonai-ts/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/README.md)). ## Layered Components ### Agents, Tasks, and Teams The smallest unit of work is an `Agent` configured with a role, goal, instructions, and optional tools. Tasks describe deliverables, and `AgentTeam` (or its TypeScript equivalent) orchestrates execution across multiple agents. Example scripts under `examples/python/agents/` demonstrate single agents, multi-agent teams, and router agents for cost-optimized LLM selection (Source: [examples/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md)). ### Tools and Plugin System Tools extend agent capabilities. PraisonAI supports two creation styles — class-based `BaseTool` subclasses and the lightweight `@tool` decorator — and registers them with agents via the `tools=[...]` parameter (Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md)). External developers can distribute tools as pip-installable plugins using the `praisonai-example-plugin` template; installed plugins are auto-discovered via Python entry points so that `tools=["example_greet"]` resolves without explicit imports (Source: [examples/python/plugin_template/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/plugin_template/README.md)). The TypeScript SDK also ships tool examples such as `ArxivSearchTool` and `ArxivDownloadTool`, downloadable as PDF buffers and importable from the `praisonai` npm package (Source: [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md)). > **Community note:** Issue #6 in the repository requests first-class support for **LangChain** and **CrewAI** tools, with users explicitly asking for Google search tools as the starting integration point. This reflects a recurring demand for broader tool interoperability across ecosystems. ### Knowledge, RAG, and Memory RAG is implemented through the `Knowledge` parameter on agents and standalone retrieval pipelines. The example catalog covers basic retrieval, auto-retrieval policies, hybrid dense+sparse search, reranking, multi-document synthesis, knowledge graphs, citations, and structured output (Source: [examples/rag/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/rag/README.md)). An end-to-end Streamlit demo uses GPT-5-nano with a built-in vector store and URL-based knowledge sources for documentation Q&A (Source: [examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md)). ### MCP Server and Protocol Layer PraisonAI implements the **Model Context Protocol** through `praisonai.mcp_server.registry.MCPToolRegistry`, which supports paginated listing, query/category filtering, and tool annotations such as `read_only_hint` and `destructive_hint` (Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md)). CLI commands expose discovery (`praisonai mcp tools search/info/schema/list`) and the server exposes MCP resources like `praisonai://agents`, `praisonai://knowledge/sources`, and `praisonai://mcp/status`, plus prompts such as `deep-research`, `code-review`, and `guardrail-check` (Source: [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md)). ### Recipes, Serving, and Deployment Agents can be authored as YAML recipes and served via `praisonai recipe serve` with auth, workers, rate limits, metrics (`/metrics`), OpenAPI (`/openapi.json`), and hot reload (`POST /admin/reload`) (Source: [examples/serve/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/serve/README.md)). A full **Creator Suite** recipe pack is included for AI content workflows — news crawling, script writing, hook generation, video assembly, and publishing — each script is independently runnable with optional OpenAI keys (Source: [examples/recipes/creator_suite/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/recipes/creator_suite/README.md)). ## Cross-Cutting Concerns | Concern | Mechanism | Example / Source | |---------|-----------|------------------| | Configuration | Consolidated params (`memory`, `output`, `knowledge`, `hooks`, `planning`, etc.) | [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) | | Security | SBOM (CycloneDX/SPDX), dependency audit, lockfile validation, PII redaction (`data_policy.pii.mode`) | [examples/security/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/security/README.md) | | Monitoring | `@monitor_function`, `track_api_call`, async/per-tool timing, multi-agent workflow stats | [examples/python/monitoring/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/monitoring/README.md) | | Profiling | `praisonai profile` with text/JSON output, snapshot baselines, opt-in lite mode via env vars | [examples/python/profiling/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/profiling/README.md) | | Industry reuse | SRAO Framework templates for Manufacturing, Energy, Healthcare with ~70% shared code | [examples/cookbooks/Industry_Templates/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/cookbooks/Industry_Templates/README.md) | | CI integration | GitHub Actions multi-agent PR reviewer triggered by `@praisonai` | [examples/yaml/pr-reviewer/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/yaml/pr-reviewer/README.md) | ## See Also - [Tools and Plugin System](tools-and-plugins.md) - [MCP Server](mcp-server.md) - [Recipe Serve and Deployment](recipe-serve.md) - [Security Features](security.md) - [RAG and Knowledge](rag-knowledge.md) - [Monitoring and Profiling](monitoring-profiling.md) --- ## Core SDK: Agent, Agents, Memory, and Workflows ### Related Pages Related topics: [PraisonAI Overview and System Architecture](#page-1), [Tools, MCP Protocol, and LLM Provider Integration](#page-3), [CLI, UI Surfaces, Workflows, and Deployment](#page-4)
Related Source Files The following source files were used to generate this page: - [src/praisonai-agents/praisonaiagents/agent/agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/agent.py) - [src/praisonai-agents/praisonaiagents/agents/agents.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agents/agents.py) - [src/praisonai-agents/praisonaiagents/agent/autonomy.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/autonomy.py) - [src/praisonai-agents/praisonaiagents/agent/memory_mixin.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/memory_mixin.py) - [src/praisonai-agents/praisonaiagents/agent/handoff.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/handoff.py) - [src/praisonai-agents/praisonaiagents/agent/context_agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/context_agent.py) - [src/praisonai-agents/praisonaiagents/runtime/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/runtime/README.md) - [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) - [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) - [examples/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md) - [examples/python/stateful/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/stateful/README.md) - [examples/python/save_output/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/save_output/README.md)
# Core SDK: Agent, Agents, Memory, and Workflows The PraisonAI Core SDK (`praisonaiagents`) is the Python foundation used to build autonomous agent systems. It exposes a unified **Agent-Centric API** that consolidates capabilities such as memory, autonomy, tools, context, and reflection behind a single `Agent` class, then composes them into multi-agent teams (`Agents`) and step-based `Workflows`. The SDK ships with a pluggable runtime abstraction, multi-backend memory, and language parity for TypeScript and Rust. As of release `v4.6.71` it is the runtime referenced by every higher-level feature in the [examples index](https://github.com/MervinPraison/PraisonAI/blob/main/examples/README.md) — agents, memory, MCP, tools, code execution, and YAML workflows all delegate to `praisonaiagents`. ## Architecture Overview ```mermaid graph TD A[Agent] -->|uses| M[Memory Mixin] A -->|uses| C[Context Agent] A -->|uses| AU[Autonomy] A -->|uses| H[Handoff] A -->|uses| T[Tools] A -->|executes via| R[AgentRuntimeProtocol] R --> RR[RuntimeRegistry] R --> PR[Built-in PraisonAI Runtime] A --> AG[Agents / AgentTeam] AG --> W[Workflows] M --> MB[(Memory Backends)] MB --> SQLITE[SQLite] MB --> REDIS[Redis] MB --> MEM0[Mem0] MB --> MONGO[MongoDB] ``` A single `Agent` composes cross-cutting concerns (memory, context, autonomy, handoff, tools) and is executed through a runtime abstraction. Multiple agents then form an `Agents` team or a `Workflow`. Source: [agent/agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/agent.py), [runtime/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/runtime/README.md). ## The `Agent` Class and Consolidated Parameters The `Agent` class in [agent/agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/agent.py) is the central abstraction. Every capability is exposed as a consolidated parameter whose value follows the "Precedence Ladder" `Instance > Config > Array > Dict > String > Bool > Default`, so the same parameter can be enabled with a boolean, a preset string, or a fully-instantiated object. Source: [consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md). | Consolidated Param | Presets | |--------------------|---------| | `memory` | `file`, `sqlite`, `redis`, `postgres`, `mem0`, `mongodb` | | `output` | `minimal`, `normal`, `verbose`, `debug`, `silent` | | `execution` | `fast`, `balanced`, `thorough`, `unlimited` | | `planning` | `reasoning`, `read_only`, `auto` | | `reflection` | `minimal`, `standard`, `thorough` | | `guardrails` | `strict`, `permissive`, `safety` | | `web` | `duckduckgo`, `tavily`, `google`, `bing`, `serper` | | `context` | `sliding_window`, `summarize`, `truncate` | | `autonomy` | `suggest`, `auto_edit`, `full_auto` | | `caching` | `enabled`, `disabled`, `prompt` | ### Cross-Cutting Concerns - **Autonomy** ([agent/autonomy.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/autonomy.py)) controls how freely an agent acts: `suggest` only proposes, `auto_edit` mutates working state, and `full_auto` permits unrestricted execution. - **Handoff** ([agent/handoff.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/handoff.py)) routes a conversation from one agent to another (for example, escalating from a triage agent to a specialist), preserving the shared transcript. - **Context** ([agent/context_agent.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/context_agent.py)) manages the prompt window with `sliding_window`, `summarize`, or `truncate` strategies so long-running sessions do not exceed model limits. ### Tools The [tools README](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) documents both function-based and class-based tools, including DuckDuckGo, Spider (web scraping), Newspaper (article extraction), and a Stock Market tool that maintains its own connection state. Community issue #6 has asked for broader parity with LangChain and CrewAI tool ecosystems; the SDK already supports custom tool authoring through function decorators and class-based wrappers, and v4.6.71 continues to expand the available integrations. ## Memory Subsystem Memory is implemented as a mixin ([agent/memory_mixin.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agent/memory_mixin.py)) so it can attach to any `Agent`. The [stateful examples](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/stateful/README.md) demonstrate three production backends in practice: - **RAG provider** — ChromaDB with embeddings for similarity search. - **Mem0 provider** — graph-augmented memory for entity relationships. - **Local provider** — SQLite for simple, single-process deployments. The same guide recommends quality scoring, descriptive session IDs for debugging, and per-session versus per-user persistence strategies. Memory is split into short-term (working context) and long-term (durable recall), with thresholds controlling what gets promoted. Source: [stateful/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/stateful/README.md). ## Multi-Agent Teams (`Agents`) The plural `Agents` class in [agents/agents.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/agents/agents.py) (also called `AgentTeam`) wraps a collection of `Agent` instances and a list of `Task` objects. Each `Task` declares a `description`, an `expected_output`, and the `agent` responsible for it; the team executes tasks in order and can share a knowledge base or memory store. The TypeScript port ([src/praisonai-ts/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/README.md)) and Rust crate ([src/praisonai-rust/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-rust/README.md)) expose the same `Agent`, `Task`, and `AgentTeam` constructs for cross-language parity, including a `#[tool]` proc-macro in Rust that mirrors Python's `@tool` decorator. ## Workflows Workflows are step-based pipelines that can be declared in Python or YAML. The [save_output examples](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/save_output/README.md) document four supported save mechanisms: 1. The `write_file` tool — the agent decides when and what to persist. 2. `Task.output_file` — automatic per-task persistence. 3. `Workflow output_file` — variable substitution per step. 4. Manual persistence — full caller control over the saving process. The [consolidated_params README](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) also lists `basic_workflow.py`, `basic_workflow_agentlike.py`, `basic_step_override.py`, and `advanced_workflow_full_features.py` to demonstrate step-level parameter overrides and the full consolidated feature set inside a workflow. ## Runtime Abstraction The runtime module ([runtime/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/runtime/README.md)) defines `AgentRuntimeProtocol`, a `RuntimeRegistry` for plugin discovery, and a built-in `praisonai` runtime. Consumers call `resolve_runtime("praisonai")` to obtain a runtime, then `runtime.run_turn(prompt)` for an asynchronous response or `runtime.stream_turn(prompt)` for token deltas. Custom runtimes can register through Python entry points, making the agent loop swappable without modifying `Agent` source. The protocol is async-first and intentionally lightweight so that future runtimes (for example, third-party harnesses) can be slotted in beside the default one. ## See Also - Tools and MCP integration (`praisonai mcp`) - YAML workflows and the `praisonai` CLI - RAG and knowledge bases (`praisonai rag`) - TypeScript SDK (`src/praisonai-ts/`) and Rust SDK (`src/praisonai-rust/`) - Runtime plugin authoring guide (`praisonaiagents/runtime/`) --- ## Tools, MCP Protocol, and LLM Provider Integration ### Related Pages Related topics: [Core SDK: Agent, Agents, Memory, and Workflows](#page-2), [CLI, UI Surfaces, Workflows, and Deployment](#page-4)
Related Source Files The following source files were used to generate this page: - [src/praisonai-agents/praisonaiagents/tools/tools.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/tools.py) - [src/praisonai-agents/praisonaiagents/tools/decorator.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/decorator.py) - [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/registry.py) - [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) - [src/praisonai-agents/praisonaiagents/mcp/mcp.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/mcp/mcp.py) - [src/praisonai-agents/praisonaiagents/mcp/mcp_transport.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/mcp/mcp_transport.py) - [src/praisonai-agents/praisonaiagents/llm/llm.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/llm/llm.py) - [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md) - [examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp/README.md) - [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md) - [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md)
# Tools, MCP Protocol, and LLM Provider Integration ## Overview PraisonAI exposes a layered tool ecosystem that lets agents call external capabilities, interoperate through the Model Context Protocol (MCP), and switch between LLM providers without rewriting agent code. The three concerns — **Tools**, **MCP**, and **LLM Provider Integration** — are designed as orthogonal building blocks: a tool is a callable unit, MCP is the transport layer that advertises and routes those tools, and the LLM layer translates provider-specific APIs into a single interface used by every agent. Community demand for richer tool support (notably issue #6 requesting LangChain / CrewAI tool compatibility, with a suggestion to start from Google tools) has shaped the current design: PraisonAI provides first-party function-based and class-based tools, a decorator path, a TypeScript mirror, and an MCP server that exposes the same surface area to external clients such as Claude Desktop, Cursor, Windsurf, and VSCode. Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md), [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). ## Tool Authoring and Registration PraisonAI's tool surface is split between a Python core (`praisonaiagents/tools`) and a TypeScript mirror (`praisonai-ts`). The Python layer ships a base `Tools` class, a `@tool` decorator, and a registry used to enumerate available capabilities. Source: [src/praisonai-agents/praisonaiagents/tools/tools.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/tools.py), [src/praisonai-agents/praisonaiagents/tools/decorator.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/decorator.py), [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/registry.py). The README recommends two authoring styles: - **Function-based tools** for narrow, single-purpose capabilities (e.g. Spider for general scraping, Newspaper for article extraction). Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md). - **Class-based tools** for stateful or multi-operation toolsets (e.g. the stock market tool, which holds a cache of tickers and exposes several related methods). Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md). The TypeScript package mirrors this pattern with explicit class instantiation and an `execute` method, as shown in the ArXiv example: `const searchTool = new ArxivSearchTool(); await searchTool.execute('query', 5);`. Source: [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md). The parity between Python and TypeScript means the same tool naming convention can be used across both runtimes. When authoring, the README emphasises four best practices: clear documentation with usage examples, robust error handling that never crashes the agent, performance-conscious implementations with caching, and user-friendly naming. Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md). ## MCP Server and Protocol Features PraisonAI implements MCP Protocol Version **2025-11-25** and ships a configurable server that can run over STDIO or HTTP Stream transports. Source: [examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp/README.md), [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). The STDIO transport is intended for desktop clients such as Claude Desktop, while the HTTP Stream transport serves browser-based or networked clients. Source: [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). ```mermaid flowchart LR Agent[PraisonAI Agent] --> Registry[Tool Registry] Registry --> Local[Local Tools] Registry --> MCPServer[PraisonAI MCP Server] MCPServer --> Claude[Claude Desktop] MCPServer --> Cursor[Cursor] MCPServer --> VSCode[VSCode MCP] MCPServer -->|HTTP Stream| Remote[Networked Clients] MCPServer --> LLM[LLM Provider] LLM --> OpenAI[OpenAI] LLM --> Anthropic[Anthropic] LLM --> Ollama[Ollama] ``` Three protocol-level features are demonstrated in the MCP examples: - **Pagination** for `tools/list`, `resources/list`, and `prompts/list` using opaque base64url cursors, a server-determined page size (default 50, max 100), and cursor validation that surfaces JSON-RPC errors for invalid input. Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md). - **Tool annotations** per MCP 2025-11-25: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` are exposed on `MCPToolDefinition`. Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md). - **Tool search and introspection** via the `praisonai mcp tools` subcommand, supporting query, category, and read-only filters. Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md). The MCP server also exposes PraisonAI-specific resources (`praisonai://agents`, `praisonai://knowledge/sources`, `praisonai://config`, `praisonai://mcp/status`) and prompts (`deep-research`, `code-review`, `workflow-auto`, `guardrail-check`, `context-engineering`, `eval-criteria`, `agent-instructions`). Source: [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). Custom tools can be registered and exposed through the `custom_tools_server.py` example, and a client example demonstrates connecting back to the server programmatically. Source: [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). ## LLM Provider Integration LLM provider integration is centralised in `praisonaiagents/llm/llm.py`, which abstracts provider-specific APIs into a single `LLM` interface consumed by every agent. Source: [src/praisonai-agents/praisonaiagents/llm/llm.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/llm/llm.py). Agents are constructed without binding to a provider, then the LLM is resolved from environment variables or explicit configuration at start time. | Provider | Transport | Configuration Surface | |----------|-----------|----------------------| | OpenAI | HTTP | `OPENAI_API_KEY` | | Anthropic | HTTP | `ANTHROPIC_API_KEY` | | Ollama | Local HTTP | `OLLAMA_BASE_URL` (or local default) | | Google (Gemini) | HTTP | `GOOGLE_API_KEY` (suggested starting point in issue #6) | Source: [src/praisonai-agents/praisonaiagents/llm/llm.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/llm/llm.py). The consolidated-parameters example set illustrates how the LLM slot is filled alongside tool selection, memory, and guardrails without changing the agent definition. Source: [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md). ## Common Failure Modes 1. **Tool not registered** — the agent cannot see a capability that is not in the registry. Verify the tool is imported before agent construction. Source: [src/praisonai-agents/praisonaiagents/tools/registry.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/registry.py). 2. **MCP transport mismatch** — Claude Desktop expects STDIO, not HTTP. Confirm `praisonai mcp serve --transport stdio` is used for desktop clients. Source: [examples/mcp_server/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp_server/README.md). 3. **Invalid pagination cursor** — corrupted or truncated cursors trigger JSON-RPC errors; the client should drop the cursor and restart. Source: [src/praisonai/examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/examples/mcp/README.md). 4. **LLM credentials missing** — the LLM layer raises on construction if the required key is absent. Check the provider's environment variable before launching. Source: [src/praisonai-agents/praisonaiagents/llm/llm.py](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/llm/llm.py). 5. **TypeScript / Python drift** — tools defined in one runtime are not automatically mirrored; reuse the naming convention from the ArXiv example when porting. Source: [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md). ## See Also - [PraisonAI Agent Core Architecture](agent-core-architecture.md) - [Multi-Agent Workflows and YAML Configuration](multi-agent-workflows.md) - [MCP Server Deployment Guide](mcp-server-deployment.md) - [LLM Provider Configuration](llm-providers.md) --- ## CLI, UI Surfaces, Workflows, and Deployment ### Related Pages Related topics: [Core SDK: Agent, Agents, Memory, and Workflows](#page-2), [Tools, MCP Protocol, and LLM Provider Integration](#page-3)
Related Source Files The following source files were used to generate this page: - [examples/yaml/pr-reviewer/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/yaml/pr-reviewer/README.md) - [examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md) - [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md) - [examples/serve/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/serve/README.md) - [examples/cookbooks/Industry_Templates/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/cookbooks/Industry_Templates/README.md) - [examples/recipes/creator_suite/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/recipes/creator_suite/README.md) - [src/praisonai-rust/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-rust/README.md) - [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) - [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) - [examples/security/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/security/README.md) - [examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp/README.md) - [src/praisonai-agents/praisonaiagents/runtime/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/runtime/README.md) - [examples/rag/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/rag/README.md)
# CLI, UI Surfaces, Workflows, and Deployment PraisonAI provides a multi-layered user surface area for building, running, and deploying AI agent systems. The project supports command-line interfaces (Python, TypeScript, Rust), web-based UIs (Streamlit), recipe-based serving, GitHub Actions integration, and the Model Context Protocol (MCP) server. This page maps these surfaces and shows how workflows map to deployment targets. ## CLI Surfaces PraisonAI exposes a unified CLI entry point across language SDKs. The Python CLI provides subcommands for running agents, workflows, recipes, MCP tools, and security tasks. ### Python CLI Commands The `praisonai` Python CLI includes commands for the full lifecycle: | Command | Purpose | |---------|---------| | `praisonai recipe serve` | Serve recipes as HTTP API with auth, workers, rate limiting | | `praisonai recipe sbom` | Generate CycloneDX or SPDX Software Bill of Materials | | `praisonai recipe audit` | Audit dependencies for vulnerabilities | | `praisonai recipe validate` | Validate recipe including lockfile checks | | `praisonai endpoints health` | Health check for served endpoints | | `praisonai endpoints list` | List recipes (with `--api-key`) | | `praisonai endpoints invoke` | Invoke a recipe with JSON input | | `praisonai mcp list-tools` | List available MCP tools with pagination | | `praisonai mcp tools search` | Search MCP tools by query/category | | `praisonai mcp tools info` | Get detailed tool information | | `praisonai mcp tools schema` | Get tool JSON schema | Source: [examples/serve/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/serve/README.md), [examples/security/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/security/README.md), [examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp/README.md) ### TypeScript and Rust CLIs The TypeScript SDK ships CLI examples such as `npx ts-node examples/tools/arxiv-tools.ts` for running tools from the command line. Source: [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md) The Rust SDK provides a `praisonai-cli` binary alongside the `praisonai` core library and `praisonai-derive` proc macros for tool creation. Source: [src/praisonai-rust/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-rust/README.md) ## UI Surfaces ### Streamlit Web UIs PraisonAI supports Streamlit for building interactive agent UIs. The `agentic_rag_gpt5` example demonstrates a complete RAG application with: - **Sidebar**: API key management, URL-based knowledge base expansion, source list display - **Main interface**: Suggested prompts, query input area, markdown-rendered responses - **Dependencies**: `streamlit>=1.28.0`, `praisonaiagents>=0.1.0`, `openai>=1.0.0`, `python-dotenv>=1.0.0` Source: [examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md) ### TypeScript Tool Examples The TypeScript SDK includes runnable tool examples showing how to instantiate and execute tools (e.g., `ArxivSearchTool`, `ArxivDownloadTool`) programmatically. Source: [src/praisonai-ts/examples/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-ts/examples/tools/README.md) ## Workflows and Recipes PraisonAI supports multiple workflow patterns consolidated under the consolidated-params API. ### Workflow Patterns The `consolidated_params` examples demonstrate single-feature, multi-agent, and workflow patterns: - **Single-feature**: `basic_agent.py`, `basic_memory.py`, `basic_output.py`, `basic_guardrails.py`, `basic_reflection.py` - **Multi-agent**: `basic_agents.py` for multi-agent with memory and planning - **Workflow**: `basic_workflow.py`, `basic_workflow_agentlike.py`, `basic_step_override.py`, `advanced_workflow_full_features.py` Each consolidated param accepts multiple input forms: `bool` (enable defaults), `string` preset, `dict` config, or a `Config` instance. Source: [examples/consolidated_params/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/consolidated_params/README.md) ### Industry Templates (SRAO Framework) The Industry Templates cookbook provides pre-built multi-agent workflows with ~70% code reuse across sectors: | Industry | Key Agents | |----------|-----------| | Manufacturing | ParseOrder, CheckInventory, OptimizeSchedule, DefectDetect | | Energy | SCADAReader, VibrationAnalyzer, PowerForecaster, MaintenanceScheduler | | Healthcare | VitalSignsCapture, EMRRetrieval, TriageRecommend... | Source: [examples/cookbooks/Industry_Templates/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/cookbooks/Industry_Templates/README.md) ### Creator Suite The Creator Suite provides content-creation workflows: news crawling, script writing, hook generation, brief generation, video building, and publishing automation. Examples are runnable as standalone Python scripts. Source: [examples/recipes/creator_suite/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/recipes/creator_suite/README.md) ### RAG Workflows The RAG examples cover retrieval patterns: `basic_retrieval.py`, `auto_retrieval.py`, `chunking_strategies.py`, `hybrid_search.py`, `reranking.py`, `knowledge_graph.py`, `structured_output.py`, and `citations.py`. Source: [examples/rag/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/rag/README.md) ## Deployment ```mermaid flowchart LR A[Recipe/Agent YAML] --> B[praisonai recipe serve] B --> C[HTTP API with /openapi.json] B --> D[Health / Metrics / Admin] C --> E[Auth: API Key] B --> F[GitHub Actions PR Review] B --> G[MCP Server 2025-11-25] G --> H[tools/list paginated] G --> I[Tool Annotations] J[Streamlit UI] --> K[Agent + Vector DB] L[Rust CLI] --> M[Tokio async runtime] ``` ### Recipe Serving The `praisonai recipe serve` command exposes recipes as an HTTP service with: - **Auth modes**: `--auth api-key` for production bindings to `0.0.0.0` - **Operational flags**: `--workers 4`, `--rate_limit 100`, `--enable_metrics`, `--enable_admin` - **Endpoints**: `GET /openapi.json`, `GET /metrics`, `POST /admin/reload` (hot reload) - **Production guidance**: Use HTTPS via reverse proxy, store API keys in env vars Source: [examples/serve/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/serve/README.md) ### GitHub Actions PR Reviewer The `examples/yaml/pr-reviewer` provides a zero-code, multi-agent PR review system deploying Security, Performance, Maintainability, and Lead Reviewer agents. The workflow: 1. Triggers on `@praisonai` mention 2. Installs PraisonAI via `pip install praisonai` 3. Executes multi-agent YAML configuration 4. Posts structured feedback categorized as Critical/High/Medium/Low Required secrets: `PRAISONAI_APP_ID`, `PRAISONAI_APP_PRIVATE_KEY`, `OPENAI_API_KEY`. Source: [examples/yaml/pr-reviewer/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/yaml/pr-reviewer/README.md) ### MCP Server (Protocol 2025-11-25) The MCP Server v2 implements the 2025-11-25 specification with: - **Pagination**: Opaque base64url cursors, default page size 50, max 100 - **Tool annotations**: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` - **CLI commands**: `praisonai mcp list-tools`, `praisonai mcp tools search`, `praisonai mcp tools info` - **Python API**: `MCPToolRegistry().list_paginated()`, `MCPToolRegistry().search()` Source: [examples/mcp/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/mcp/README.md) ### Runtime System The runtime module provides a pluggable execution layer via `AgentRuntimeProtocol` and `RuntimeRegistry`. The built-in `praisonai` runtime wraps existing agent logic with async-first design. Custom runtimes register via `register_runtime()`. Source: [src/praisonai-agents/praisonaiagents/runtime/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/runtime/README.md) ### Security Deployment Security features are configurable in `TEMPLATE.yaml` under `data_policy.pii` with modes `allow`, `deny`, or `redact` and configurable fields (`email`, `phone`, `ssn`, `credit_card`). Source: [examples/security/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/examples/security/README.md) ## Community Context The top community issue (#6) requests support for LangChain and CrewAI tools. PraisonAI's tool system is designed to be extensible: developers can build plugin packages using the `@tool` decorator or `BaseTool` class, and tools can be installed as separate pip packages. The plugin system in `praisonaiagents/tools` directly addresses this need by allowing external developers to distribute tool packages. Source: [src/praisonai-agents/praisonaiagents/tools/README.md](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/tools/README.md) ## See Also - PraisonAI Tools Guide - RAG Examples - Recipe Serving Advanced Features - MCP Server Protocol Reference - Runtime System Documentation --- --- ## Pitfall Log Project: MervinPraison/PraisonAI Summary: Found 13 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1590 ## 2. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1941 ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1936 ## 4. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2125 ## 5. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/1654 ## 6. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/MervinPraison/PraisonAI ## 7. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI ## 8. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/MervinPraison/PraisonAI ## 9. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/MervinPraison/PraisonAI ## 10. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2153 ## 11. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/MervinPraison/PraisonAI/issues/2148 ## 12. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI ## 13. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/MervinPraison/PraisonAI