Documentation Style Guide

How to write PraisonAI documentation pages — structure, components, diagrams, and writing rules

Every PraisonAI documentation page follows the same structure, component set, and visual language — this guide is both the reference and the example.

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarise topics clearly.",
)

agent.start("What is agentic AI?")

The user copies the opening example, runs the agent, then follows the page structure below.

---

Documentation Creation Process

Read the SDK source before writing anything — documentation must reflect SDK ground truth, not assumptions.

1. Read SDK source

   Open and read the actual SDK implementation file in praisonaiagents/ before writing a single word of documentation.

   # Example: reading agent source before documenting
   # praisonaiagents/agent/agent.py  ← read this first
   from praisonaiagents import Agent
   
   agent = Agent(
       name="Research Agent",
       instructions="Research and summarize topics"
   )
   agent.start("What is agentic AI?")
   
2. Extract all parameters

   Pull every parameter, type, default value, and description from the SDK source or config class.

   # praisonaiagents/config/feature_configs.py
   @dataclass
   class CachingConfig:
       enabled: bool = True          # Extract: enabled, bool, True
       ttl: int = 3600               # Extract: ttl, int, 3600
       backend: str = "memory"       # Extract: backend, str, "memory"
   
3. Check existing docs

   Search docs/ for related pages before creating a new one — avoid duplication, ensure consistency.

4. Write the page

   Follow the Page Structure Template and every rule in this guide.

SDK-First Cycle

Never batch-update multiple pages without reading source for each.

Step	Action
READ	Open the actual SDK source file
UNDERSTAND	Comprehend the implementation, APIs, and behaviour
DOCUMENT	Write documentation based on SDK truth
REPEAT	Move to the next feature and restart

File Locations

Content Type	SDK Location	Docs Location
Feature configs	praisonaiagents/config/feature_configs.py	docs/concepts/*.mdx
Agent class	praisonaiagents/agent/agent.py	docs/concepts/agents.mdx
MCP integration	praisonaiagents/mcp/mcp.py	docs/concepts/mcp.mdx
Skills	praisonaiagents/skills/	docs/concepts/skills.mdx
Memory	praisonaiagents/memory/	docs/concepts/memory.mdx
Knowledge	praisonaiagents/knowledge/	docs/concepts/knowledge.mdx

Multi-SDK Reference

SDK	Source Code Path	Documentation Path	Parity Tracker
Python	Repo root praisonaiagents/ (synced copy; upstream: praisonai-package/src/praisonai-agents/)	docs/concepts/, docs/features/	docs/features/DOCS_PARITY.md
TypeScript/JS	praisonai-package/src/praisonai-ts/src/	docs/js/	docs/js/DOCS_PARITY.md
Rust	praisonai-package/src/praisonai-rust/src/	docs/rust/	docs/rust/DOCS_PARITY.md

TypeScript SDK Structure

praisonai-ts/src/
├── agents/           # Agent implementations
├── tools/            # Tool definitions
├── memory/           # Memory implementations
├── mcp/              # MCP protocol support
├── observability/    # Tracing integrations
└── index.ts          # Main exports

Rust SDK Structure

praisonai-rust/src/
├── agent/            # Agent and config
├── llm/              # LLM provider
├── tools/            # Tool system
├── memory/           # Memory stores
├── mcp/              # MCP client
└── lib.rs            # Main exports

---

Folder Placement Rules

Where a file lives determines who can change it — AI agents have write access to most folders but never docs/concepts/.

Critical folder rules — violations cause PRs to be rejected:

• docs/concepts/ is HUMAN ONLY — requires explicit human approval. Never create or modify files here.
• docs/js/ and docs/rust/ are auto-generated by the parity system — never edit manually.
• If an issue mentions “concepts”, still place the file in docs/features/.

Folder	Who Can Write	Purpose
docs/concepts/	HUMAN ONLY	Core architecture concepts
docs/features/	AI agents + humans	Feature documentation, guides, integrations
docs/tools/	AI agents + humans	Tool-specific documentation
docs/guides/	AI agents + humans	How-to guides and tutorials
docs/js/, docs/rust/	Auto-generated ONLY	Managed by parity system

---

AI Agent Behavioural Rules

Mandatory for all AI agents working in this repository:

1. ALWAYS read AGENTS.md before starting work
2. ALWAYS read the SDK source code before documenting a feature
3. NEVER guess API signatures — read the actual code
4. NEVER create placeholder content or stub pages
5. NEVER modify docs.json “Concepts” group entries
6. ALWAYS create a feature branch (never commit to main)
7. ALWAYS create a PR with gh pr create
8. ALWAYS verify docs.json is valid JSON after modifications
9. ALWAYS use Mintlify components (Steps, AccordionGroup, CardGroup)
10. ALWAYS include a hero Mermaid diagram with the standard colour scheme

---

Page Structure Template

Every documentation page follows this exact skeleton.

---
title: "Feature Name"
sidebarTitle: "Feature Name"
description: "One-line description of what this feature does"
icon: "icon-name"
---

{/* One sentence explaining the feature — what it does, not how */}

