<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/14-examples-and-tutorials -->

# Examples and Tutorials

- README.md
- docker/Dockerfile
- docker/Dockerfile.chat
- docker/Dockerfile.dev
- docker/Dockerfile.ui
- docker/README.md
- src/praisonai-agents/pyproject.toml
- src/praisonai-agents/uv.lock
- src/praisonai/README.md
- src/praisonai/praisonai.rb
- src/praisonai/praisonai/cli/main.py
- src/praisonai/praisonai/deploy.py
- src/praisonai/praisonai/version.py
- src/praisonai/pyproject.toml
- src/praisonai/uv.lock

This page provides practical examples and step-by-step tutorials for building AI agent systems with PraisonAI. It covers quick start patterns, Python SDK usage, JavaScript SDK, CLI commands, and deployment scenarios with working code examples that can be copied and executed immediately.

For comprehensive API documentation, see [Python API Reference](/MervinPraison/PraisonAI/12.1-python-api-reference). For framework integration details, see [CrewAI Integration](/MervinPraison/PraisonAI/13.1-crewai-integration) and [AutoGen Integration](/MervinPraison/PraisonAI/13.2-autogen-integration). For production deployment architecture, see [Cloud Deployment](/MervinPraison/PraisonAI/9.2-cloud-deployment).

## Example Organization

```

```

**Sources:** [README.md48-124](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L48-L124)

## Quick Start Examples

### Minimal Agent Setup

The fastest path to a working agent requires three steps: installation, API key configuration, and agent initialization.

```

```

#### Single Agent Example

```

```

This creates an `Agent` instance from [praisonaiagents.agent.agent.Agent](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.agent.agent.Agent) and calls the `start` method which handles the complete execution lifecycle: message formatting, LLM invocation via [praisonaiagents.llm.llm.LLM](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.llm.llm.LLM) and response processing.

**Environment Requirements:**

- OPENAI_API_KEY : Required for default model gpt-4o-mini
- OPENAI_BASE_URL : Optional, for custom endpoints (Ollama, Groq)

**Sources:** [README.md153-166](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L153-L166) [README.md523-533](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L523-L533)

#### Multi-Agent Example

```

```

