Skip to main content
PraisonAI Architecture

​
Philosophy

PraisonAI is built on a simple philosophy:

Simpler

Fewer concepts, cleaner API than competitors

Faster

Lazy loading, minimal overhead, performance-first

Extensible

Protocol-driven, plugin-ready architecture

​
Agent-Centric Design

Every design decision centers on:
The core execution unit. Autonomous entities that can think, act, and learn.
Extend agent capabilities. Functions, APIs, and integrations agents can use.
Short-term and long-term persistence. Context that persists across interactions.
Multi-agent coordination patterns. Sequential, parallel, and routing logic.
State management and checkpointing. Resume from any point.

​
Protocol-Driven Core

┌─────────────────────────────────────────┐
│           praisonai (Wrapper)           │
│  CLI • Integrations • Heavy Impls       │
├─────────────────────────────────────────┤
│         praisonaiagents (Core)          │
│  Protocols • Hooks • Base Classes       │
├─────────────────────────────────────────┤
│        praisonai-tools (External)       │
│  Optional • Plugins • Community         │
└─────────────────────────────────────────┘
The core SDK must remain lightweight. Heavy implementations go in the wrapper.

​
Naming Conventions

1

Registration

Use add_X() for user-facing, register_X() for framework
add_hook("before_tool", handler)    # User-facing
register_tool(my_tool)              # Framework
2

Retrieval

Use get_X() for single, search_X() for query, list_X() for all
tool = get_tool("search")           # By ID
results = search_memory("query")    # By query
tools = list_tools()                # All
3

Configuration

Use XConfig suffix for configuration dataclasses
MemoryConfig, HooksConfig, KnowledgeConfig
4

Protocols

Use XProtocol suffix for abstract interfaces
MemoryProtocol, AgentProtocol, ToolProtocol

​
Performance Rules

Lazy Imports

Heavy dependencies imported inside functions, not at module level

Optional Dependencies

ChromaDB, LiteLLM, FastAPI etc. are optional extras

No Hot-Path Impact

No heavy work in frequently-called code paths

< 200ms Import

Package import time target under 200 milliseconds
def use_chromadb():
    try:
        import chromadb  # Imported when needed
    except ImportError:
        raise ImportError("pip install praisonaiagents[memory]")

​
Simple API Philosophy

Fewer parameters, sensible defaults, explicit overrides when needed.
from praisonaiagents import Agent

agent = Agent(name="assistant")
response = agent.start("Hello!")

​
Safety by Default

Multi-Agent Safe

No shared mutable state between agents

Async Safe

Full async/await support throughout

Guardrails

Built-in safety checks and policies

HITL Ready

Human-in-the-loop approval workflows

​
Implementation Checklist

Use this checklist for every new feature:
Protocol-first: Add protocol to core if needed
No new deps: Use optional dependencies only
Lazy imports: Heavy deps imported inside functions
Naming: Follow conventions (add_, get_, XConfig)
Tests: TDD - write failing tests first
CLI: Add corresponding CLI command
Docs: Update documentation
Examples: Add to examples directory
Multi-agent safe: No shared mutable state
Async-safe: Support async/await

Getting Started

Build your first agent in 5 minutes

Tools Guide

Create and use custom tools

Memory Guide

Add persistence to your agents

Workflows

Multi-agent coordination patterns