{/* Hero Mermaid diagram showing the concept visually */}

## Quick Start

<Steps>
<Step title="Simple Usage">
{/* Minimal code example — enable with True */}
</Step>

<Step title="With Configuration">
{/* Code example with config class */}
</Step>
</Steps>

---

## How It Works

{/* Sequence diagram or flow diagram */}

{/* Brief explanation table */}

---

## Configuration Options

{/* Link to auto-generated SDK reference — DO NOT duplicate SDK parameters here */}

<Card title="[Feature] API Reference" icon="code" href="/docs/sdk/reference/typescript/classes/[FeatureConfig]">
  TypeScript configuration options
</Card>

---

## Common Patterns

{/* 2–3 practical usage patterns */}

---

## Best Practices

<AccordionGroup>
{/* 3–4 best practices as accordions */}
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
{/* 2 related concept pages */}
</CardGroup>

---

Mermaid Diagram Standards

Every page starts with a hero Mermaid diagram using the standard colour scheme.

Colour Scheme

Colour	Hex	Use
Dark Red	#8B0000	Agents, inputs, outputs, tasks
Teal	#189AB4	Tools, processes, middleware
Green	#10B981	Success, results, completion
Amber	#F59E0B	Warnings, planners, intermediate steps
Indigo	#6366F1	Configuration, settings, options
White	#fff	Text — always white on coloured backgrounds
Grey	#7C90A0	Stroke/border colour

Diagram Types by Use Case

Use Case	Diagram Type
Feature overview	graph LR — flow left-to-right
Process flow	graph TB — steps top-to-bottom
Interactions	sequenceDiagram — agent-user-system interactions
Options/modes	graph TB with subgraphs

Hero Diagram (rendered)

Hero Diagram (source)

graph LR
    subgraph "Feature Name"
        A[📋 Input] --> B[🧠 Process]
        B --> C[✅ Output]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class B process
    class C output

Sequence Diagram (rendered)

Sequence Diagram (source)

sequenceDiagram
    participant User
    participant Agent
    participant Feature

    User->>Agent: Request
    Agent->>Feature: Process
    Feature-->>Agent: Result
    Agent-->>User: Response

---

Mintlify Components Usage

Every page must use <Steps>, <AccordionGroup>, and <CardGroup cols={2}> — these are not optional.

Required Components

Component	Purpose	Required In
<Steps>	Sequential flows	Quick Start section
<AccordionGroup>	Grouped content	Best Practices section
<CardGroup cols={2}>	Related links	Related section
<Tabs>	Multi-language examples	Code comparison
<Note> / <Warning> / <Tip>	Callouts	Context-dependent

Component Syntax

Steps:

<Steps>
<Step title="First Step">
Content here.
</Step>
<Step title="Second Step">
Content here.
</Step>
</Steps>

