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:

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

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

Correct (Lazy)

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

import chromadb  # ❌ Adds 500ms+ to import time

---

Simple API Philosophy

Fewer parameters, sensible defaults, explicit overrides when needed.

Basic

from praisonaiagents import Agent

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

With Tools

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

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
)

---

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

---

Quick Links

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