The `Agents` class from [praisonaiagents.agents.agents.Agents](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.agents.agents.Agents) orchestrates multiple agents sequentially, passing output from each agent as context to the next. The execution flow is managed by [Agents.start50-100](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/Agents.start#L50-L100) which handles task distribution and result aggregation.

**Sources:** [README.md537-551](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L537-L551)

## Python SDK Examples

### Agent with Planning Mode

Planning mode enables agents to decompose complex tasks into steps before execution.

```

```

```

```

**Execution Flow:**

1. PlanningAgent from praisonaiagents.agents.agents.PlanningAgent analyzes the task
2. Generates multi-step plan with TodoList from praisonaiagents.tools.todo.TodoList
3. Executes each step via AgentTeam.run_sequential
4. Passes context between steps
5. Returns aggregated result

**Sources:** [README.md554-577](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L554-L577)

### Deep Research Agent

Automated research with real-time streaming using OpenAI or Gemini Deep Research APIs.

```

```

The `DeepResearchAgent` from [praisonaiagents.agents.agents.DeepResearchAgent](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.agents.agents.DeepResearchAgent) provides:

- Multi-provider support (OpenAI, Gemini, LiteLLM)
- Real-time streaming via Server-Sent Events
- Structured citations with URLs
- Built-in tools: web search, code interpreter, file search

**Gemini Deep Research:**

```

```

**Sources:** [README.md581-617](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L581-L617)

### Query Rewriter Agent

Transforms user queries to improve RAG retrieval quality using multiple strategies.

```

```

```

```

Available strategies from [praisonaiagents.agents.agents.RewriteStrategy](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.agents.agents.RewriteStrategy):

- BASIC : Expand abbreviations, fix typos
- HYDE : Generate hypothetical document for semantic matching
- STEP_BACK : Generate higher-level concept questions
- SUB_QUERIES : Decompose multi-part questions
- MULTI_QUERY : Generate paraphrased versions
- CONTEXTUAL : Resolve references using chat history
- AUTO : Automatically detect best strategy

**Sources:** [README.md619-652](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L619-L652)

### Agent Memory

Enable persistent memory without additional dependencies.

```

```

**Memory Types:**

**Advanced Memory Operations:**

```

```

**Sources:** [README.md654-709](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L654-L709)

### Workflow Patterns

Create complex multi-agent workflows with control structures.

```

```

#### Routing Pattern

```

```

The `route` function from [praisonaiagents.workflows.patterns.route](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.workflows.patterns.route) creates a `RouteWorkflowStep` that conditionally executes branches based on the classifier's output.

#### Parallel Pattern

```

```

The `parallel` function from [praisonaiagents.workflows.patterns.parallel](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.workflows.patterns.parallel) executes multiple agents concurrently using `asyncio.gather` and combines results.

#### Loop Pattern

```

```

The `loop` function from [praisonaiagents.workflows.patterns.loop](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.workflows.patterns.loop) iterates the agent over each item in the specified variable.

#### Repeat Pattern (Evaluator-Optimizer)

```

```

The `repeat` function from [praisonaiagents.workflows.patterns.repeat](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.workflows.patterns.repeat) implements an evaluator-optimizer loop, re-executing until a condition is met.

**Sources:** [README.md775-877](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L775-L877)

## JavaScript SDK Examples

### Installation and Basic Usage

```

```

```

```

### Multi-Agent System

```

```

The JavaScript SDK from `npm` package `praisonai` mirrors the Python API structure with `Agent` and `Agents` classes.

**Sources:** [README.md189-192](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L189-L192)

## CLI Examples

### Quick Reference Commands

```

```

**Sources:** [src/praisonai/praisonai/cli/main.py1-50](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L1-L50)

### Auto Mode

Automatically generate agent configurations from natural language descriptions.

```

```

The `auto` command invokes `AutoGenerator` from [praisonai.auto.AutoGenerator](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonai.auto.AutoGenerator) which uses an LLM to generate YAML configurations matching the description.

**Sources:** [README.md153-166](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L153-L166)

### Init Command

Bootstrap a new agent project with a template configuration.

```

```

The `init` command creates a starter `agents.yaml` file via [praisonai.cli.main.PraisonAI.main](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonai.cli.main.PraisonAI.main) with example agent definitions.

### Deep Research CLI

Terminal-based deep research with real-time streaming.

```

```

### Planning Mode CLI

Enable planning for any CLI execution.

```

```

### Memory CLI

Manage agent memory from the command line.

```

```

Memory commands interface with [praisonaiagents.memory.FileMemory](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.memory.FileMemory) for persistent storage.

### Session CLI

Save and resume conversation sessions.

```

```

Session management uses [praisonaiagents.memory.FileMemory.save_session](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.memory.FileMemory.save_session) and [praisonaiagents.memory.FileMemory.resume_session](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonaiagents.memory.FileMemory.resume_session) for persistence.

### MCP Config CLI

Manage Model Context Protocol configurations.

```

```

MCP configuration is stored in `~/.praison/mcp_config.json` and managed via [praisonai.cli.features.mcp](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/praisonai.cli.features.mcp)

**Sources:** [README.md82-88](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L82-L88)

## Deployment Examples

### Docker Deployment Architecture

```

```

**Sources:** [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47) [docker/Dockerfile.ui1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L33) [docker/Dockerfile.chat1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L33) [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47)

### Single Container Deployment

#### UI Service (Port 8082)

```

```

The UI Dockerfile [docker/Dockerfile.ui1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L33) installs `praisonai[ui]` which includes Chainlit dependencies and sets `CHAINLIT_CONFIG_DIR=/root/.praison` to avoid root directory clutter.

#### Chat Service (Port 8083)

```

```

The Chat Dockerfile [docker/Dockerfile.chat1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L33) installs `praisonai[chat]` with crawl4ai and Playwright dependencies.

#### API Service (Port 8080)

```

```

The API Dockerfile [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47) creates a minimal Flask/Gunicorn service with health check endpoint at `/health`.

**Sources:** [docker/README.md23-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L23-L33)

### Multi-Service Docker Compose

Create `docker-compose.yml`:

```

```

Run all services:

```

```

The shared volume `praison_data` ensures all services use the same configuration directory at `/root/.praison`.

**Sources:** [docker/README.md36-51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L36-L51)

### Cloud Deployment with CloudDeployer

The `CloudDeployer` class automates deployment to Google Cloud Run.

```

```

**Deployment Flow:**

```

```

**Generated Dockerfile:**

```

```

**Generated api.py:**

```

```

The `CloudDeployer` class [src/praisonai/praisonai/deploy.py6-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L6-L186) handles:

1. Loading environment variables from .env deploy.py 32-34
2. Creating Flask API wrapper deploy.py 64-91
3. Creating production Dockerfile deploy.py 36-63
4. Building and pushing Docker image deploy.py 98-181
5. Deploying to Cloud Run with environment variables deploy.py 146-149

**CLI Usage:**

```

```

**Sources:** [src/praisonai/praisonai/deploy.py1-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L1-L186) [docker/README.md224-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L224-L264)

### Development Container

For local development with full tooling:

```

```

The development Dockerfile [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47) includes:

- Core PraisonAI with all features: praisonai[ui,chat,realtime,code]
- Development tools: jupyter , jupyterlab , pytest , mkdocs
- System dependencies: gcc , git , vim , nano

**Sources:** [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47) [docker/README.md137-143](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L137-L143)

## Example Patterns Summary

**Sources:** [README.md48-124](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L48-L124) [docker/README.md1-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L1-L264)