AccordionGroup:

<AccordionGroup>
<Accordion title="Best Practice Title">
Content here.
</Accordion>
<Accordion title="Another Practice">
Content here.
</Accordion>
</AccordionGroup>

CardGroup:

<CardGroup cols={2}>
<Card title="Card Title" icon="icon-name" href="/docs/path">
Card description.
</Card>
<Card title="Card Title" icon="icon-name" href="/docs/path">
Card description.
</Card>
</CardGroup>

Tabs:

<Tabs>
<Tab title="Python">
```python
code here
```
</Tab>
<Tab title="TypeScript">
```typescript
code here
```
</Tab>
</Tabs>

---

Code Example Standards

Every example must run without modification — copy-paste success is the bar.

Code Quality Rules

1. Run without modification (copy-paste success)
2. Include ALL necessary imports
3. Use realistic but simple data
4. Be the shortest way to accomplish the task
5. Show the feature being documented, not unrelated features

Import Patterns

Use these exact imports — no complex sub-module paths:

# Single agent
from praisonaiagents import Agent

# Agent with planning
from praisonaiagents import Agent, PlanningConfig

# Multi-agent
from praisonaiagents import Agent, Task, PraisonAIAgents

# MCP
from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

# Workflows — use simple import, not sub-module
from praisonaiagents import when, parallel, loop

Simple Quick Start Example

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarize topics",
    feature=True
)

agent.start("What is agentic AI?")

Config Class Example

from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Research Agent",
    instructions="Research and summarize topics",
    planning=PlanningConfig(
        model="gpt-4o",
        verbose=True
    )
)

agent.start("Plan a research strategy for AI safety")

Configuration Table Format

