Core Principles

Engineering principles and design philosophy behind PraisonAI

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:

Diagram

Agents

The core execution unit. Autonomous entities that can think, act, and learn.

Tools

Extend agent capabilities. Functions, APIs, and integrations agents can use.

Memory

Short-term and long-term persistence. Context that persists across interactions.

Workflows

Multi-agent coordination patterns. Sequential, parallel, and routing logic.

Sessions

State management and checkpointing. Resume from any point.

Protocol-Driven Core

Architecture

┌─────────────────────────────────────────┐
│           praisonai (Wrapper)           │
│  CLI • Integrations • Heavy Impls       │
├─────────────────────────────────────────┤
│         praisonaiagents (Core)          │
│  Protocols • Hooks • Base Classes       │
├─────────────────────────────────────────┤
│        praisonai-tools (External)       │
│  Optional • Plugins • Community         │
└─────────────────────────────────────────┘

What Goes Where

Core SDK	Wrapper	External
Protocols	CLI commands	Community tools
Hooks	Heavy integrations	Optional plugins
Base classes	Database adapters	Marketplace
Decorators	UI components	Third-party

Naming Conventions

Registration

Use add_X() for user-facing, register_X() for framework

python

add_hook("before_tool", handler)    # User-facing
register_tool(my_tool)              # Framework

Retrieval

Use get_X() for single, search_X() for query, list_X() for all

python

tool = get_tool("search")           # By ID
results = search_memory("query")    # By query
tools = list_tools()                # All

Configuration
Use XConfig suffix for configuration dataclasses
python
```
MemoryConfig, HooksConfig, KnowledgeConfig
```
Protocols
Use XProtocol suffix for abstract interfaces
python
```
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

Package import time target under 200 milliseconds

Correct (Lazy)

def use_chromadb():
    try:
        import chromadb  # Imported when needed
    except ImportError:
        raise ImportError("pip install praisonaiagents[memory]")

Wrong (Module Level)

import chromadb  # ❌ Adds 500ms+ to import time

Simple API Philosophy

Basic

python

from praisonaiagents import Agent

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

With Tools

python

from praisonaiagents import Agent, tool

@tool
def search(query: str) -> list:
    """Search the web."""
    return [{"result": query}]

agent = Agent(name="researcher", tools=[search])

Full Control

python

from praisonaiagents import Agent, MemoryConfig, HooksConfig

def validate(tool_call):
    """Validate tool calls before execution."""
    return True

def safety_check(output):
    """Check output for safety."""
    return True, output

agent = Agent(
    name="assistant",
    llm="gpt-4o-mini",
    memory=MemoryConfig(backend="file"),
    hooks=HooksConfig(on_tool_call=validate),
    guardrails=safety_check
)