> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Principles
> Engineering principles and design philosophy behind PraisonAI
## Philosophy
PraisonAI is built on a simple philosophy:
Fewer concepts, cleaner API than competitors
Lazy loading, minimal overhead, performance-first
Protocol-driven, plugin-ready architecture
***
## Agent-Centric Design
Every design decision centers on:
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
A[Agent]:::agent --> B[Tools]:::tool
A --> C[Memory]:::tool
A --> D[Workflows]:::agent
D --> E[Multi-Agent]:::agent
classDef agent fill:#8B0000,color:#fff
classDef tool fill:#189AB4,color:#fff
```
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 │
└─────────────────────────────────────────┘
```
| 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
Use `add_X()` for user-facing, `register_X()` for framework
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
add_hook("before_tool", handler) # User-facing
register_tool(my_tool) # Framework
```
Use `get_X()` for single, `search_X()` for query, `list_X()` for all
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
tool = get_tool("search") # By ID
results = search_memory("query") # By query
tools = list_tools() # All
```
Use `XConfig` suffix for configuration dataclasses
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
MemoryConfig, HooksConfig, KnowledgeConfig
```
Use `XProtocol` suffix for abstract interfaces
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
MemoryProtocol, AgentProtocol, ToolProtocol
```
***
## Performance Rules
Heavy dependencies imported inside functions, not at module level
ChromaDB, LiteLLM, FastAPI etc. are optional extras
No heavy work in frequently-called code paths
Package import time target under 200 milliseconds
```python Correct (Lazy) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def use_chromadb():
try:
import chromadb # Imported when needed
except ImportError:
raise ImportError("pip install praisonaiagents[memory]")
```
```python Wrong (Module Level) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import chromadb # ❌ Adds 500ms+ to import time
```
***
## Simple API Philosophy
Fewer parameters, sensible defaults, explicit overrides when needed.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(name="assistant")
response = agent.start("Hello!")
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, tool
@tool
def search(query: str) -> list:
"""Search the web."""
return [{"result": query}]
agent = Agent(name="researcher", tools=[search])
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
No shared mutable state between agents
Full async/await support throughout
Built-in safety checks and policies
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
Build your first agent in 5 minutes
Create and use custom tools
Add persistence to your agents
Multi-agent coordination patterns