Document every SDK option in this format:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option_name` | `type` | `default` | What it does |

---

Writing Style

Concise, active voice, direct — after reading a page, users should think “is it really this easy?”

Do / Don’t

Principle	Do	Don’t
Concise	”Planning breaks tasks into steps"	"Planning is a feature that allows agents to break down complex tasks into smaller, more manageable steps”
Active voice	”Enable planning with planning=True"	"Planning can be enabled by setting the planning parameter to True”
Direct	”Use gpt-4o for planning"	"It is recommended that you consider using gpt-4o for planning”
Specific	”Set timeout=60 for slow servers"	"Increase the timeout if needed”

Section Introductions

Each section starts with exactly one sentence — no multi-sentence preamble.

✅ Good: "Planning enables agents to think before acting."
❌ Bad:  "Planning is a powerful feature that enables agents to think before acting.
          It allows them to break down complex tasks into smaller steps."

Forbidden phrases — never use these:

• “In this section, we will…”
• “As you can see…”
• “It’s important to note that…”
• “Please note that…”
• “Let’s take a look at…”
• “The following example shows…”

---

Configuration Documentation Pattern

Features support multiple configuration levels — document each level the feature actually supports.

Precedence ladder: Instance > Config > Array > Dict > String > Bool > Default

# Level 1: Bool (simplest)
agent = Agent(feature=True)

# Level 2: String
agent = Agent(feature="option_name")

# Level 3: Dict
agent = Agent(feature={"option": "value", "enabled": True})

# Level 4: Array
agent = Agent(feature=["option1", "option2"])

# Level 5: Config class
agent = Agent(feature=FeatureConfig(option="value"))

# Level 6: Instance (full control)
feature_instance = Feature(option="value")
agent = Agent(feature=feature_instance)

SDK Config Extraction

When reading feature_configs.py, extract every field:

@dataclass
class FeatureConfig:
    option1: str = "default"       # Extract: option1, str, "default"
    option2: bool = False          # Extract: option2, bool, False
    option3: Optional[int] = None  # Extract: option3, int, None

Convert to documentation table:

Option	Type	Default	Description
option1	str	"default"	Description from docstring
option2	bool	False	Description from docstring
option3	int	None	Description from docstring

---

Mintlify Frontmatter

All four fields are required on every page.

---
title: "Feature Name"           # Display title
sidebarTitle: "Feature Name"    # Sidebar title (usually same as title)
description: "One-line desc"    # Meta description
icon: "icon-name"               # Lucide icon name
---

Icon Selection

Feature Type	Icon
Planning	list-check
Reflection	rotate
Skills	puzzle-piece
Hooks	webhook
Autonomy	robot
Output	display
Execution	play
Caching	database
Templates	file-code
Web	globe
MCP	plug
Memory	brain
Knowledge	book
Tools	wrench
Agents	user

---

Quality Checklist

Run through this before submitting any documentation page.

Structure

• Frontmatter complete (title, sidebarTitle, description, icon)
• Hero Mermaid diagram present
• Quick Start uses <Steps> component
• Configuration Options table complete
• Best Practices uses <AccordionGroup>
• Related section uses <CardGroup cols={2}>

SDK Accuracy

• All config options documented
• Types match SDK exactly
• Defaults match SDK exactly
• Import paths are correct
• No undocumented features

Code Quality

• All examples run without modification
• All imports included
• Examples are minimal (shortest way to accomplish the task)
• No placeholder values like "your-key-here"

Diagrams

• Colour scheme matches standard (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1)
• White text on coloured backgrounds (color:#fff)
• classDef declarations present
• Diagram explains the concept visually

Writing

• One-sentence section intros
• No forbidden phrases
• Active voice throughout
• Concise explanations

---

Complete Page Example

A full Caching page demonstrating every rule in this guide.

---
title: "Caching"
sidebarTitle: "Caching"
description: "Cache LLM responses to reduce costs and latency"
icon: "database"
---

Caching stores LLM responses to avoid redundant API calls, reducing costs and improving response times.

````mermaid
graph LR
    subgraph "Caching Flow"
        Request[📝 Request] --> Check{🔍 Cache?}
        Check -->|Hit| Return[⚡ Return]
        Check -->|Miss| LLM[🤖 LLM]
        LLM --> Store[💾 Store]
        Store --> Return
    end

    classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef cache fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Request request
    class Check,Store cache
    class LLM,Return result
````

## Quick Start

<Steps>
<Step title="Enable Caching">
````python
from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Answer questions concisely",
    cache=True
)

agent.start("What is machine learning?")
````
</Step>

<Step title="Configure Cache">
````python
from praisonaiagents import Agent, CachingConfig

agent = Agent(
    name="Research Agent",
    instructions="Answer questions concisely",
    cache=CachingConfig(
        ttl=3600,
        backend="memory"
    )
)

agent.start("What is machine learning?")
````
</Step>
</Steps>

---

## How It Works

````mermaid
sequenceDiagram
    participant User
    participant Agent
    participant Cache
    participant LLM

    User->>Agent: Request
    Agent->>Cache: Check cache
    Cache-->>Agent: Miss
    Agent->>LLM: Send prompt
    LLM-->>Agent: Response
    Agent->>Cache: Store response
    Agent-->>User: Response

    User->>Agent: Same request
    Agent->>Cache: Check cache
    Cache-->>Agent: Hit
    Agent-->>User: Cached response
````

---

## Best Practices

<AccordionGroup>
<Accordion title="Set TTL based on data freshness">
Use short TTL (300s) for frequently changing data, longer TTL (3600s) for stable content.
</Accordion>
<Accordion title="Use disk backend for persistence">
Memory cache resets on restart — use `backend="disk"` to persist across sessions.
</Accordion>
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
<Card title="Planning" icon="list-check" href="/docs/features/planning-mode">
  Plan before executing to improve accuracy.
</Card>
<Card title="Memory" icon="brain" href="/docs/features/advanced-memory">
  Store and retrieve long-term information.
</Card>
</CardGroup>

---

Related

Contributing Guide

How to fork, clone, and submit pull requests to PraisonAI.

AGENTS.md on GitHub

The source-of-truth instructions file this guide mirrors.