Release v2.3.59

Changed all https://docs.praison.ai/cli/* URLs to https://docs.praison.ai/docs/cli/*
Fixed 39 URLs total

.github/actions/claude-code-action/action.yml

@@ -86,13 +86,29 @@ runs:
     - name: Extract GitHub Context and Create Prompt
       shell: bash
       id: prepare_context
+      env:
+        # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+        EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
+        EVENT_ISSUE_TITLE: ${{ github.event.issue.title }}
+        EVENT_ISSUE_BODY: ${{ github.event.issue.body }}
+        EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+        EVENT_PR_TITLE: ${{ github.event.pull_request.title }}
+        EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+        EVENT_REVIEW_BODY: ${{ github.event.review.body }}
+        EVENT_ASSIGNEE_LOGIN: ${{ github.event.assignee.login }}
+        INPUT_TRIGGER_PHRASE: ${{ inputs.trigger_phrase }}
+        INPUT_ASSIGNEE_TRIGGER: ${{ inputs.assignee_trigger }}
+        INPUT_DIRECT_PROMPT: ${{ inputs.direct_prompt }}
+        EVENT_ACTION: ${{ github.event.action }}
+        EVENT_NAME: ${{ github.event_name }}
+        REPO_NAME: ${{ github.repository }}
       run: |
-        echo "🔍 Extracting GitHub context from event: ${{ github.event_name }}"
+        echo "🔍 Extracting GitHub context from event: $EVENT_NAME"
         
         # Function to check for trigger phrase
         check_trigger() {
           local text="$1"
-          local trigger="${{ inputs.trigger_phrase }}"
+          local trigger="$INPUT_TRIGGER_PHRASE"
           if [[ "$text" == *"$trigger"* ]]; then
             return 0
           fi
@@ -104,11 +120,11 @@ runs:
         USER_REQUEST=""
         CONTEXT_INFO=""
         
-        case "${{ github.event_name }}" in
+        case "$EVENT_NAME" in
           "issue_comment")
-            COMMENT_BODY="${{ github.event.comment.body }}"
-            ISSUE_TITLE="${{ github.event.issue.title }}"
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
             
             if check_trigger "$COMMENT_BODY"; then
               TRIGGER_FOUND="true"
@@ -118,9 +134,9 @@ runs:
             ;;
             
           "pull_request_review_comment")
-            COMMENT_BODY="${{ github.event.comment.body }}"
-            PR_TITLE="${{ github.event.pull_request.title }}"
-            PR_NUMBER="${{ github.event.pull_request.number }}"
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
             
             if check_trigger "$COMMENT_BODY"; then
               TRIGGER_FOUND="true"
@@ -130,9 +146,9 @@ runs:
             ;;
             
           "pull_request_review")
-            REVIEW_BODY="${{ github.event.review.body }}"
-            PR_TITLE="${{ github.event.pull_request.title }}"
-            PR_NUMBER="${{ github.event.pull_request.number }}"
+            REVIEW_BODY="$EVENT_REVIEW_BODY"
+            PR_TITLE="$EVENT_PR_TITLE"
+            PR_NUMBER="$EVENT_PR_NUMBER"
             
             if check_trigger "$REVIEW_BODY"; then
               TRIGGER_FOUND="true"
@@ -142,17 +158,17 @@ runs:
             ;;
             
           "issues")
-            ISSUE_BODY="${{ github.event.issue.body }}"
-            ISSUE_TITLE="${{ github.event.issue.title }}"
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+            ISSUE_BODY="$EVENT_ISSUE_BODY"
+            ISSUE_TITLE="$EVENT_ISSUE_TITLE"
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
             
             if check_trigger "$ISSUE_TITLE" || check_trigger "$ISSUE_BODY"; then
               TRIGGER_FOUND="true"
               USER_REQUEST="$ISSUE_BODY"
               CONTEXT_INFO="Issue #$ISSUE_NUMBER: $ISSUE_TITLE"
-            elif [[ "${{ github.event.action }}" == "assigned" && -n "${{ inputs.assignee_trigger }}" ]]; then
-              ASSIGNEE="${{ github.event.assignee.login }}"
-              if [[ "$ASSIGNEE" == "${{ inputs.assignee_trigger }}" ]]; then
+            elif [[ "$EVENT_ACTION" == "assigned" && -n "$INPUT_ASSIGNEE_TRIGGER" ]]; then
+              ASSIGNEE="$EVENT_ASSIGNEE_LOGIN"
+              if [[ "$ASSIGNEE" == "$INPUT_ASSIGNEE_TRIGGER" ]]; then
                 TRIGGER_FOUND="true"
                 USER_REQUEST="$ISSUE_BODY"
                 CONTEXT_INFO="Issue #$ISSUE_NUMBER assigned to $ASSIGNEE: $ISSUE_TITLE"
@@ -162,9 +178,9 @@ runs:
         esac
         
         # Check for direct prompt override
-        if [[ -n "${{ inputs.direct_prompt }}" ]]; then
+        if [[ -n "$INPUT_DIRECT_PROMPT" ]]; then
           TRIGGER_FOUND="true"
-          USER_REQUEST="${{ inputs.direct_prompt }}"
+          USER_REQUEST="$INPUT_DIRECT_PROMPT"
           CONTEXT_INFO="Automated GitHub workflow"
         fi
         
@@ -181,9 +197,9 @@ runs:
         cat > /tmp/claude-action/github-context-prompt.txt << EOF
         You are Claude Code, an AI assistant helping with GitHub workflows and code.
         
-        Repository: ${{ github.repository }}
+        Repository: $REPO_NAME
         Context: $CONTEXT_INFO
-        Event: ${{ github.event_name }}
+        Event: $EVENT_NAME
         
         User Request:
         $USER_REQUEST

.github/workflows/docker-publish.yml

@@ -1,45 +1,54 @@
-name: Daily Publish Docker
+name: Publish Docker
 
 on:
-  push:
-    branches:
-      - main
-  schedule:
-    - cron: '0 0 * * *'
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Docker image tag (default: latest)'
+        required: false
+        default: 'latest'
 
 jobs:
-  check-and-build:
+  build-and-push:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
     
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Check last commit time
-        id: check_commit
-        run: |
-          last_commit_time=$(git log -1 --format=%ct)
-          current_time=$(date +%s)
-          time_diff=$((current_time - last_commit_time))
-          if [ $time_diff -ge 120 ] && [ $time_diff -lt 240 ]; then
-            echo "should_run=true" >> $GITHUB_OUTPUT
-          else
-            echo "should_run=false" >> $GITHUB_OUTPUT
-          fi
+        uses: actions/checkout@v4
 
       - name: Set up Docker Buildx
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/setup-buildx-action@v1
+        uses: docker/setup-buildx-action@v3
 
-      - name: Log in to the GitHub Container Registry
-        if: steps.check_commit.outputs.should_run == 'true'
-        run: echo ${{ secrets.GH_TOKEN }} | docker login ghcr.io -u USERNAME --password-stdin
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/mervinpraison/praisonai
+          tags: |
+            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }}
+            type=raw,value=${{ github.event.inputs.tag || 'latest' }},enable=${{ github.event_name == 'workflow_dispatch' }}
 
       - name: Build and push Docker image
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v5
         with:
           context: .
           file: ./docker/Dockerfile
           push: true
-          tags: ghcr.io/mervinpraison/praisonai:latest
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/gemini-issue-review.yml

@@ -46,12 +46,16 @@ jobs:
         id: issue_data
         env:
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+          # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
         run: |
           # Get issue number from event or context
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
-          elif [ "${{ github.event_name }}" = "issues" ]; then
-            ISSUE_NUMBER="${{ github.event.issue.number }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
+          elif [ "$EVENT_NAME" = "issues" ]; then
+            ISSUE_NUMBER="$EVENT_ISSUE_NUMBER"
           else
             echo "Unable to determine issue number"
             exit 1
@@ -62,8 +66,8 @@ jobs:
           
           # Extract additional instructions from comment if triggered by comment
           ADDITIONAL_INSTRUCTIONS=""
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            COMMENT_BODY="${{ github.event.comment.body }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
             ADDITIONAL_INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed -n 's/.*@gemini[[:space:]]*\(.*\)/\1/p' | head -1)
           fi
           

.github/workflows/gemini-pr-review.yml

@@ -55,21 +55,27 @@ jobs:
         id: get_pr
         env:
           GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+          # Pass user-controlled inputs via environment variables to prevent script injection (GHSL-2025-093)
+          EVENT_NAME: ${{ github.event_name }}
+          EVENT_INPUTS_PR_NUMBER: ${{ github.event.inputs.pr_number }}
+          EVENT_ISSUE_NUMBER: ${{ github.event.issue.number }}
+          EVENT_PR_NUMBER: ${{ github.event.pull_request.number }}
+          EVENT_COMMENT_BODY: ${{ github.event.comment.body }}
         run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            PR_NUMBER=${{ github.event.inputs.pr_number }}
-          elif [ "${{ github.event_name }}" = "issue_comment" ]; then
-            PR_NUMBER=${{ github.event.issue.number }}
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+            PR_NUMBER=$EVENT_INPUTS_PR_NUMBER
+          elif [ "$EVENT_NAME" = "issue_comment" ]; then
+            PR_NUMBER=$EVENT_ISSUE_NUMBER
           else
-            PR_NUMBER=${{ github.event.pull_request.number }}
+            PR_NUMBER=$EVENT_PR_NUMBER
           fi
           
           echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
           
           # Extract additional instructions from comment (if triggered by comment)
           ADDITIONAL_INSTRUCTIONS=""
-          if [ "${{ github.event_name }}" = "issue_comment" ]; then
-            COMMENT_BODY="${{ github.event.comment.body }}"
+          if [ "$EVENT_NAME" = "issue_comment" ]; then
+            COMMENT_BODY="$EVENT_COMMENT_BODY"
             ADDITIONAL_INSTRUCTIONS=$(echo "$COMMENT_BODY" | sed 's/.*@gemini//' | xargs)
           fi
           echo "additional_instructions=$ADDITIONAL_INSTRUCTIONS" >> "$GITHUB_OUTPUT"

.github/workflows/test-comprehensive.yml

@@ -27,6 +27,9 @@ jobs:
   comprehensive-test:
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      OPENAI_MODEL_NAME: gpt-4o-mini
     strategy:
       matrix:
         python-version: ["3.11"]
@@ -55,11 +58,13 @@ jobs:
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
-    - name: Set environment variables
+    - name: Verify environment variables
       run: |
-        echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY || 'sk-test-key-for-github-actions-testing-only-not-real' }}" >> $GITHUB_ENV
-        echo "OPENAI_API_BASE=${{ secrets.OPENAI_API_BASE || 'https://api.openai.com/v1' }}" >> $GITHUB_ENV
-        echo "OPENAI_MODEL_NAME=${{ secrets.OPENAI_MODEL_NAME || 'gpt-5-nano' }}" >> $GITHUB_ENV
+        if [ -n "$OPENAI_API_KEY" ]; then
+          echo "✅ OPENAI_API_KEY is set (length: ${#OPENAI_API_KEY})"
+        else
+          echo "⚠️ OPENAI_API_KEY is NOT set"
+        fi
 
     - name: Run Comprehensive Test Suite
       run: |

.github/workflows/test-core.yml

@@ -34,7 +34,7 @@ jobs:
         cd src/praisonai
         uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
         uv pip install --system duckduckgo_search
-        uv pip install --system pytest pytest-asyncio pytest-cov
+        uv pip install --system pytest pytest-asyncio pytest-cov pytest-timeout
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
@@ -262,7 +262,7 @@ jobs:
         export OPENAI_API_KEY="$OPENAI_API_KEY"
         export OPENAI_API_BASE="$OPENAI_API_BASE"
         export OPENAI_MODEL_NAME="$OPENAI_MODEL_NAME"
-        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings
+        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings -m "not real" --timeout=60
 
     - name: Upload coverage reports to Codecov
       if: matrix.python-version == '3.11'

.github/workflows/unittest.yml

@@ -27,7 +27,7 @@ jobs:
         cd src/praisonai
         uv pip install --system ."[ui,gradio,api,agentops,google,openai,anthropic,cohere,chat,code,realtime,call,crewai,autogen]"
         uv pip install --system duckduckgo_search
-        uv pip install --system pytest pytest-asyncio pytest-cov
+        uv pip install --system pytest pytest-asyncio pytest-cov pytest-timeout
         # Install knowledge dependencies from praisonai-agents
         uv pip install --system "praisonaiagents[knowledge]"
 
@@ -489,7 +489,7 @@ jobs:
 
     - name: Run Legacy Example Tests
       run: |
-        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings
+        cd src/praisonai && python -m pytest tests/test.py -v --tb=short --disable-warnings -m "not real" --timeout=60
       continue-on-error: true
 
     - name: Upload coverage reports to Codecov

.gitignore

@@ -77,4 +77,7 @@ agents/praisonaiagents/praisonaiagents.egg-info
 .qodo
 CopilotKit*
 .gemini
-issue_details.json
+issue_details.json
+
+# MCP Registry tokens
+.mcpregistry_*

docker/Dockerfile

@@ -14,9 +14,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN mkdir -p /root/.praison
 
 # Install Python packages (using latest versions)
+# Note: praisonai is installed from PyPI - remove version pin to use latest available
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.2.86" \
+    praisonai \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.2.86" \
+    "praisonai>=2.3.59" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.2.86" \
+    "praisonai>=2.3.59" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.serve

@@ -0,0 +1,25 @@
+# Dockerfile for PraisonAI Serve API
+# Deploy to Railway, Render, Fly.io, or any container platform
+#
+# Build: docker build -f Dockerfile.serve -t praisonai-serve .
+# Run:   docker run -p 8005:8005 -e OPENAI_API_KEY=sk-xxx praisonai-serve
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+RUN pip install --no-cache-dir praisonai praisonaiagents
+
+# Copy agents configuration
+COPY agents.yaml .
+
+# Expose the API port
+EXPOSE 8005
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8005/health || exit 1
+
+# Start the API server
+CMD ["praisonai", "serve", "agents.yaml", "--host", "0.0.0.0", "--port", "8005"]

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.2.86" \
+    "praisonai>=2.3.59" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

docker/README.md

@@ -121,7 +121,7 @@ healthcheck:
 ## 📦 Package Versions
 
 All Docker images use consistent, up-to-date versions:
-- PraisonAI: `>=2.2.86`
+- PraisonAI: `>=2.2.95`
 - PraisonAI Agents: `>=0.0.92`
 - Python: `3.11-slim`
 
@@ -218,7 +218,7 @@ docker-compose up -d
 ### Version Pinning
 To use specific versions, update the Dockerfile:
 ```dockerfile
-RUN pip install "praisonai==2.2.86" "praisonaiagents==0.0.92"
+RUN pip install "praisonai==2.2.95" "praisonaiagents==0.0.92"
 ```
 
 ## 🌐 Production Deployment

docker/docker-compose.dev.yml

@@ -137,22 +137,11 @@ services:
       POSTGRES_USER: praisonai
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-praisonai_dev_pass}
     volumes:
-   database:
-     image: postgres:15-alpine
-     environment:
-       POSTGRES_DB: praisonai_dev
-       POSTGRES_USER: praisonai
-       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-praisonai_dev_pass}
-     volumes:
-       - postgres_data:/var/lib/postgresql/data
-     read_only: true
-     tmpfs:
-       - /tmp
-       - /var/tmp
-     ports:
-       - "5432:5432"
-     networks:
       - postgres_data:/var/lib/postgresql/data
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /var/tmp
     ports:
       - "5432:5432"
     networks:

examples/README.md

@@ -0,0 +1,49 @@
+# PraisonAI Examples
+
+This folder contains examples for PraisonAI. For detailed documentation, visit [docs.praison.ai](https://docs.praison.ai).
+
+## Structure
+
+```
+examples/
+├── python/           # Python examples
+│   ├── agents/       # Agent examples (single, multi, router, etc.)
+│   ├── workflows/    # Workflow patterns (routing, parallel, loop)
+│   ├── tools/        # Custom tools examples
+│   ├── mcp/          # MCP protocol examples
+│   ├── memory/       # Memory and sessions
+│   ├── code/         # Code editing and external CLI tools
+│   └── ...
+├── yaml/             # YAML workflow examples
+└── cookbooks/        # Complete use-case examples
+```
+
+## Quick Links
+
+| Category | Examples | Docs |
+|----------|----------|------|
+| **Agents** | [python/agents/](python/agents/) | [📖](https://docs.praison.ai/concepts/agents) |
+| **Workflows** | [python/workflows/](python/workflows/) | [📖](https://docs.praison.ai/features/workflows) |
+| **Model Router** | [python/agents/router-agent-cost-optimization.py](python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/features/model-router) |
+| **MCP** | [python/mcp/](python/mcp/) | [📖](https://docs.praison.ai/mcp) |
+| **Memory** | [python/memory/](python/memory/) | [📖](https://docs.praison.ai/concepts/memory) |
+| **Tools** | [python/tools/](python/tools/) | [📖](https://docs.praison.ai/tools) |
+| **Code** | [python/code/](python/code/) | [📖](https://docs.praison.ai/code) |
+| **YAML** | [yaml/](yaml/) | [📖](https://docs.praison.ai/features/yaml-workflows) |
+
+## Running Examples
+
+```bash
+# Install PraisonAI
+pip install praisonai
+
+# Set API key
+export OPENAI_API_KEY=your_key_here
+
+# Run an example
+python examples/python/agents/single-agent.py
+```
+
+## CLI Commands
+
+See the main [README.md](../README.md#-cli--no-code-interface) for all CLI commands.

examples/context/00_agent_fast_context_basic.py

@@ -0,0 +1,89 @@
+"""
+Fast Context with Agent - Basic Example
+
+This is the simplest way to use Fast Context with an Agent.
+Just set fast_context=True and the agent will automatically
+have access to rapid code search capabilities.
+
+Fast Context provides:
+- 10-20x faster code search than traditional methods
+- Parallel execution (8 concurrent searches)
+- Automatic caching for repeated queries
+- Seamless integration with Agent workflows
+"""
+
+from praisonaiagents import Agent
+
+def main():
+    print("=" * 60)
+    print("Agent with Fast Context - Basic Example")
+    print("=" * 60)
+    
+    # Create an agent with Fast Context enabled
+    # This is the simplest configuration
+    agent = Agent(
+        name="CodeAssistant",
+        instructions="You are a helpful code assistant.",
+        fast_context=True,  # Enable Fast Context
+        fast_context_path=".",  # Search in current directory
+        verbose=False
+    )
+    
+    print("\n✓ Agent created with Fast Context enabled")
+    print(f"  - fast_context_enabled: {agent.fast_context_enabled}")
+    print(f"  - fast_context_path: {agent.fast_context_path}")
+    print(f"  - fast_context_model: {agent.fast_context_model}")
+    
+    # Use delegate_to_fast_context to search code
+    print("\n" + "-" * 60)
+    print("Searching for 'class Agent' in the codebase...")
+    print("-" * 60)
+    
+    context = agent.delegate_to_fast_context("class Agent")
+    
+    if context:
+        print(f"\n✓ Found relevant code!")
+        print(f"  Context length: {len(context)} characters")
+        print("\nPreview of found context:")
+        print("-" * 40)
+        # Show first 500 characters
+        preview = context[:500]
+        print(preview)
+        if len(context) > 500:
+            print("...")
+    else:
+        print("\n✗ No relevant code found")
+    
+    # Another search example
+    print("\n" + "-" * 60)
+    print("Searching for 'def chat' in the codebase...")
+    print("-" * 60)
+    
+    context = agent.delegate_to_fast_context("def chat")
+    
+    if context:
+        print(f"\n✓ Found relevant code!")
+        print(f"  Context length: {len(context)} characters")
+    else:
+        print("\n✗ No relevant code found")
+    
+    # Access FastContext directly for more control
+    print("\n" + "-" * 60)
+    print("Direct FastContext access for advanced usage...")
+    print("-" * 60)
+    
+    fc = agent.fast_context
+    if fc:
+        result = fc.search("import")
+        print(f"\n✓ Direct search for 'import':")
+        print(f"  Files found: {result.total_files}")
+        print(f"  Search time: {result.search_time_ms}ms")
+        print(f"  From cache: {result.from_cache}")
+    
+    print("\n" + "=" * 60)
+    print("Fast Context makes code search instant for your agents!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

examples/context/01_basic_fast_context.py

@@ -0,0 +1,84 @@
+"""
+Example 1: Basic Fast Context Usage
+
+This example demonstrates the basic usage of Fast Context for rapid code search.
+Fast Context is 10-20x faster than traditional sequential search because it:
+- Executes up to 8 tool calls in parallel
+- Limits search to 4 turns maximum
+- Uses a lightweight model optimized for search
+"""
+
+from praisonaiagents.context.fast import FastContext
+import time
+
+def main():
+    print("=" * 70)
+    print("Fast Context - Basic Usage Example")
+    print("=" * 70)
+    
+    # Create FastContext instance pointing to the praisonai-agents codebase
+    fc = FastContext(
+        workspace_path="/Users/praison/praisonai-package/src/praisonai-agents"
+    )
+    
+    # Example 1: Simple pattern search
+    print("\n1. Simple Pattern Search")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result = fc.search("def chat")
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Query: 'def chat'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms (total: {elapsed:.0f}ms)")
+    print(f"   Turns used: {result.turns_used}")
+    print(f"   Tool calls: {result.total_tool_calls}")
+    
+    if result.files:
+        print("\n   Top matches:")
+        for f in result.files[:3]:
+            print(f"   - {f.path}")
+            for lr in f.line_ranges[:2]:
+                print(f"     Lines {lr.start}-{lr.end}")
+    
+    # Example 2: Search for class definitions
+    print("\n2. Search for Class Definitions")
+    print("-" * 40)
+    
+    result = fc.search("class Agent")
+    print(f"   Query: 'class Agent'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms")
+    
+    if result.files:
+        print("\n   Files containing 'class Agent':")
+        for f in result.files[:5]:
+            print(f"   - {f.path} (relevance: {f.relevance_score:.2f})")
+    
+    # Example 3: Search for imports
+    print("\n3. Search for Specific Imports")
+    print("-" * 40)
+    
+    result = fc.search("from typing import")
+    print(f"   Query: 'from typing import'")
+    print(f"   Files found: {result.total_files}")
+    print(f"   Search time: {result.search_time_ms}ms")
+    
+    # Example 4: Get formatted context string
+    print("\n4. Get Formatted Context for Agent")
+    print("-" * 40)
+    
+    context = fc.get_context_for_agent("authentication", max_files=3)
+    print(f"   Context length: {len(context)} characters")
+    print(f"   Preview:")
+    preview = context[:300].replace('\n', '\n   ')
+    print(f"   {preview}...")
+    
+    print("\n" + "=" * 70)
+    print("Fast Context provides rapid, parallel code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/02_parallel_vs_sequential.py

@@ -0,0 +1,113 @@
+"""
+Example 2: Parallel vs Sequential Search Comparison
+
+This example demonstrates the speed advantage of Fast Context's parallel
+execution compared to traditional sequential search.
+
+Key insight: Fast Context executes up to 8 searches simultaneously,
+making it 5-10x faster for complex queries.
+"""
+
+import time
+import os
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.search_tools import grep_search, glob_search
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def sequential_search(queries: list) -> dict:
+    """Traditional sequential search - one query at a time."""
+    results = {}
+    for query in queries:
+        results[query] = grep_search(
+            search_path=WORKSPACE,
+            pattern=query,
+            max_results=20
+        )
+    return results
+
+
+def parallel_search_with_fast_context(queries: list) -> dict:
+    """Fast Context parallel search - multiple queries at once."""
+    fc = FastContext(workspace_path=WORKSPACE)
+    results = {}
+    for query in queries:
+        result = fc.search(query)
+        results[query] = result
+    return results
+
+
+def main():
+    print("=" * 70)
+    print("Parallel vs Sequential Search Comparison")
+    print("=" * 70)
+    
+    # Define multiple search queries
+    queries = [
+        "def __init__",
+        "class Agent",
+        "async def",
+        "import logging",
+        "from typing",
+    ]
+    
+    print(f"\nSearching for {len(queries)} patterns in the codebase...")
+    print(f"Workspace: {WORKSPACE}")
+    
+    # Sequential search
+    print("\n1. Sequential Search (Traditional)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    seq_results = sequential_search(queries)
+    seq_time = (time.perf_counter() - start) * 1000
+    
+    total_seq_matches = sum(len(r) for r in seq_results.values())
+    print(f"   Total matches: {total_seq_matches}")
+    print(f"   Time: {seq_time:.0f}ms")
+    
+    # Fast Context search (with caching disabled for fair comparison)
+    print("\n2. Fast Context Search (Parallel)")
+    print("-" * 40)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    
+    start = time.perf_counter()
+    fc_results = {}
+    for query in queries:
+        fc_results[query] = fc.search(query)
+    fc_time = (time.perf_counter() - start) * 1000
+    
+    total_fc_matches = sum(r.total_files for r in fc_results.values())
+    print(f"   Total files found: {total_fc_matches}")
+    print(f"   Time: {fc_time:.0f}ms")
+    
+    # Comparison
+    print("\n3. Comparison")
+    print("-" * 40)
+    
+    speedup = seq_time / fc_time if fc_time > 0 else float('inf')
+    print(f"   Sequential: {seq_time:.0f}ms")
+    print(f"   Fast Context: {fc_time:.0f}ms")
+    print(f"   Speedup: {speedup:.1f}x faster")
+    
+    # Detailed results
+    print("\n4. Results by Query")
+    print("-" * 40)
+    
+    for query in queries:
+        seq_count = len(seq_results[query])
+        fc_count = fc_results[query].total_files
+        fc_ms = fc_results[query].search_time_ms
+        print(f"   '{query}':")
+        print(f"      Sequential: {seq_count} matches")
+        print(f"      Fast Context: {fc_count} files in {fc_ms}ms")
+    
+    print("\n" + "=" * 70)
+    print(f"Fast Context is {speedup:.1f}x faster due to parallel execution!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/03_caching_performance.py

@@ -0,0 +1,132 @@
+"""
+Example 3: Caching Performance Demonstration
+
+This example shows how Fast Context's caching dramatically improves
+performance for repeated queries.
+
+Key benefits:
+- First query: Full search execution
+- Subsequent queries: Instant cache hit (0ms search time)
+- Configurable TTL (time-to-live)
+"""
+
+import time
+from praisonaiagents.context.fast import FastContext
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Fast Context Caching Performance")
+    print("=" * 70)
+    
+    # Create FastContext with caching enabled
+    fc = FastContext(
+        workspace_path=WORKSPACE,
+        cache_enabled=True,
+        cache_ttl=300  # 5 minutes
+    )
+    
+    query = "def execute"
+    
+    print(f"\nQuery: '{query}'")
+    print(f"Cache TTL: 300 seconds")
+    
+    # First search - cache miss
+    print("\n1. First Search (Cache Miss)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result1 = fc.search(query)
+    elapsed1 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result1.total_files}")
+    print(f"   From cache: {result1.from_cache}")
+    print(f"   Search time: {result1.search_time_ms}ms")
+    print(f"   Total time: {elapsed1:.1f}ms")
+    
+    # Second search - cache hit
+    print("\n2. Second Search (Cache Hit)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result2 = fc.search(query)
+    elapsed2 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result2.total_files}")
+    print(f"   From cache: {result2.from_cache}")
+    print(f"   Search time: {result2.search_time_ms}ms")
+    print(f"   Total time: {elapsed2:.1f}ms")
+    
+    # Third search - still cached
+    print("\n3. Third Search (Still Cached)")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    result3 = fc.search(query)
+    elapsed3 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result3.total_files}")
+    print(f"   From cache: {result3.from_cache}")
+    print(f"   Total time: {elapsed3:.1f}ms")
+    
+    # Clear cache and search again
+    print("\n4. After Cache Clear")
+    print("-" * 40)
+    
+    fc.clear_cache()
+    print("   Cache cleared!")
+    
+    start = time.perf_counter()
+    result4 = fc.search(query)
+    elapsed4 = (time.perf_counter() - start) * 1000
+    
+    print(f"   Files found: {result4.total_files}")
+    print(f"   From cache: {result4.from_cache}")
+    print(f"   Search time: {result4.search_time_ms}ms")
+    print(f"   Total time: {elapsed4:.1f}ms")
+    
+    # Performance comparison
+    print("\n5. Performance Summary")
+    print("-" * 40)
+    
+    cache_speedup = elapsed1 / elapsed2 if elapsed2 > 0 else float('inf')
+    
+    print(f"   First search (no cache): {elapsed1:.1f}ms")
+    print(f"   Cached searches: ~{elapsed2:.1f}ms")
+    print(f"   Cache speedup: {cache_speedup:.0f}x faster")
+    
+    # Multiple different queries
+    print("\n6. Multiple Query Caching")
+    print("-" * 40)
+    
+    queries = ["class Agent", "async def", "import os", "def __init__"]
+    
+    # First pass - populate cache
+    print("   First pass (populating cache):")
+    start = time.perf_counter()
+    for q in queries:
+        fc.search(q)
+    first_pass = (time.perf_counter() - start) * 1000
+    print(f"   Time: {first_pass:.0f}ms")
+    
+    # Second pass - all cached
+    print("   Second pass (all cached):")
+    start = time.perf_counter()
+    for q in queries:
+        r = fc.search(q)
+        assert r.from_cache, f"Expected cache hit for '{q}'"
+    second_pass = (time.perf_counter() - start) * 1000
+    print(f"   Time: {second_pass:.1f}ms")
+    
+    multi_speedup = first_pass / second_pass if second_pass > 0 else float('inf')
+    print(f"   Speedup: {multi_speedup:.0f}x faster")
+    
+    print("\n" + "=" * 70)
+    print("Caching provides instant results for repeated queries!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/04_agent_integration.py

@@ -0,0 +1,112 @@
+"""
+Example 4: Agent Integration with Fast Context
+
+This example shows how to use Fast Context integrated with the Agent class
+for automatic code search delegation.
+
+Benefits:
+- Seamless integration with existing Agent workflows
+- Automatic context injection for code-related queries
+- Configurable via Agent parameters or environment variables
+"""
+
+from praisonaiagents import Agent
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Agent Integration with Fast Context")
+    print("=" * 70)
+    
+    # Create an agent with Fast Context enabled
+    print("\n1. Creating Agent with Fast Context")
+    print("-" * 40)
+    
+    agent = Agent(
+        name="CodeAssistant",
+        instructions="You are a helpful code assistant that can search and analyze code.",
+        fast_context=True,
+        fast_context_path=WORKSPACE,
+        fast_context_model="gpt-4o-mini",
+        fast_context_max_turns=4,
+        fast_context_parallelism=8,
+        fast_context_timeout=30.0,
+        verbose=False
+    )
+    
+    print(f"   Agent name: {agent.name}")
+    print(f"   Fast Context enabled: {agent.fast_context_enabled}")
+    print(f"   Fast Context path: {agent.fast_context_path}")
+    print(f"   Fast Context model: {agent.fast_context_model}")
+    print(f"   Max turns: {agent.fast_context_max_turns}")
+    print(f"   Parallelism: {agent.fast_context_parallelism}")
+    
+    # Use delegate_to_fast_context for code search
+    print("\n2. Delegating Code Search to Fast Context")
+    print("-" * 40)
+    
+    queries = [
+        "find the Agent class definition",
+        "search for authentication handlers",
+        "locate memory management code",
+    ]
+    
+    for query in queries:
+        print(f"\n   Query: '{query}'")
+        context = agent.delegate_to_fast_context(query)
+        
+        if context:
+            # Show preview of context
+            lines = context.split('\n')
+            preview_lines = lines[:5]
+            print(f"   Found context ({len(context)} chars):")
+            for line in preview_lines:
+                print(f"      {line[:60]}{'...' if len(line) > 60 else ''}")
+            if len(lines) > 5:
+                print(f"      ... and {len(lines) - 5} more lines")
+        else:
+            print("   No relevant code found")
+    
+    # Access the FastContext instance directly
+    print("\n3. Direct FastContext Access")
+    print("-" * 40)
+    
+    fc = agent.fast_context
+    if fc:
+        result = fc.search("def chat")
+        print(f"   Direct search for 'def chat':")
+        print(f"   Files found: {result.total_files}")
+        print(f"   Search time: {result.search_time_ms}ms")
+        
+        for f in result.files[:3]:
+            print(f"   - {f.path}")
+    
+    # Show configuration options
+    print("\n4. Configuration Options")
+    print("-" * 40)
+    
+    print("   Agent parameters:")
+    print("   - fast_context=True              # Enable Fast Context")
+    print("   - fast_context_path='.'          # Workspace path")
+    print("   - fast_context_model='gpt-4o-mini'  # Search model")
+    print("   - fast_context_max_turns=4       # Max search turns")
+    print("   - fast_context_parallelism=8     # Parallel calls")
+    print("   - fast_context_timeout=30.0      # Timeout (seconds)")
+    
+    print("\n   Environment variables:")
+    print("   - FAST_CONTEXT_MODEL")
+    print("   - FAST_CONTEXT_MAX_TURNS")
+    print("   - FAST_CONTEXT_PARALLELISM")
+    print("   - FAST_CONTEXT_TIMEOUT")
+    print("   - FAST_CONTEXT_CACHE")
+    print("   - FAST_CONTEXT_CACHE_TTL")
+    
+    print("\n" + "=" * 70)
+    print("Fast Context integrates seamlessly with Agent for code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/05_file_and_symbol_indexing.py

@@ -0,0 +1,121 @@
+"""
+Example 5: File and Symbol Indexing
+
+This example demonstrates the file and symbol indexing capabilities
+that power Fast Context's rapid search.
+
+Features:
+- FileIndexer: Index file metadata for fast lookups
+- SymbolIndexer: Extract code symbols (functions, classes, imports)
+- Support for Python, JavaScript, TypeScript, Go, Rust, Java
+"""
+
+import time
+from praisonaiagents.context.fast.indexer import (
+    FileIndexer,
+    SymbolIndexer,
+    SymbolType
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("File and Symbol Indexing")
+    print("=" * 70)
+    
+    # File Indexer
+    print("\n1. File Indexer")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    file_indexer = FileIndexer(workspace_path=WORKSPACE)
+    file_count = file_indexer.index()
+    file_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Indexed {file_count} files in {file_time:.0f}ms")
+    
+    stats = file_indexer.get_stats()
+    print(f"   Total size: {stats['total_size_mb']} MB")
+    print(f"   Extensions: {list(stats['extensions'].keys())[:5]}")
+    
+    # Find files by pattern
+    print("\n   Finding files by pattern:")
+    py_files = file_indexer.find_by_pattern("**/*.py")
+    print(f"   - Python files (*.py): {len(py_files)}")
+    
+    agent_files = file_indexer.find_by_pattern("**/agent*.py")
+    print(f"   - Agent files (agent*.py): {len(agent_files)}")
+    
+    # Find files by name
+    print("\n   Finding files by name:")
+    init_files = file_indexer.find_by_name("__init__.py", exact=True)
+    print(f"   - __init__.py files: {len(init_files)}")
+    
+    agent_matches = file_indexer.find_by_name("agent")
+    print(f"   - Files containing 'agent': {len(agent_matches)}")
+    
+    # Symbol Indexer
+    print("\n2. Symbol Indexer")
+    print("-" * 40)
+    
+    start = time.perf_counter()
+    symbol_indexer = SymbolIndexer(workspace_path=WORKSPACE)
+    symbol_count = symbol_indexer.index()
+    symbol_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Indexed {symbol_count} symbols in {symbol_time:.0f}ms")
+    
+    stats = symbol_indexer.get_stats()
+    print(f"   Files indexed: {stats['total_files']}")
+    print(f"   Symbols by type:")
+    for sym_type, count in stats['by_type'].items():
+        print(f"      - {sym_type}: {count}")
+    
+    # Find symbols by name
+    print("\n   Finding symbols by name:")
+    
+    agent_symbols = symbol_indexer.find_by_name("Agent", exact=True)
+    print(f"   - 'Agent' (exact): {len(agent_symbols)} symbols")
+    for sym in agent_symbols[:3]:
+        print(f"      {sym.symbol_type.value}: {sym.name} in {sym.file_path}:{sym.line_number}")
+    
+    chat_symbols = symbol_indexer.find_by_name("chat")
+    print(f"   - 'chat' (partial): {len(chat_symbols)} symbols")
+    for sym in chat_symbols[:3]:
+        print(f"      {sym.symbol_type.value}: {sym.name} in {sym.file_path}:{sym.line_number}")
+    
+    # Find symbols by type
+    print("\n   Finding symbols by type:")
+    
+    classes = symbol_indexer.find_by_type(SymbolType.CLASS)
+    print(f"   - Classes: {len(classes)}")
+    for cls in classes[:5]:
+        print(f"      class {cls.name} in {cls.file_path}:{cls.line_number}")
+    
+    functions = symbol_indexer.find_by_type(SymbolType.FUNCTION)
+    print(f"   - Functions: {len(functions)}")
+    
+    methods = symbol_indexer.find_by_type(SymbolType.METHOD)
+    print(f"   - Methods: {len(methods)}")
+    
+    imports = symbol_indexer.find_by_type(SymbolType.IMPORT)
+    print(f"   - Imports: {len(imports)}")
+    
+    # Performance comparison
+    print("\n3. Performance Summary")
+    print("-" * 40)
+    
+    print(f"   File indexing: {file_time:.0f}ms for {file_count} files")
+    print(f"   Symbol indexing: {symbol_time:.0f}ms for {symbol_count} symbols")
+    print(f"   Files per second: {file_count / (file_time / 1000):.0f}")
+    print(f"   Symbols per second: {symbol_count / (symbol_time / 1000):.0f}")
+    
+    print("\n" + "=" * 70)
+    print("Indexing enables instant lookups for files and symbols!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/06_context_injection.py

@@ -0,0 +1,163 @@
+"""
+Example 6: Context Injection for Agents
+
+This example demonstrates how Fast Context results can be formatted
+and injected into agent prompts for better code understanding.
+
+Features:
+- Multiple format styles (markdown, xml, plain)
+- Token budget management
+- Precision over recall (avoid context pollution)
+"""
+
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.context_injector import (
+    ContextInjector,
+    InjectionConfig,
+    inject_fast_context
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Context Injection for Agents")
+    print("=" * 70)
+    
+    # Search for code
+    fc = FastContext(workspace_path=WORKSPACE)
+    result = fc.search("class Agent")
+    
+    print(f"\nSearch results: {result.total_files} files found")
+    
+    # Markdown format (default)
+    print("\n1. Markdown Format")
+    print("-" * 40)
+    
+    config_md = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        max_lines_per_file=20,
+        format_style="markdown",
+        include_line_numbers=True,
+        include_file_content=True,
+        prioritize_precision=True
+    )
+    
+    injector_md = ContextInjector(config_md)
+    md_context = injector_md.format_context(result)
+    
+    print(f"   Format: Markdown")
+    print(f"   Length: {len(md_context)} chars (~{len(md_context)//4} tokens)")
+    print(f"   Preview:")
+    for line in md_context.split('\n')[:10]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # XML format
+    print("\n2. XML Format")
+    print("-" * 40)
+    
+    config_xml = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        format_style="xml",
+        prioritize_precision=True
+    )
+    
+    injector_xml = ContextInjector(config_xml)
+    xml_context = injector_xml.format_context(result)
+    
+    print(f"   Format: XML")
+    print(f"   Length: {len(xml_context)} chars")
+    print(f"   Preview:")
+    for line in xml_context.split('\n')[:10]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # Plain text format
+    print("\n3. Plain Text Format")
+    print("-" * 40)
+    
+    config_plain = InjectionConfig(
+        max_tokens=2000,
+        max_files=3,
+        format_style="plain"
+    )
+    
+    injector_plain = ContextInjector(config_plain)
+    plain_context = injector_plain.format_context(result)
+    
+    print(f"   Format: Plain")
+    print(f"   Length: {len(plain_context)} chars")
+    print(f"   Preview:")
+    for line in plain_context.split('\n')[:8]:
+        print(f"   {line[:70]}")
+    print("   ...")
+    
+    # Inject into prompts
+    print("\n4. Injecting into Prompts")
+    print("-" * 40)
+    
+    system_prompt = "You are a helpful code assistant."
+    user_message = "Explain how the Agent class works."
+    
+    injected = inject_fast_context(
+        result=result,
+        system_prompt=system_prompt,
+        user_message=user_message,
+        max_tokens=1500,
+        format_style="markdown"
+    )
+    
+    print(f"   Original system prompt: {len(system_prompt)} chars")
+    print(f"   Injected system prompt: {len(injected['system_prompt'])} chars")
+    print(f"   User message unchanged: {injected['user_message'] == user_message}")
+    
+    # Token budget management
+    print("\n5. Token Budget Management")
+    print("-" * 40)
+    
+    budgets = [500, 1000, 2000, 4000]
+    
+    for budget in budgets:
+        config = InjectionConfig(max_tokens=budget, max_files=10)
+        injector = ContextInjector(config)
+        context = injector.format_context(result)
+        estimated_tokens = len(context) // 4
+        print(f"   Budget: {budget} tokens -> {len(context)} chars (~{estimated_tokens} tokens)")
+    
+    # Precision mode
+    print("\n6. Precision vs Recall")
+    print("-" * 40)
+    
+    # High precision (fewer, more relevant results)
+    config_precision = InjectionConfig(
+        max_tokens=2000,
+        max_files=5,
+        prioritize_precision=True
+    )
+    injector_precision = ContextInjector(config_precision)
+    precision_context = injector_precision.format_context(result)
+    
+    # Lower precision (more results)
+    config_recall = InjectionConfig(
+        max_tokens=2000,
+        max_files=10,
+        prioritize_precision=False
+    )
+    injector_recall = ContextInjector(config_recall)
+    recall_context = injector_recall.format_context(result)
+    
+    print(f"   High precision mode: {len(precision_context)} chars")
+    print(f"   High recall mode: {len(recall_context)} chars")
+    print(f"   Precision mode is more focused for better agent understanding")
+    
+    print("\n" + "=" * 70)
+    print("Context injection formats search results for optimal agent use!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/07_search_tools_demo.py

@@ -0,0 +1,213 @@
+"""
+Example 7: Search Tools Deep Dive
+
+This example demonstrates the individual search tools that power Fast Context:
+- grep_search: Pattern-based search with regex support
+- glob_search: File pattern matching
+- read_file: Read file contents with line ranges
+- list_directory: Directory listing with filtering
+"""
+
+import time
+from praisonaiagents.context.fast.search_tools import (
+    grep_search,
+    glob_search,
+    read_file,
+    list_directory
+)
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def main():
+    print("=" * 70)
+    print("Search Tools Deep Dive")
+    print("=" * 70)
+    
+    # grep_search
+    print("\n1. grep_search - Pattern Search")
+    print("-" * 40)
+    
+    # Simple pattern
+    start = time.perf_counter()
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern="def __init__",
+        max_results=10
+    )
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Pattern: 'def __init__'")
+    print(f"   Matches: {len(results)}")
+    print(f"   Time: {elapsed:.0f}ms")
+    if results:
+        print(f"   First match: {results[0]['path']}:{results[0]['line_number']}")
+    
+    # Regex pattern
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern=r"class \w+Agent",
+        is_regex=True,
+        max_results=10
+    )
+    print(f"\n   Regex: 'class \\w+Agent'")
+    print(f"   Matches: {len(results)}")
+    for r in results[:3]:
+        print(f"   - {r['path']}:{r['line_number']}: {r['content'][:50]}...")
+    
+    # Case sensitive
+    results_sensitive = grep_search(
+        search_path=WORKSPACE,
+        pattern="Agent",
+        case_sensitive=True,
+        max_results=50
+    )
+    results_insensitive = grep_search(
+        search_path=WORKSPACE,
+        pattern="agent",
+        case_sensitive=False,
+        max_results=50
+    )
+    print(f"\n   Case sensitive 'Agent': {len(results_sensitive)} matches")
+    print(f"   Case insensitive 'agent': {len(results_insensitive)} matches")
+    
+    # With context lines
+    results = grep_search(
+        search_path=WORKSPACE,
+        pattern="class Agent:",
+        context_lines=2,
+        max_results=3
+    )
+    print(f"\n   With 2 context lines:")
+    if results:
+        print(f"   {results[0]['path']}:")
+        if results[0].get('context'):
+            for line in results[0]['context'].split('\n')[:5]:
+                print(f"      {line[:60]}")
+    
+    # glob_search
+    print("\n2. glob_search - File Pattern Matching")
+    print("-" * 40)
+    
+    # Find Python files
+    start = time.perf_counter()
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/*.py",
+        max_results=100
+    )
+    elapsed = (time.perf_counter() - start) * 1000
+    
+    print(f"   Pattern: '**/*.py'")
+    print(f"   Files found: {len(results)}")
+    print(f"   Time: {elapsed:.0f}ms")
+    
+    # Find specific files
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/agent*.py",
+        max_results=20
+    )
+    print(f"\n   Pattern: '**/agent*.py'")
+    print(f"   Files found: {len(results)}")
+    for r in results[:5]:
+        print(f"   - {r['path']} ({r['size']} bytes)")
+    
+    # Find test files
+    results = glob_search(
+        search_path=WORKSPACE,
+        pattern="**/test_*.py",
+        max_results=50
+    )
+    print(f"\n   Pattern: '**/test_*.py'")
+    print(f"   Test files: {len(results)}")
+    
+    # read_file
+    print("\n3. read_file - Read File Contents")
+    print("-" * 40)
+    
+    # Read entire file
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/__init__.py",
+        max_lines=20
+    )
+    
+    print(f"   File: praisonaiagents/__init__.py")
+    print(f"   Success: {result['success']}")
+    print(f"   Lines: {result.get('total_lines', 'N/A')}")
+    if result['success']:
+        lines = result['content'].split('\n')[:5]
+        print(f"   Preview:")
+        for line in lines:
+            print(f"      {line[:60]}")
+    
+    # Read specific line range
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/agent/agent.py",
+        start_line=1,
+        end_line=20
+    )
+    
+    print(f"\n   File: agent/agent.py (lines 1-20)")
+    print(f"   Success: {result['success']}")
+    if result['success']:
+        lines = result['content'].split('\n')[:5]
+        print(f"   Preview:")
+        for line in lines:
+            print(f"      {line[:60]}")
+    
+    # Read with context
+    result = read_file(
+        filepath=f"{WORKSPACE}/praisonaiagents/agent/agent.py",
+        start_line=100,
+        end_line=105,
+        context_lines=3
+    )
+    
+    print(f"\n   File: agent/agent.py (lines 100-105 with 3 context lines)")
+    print(f"   Success: {result['success']}")
+    
+    # list_directory
+    print("\n4. list_directory - Directory Listing")
+    print("-" * 40)
+    
+    # List root
+    result = list_directory(
+        dir_path=WORKSPACE,
+        recursive=False,
+        max_entries=20
+    )
+    
+    print(f"   Directory: {WORKSPACE}")
+    print(f"   Success: {result['success']}")
+    print(f"   Entries: {len(result.get('entries', []))}")
+    
+    dirs = [e for e in result.get('entries', []) if e.get('is_dir')]
+    files = [e for e in result.get('entries', []) if not e.get('is_dir')]
+    print(f"   Directories: {len(dirs)}")
+    print(f"   Files: {len(files)}")
+    
+    # List recursive with depth limit
+    result = list_directory(
+        dir_path=f"{WORKSPACE}/praisonaiagents",
+        recursive=True,
+        max_depth=2,
+        max_entries=50
+    )
+    
+    print(f"\n   Directory: praisonaiagents (recursive, depth=2)")
+    print(f"   Entries: {len(result.get('entries', []))}")
+    
+    # Show directory structure
+    print(f"   Structure:")
+    for entry in result.get('entries', [])[:10]:
+        prefix = "📁" if entry.get('is_dir') else "📄"
+        print(f"      {prefix} {entry['name']}")
+    
+    print("\n" + "=" * 70)
+    print("These search tools power Fast Context's rapid code search!")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

examples/context/08_comprehensive_benchmark.py

@@ -0,0 +1,227 @@
+"""
+Example 8: Comprehensive Benchmark
+
+This example provides a comprehensive benchmark comparing Fast Context
+performance against traditional search approaches.
+
+Metrics measured:
+- Search latency
+- Throughput (queries per second)
+- Cache effectiveness
+- Parallel execution speedup
+"""
+
+import time
+import statistics
+from praisonaiagents.context.fast import FastContext
+from praisonaiagents.context.fast.search_tools import grep_search
+from praisonaiagents.context.fast.indexer import FileIndexer, SymbolIndexer
+
+WORKSPACE = "/Users/praison/praisonai-package/src/praisonai-agents"
+
+
+def benchmark_search_latency():
+    """Benchmark search latency."""
+    print("\n1. Search Latency Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    
+    queries = [
+        "def __init__",
+        "class Agent",
+        "import logging",
+        "async def",
+        "from typing import",
+    ]
+    
+    # Warm up
+    fc.search("warmup")
+    
+    # Benchmark each query
+    latencies = []
+    for query in queries:
+        times = []
+        for _ in range(3):  # 3 runs per query
+            start = time.perf_counter()
+            fc.search(query)
+            elapsed = (time.perf_counter() - start) * 1000
+            times.append(elapsed)
+        
+        avg = statistics.mean(times)
+        latencies.append(avg)
+        print(f"   '{query}': {avg:.1f}ms (min: {min(times):.1f}, max: {max(times):.1f})")
+    
+    print(f"\n   Average latency: {statistics.mean(latencies):.1f}ms")
+    print(f"   Median latency: {statistics.median(latencies):.1f}ms")
+    print(f"   P95 latency: {sorted(latencies)[int(len(latencies)*0.95)]:.1f}ms")
+
+
+def benchmark_throughput():
+    """Benchmark queries per second."""
+    print("\n2. Throughput Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=True)
+    
+    queries = ["def", "class", "import", "return", "if", "for", "while", "try"]
+    
+    # Cold run (no cache)
+    fc.clear_cache()
+    start = time.perf_counter()
+    for query in queries:
+        fc.search(query)
+    cold_time = time.perf_counter() - start
+    cold_qps = len(queries) / cold_time
+    
+    print(f"   Cold (no cache):")
+    print(f"      Queries: {len(queries)}")
+    print(f"      Time: {cold_time*1000:.0f}ms")
+    print(f"      Throughput: {cold_qps:.1f} queries/second")
+    
+    # Warm run (cached)
+    start = time.perf_counter()
+    for _ in range(10):  # 10 iterations
+        for query in queries:
+            fc.search(query)
+    warm_time = time.perf_counter() - start
+    warm_qps = (len(queries) * 10) / warm_time
+    
+    print(f"\n   Warm (cached):")
+    print(f"      Queries: {len(queries) * 10}")
+    print(f"      Time: {warm_time*1000:.0f}ms")
+    print(f"      Throughput: {warm_qps:.0f} queries/second")
+    
+    print(f"\n   Cache speedup: {warm_qps/cold_qps:.0f}x")
+
+
+def benchmark_cache_effectiveness():
+    """Benchmark cache hit rate and speedup."""
+    print("\n3. Cache Effectiveness Benchmark")
+    print("-" * 50)
+    
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=True)
+    fc.clear_cache()
+    
+    queries = ["Agent", "chat", "memory", "tool", "execute"]
+    
+    # First pass - cache misses
+    miss_times = []
+    for query in queries:
+        start = time.perf_counter()
+        result = fc.search(query)
+        elapsed = (time.perf_counter() - start) * 1000
+        miss_times.append(elapsed)
+        assert not result.from_cache
+    
+    # Second pass - cache hits
+    hit_times = []
+    for query in queries:
+        start = time.perf_counter()
+        result = fc.search(query)
+        elapsed = (time.perf_counter() - start) * 1000
+        hit_times.append(elapsed)
+        assert result.from_cache
+    
+    avg_miss = statistics.mean(miss_times)
+    avg_hit = statistics.mean(hit_times)
+    
+    print(f"   Cache miss (first query): {avg_miss:.1f}ms avg")
+    print(f"   Cache hit (repeat query): {avg_hit:.2f}ms avg")
+    print(f"   Cache speedup: {avg_miss/avg_hit:.0f}x faster")
+    print(f"   Time saved per cached query: {avg_miss - avg_hit:.1f}ms")
+
+
+def benchmark_parallel_execution():
+    """Benchmark parallel vs sequential execution."""
+    print("\n4. Parallel Execution Benchmark")
+    print("-" * 50)
+    
+    queries = ["def", "class", "import", "return", "async"]
+    
+    # Sequential (one at a time)
+    start = time.perf_counter()
+    for query in queries:
+        grep_search(WORKSPACE, query, max_results=20)
+    seq_time = (time.perf_counter() - start) * 1000
+    
+    # Parallel (Fast Context)
+    fc = FastContext(workspace_path=WORKSPACE, cache_enabled=False)
+    start = time.perf_counter()
+    for query in queries:
+        fc.search(query)
+    par_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   Sequential: {seq_time:.0f}ms")
+    print(f"   Parallel (Fast Context): {par_time:.0f}ms")
+    print(f"   Speedup: {seq_time/par_time:.1f}x")
+
+
+def benchmark_indexing():
+    """Benchmark indexing performance."""
+    print("\n5. Indexing Performance Benchmark")
+    print("-" * 50)
+    
+    # File indexing
+    start = time.perf_counter()
+    file_indexer = FileIndexer(workspace_path=WORKSPACE)
+    file_count = file_indexer.index()
+    file_time = (time.perf_counter() - start) * 1000
+    
+    print(f"   File Indexer:")
+    print(f"      Files: {file_count}")
+    print(f"      Time: {file_time:.0f}ms")
+    print(f"      Rate: {file_count/(file_time/1000):.0f} files/second")
+    
+    # Symbol indexing
+    start = time.perf_counter()
+    symbol_indexer = SymbolIndexer(workspace_path=WORKSPACE)
+    symbol_count = symbol_indexer.index()
+    symbol_time = (time.perf_counter() - start) * 1000
+    
+    print(f"\n   Symbol Indexer:")
+    print(f"      Symbols: {symbol_count}")
+    print(f"      Time: {symbol_time:.0f}ms")
+    print(f"      Rate: {symbol_count/(symbol_time/1000):.0f} symbols/second")
+    
+    # Lookup performance
+    start = time.perf_counter()
+    for _ in range(100):
+        file_indexer.find_by_pattern("**/*.py")
+    lookup_time = (time.perf_counter() - start) * 1000
+    
+    print(f"\n   Lookup Performance:")
+    print(f"      100 pattern lookups: {lookup_time:.1f}ms")
+    print(f"      Per lookup: {lookup_time/100:.2f}ms")
+
+
+def main():
+    print("=" * 70)
+    print("Fast Context Comprehensive Benchmark")
+    print("=" * 70)
+    print(f"\nWorkspace: {WORKSPACE}")
+    
+    benchmark_search_latency()
+    benchmark_throughput()
+    benchmark_cache_effectiveness()
+    benchmark_parallel_execution()
+    benchmark_indexing()
+    
+    print("\n" + "=" * 70)
+    print("Summary")
+    print("=" * 70)
+    print("""
+   Fast Context provides:
+   ✓ Sub-100ms search latency for most queries
+   ✓ 100+ queries/second with caching
+   ✓ 100x+ speedup for cached queries
+   ✓ 2-5x speedup from parallel execution
+   ✓ 1000+ files/second indexing rate
+   
+   These benchmarks demonstrate why Fast Context is ideal for
+   rapid code search in AI agent workflows.
+""")
+
+
+if __name__ == "__main__":
+    main()

examples/cookbooks/Finance_Market_Job_Agents/Ai_Job_Hunting_Assistant.ipynb

@@ -29,7 +29,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {
     "colab": {
      "base_uri": "https://localhost:8080/"
@@ -71,7 +71,6 @@
     "import pandas as pd\n",
     "\n",
     "print(\"📦 Dependencies installed!\")\n",
-    "print(\"🔄 Converting from AGNO → PraisonAI\")\n",
     "print(\"🎯 Building Job Hunting Agent System\")"
    ]
   },

examples/cookbooks/rag_examples/agentic_rag/PraisonAI_RecipeAgent.ipynb

@@ -0,0 +1,481 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "LJRJRQtFTagH"
+   },
+   "source": [
+    "# AI RAG Agent with Web Access using PraisonAI"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "Ph4RVTBCTcmB"
+   },
+   "source": [
+    "This notebook demonstrates how to build a Retrieval-Augmented Generation (RAG) agent with web access using GPT-4o and PraisonAI. The agent specializes in Thai recipes and can search the web for additional information."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "tMxfwPPATy_o"
+   },
+   "source": [
+    "This RAG agent:\n",
+    "*   Creates an AI assistant specialized in Thai recipes and cooking\n",
+    "*   Has access to a PDF knowledge base about Thai recipes\n",
+    "*   Can search the web using DuckDuckGo for additional information\n",
+    "*   Provides comprehensive answers about Thai cuisine\n",
+    "*   Uses PraisonAI framework for agent management"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "h68oMaCITmqt"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Dhivya-Bharathy/PraisonAI/blob/main/examples/cookbooks/rag_examples/agentic_rag/PraisonAI_RecipeAgent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "cAdzoWXJUMfF"
+   },
+   "source": [
+    "# Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "9D-2TlOrUNcu"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install praisonaiagents openai requests"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "yY-4-kEIUW40"
+   },
+   "source": [
+    "# Set Up API Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "f5bhQ05yUX6J",
+    "outputId": "dcf9d0d9-332e-4136-9289-4c39d898005c"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Enter your OpenAI API key: ··········\n",
+      "✅ API key set successfully!\n"
+     ]
+    }
+   ],
+   "source": [
+    "import os\n",
+    "\n",
+    "# Set your OpenAI API key here\n",
+    "os.environ['OPENAI_API_KEY'] = 'Enter your api key here'\n",
+    "\n",
+    "# Or use this method to input it securely\n",
+    "from getpass import getpass\n",
+    "api_key = getpass('Enter your OpenAI API key: ')\n",
+    "os.environ['OPENAI_API_KEY'] = api_key\n",
+    "\n",
+    "print(\"✅ API key set successfully!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "Eh0j-SegUi13"
+   },
+   "source": [
+    "# Tools"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "Z1A9oifIUkQN",
+    "outputId": "9be78226-36fa-43c4-865d-2f7e6e2ba9de"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "✅ Tools imported successfully!\n"
+     ]
+    }
+   ],
+   "source": [
+    "from praisonaiagents import Agent\n",
+    "import requests\n",
+    "import tempfile\n",
+    "from pathlib import Path\n",
+    "\n",
+    "print(\"✅ Tools imported successfully!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "efnnREHXUnYA"
+   },
+   "source": [
+    "# YAML Prompt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "kcM14-yQUqG-",
+    "outputId": "c5b6288d-a789-4a93-e20c-1d285370b667"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "✅ Agent instructions configured!\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Agent configuration and instructions\n",
+    "AGENT_INSTRUCTIONS = \"\"\"\n",
+    "You are a helpful AI assistant specialized in Thai recipes and cooking.\n",
+    "\n",
+    "You have access to a PDF knowledge base about Thai recipes from: https://phi-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf\n",
+    "\n",
+    "You can also search the web for additional information about Thai cooking, ingredients, and techniques.\n",
+    "\n",
+    "When answering questions:\n",
+    "1. Use your knowledge about Thai cuisine to provide helpful information\n",
+    "2. If needed, search the web for additional details, current information, or clarification\n",
+    "3. Provide comprehensive, helpful answers about Thai cuisine\n",
+    "4. Always be informative and helpful about Thai cooking!\n",
+    "\n",
+    "You can use the internet_search function to search the web when needed.\n",
+    "\n",
+    "Focus on providing practical cooking advice, ingredient information, and authentic Thai recipe guidance.\n",
+    "\"\"\"\n",
+    "\n",
+    "print(\"✅ Agent instructions configured!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "MCBRcXFJUulY"
+   },
+   "source": [
+    "# Main"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "YaRLbgMmUvXv",
+    "outputId": "8ed8d9f8-85a7-48de-ccc6-f617cd672a85"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🤖 Thai Recipe RAG Agent created successfully!\n",
+      "The agent is ready to answer questions about Thai cooking.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Create the RAG agent\n",
+    "rag_agent = Agent(\n",
+    "    instructions=AGENT_INSTRUCTIONS,\n",
+    "    llm=\"gpt-4o\",\n",
+    "    markdown=True,\n",
+    "    verbose=True\n",
+    ")\n",
+    "\n",
+    "print(\"🤖 Thai Recipe RAG Agent created successfully!\")\n",
+    "print(\"The agent is ready to answer questions about Thai cooking.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "QvZM94pGU0IX"
+   },
+   "source": [
+    "# Test the Agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 1000,
+     "referenced_widgets": [
+      "47739975c9f04ee5b4e69e8f445cbeda",
+      "08888d583cba4c01b3fdf8f30b06ca4f"
+     ]
+    },
+    "id": "QPdrleKxU1VN",
+    "outputId": "a71a86cd-eff8-4309-9b50-173a30066c90"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "🤔 Question: What are the essential ingredients for Thai cooking?\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╭─ </span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8; font-weight: bold\">Agent Info</span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\"> ────────────────────────────────────────────────────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #ff9b9b; text-decoration-color: #ff9b9b; font-weight: bold\">👤 Agent:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Agent</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #b4b4b3; text-decoration-color: #b4b4b3; font-weight: bold\">Role:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Assistant</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[38;2;210;227;200m╭─\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[1;38;2;210;227;200mAgent Info\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[38;2;210;227;200m───────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[38;2;210;227;200m─╮\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;255;155;155m👤 Agent:\u001b[0m \u001b[38;2;255;229;229mAgent\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;180;180;179mRole:\u001b[0m \u001b[38;2;255;229;229mAssistant\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "47739975c9f04ee5b4e69e8f445cbeda",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"></pre>\n"
+      ],
+      "text/plain": []
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\">\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #7f7f7f; text-decoration-color: #7f7f7f\">Response generated in 8.4s</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[2mResponse generated in 8.4s\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭───────────────────────────────────────────────────── Task ──────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> What are the essential ingredients for Thai cooking?                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m────────────────────────────────────────────────────\u001b[0m\u001b[36m Task \u001b[0m\u001b[36m─────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m What are the essential ingredients for Thai cooking?                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭─────────────────────────────────────────────────── Response ────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour,  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  1 </span><span style=\"font-weight: bold\">Fish Sauce (Nam Pla)</span>: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking,   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>used to add depth of flavor.                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  2 </span><span style=\"font-weight: bold\">Lime Juice</span>: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  3 </span><span style=\"font-weight: bold\">Chilies</span>: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>certain recipes.                                                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  4 </span><span style=\"font-weight: bold\">Lemongrass</span>: A citrusy, fragrant herb that is often used in soups, curries, and teas.                        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  5 </span><span style=\"font-weight: bold\">Galangal</span>: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.         <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  6 </span><span style=\"font-weight: bold\">Kaffir Lime Leaves</span>: They add a distinct, zesty citrus aroma and flavor to Thai dishes.                      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  7 </span><span style=\"font-weight: bold\">Coconut Milk</span>: Adds richness and creaminess, commonly used in curries and desserts.                          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  8 </span><span style=\"font-weight: bold\">Palm Sugar</span>: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">  9 </span><span style=\"font-weight: bold\">Tamarind Paste</span>: Provides a sour element to many dishes, particularly pad Thai and some sauces.              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 10 </span><span style=\"font-weight: bold\">Thai Basil</span>: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 11 </span><span style=\"font-weight: bold\">Coriander (Cilantro)</span>: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>sauces and stocks.                                                                                          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> 12 </span><span style=\"font-weight: bold\">Shrimp Paste</span>: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">    </span>dishes.                                                                                                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> These ingredients are commonly used in combination to create the complex and rich flavors characteristic of     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> of Thai dishes.                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m──────────────────────────────────────────────────\u001b[0m\u001b[36m Response \u001b[0m\u001b[36m───────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour,  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  1 \u001b[0m\u001b[1mFish Sauce (Nam Pla)\u001b[0m: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking,   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mused to add depth of flavor.                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  2 \u001b[0m\u001b[1mLime Juice\u001b[0m: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  3 \u001b[0m\u001b[1mChilies\u001b[0m: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mcertain recipes.                                                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  4 \u001b[0m\u001b[1mLemongrass\u001b[0m: A citrusy, fragrant herb that is often used in soups, curries, and teas.                        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  5 \u001b[0m\u001b[1mGalangal\u001b[0m: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.         \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  6 \u001b[0m\u001b[1mKaffir Lime Leaves\u001b[0m: They add a distinct, zesty citrus aroma and flavor to Thai dishes.                      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  7 \u001b[0m\u001b[1mCoconut Milk\u001b[0m: Adds richness and creaminess, commonly used in curries and desserts.                          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  8 \u001b[0m\u001b[1mPalm Sugar\u001b[0m: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m  9 \u001b[0m\u001b[1mTamarind Paste\u001b[0m: Provides a sour element to many dishes, particularly pad Thai and some sauces.              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 10 \u001b[0m\u001b[1mThai Basil\u001b[0m: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 11 \u001b[0m\u001b[1mCoriander (Cilantro)\u001b[0m: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0msauces and stocks.                                                                                          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m 12 \u001b[0m\u001b[1mShrimp Paste\u001b[0m: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m    \u001b[0mdishes.                                                                                                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m These ingredients are commonly used in combination to create the complex and rich flavors characteristic of     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m of Thai dishes.                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "�� Answer: Thai cooking is known for its balance of five fundamental taste senses in each dish or the overall meal: sour, sweet, salty, bitter, and spicy. Essential ingredients that help achieve this balance include:\n",
+      "\n",
+      "1. **Fish Sauce (Nam Pla)**: A salty, savory sauce made from fermented fish. It's a cornerstone of Thai cooking, used to add depth of flavor.\n",
+      "\n",
+      "2. **Lime Juice**: Used to add a fresh, tangy citrus flavor to dishes, especially in salads and some curries.\n",
+      "\n",
+      "3. **Chilies**: Thai cuisine often features fresh Thai bird's eye chilies for heat, as well as dried chilies for certain recipes.\n",
+      "\n",
+      "4. **Lemongrass**: A citrusy, fragrant herb that is often used in soups, curries, and teas.\n",
+      "\n",
+      "5. **Galangal**: Similar to ginger, galangal has a sharp, peppery flavor and is used in soups and curries.\n",
+      "\n",
+      "6. **Kaffir Lime Leaves**: They add a distinct, zesty citrus aroma and flavor to Thai dishes.\n",
+      "\n",
+      "7. **Coconut Milk**: Adds richness and creaminess, commonly used in curries and desserts.\n",
+      "\n",
+      "8. **Palm Sugar**: Used as a sweetener, palm sugar has a nuanced flavor, unlike regular sugar.\n",
+      "\n",
+      "9. **Tamarind Paste**: Provides a sour element to many dishes, particularly pad Thai and some sauces.\n",
+      "\n",
+      "10. **Thai Basil**: Adds a spicy, peppery flavor, different from the sweet basil used in Western cooking.\n",
+      "\n",
+      "11. **Coriander (Cilantro)**: Used as a garnish and for its fresh, citrusy leaves and roots, which add depth to sauces and stocks.\n",
+      "\n",
+      "12. **Shrimp Paste**: A very pungent paste made from fermented shrimp, used sparingly to enrich the flavor of dishes.\n",
+      "\n",
+      "These ingredients are commonly used in combination to create the complex and rich flavors characteristic of Thai cuisine. Fresh and high-quality versions of these ingredients contribute significantly to the authenticity of Thai dishes.\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Test question 1: Basic Thai cooking\n",
+    "question1 = \"What are the essential ingredients for Thai cooking?\"\n",
+    "print(f\"🤔 Question: {question1}\")\n",
+    "\n",
+    "try:\n",
+    "    response1 = rag_agent.start(question1)\n",
+    "    print(f\"�� Answer: {response1}\")\n",
+    "except Exception as e:\n",
+    "    print(f\"❌ Error: {e}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

examples/cookbooks/rag_examples/agentic_rag/agentic_rag_gpt5_praisonai_agents.ipynb

@@ -0,0 +1,556 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "EA8l4cSVl3Lx"
+   },
+   "source": [
+    "# Agentic RAG with GPT-5 - Colab Notebook"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "I-8nOxJ2l7nO"
+   },
+   "source": [
+    "This Colab notebook sets up a Streamlit app using PraisonAI Agents framework.\n",
+    "It allows you to interact with an AI agent powered by GPT-5 for Q&A.\n",
+    "Currently, the knowledge base functionality is disabled due to compatibility issues."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "g5I1tMkxmDQe"
+   },
+   "source": [
+    "- GPT-5 Integration (via OpenAI API)\n",
+    "- Streamlit Web App\n",
+    "- Agent Framework: PraisonAI Agents\n",
+    "- Markdown-formatted responses"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "yeEno7U0q2U_"
+   },
+   "source": [
+    "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Dhivya-Bharathy/PraisonAI/blob/main/examples/cookbooks/Qwen2.5_InstructionAgent.ipynb)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "WV2GnzZCmGBR"
+   },
+   "source": [
+    "# Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "20wAadXemJ0k"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install praisonaiagents python-dotenv streamlit"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "l71uCRarndvy"
+   },
+   "source": [
+    "# Set API Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "id": "brfc-ZZKnfre"
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from dotenv import load_dotenv\n",
+    "\n",
+    "load_dotenv()\n",
+    "\n",
+    "OPENAI_API_KEY = \"Enter your api key here\"\n",
+    "\n",
+    "os.environ[\"OPENAI_API_KEY\"] = OPENAI_API_KEY\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "d1fGzyQCn1aQ"
+   },
+   "source": [
+    "# Tools and Imports"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "id": "GcNPLkZXntIS"
+   },
+   "outputs": [],
+   "source": [
+    "import streamlit as st\n",
+    "from praisonaiagents import Agent\n",
+    "\n",
+    "# YAML Prompt Configuration\n",
+    "agent_config = {\n",
+    "    \"name\": \"Knowledge Agent\",\n",
+    "    \"instructions\": [\n",
+    "        \"You are a helpful AI assistant. Answer questions based on your general knowledge.\",\n",
+    "        \"Provide clear, well-structured answers in markdown format.\",\n",
+    "        \"Use proper markdown formatting with headers, lists, and emphasis where appropriate.\",\n",
+    "        \"Structure your response with clear sections and bullet points when helpful.\",\n",
+    "    ],\n",
+    "    \"llm\": \"gpt-5-nano\",\n",
+    "    \"markdown\": True,\n",
+    "    \"verbose\": True\n",
+    "}\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "jkmrh0gIn_4a"
+   },
+   "source": [
+    "# Initialize Agent"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "id": "qaJvf8RyoAsB"
+   },
+   "outputs": [],
+   "source": [
+    "def create_agent():\n",
+    "    \"\"\"Create an agent with reasoning capabilities\"\"\"\n",
+    "    return Agent(\n",
+    "        name=agent_config[\"name\"],\n",
+    "        instructions=agent_config[\"instructions\"],\n",
+    "        llm=agent_config[\"llm\"],\n",
+    "        markdown=agent_config[\"markdown\"],\n",
+    "        verbose=agent_config[\"verbose\"]\n",
+    "    )"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "kvGJh3bbqTmh"
+   },
+   "source": [
+    "# Main Function"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 1000,
+     "referenced_widgets": [
+      "ad296d97510246de8eb0138ce8a8a166",
+      "f6e502b3dca442f0ae6c5739f5a6d159"
+     ]
+    },
+    "id": "_QyxzqKKqUrW",
+    "outputId": "97be7e02-b034-4004-e9e3-56337e3f2887"
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "�� Initializing Agentic RAG with GPT-5...\n",
+      "📚 Loading agent...\n",
+      "✅ Agent loaded successfully!\n",
+      "\n",
+      "🎯 Example queries you can try:\n",
+      "1. What is PraisonAI and how do Agents work?\n",
+      "2. What are Teams in PraisonAI and how do they work?\n",
+      "3. Give me a step-by-step guide to building a RAG system.\n",
+      "4. What are AI Agents?\n",
+      "\n",
+      "============================================================\n",
+      "\n",
+      "🤔 Enter your question (or 'quit' to exit):\n",
+      "> What is PraisonAI and how do Agents work?\n",
+      "🔍 Processing your question...\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╭─ </span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8; font-weight: bold\">Agent Info</span><span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\"> ────────────────────────────────────────────────────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #ff9b9b; text-decoration-color: #ff9b9b; font-weight: bold\">👤 Agent:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Knowledge Agent</span>                                                                                      <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>  <span style=\"color: #b4b4b3; text-decoration-color: #b4b4b3; font-weight: bold\">Role:</span> <span style=\"color: #ffe5e5; text-decoration-color: #ffe5e5\">Assistant</span>                                                                                                <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>                                                                                                                 <span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">│</span>\n",
+       "<span style=\"color: #d2e3c8; text-decoration-color: #d2e3c8\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[38;2;210;227;200m╭─\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[1;38;2;210;227;200mAgent Info\u001b[0m\u001b[38;2;210;227;200m \u001b[0m\u001b[38;2;210;227;200m───────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[38;2;210;227;200m─╮\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;255;155;155m👤 Agent:\u001b[0m \u001b[38;2;255;229;229mKnowledge Agent\u001b[0m                                                                                      \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m  \u001b[1;38;2;180;180;179mRole:\u001b[0m \u001b[38;2;255;229;229mAssistant\u001b[0m                                                                                                \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m│\u001b[0m                                                                                                                 \u001b[38;2;210;227;200m│\u001b[0m\n",
+       "\u001b[38;2;210;227;200m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "ad296d97510246de8eb0138ce8a8a166",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Output()"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"></pre>\n"
+      ],
+      "text/plain": []
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\">\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #7f7f7f; text-decoration-color: #7f7f7f\">Response generated in 9.4s</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[2mResponse generated in 9.4s\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭───────────────────────────────────────────────────── Task ──────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> What is PraisonAI and how do Agents work?                                                                       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m────────────────────────────────────────────────────\u001b[0m\u001b[36m Task \u001b[0m\u001b[36m─────────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m What is PraisonAI and how do Agents work?                                                                       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "data": {
+      "text/html": [
+       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #008080; text-decoration-color: #008080\">╭─────────────────────────────────────────────────── Response ────────────────────────────────────────────────────╮</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┃                                             <span style=\"font-weight: bold\">What is PraisonAI?</span>                                              ┃ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> productivity. It typically involves developing AI models that can assist in various tasks, automate processes,  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> and provide insights based on data analysis.                                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                            <span style=\"font-weight: bold; text-decoration: underline\">Key Features of PraisonAI</span>                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Task Automation</span>: Automates repetitive tasks, allowing users to focus on more strategic activities.           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Data Insights</span>: Analyzes large sets of data to provide actionable insights.                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Natural Language Processing</span>: Enables users to interact with the AI through natural language, making it       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>user-friendly.                                                                                               <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Customizable Solutions</span>: Tailors AI applications to meet specific user needs across various industries.       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┃                                      <span style=\"font-weight: bold\">How Do Agents Work in PraisonAI?</span>                                       ┃ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or          <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> functions. Here’s how they typically operate:                                                                   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                               <span style=\"font-weight: bold; text-decoration: underline\">1. Types of Agents</span>                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Reactive Agents</span>: Respond to the current environment without internal memory. They act solely based on        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>current inputs.                                                                                              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Deliberative Agents</span>: Have a model of their environment, plan their actions, and retain memories of past      <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>interactions.                                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Learning Agents</span>: Improve their performance over time through experience, adapting to new information.        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                           <span style=\"font-weight: bold; text-decoration: underline\">2. Functionality of Agents</span>                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Task Execution</span>: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>customer support.                                                                                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Interaction</span>: They often interact with users through chat interfaces or APIs, providing a seamless user       <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>experience.                                                                                                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Integration</span>: Can be integrated with other systems or software to enhance functionality, such as CRM systems, <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>databases, or other AI tools.                                                                                <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Continuous Learning</span>: Agents may utilize machine learning algorithms to adapt and evolve based on user        <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\">   </span>interactions and data received.                                                                              <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                           <span style=\"font-weight: bold; text-decoration: underline\">3. Benefits of Using Agents</span>                                           <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Increased Efficiency</span>: Automate routine tasks to reduce workload.                                             <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">24/7 Availability</span>: Provide consistent support and functionality without downtime.                            <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Scalability</span>: Easily scale operations by deploying more agents as needed.                                     <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> <span style=\"color: #808000; text-decoration-color: #808000; font-weight: bold\"> • </span><span style=\"font-weight: bold\">Data-Driven Decisions</span>: Use data insights to inform strategy and operations.                                  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                   <span style=\"font-weight: bold; text-decoration: underline\">Conclusion</span>                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span>                                                                                                                 <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart  <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether   <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> they are simple reactive agents or complex learning entities, their design focuses on making operations         <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">│</span> smoother and more effective.                                                                                    <span style=\"color: #008080; text-decoration-color: #008080\">│</span>\n",
+       "<span style=\"color: #008080; text-decoration-color: #008080\">╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯</span>\n",
+       "</pre>\n"
+      ],
+      "text/plain": [
+       "\u001b[36m╭─\u001b[0m\u001b[36m──────────────────────────────────────────────────\u001b[0m\u001b[36m Response \u001b[0m\u001b[36m───────────────────────────────────────────────────\u001b[0m\u001b[36m─╮\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┃                                             \u001b[1mWhat is PraisonAI?\u001b[0m                                              ┃ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m productivity. It typically involves developing AI models that can assist in various tasks, automate processes,  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m and provide insights based on data analysis.                                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                            \u001b[1;4mKey Features of PraisonAI\u001b[0m                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mTask Automation\u001b[0m: Automates repetitive tasks, allowing users to focus on more strategic activities.           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mData Insights\u001b[0m: Analyzes large sets of data to provide actionable insights.                                   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mNatural Language Processing\u001b[0m: Enables users to interact with the AI through natural language, making it       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0muser-friendly.                                                                                               \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mCustomizable Solutions\u001b[0m: Tailors AI applications to meet specific user needs across various industries.       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┃                                      \u001b[1mHow Do Agents Work in PraisonAI?\u001b[0m                                       ┃ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or          \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m functions. Here’s how they typically operate:                                                                   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                               \u001b[1;4m1. \u001b[0m\u001b[1;4mTypes of Agents\u001b[0m                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mReactive Agents\u001b[0m: Respond to the current environment without internal memory. They act solely based on        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mcurrent inputs.                                                                                              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mDeliberative Agents\u001b[0m: Have a model of their environment, plan their actions, and retain memories of past      \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0minteractions.                                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mLearning Agents\u001b[0m: Improve their performance over time through experience, adapting to new information.        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                           \u001b[1;4m2. \u001b[0m\u001b[1;4mFunctionality of Agents\u001b[0m                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mTask Execution\u001b[0m: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mcustomer support.                                                                                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mInteraction\u001b[0m: They often interact with users through chat interfaces or APIs, providing a seamless user       \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mexperience.                                                                                                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mIntegration\u001b[0m: Can be integrated with other systems or software to enhance functionality, such as CRM systems, \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0mdatabases, or other AI tools.                                                                                \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mContinuous Learning\u001b[0m: Agents may utilize machine learning algorithms to adapt and evolve based on user        \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m   \u001b[0minteractions and data received.                                                                              \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                           \u001b[1;4m3. \u001b[0m\u001b[1;4mBenefits of Using Agents\u001b[0m                                           \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mIncreased Efficiency\u001b[0m: Automate routine tasks to reduce workload.                                             \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1m24/7 Availability\u001b[0m: Provide consistent support and functionality without downtime.                            \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mScalability\u001b[0m: Easily scale operations by deploying more agents as needed.                                     \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m \u001b[1;33m • \u001b[0m\u001b[1mData-Driven Decisions\u001b[0m: Use data insights to inform strategy and operations.                                  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                   \u001b[1;4mConclusion\u001b[0m                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m                                                                                                                 \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart  \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether   \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m they are simple reactive agents or complex learning entities, their design focuses on making operations         \u001b[36m│\u001b[0m\n",
+       "\u001b[36m│\u001b[0m smoother and more effective.                                                                                    \u001b[36m│\u001b[0m\n",
+       "\u001b[36m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "💡 Answer:\n",
+      "========================================\n",
+      "# What is PraisonAI?\n",
+      "\n",
+      "PraisonAI is a platform designed to leverage artificial intelligence to enhance personal and business productivity. It typically involves developing AI models that can assist in various tasks, automate processes, and provide insights based on data analysis.\n",
+      "\n",
+      "## Key Features of PraisonAI\n",
+      "\n",
+      "- **Task Automation**: Automates repetitive tasks, allowing users to focus on more strategic activities.\n",
+      "- **Data Insights**: Analyzes large sets of data to provide actionable insights.\n",
+      "- **Natural Language Processing**: Enables users to interact with the AI through natural language, making it user-friendly.\n",
+      "- **Customizable Solutions**: Tailors AI applications to meet specific user needs across various industries.\n",
+      "\n",
+      "# How Do Agents Work in PraisonAI?\n",
+      "\n",
+      "Agents in PraisonAI refer to autonomous or semi-autonomous AI systems that perform designated tasks or functions. Here’s how they typically operate:\n",
+      "\n",
+      "## 1. **Types of Agents**\n",
+      "\n",
+      "- **Reactive Agents**: Respond to the current environment without internal memory. They act solely based on current inputs.\n",
+      "- **Deliberative Agents**: Have a model of their environment, plan their actions, and retain memories of past interactions.\n",
+      "- **Learning Agents**: Improve their performance over time through experience, adapting to new information.\n",
+      "\n",
+      "## 2. **Functionality of Agents**\n",
+      "\n",
+      "- **Task Execution**: Agents can carry out specific tasks as programmed, such as scheduling, data entry, or customer support.\n",
+      "- **Interaction**: They often interact with users through chat interfaces or APIs, providing a seamless user experience.\n",
+      "- **Integration**: Can be integrated with other systems or software to enhance functionality, such as CRM systems, databases, or other AI tools.\n",
+      "- **Continuous Learning**: Agents may utilize machine learning algorithms to adapt and evolve based on user interactions and data received.\n",
+      "\n",
+      "## 3. **Benefits of Using Agents**\n",
+      "\n",
+      "- **Increased Efficiency**: Automate routine tasks to reduce workload.\n",
+      "- **24/7 Availability**: Provide consistent support and functionality without downtime.\n",
+      "- **Scalability**: Easily scale operations by deploying more agents as needed.\n",
+      "- **Data-Driven Decisions**: Use data insights to inform strategy and operations.\n",
+      "\n",
+      "## Conclusion\n",
+      "\n",
+      "PraisonAI represents a robust platform for enhancing productivity through AI, with agents serving as the heart of this solution, performing various tasks and supporting users in achieving their goals efficiently. Whether they are simple reactive agents or complex learning entities, their design focuses on making operations smoother and more effective.\n",
+      "========================================\n",
+      "\n",
+      "🤔 Enter your question (or 'quit' to exit):\n",
+      "> quit\n",
+      "👋 Goodbye!\n"
+     ]
+    }
+   ],
+   "source": [
+    "def main():\n",
+    "    print(\"�� Initializing Agentic RAG with GPT-5...\")\n",
+    "\n",
+    "    # Check if API key is set\n",
+    "    if not OPENAI_API_KEY or OPENAI_API_KEY == \"your_openai_api_key_here\":\n",
+    "        print(\"❌ Please set your OpenAI API key first!\")\n",
+    "        print(\"�� Get your key from: https://platform.openai.com/\")\n",
+    "        return\n",
+    "\n",
+    "    try:\n",
+    "        # Create agent\n",
+    "        print(\"📚 Loading agent...\")\n",
+    "        agent = create_agent()\n",
+    "        print(\"✅ Agent loaded successfully!\")\n",
+    "\n",
+    "        # Example queries\n",
+    "        example_queries = [\n",
+    "            \"What is PraisonAI and how do Agents work?\",\n",
+    "            \"What are Teams in PraisonAI and how do they work?\",\n",
+    "            \"Give me a step-by-step guide to building a RAG system.\",\n",
+    "            \"What are AI Agents?\"\n",
+    "        ]\n",
+    "\n",
+    "        print(\"\\n🎯 Example queries you can try:\")\n",
+    "        for i, query in enumerate(example_queries, 1):\n",
+    "            print(f\"{i}. {query}\")\n",
+    "\n",
+    "        print(\"\\n\" + \"=\"*60)\n",
+    "\n",
+    "        # Interactive query loop\n",
+    "        while True:\n",
+    "            print(\"\\n🤔 Enter your question (or 'quit' to exit):\")\n",
+    "            user_query = input(\"> \")\n",
+    "\n",
+    "            if user_query.lower() in ['quit', 'exit', 'q']:\n",
+    "                print(\"👋 Goodbye!\")\n",
+    "                break\n",
+    "\n",
+    "            if user_query.strip():\n",
+    "                print(\"🔍 Processing your question...\")\n",
+    "                try:\n",
+    "                    response = agent.start(user_query)\n",
+    "                    print(\"\\n💡 Answer:\")\n",
+    "                    print(\"=\"*40)\n",
+    "                    print(response)\n",
+    "                    print(\"=\"*40)\n",
+    "                except Exception as e:\n",
+    "                    print(f\"❌ Error: {str(e)}\")\n",
+    "                    print(f\"🔍 Error type: {type(e).__name__}\")\n",
+    "                    print(\"💡 This might be due to API issues or model access problems.\")\n",
+    "            else:\n",
+    "                print(\"❌ Please enter a valid question.\")\n",
+    "\n",
+    "    except Exception as e:\n",
+    "        print(f\"❌ Failed to initialize agent: {str(e)}\")\n",
+    "        print(\"�� Make sure your API key is correct and you have sufficient credits.\")\n",
+    "\n",
+    "# Run the main function\n",
+    "if __name__ == \"__main__\":\n",
+    "    main()"
+   ]
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

examples/cookbooks/yaml/aws_bedrock_agents.yaml

@@ -1,10 +1,10 @@
 framework: crewai
 topic: "Technology Research and Content Creation using AWS Bedrock"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   research_specialist:
     role: "Research Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are an experienced technology researcher with deep expertise in analyzing 
       emerging technologies and market trends. You excel at gathering comprehensive 
       information from various sources and synthesizing it into actionable insights.
@@ -35,7 +35,7 @@ roles:
 
   content_creator:
     role: "Technical Content Creator"
-    backstory: |
+    instructions:  # Canonical |
       You are a skilled technical writer and content creator who specializes in 
       translating complex technology concepts into engaging, accessible content 
       for various audiences including developers, business leaders, and end users.
@@ -64,7 +64,7 @@ roles:
 
   quality_reviewer:
     role: "Content Quality Reviewer"
-    backstory: |
+    instructions:  # Canonical |
       You are a meticulous editor and quality assurance specialist with extensive 
       experience in technical content review. You ensure accuracy, clarity, and 
       consistency while maintaining the intended tone and message.

examples/cookbooks/yaml/secondary_market_research_agents.yaml

@@ -8,10 +8,10 @@ variables:
   industry: "Electric Vehicles"
   research_focus: "comprehensive market analysis"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   market_overview_specialist:
     role: "Market Overview Specialist" 
-    backstory: |
+    instructions:  # Canonical |
       You are a seasoned market research analyst with 10+ years of experience 
       in analyzing market dynamics, trends, and growth patterns across various 
       industries. You excel at synthesizing complex market data into clear, 
@@ -64,7 +64,7 @@ roles:
 
   competitive_intelligence_analyst:
     role: "Competitive Intelligence Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a competitive intelligence expert specializing in analyzing 
       competitive landscapes, market positioning, and strategic intelligence. 
       You have deep expertise in competitor analysis, market share assessment, 
@@ -119,7 +119,7 @@ roles:
 
   financial_performance_analyst:
     role: "Financial Performance Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a financial analyst with expertise in corporate finance, 
       financial statement analysis, and industry benchmarking. You specialize 
       in analyzing financial performance metrics, trends, and comparative 
@@ -173,7 +173,7 @@ roles:
 
   growth_opportunities_researcher:
     role: "Growth Opportunities Researcher"
-    backstory: |
+    instructions:  # Canonical |
       You are a strategic business analyst specializing in identifying growth 
       opportunities, market expansion strategies, and emerging business models. 
       You excel at spotting trends, gaps, and untapped potential in markets 
@@ -228,7 +228,7 @@ roles:
 
   risk_assessment_specialist:
     role: "Risk Assessment Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are a risk management expert with extensive experience in identifying, 
       analyzing, and assessing business risks across various industries. You 
       specialize in market risks, competitive threats, regulatory challenges, 
@@ -287,7 +287,7 @@ roles:
 
   research_report_synthesizer:
     role: "Research Report Synthesizer"
-    backstory: |
+    instructions:  # Canonical |
       You are an expert business report writer and analyst with extensive 
       experience in synthesizing complex research findings into clear, 
       actionable business intelligence reports. You excel at creating 

examples/python/a2a/a2a-server.py

@@ -0,0 +1,53 @@
+"""
+PraisonAI A2A Server Example
+
+Expose a PraisonAI Agent as an A2A (Agent2Agent) Server.
+This enables other AI agents to discover and communicate with your agent.
+
+Run:
+    uvicorn a2a-server:app --reload
+
+Endpoints:
+    GET /.well-known/agent.json  - Agent Card for discovery
+    GET /status                   - Server status
+"""
+
+from praisonaiagents import Agent, A2A
+from fastapi import FastAPI
+
+# Create an agent with tools
+def search_web(query: str) -> str:
+    """Search the web for information."""
+    return f"Search results for: {query}"
+
+def calculate(expression: str) -> str:
+    """Calculate a mathematical expression."""
+    try:
+        return f"Result: {eval(expression)}"
+    except Exception:
+        return "Invalid expression"
+
+agent = Agent(
+    name="Research Assistant",
+    role="Research Analyst",
+    goal="Help users research topics and answer questions",
+    tools=[search_web, calculate]
+)
+
+# Expose as A2A Server
+a2a = A2A(
+    agent=agent,
+    url="http://localhost:8000/a2a",
+    version="1.0.0"
+)
+
+# Create FastAPI app
+app = FastAPI(
+    title="PraisonAI A2A Server",
+    description="A2A-compatible agent server"
+)
+app.include_router(a2a.get_router())
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

examples/python/agents/autoagents_workflow_patterns.py

@@ -0,0 +1,132 @@
+"""
+AutoAgents Workflow Patterns Example
+
+This example demonstrates the new workflow auto-generation features:
+- Dynamic agent count based on task complexity
+- Multiple workflow patterns (sequential, parallel, routing, orchestrator-workers, evaluator-optimizer)
+- Pattern recommendation based on task keywords
+
+Documentation: https://docs.praison.ai/features/autoagents
+CLI Reference: https://docs.praison.ai/nocode/auto
+"""
+
+from praisonai.auto import AutoGenerator, WorkflowAutoGenerator
+import os
+import tempfile
+
+# Ensure API key is set
+if not os.environ.get("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    exit(1)
+
+print("=" * 60)
+print("AutoAgents Workflow Patterns Demo")
+print("=" * 60)
+
+# =============================================================================
+# Example 1: Dynamic Agent Count (Simple vs Complex Tasks)
+# =============================================================================
+print("\n📊 Example 1: Dynamic Agent Count")
+print("-" * 40)
+
+# Simple task - should create 1-2 agents
+with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+    simple_file = f.name
+
+simple_generator = AutoGenerator(
+    topic="Write a haiku about spring",
+    agent_file=simple_file,
+    framework="praisonai"
+)
+
+print("Simple task: 'Write a haiku about spring'")
+result = simple_generator.generate()
+print(f"Generated: {result}")
+
+# Complex task - should create 3-4 agents
+with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+    complex_file = f.name
+
+complex_generator = AutoGenerator(
+    topic="Research AI trends, analyze market data, write a comprehensive report with executive summary",
+    agent_file=complex_file,
+    framework="praisonai"
+)
+
+print("\nComplex task: 'Research AI trends, analyze market data...'")
+result = complex_generator.generate()
+print(f"Generated: {result}")
+
+# =============================================================================
+# Example 2: Pattern Recommendation
+# =============================================================================
+print("\n🎯 Example 2: Pattern Recommendation")
+print("-" * 40)
+
+test_tasks = [
+    ("Write a blog post", "sequential"),
+    ("Research from multiple sources simultaneously", "parallel"),
+    ("Classify and route customer requests", "routing"),
+    ("Comprehensive analysis and break down the problem", "orchestrator-workers"),
+    ("Refine and improve content quality", "evaluator-optimizer"),
+]
+
+for task, expected in test_tasks:
+    generator = WorkflowAutoGenerator(topic=task)
+    recommended = generator.recommend_pattern()
+    status = "✅" if recommended == expected else "⚠️"
+    print(f"{status} Task: '{task[:40]}...'")
+    print(f"   Recommended: {recommended}")
+
+# =============================================================================
+# Example 3: Generate Workflow with Specific Pattern
+# =============================================================================
+print("\n🔄 Example 3: Generate Workflows with Patterns")
+print("-" * 40)
+
+patterns = ["sequential", "parallel", "orchestrator-workers", "evaluator-optimizer"]
+
+for pattern in patterns:
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        workflow_file = f.name
+    
+    generator = WorkflowAutoGenerator(
+        topic="Create a market analysis report",
+        workflow_file=workflow_file
+    )
+    
+    print(f"\n📋 Pattern: {pattern}")
+    result = generator.generate(pattern=pattern)
+    print(f"   Generated: {result}")
+    
+    # Read and show structure
+    import yaml
+    with open(result, 'r') as f:
+        data = yaml.safe_load(f)
+    print(f"   Agents: {list(data.get('agents', {}).keys())}")
+    print(f"   Steps: {len(data.get('steps', []))}")
+
+# =============================================================================
+# Example 4: CLI Usage (for reference)
+# =============================================================================
+print("\n💻 Example 4: CLI Commands (for reference)")
+print("-" * 40)
+print("""
+# Auto-generate agents (dynamic count)
+praisonai --auto "Write a haiku about spring"
+
+# Auto-generate workflow with pattern
+praisonai workflow auto "Research and write a report" --pattern sequential
+praisonai workflow auto "Research from multiple sources" --pattern parallel
+praisonai workflow auto "Comprehensive market analysis" --pattern orchestrator-workers
+praisonai workflow auto "Refine content quality" --pattern evaluator-optimizer
+
+# With output file
+praisonai workflow auto "Customer support routing" --pattern routing --output support.yaml
+""")
+
+print("\n" + "=" * 60)
+print("✅ AutoAgents Workflow Patterns Demo Complete!")
+print("=" * 60)
+print("\nDocumentation: https://docs.praison.ai/features/autoagents")
+print("CLI Reference: https://docs.praison.ai/nocode/auto")

examples/python/cli/autonomy_modes_example.py

@@ -0,0 +1,38 @@
+"""
+Autonomy Modes Example for PraisonAI CLI.
+
+Control AI autonomy: suggest, auto_edit, full_auto.
+Docs: https://docs.praison.ai/cli/autonomy-modes
+"""
+
+from praisonai.cli.features import AutonomyModeHandler
+from praisonai.cli.features.autonomy_mode import ActionRequest, ActionType
+
+# Initialize with suggest mode (safest)
+handler = AutonomyModeHandler()
+manager = handler.initialize(mode="suggest")
+
+print(f"Current mode: {handler.get_mode()}")
+print("Available modes: suggest, auto_edit, full_auto")
+
+# Create an action request
+action = ActionRequest(
+    action_type=ActionType.FILE_WRITE,
+    description="Edit src/main.py to add logging",
+    details={"file": "src/main.py"}
+)
+
+# In suggest mode, this would require approval
+# For demo, we'll just show the action
+print(f"\nAction: {action.description}")
+print(f"Type: {action.action_type.value}")
+print("Would require approval in 'suggest' mode")
+
+# Change to auto_edit mode
+handler.set_mode("auto_edit")
+print(f"\nChanged to: {handler.get_mode()}")
+print("File edits now auto-approved, shell commands still require approval")
+
+# Get statistics
+stats = handler.get_stats()
+print(f"\nStats: {stats}")

examples/python/cli/cost_tracking_example.py

@@ -0,0 +1,34 @@
+"""
+Cost Tracking Example for PraisonAI CLI.
+
+Real-time token usage and cost monitoring.
+Docs: https://docs.praison.ai/cli/cost-tracking
+"""
+
+from praisonai.cli.features import CostTrackerHandler
+
+# Initialize tracker
+handler = CostTrackerHandler()
+tracker = handler.initialize(session_id="demo-session")
+
+# Track some requests
+handler.track_request("gpt-4o", input_tokens=1000, output_tokens=500)
+handler.track_request("gpt-4o-mini", input_tokens=2000, output_tokens=800)
+handler.track_request("claude-3-5-sonnet", input_tokens=1500, output_tokens=600)
+
+# Get totals
+print(f"Total tokens: {handler.get_tokens():,}")
+print(f"Total cost: ${handler.get_cost():.4f}")
+
+# Get detailed summary
+summary = handler.get_summary()
+print("\n=== Session Summary ===")
+print(f"Session ID: {summary['session_id']}")
+print(f"Total requests: {summary['total_requests']}")
+print(f"Input tokens: {summary['total_input_tokens']:,}")
+print(f"Output tokens: {summary['total_output_tokens']:,}")
+print(f"Total cost: ${summary['total_cost']:.4f}")
+print(f"Avg cost/request: ${summary['avg_cost_per_request']:.4f}")
+
+# Display formatted (uses Rich if available)
+handler.display_summary()

examples/python/cli/git_integration_example.py

@@ -0,0 +1,45 @@
+"""
+Git Integration Example for PraisonAI CLI.
+
+Auto-commit with AI messages, diff viewing, undo.
+Docs: https://docs.praison.ai/cli/git-integration
+"""
+
+from praisonai.cli.features import GitIntegrationHandler
+
+# Initialize
+handler = GitIntegrationHandler(verbose=True)
+git = handler.initialize(repo_path=".")
+
+# Check if it's a git repo
+if not git.is_repo:
+    print("Not a git repository!")
+    exit(1)
+
+# Show status
+print("=== Git Status ===")
+status = handler.show_status()
+print(f"Branch: {status.branch}")
+print(f"Staged: {len(status.staged_files)}")
+print(f"Modified: {len(status.modified_files)}")
+print(f"Untracked: {len(status.untracked_files)}")
+
+# Show diff (if any changes)
+if status.has_changes:
+    print("\n=== Diff ===")
+    diff = handler.show_diff()
+    if diff:
+        print(diff[:300] + "..." if len(diff) > 300 else diff)
+
+# Show recent commits
+print("\n=== Recent Commits ===")
+commits = handler.show_log(count=5)
+for c in commits:
+    print(f"  {c.short_hash} {c.message[:50]}")
+
+# To commit with AI message:
+# commit = handler.commit()  # Auto-generates message
+# commit = handler.commit(message="Custom message")
+
+# To undo last commit:
+# handler.undo(soft=True)  # Keeps changes staged

examples/python/cli/interactive_tui_example.py

@@ -0,0 +1,49 @@
+"""
+Interactive TUI Example for PraisonAI CLI.
+
+Rich terminal interface with completions and history.
+Docs: https://docs.praison.ai/cli/interactive-tui
+"""
+
+from praisonai.cli.features import InteractiveTUIHandler
+from praisonai.cli.features.interactive_tui import InteractiveConfig
+
+# Custom configuration
+config = InteractiveConfig(
+    prompt="ai> ",
+    multiline=True,
+    enable_completions=True,
+    show_status_bar=True
+)
+
+# Define callbacks
+def on_input(text):
+    """Handle regular input."""
+    return f"You said: {text}"
+
+def on_command(cmd):
+    """Handle slash commands."""
+    if cmd == "/exit":
+        return {"type": "exit"}
+    return {"type": "command", "message": f"Executed: {cmd}"}
+
+# Initialize
+handler = InteractiveTUIHandler()
+session = handler.initialize(
+    config=config,
+    on_input=on_input,
+    on_command=on_command
+)
+
+# Add commands for completion
+session.add_commands(["help", "exit", "cost", "model", "plan"])
+
+# Add symbols from codebase
+session.add_symbols(["MyClass", "my_function"])
+
+print("Interactive TUI initialized!")
+print("Commands available: /help, /exit, /cost, /model, /plan")
+print("Run handler.run() to start interactive session")
+
+# Uncomment to run interactive session:
+# handler.run()

examples/python/cli/repo_map_example.py

@@ -0,0 +1,24 @@
+"""
+Repository Map Example for PraisonAI CLI.
+
+Intelligent codebase mapping with symbol extraction.
+Docs: https://docs.praison.ai/cli/repo-map
+"""
+
+from praisonai.cli.features import RepoMapHandler
+
+# Initialize with current directory
+handler = RepoMapHandler(verbose=True)
+repo_map = handler.initialize(root=".")
+
+# Get the repository map
+print("=== Repository Map ===")
+map_str = handler.get_map()
+print(map_str[:500] if len(map_str) > 500 else map_str)
+print("..." if len(map_str) > 500 else "")
+
+# Refresh after file changes
+handler.refresh()
+
+# Get symbols for a specific file (if exists)
+# symbols = handler.get_context("MyClass")

examples/python/cli/sandbox_execution_example.py

@@ -0,0 +1,42 @@
+"""
+Sandbox Execution Example for PraisonAI CLI.
+
+Secure isolated command execution (--sandbox flag).
+Docs: https://docs.praison.ai/cli/sandbox-execution
+"""
+
+from praisonai.cli.features import SandboxExecutorHandler
+from praisonai.cli.features.sandbox_executor import SandboxMode
+
+# Initialize with basic sandbox
+handler = SandboxExecutorHandler(verbose=True)
+sandbox = handler.initialize(mode="basic")
+
+print(f"Sandbox mode: {handler.get_mode()}")
+print(f"Sandbox enabled: {handler.is_enabled}")
+
+# Execute a safe command
+print("\n=== Safe Command ===")
+result = handler.execute("echo 'Hello from sandbox!'")
+print(f"Success: {result.success}")
+print(f"Output: {result.stdout.strip()}")
+print(f"Sandboxed: {result.was_sandboxed}")
+
+# Try a blocked command
+print("\n=== Blocked Command ===")
+result = handler.execute("rm -rf /")
+print(f"Success: {result.success}")
+print(f"Violations: {result.policy_violations}")
+
+# Validate command before execution
+print("\n=== Command Validation ===")
+violations = handler.validate_command("sudo apt install something")
+if violations:
+    print(f"Command blocked: {violations}")
+else:
+    print("Command allowed")
+
+# Available modes
+print("\n=== Available Modes ===")
+for mode in SandboxMode:
+    print(f"  {mode.value}")

examples/python/cli/slash_commands_example.py

@@ -0,0 +1,51 @@
+"""
+Slash Commands Example for PraisonAI CLI.
+
+Demonstrates interactive slash commands like /help, /cost, /model.
+Docs: https://docs.praison.ai/cli/slash-commands
+"""
+
+from praisonai.cli.features import SlashCommandHandler
+from praisonai.cli.features.slash_commands import SlashCommand, CommandKind
+
+# Create handler
+handler = SlashCommandHandler()
+
+# Execute commands
+print("=== /help ===")
+result = handler.execute("/help")
+print(result.get("message", ""))
+
+print("\n=== /cost ===")
+result = handler.execute("/cost")
+print(result.get("message", ""))
+
+print("\n=== /model ===")
+result = handler.execute("/model")
+print(result.get("message", ""))
+
+# Check if input is a command
+print("\n=== Command Detection ===")
+print(f"/help is command: {handler.is_command('/help')}")
+print(f"hello is command: {handler.is_command('hello')}")
+
+# Get completions for auto-complete
+print("\n=== Completions for '/he' ===")
+completions = handler.get_completions("/he")
+print(completions)
+
+# Register custom command
+def my_custom_handler(args, context):
+    return {"type": "custom", "message": f"Custom command with args: {args}"}
+
+custom_cmd = SlashCommand(
+    name="mycommand",
+    description="My custom command",
+    handler=my_custom_handler,
+    kind=CommandKind.ACTION,
+    aliases=["mc"]
+)
+
+handler.register(custom_cmd)
+result = handler.execute("/mycommand arg1 arg2")
+print(f"\n=== Custom Command ===\n{result.get('message', '')}")

examples/python/code/claude_code_example.py

@@ -0,0 +1,34 @@
+"""
+Claude Code CLI Integration Example
+
+Demonstrates how to use Claude Code CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import ClaudeCodeIntegration
+
+async def main():
+    # Create Claude Code integration
+    claude = ClaudeCodeIntegration(
+        workspace=".",
+        output_format="json",
+        skip_permissions=True,
+        system_prompt="Be concise and follow best practices",
+        allowed_tools=["Read", "Write", "Bash"]
+    )
+    
+    # Check availability
+    print(f"Claude CLI available: {claude.is_available}")
+    print(f"Claude SDK available: {claude.sdk_available}")
+    
+    # Execute a coding task
+    result = await claude.execute("List all Python files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream output
+    print("\nStreaming output:")
+    async for event in claude.stream("Explain the project structure"):
+        print(event)
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/code_editing_example.py

@@ -0,0 +1,60 @@
+"""
+Code Editing Tools Example
+
+Demonstrates how to use PraisonAI's code editing tools with SEARCH/REPLACE diffs.
+"""
+
+from praisonai.code import (
+    set_workspace,
+    code_read_file,
+    code_write_file,
+    code_apply_diff,
+    code_list_files,
+    code_execute_command,
+    CODE_TOOLS
+)
+
+# Set workspace
+set_workspace(".")
+
+# List files
+print("Files in current directory:")
+files = code_list_files(".", recursive=False)
+for f in files:
+    print(f"  {f}")
+
+# Read a file
+print("\nReading example file:")
+try:
+    content = code_read_file("README.md", start_line=1, end_line=10)
+    print(content)
+except Exception as e:
+    print(f"  File not found: {e}")
+
+# Write a file
+print("\nWriting test file:")
+code_write_file("test_output.txt", "Hello from PraisonAI Code Tools!")
+print("  Created test_output.txt")
+
+# Apply a diff
+print("\nApplying diff:")
+diff = """
+<<<<<<< SEARCH
+Hello from PraisonAI Code Tools!
+=======
+Hello from PraisonAI Code Tools!
+This line was added by a diff.
+>>>>>>> REPLACE
+"""
+result = code_apply_diff("test_output.txt", diff)
+print(f"  {result}")
+
+# Execute command
+print("\nExecuting command:")
+output = code_execute_command("cat test_output.txt")
+print(f"  {output}")
+
+# Cleanup
+import os
+os.remove("test_output.txt")
+print("\nCleanup complete.")

examples/python/code/codex_cli_example.py

@@ -0,0 +1,36 @@
+"""
+Codex CLI Integration Example
+
+Demonstrates how to use OpenAI Codex CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import CodexCLIIntegration
+
+async def main():
+    # Create Codex CLI integration
+    codex = CodexCLIIntegration(
+        workspace=".",
+        full_auto=True,
+        sandbox="danger-full-access",
+        json_output=True
+    )
+    
+    # Check availability
+    print(f"Codex CLI available: {codex.is_available}")
+    print(f"Full Auto: {codex.full_auto}")
+    print(f"Sandbox: {codex.sandbox}")
+    
+    # Execute a coding task
+    result = await codex.execute("List files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream JSON events
+    print("\nStreaming events:")
+    async for event in codex.stream("Explain the project"):
+        event_type = event.get("type", "")
+        if event_type == "item.completed":
+            print(f"  {event}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/cursor_cli_example.py

@@ -0,0 +1,37 @@
+"""
+Cursor CLI Integration Example
+
+Demonstrates how to use Cursor CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import CursorCLIIntegration
+
+async def main():
+    # Create Cursor CLI integration
+    cursor = CursorCLIIntegration(
+        workspace=".",
+        output_format="json",
+        force=True,
+        model="gpt-5",
+        stream_partial=True
+    )
+    
+    # Check availability
+    print(f"Cursor CLI available: {cursor.is_available}")
+    print(f"Force mode: {cursor.force}")
+    print(f"Model: {cursor.model}")
+    
+    # Execute a coding task
+    result = await cursor.execute("List files in the current directory")
+    print(f"Result: {result}")
+    
+    # Stream output
+    print("\nStreaming output:")
+    async for event in cursor.stream("Explain the project"):
+        content = event.get("content", "")
+        if content:
+            print(content, end="", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/external_agents_example.py

@@ -0,0 +1,58 @@
+"""
+External Agents Integration Example
+
+Demonstrates how to use all external CLI integrations as agent tools.
+"""
+
+import asyncio
+from praisonai.integrations import (
+    ClaudeCodeIntegration,
+    GeminiCLIIntegration,
+    CodexCLIIntegration,
+    CursorCLIIntegration,
+    get_available_integrations
+)
+
+async def main():
+    # Check availability of all integrations
+    print("=== External CLI Integrations ===\n")
+    
+    availability = get_available_integrations()
+    print("Availability:")
+    for name, avail in availability.items():
+        status = "✅" if avail else "❌"
+        print(f"  {status} {name}")
+    
+    # Create integrations
+    print("\n--- Claude Code ---")
+    claude = ClaudeCodeIntegration(workspace=".", skip_permissions=True)
+    print(f"CLI: {claude.cli_command}")
+    print(f"Available: {claude.is_available}")
+    tool = claude.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Gemini CLI ---")
+    gemini = GeminiCLIIntegration(workspace=".", model="gemini-2.5-flash")
+    print(f"CLI: {gemini.cli_command}")
+    print(f"Available: {gemini.is_available}")
+    tool = gemini.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Codex CLI ---")
+    codex = CodexCLIIntegration(workspace=".", full_auto=True)
+    print(f"CLI: {codex.cli_command}")
+    print(f"Available: {codex.is_available}")
+    tool = codex.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n--- Cursor CLI ---")
+    cursor = CursorCLIIntegration(workspace=".", force=True)
+    print(f"CLI: {cursor.cli_command}")
+    print(f"Available: {cursor.is_available}")
+    tool = cursor.as_tool()
+    print(f"Tool: {tool.__name__}")
+    
+    print("\n=== All integrations ready ===")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/code/gemini_cli_example.py

@@ -0,0 +1,33 @@
+"""
+Gemini CLI Integration Example
+
+Demonstrates how to use Gemini CLI as an agent tool in PraisonAI.
+"""
+
+import asyncio
+from praisonai.integrations import GeminiCLIIntegration
+
+async def main():
+    # Create Gemini CLI integration
+    gemini = GeminiCLIIntegration(
+        workspace=".",
+        model="gemini-2.5-flash",
+        output_format="json",
+        include_directories=["../lib", "../docs"]
+    )
+    
+    # Check availability
+    print(f"Gemini CLI available: {gemini.is_available}")
+    print(f"Model: {gemini.model}")
+    
+    # Execute a coding task
+    result = await gemini.execute("Analyze the code structure")
+    print(f"Result: {result}")
+    
+    # Execute with stats
+    result, stats = await gemini.execute_with_stats("Explain main.py")
+    print(f"Result: {result}")
+    print(f"Stats: {stats}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/python/general/auto_agents_example.py

@@ -1,11 +1,48 @@
+"""
+AutoAgents Example
+
+AutoAgents automatically creates and manages AI agents based on high-level instructions.
+It features dynamic agent count based on task complexity.
+
+Documentation: https://docs.praison.ai/features/autoagents
+CLI Reference: https://docs.praison.ai/nocode/auto
+
+New Features:
+- Dynamic agent count (1-4 based on task complexity)
+- Workflow patterns: sequential, parallel, routing, orchestrator-workers, evaluator-optimizer
+- Pattern recommendation based on task keywords
+- Tool preservation from LLM suggestions
+"""
+
 from praisonaiagents import AutoAgents
 from praisonaiagents.tools import duckduckgo
 
+# Basic usage - AutoAgents analyzes complexity and creates optimal agents
 agents = AutoAgents(
     instructions="Search for information about AI Agents",
     tools=[duckduckgo],
-    process="sequential",
-    verbose=True
+    process="sequential",  # or "hierarchical"
+    verbose=True,
+    max_agents=3  # Maximum number of agents to create
 )
 
-agents.start()
+result = agents.start()
+print(result)
+
+# =============================================================================
+# CLI Usage Examples (for reference)
+# =============================================================================
+# 
+# # Auto-generate agents (dynamic count based on complexity)
+# praisonai --auto "Write a haiku about spring"
+# praisonai --auto "Research AI trends, analyze data, write report"
+#
+# # Auto-generate workflow with specific pattern
+# praisonai workflow auto "Research and write" --pattern sequential
+# praisonai workflow auto "Research from multiple sources" --pattern parallel
+# praisonai workflow auto "Comprehensive analysis" --pattern orchestrator-workers
+# praisonai workflow auto "Refine content quality" --pattern evaluator-optimizer
+#
+# # With framework selection
+# praisonai --framework crewai --auto "Create a movie script"
+# praisonai --framework autogen --auto "Create a movie script"

examples/python/mcp/mcp-backward-compat.py

@@ -0,0 +1,83 @@
+"""
+MCP Backward Compatibility Example
+
+Demonstrates backward compatibility with older MCP servers
+using the deprecated HTTP+SSE transport (protocol version 2024-11-05).
+
+Features:
+- Legacy SSE endpoint detection (/sse suffix)
+- Automatic transport negotiation
+- Protocol version support (2024-11-05 to 2025-11-25)
+
+Protocol: MCP 2025-11-25 with 2024-11-05 compatibility
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # Legacy SSE server (auto-detected via /sse suffix)
+# agent_legacy = Agent(
+#     name="Legacy SSE Assistant",
+#     tools=MCP("http://localhost:8080/sse")
+# )
+#
+# # Modern Streamable HTTP server
+# agent_modern = Agent(
+#     name="Modern HTTP Assistant",
+#     tools=MCP("http://localhost:8080/mcp")
+# )
+
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_transport import get_transport_type
+    from praisonaiagents.mcp.mcp_compat import (
+        detect_transport_support,
+        is_legacy_sse_url,
+        TransportNegotiator
+    )
+    from praisonaiagents.mcp.mcp_session import VALID_PROTOCOL_VERSIONS
+    
+    print("MCP Backward Compatibility Example")
+    print("=" * 50)
+    
+    # URL detection
+    print("\n1. URL-based Transport Detection:")
+    urls = [
+        "http://localhost:8080/sse",
+        "https://api.example.com/sse",
+        "http://localhost:8080/mcp",
+        "https://api.example.com/mcp",
+    ]
+    for url in urls:
+        transport = get_transport_type(url)
+        legacy = is_legacy_sse_url(url)
+        print(f"   {url}")
+        print(f"      Transport: {transport}, Legacy: {legacy}")
+    
+    # Transport negotiation
+    print("\n2. Transport Negotiation (HTTP response based):")
+    responses = [
+        (200, "application/json", "Streamable HTTP"),
+        (200, "text/event-stream", "SSE stream"),
+        (400, None, "Fallback to SSE"),
+        (404, None, "Fallback to SSE"),
+        (405, None, "Fallback to SSE"),
+    ]
+    for status, content_type, desc in responses:
+        detected = detect_transport_support(status, content_type)
+        print(f"   HTTP {status} ({desc}): {detected}")
+    
+    # Protocol versions
+    print("\n3. Supported Protocol Versions:")
+    for version in sorted(VALID_PROTOCOL_VERSIONS):
+        print(f"   - {version}")
+    
+    # Negotiator
+    print("\n4. Transport Negotiator:")
+    negotiator = TransportNegotiator("https://api.example.com/mcp")
+    print(f"   Base URL: {negotiator.base_url}")
+    print(f"   Try Streamable first: {negotiator.should_try_streamable_first()}")
+    
+    negotiator_sse = TransportNegotiator("https://api.example.com/sse")
+    print(f"   SSE URL: {negotiator_sse.base_url}")
+    print(f"   Try Streamable first: {negotiator_sse.should_try_streamable_first()}")

examples/python/mcp/mcp-custom-transport.py

@@ -0,0 +1,110 @@
+"""
+MCP Custom Transport Example
+
+Demonstrates how to create custom MCP transports by extending
+the BaseTransport class.
+
+Features:
+- BaseTransport abstract class
+- TransportRegistry for registration
+- TransportConfig for configuration
+- Pluggable transport mechanism
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents.mcp.mcp_transport import (
+    BaseTransport,
+    TransportConfig,
+    TransportRegistry,
+    get_default_registry
+)
+
+# Custom transport implementation
+class MyCustomTransport(BaseTransport):
+    """Example custom transport implementation."""
+    
+    def __init__(self, url: str, config: TransportConfig = None):
+        self.url = url
+        self.config = config or TransportConfig()
+        self._connected = False
+    
+    async def connect(self):
+        """Establish connection."""
+        print(f"Connecting to {self.url}...")
+        self._connected = True
+        print("Connected!")
+    
+    async def send(self, message: dict):
+        """Send JSON-RPC message."""
+        if not self._connected:
+            raise RuntimeError("Not connected")
+        print(f"Sending: {message}")
+    
+    async def receive(self) -> dict:
+        """Receive JSON-RPC message."""
+        if not self._connected:
+            raise RuntimeError("Not connected")
+        return {"jsonrpc": "2.0", "result": "ok", "id": 1}
+    
+    async def close(self):
+        """Close connection."""
+        print("Closing connection...")
+        self._connected = False
+    
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+
+if __name__ == "__main__":
+    import asyncio
+    
+    print("MCP Custom Transport Example")
+    print("=" * 50)
+    
+    # 1. Transport configuration
+    print("\n1. Transport Configuration:")
+    config = TransportConfig(
+        timeout=60,
+        debug=True,
+        retry_count=3,
+        retry_delay=1.0,
+        auth_token="my-token"
+    )
+    print(f"   Timeout: {config.timeout}s")
+    print(f"   Debug: {config.debug}")
+    print(f"   Retry count: {config.retry_count}")
+    
+    # 2. Default registry
+    print("\n2. Default Transport Registry:")
+    registry = get_default_registry()
+    print(f"   Registered transports: {registry.list_transports()}")
+    
+    # 3. Register custom transport
+    print("\n3. Registering Custom Transport:")
+    custom_registry = TransportRegistry()
+    custom_registry.register("my_custom", MyCustomTransport)
+    print(f"   Registered: {custom_registry.list_transports()}")
+    
+    # 4. Use custom transport
+    print("\n4. Using Custom Transport:")
+    
+    async def demo():
+        transport = MyCustomTransport("custom://localhost:8080", config)
+        
+        async with transport:
+            await transport.send({"jsonrpc": "2.0", "method": "test", "id": 1})
+            response = await transport.receive()
+            print(f"   Response: {response}")
+    
+    asyncio.run(demo())
+    
+    # 5. BaseTransport interface
+    print("\n5. BaseTransport Interface:")
+    print("   Required methods:")
+    print("   - async connect()")
+    print("   - async send(message: dict)")
+    print("   - async receive() -> dict")
+    print("   - async close()")
+    print("   - @property is_connected -> bool")

examples/python/mcp/mcp-resumability.py

@@ -0,0 +1,47 @@
+"""
+MCP Resumability Example
+
+Demonstrates SSE stream resumability for MCP transports.
+Resumability allows recovering from disconnections without losing messages.
+
+Features:
+- Event ID tracking per stream
+- Last-Event-ID header on reconnection
+- Retry delay handling from server
+- Message replay on reconnection
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Agent with resumability support (automatic)
+agent = Agent(
+    name="Resumable Assistant",
+    instructions="You are a helpful assistant with resumable connections.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# Resumability is automatic - the MCP client:
+# 1. Tracks event IDs from SSE streams (id: field)
+# 2. Stores last event ID per stream
+# 3. Includes Last-Event-ID header on reconnection
+# 4. Respects retry delay from server (retry: field)
+
+if __name__ == "__main__":
+    print("MCP Resumability Example")
+    print("=" * 40)
+    print()
+    print("SSE Event Format:")
+    print("  id: event-123")
+    print("  retry: 3000")
+    print("  data: {\"jsonrpc\": \"2.0\", ...}")
+    print()
+    print("Resumability Flow:")
+    print("1. Client receives SSE events with id: field")
+    print("2. Client stores last event ID")
+    print("3. On disconnection, client reconnects with Last-Event-ID header")
+    print("4. Server replays messages after that event ID")
+    print("5. Client respects retry: field for reconnection delay")
+    print()
+    print("This prevents message loss during network interruptions.")

examples/python/mcp/mcp-schema-converter.py

@@ -0,0 +1,82 @@
+"""MCP Schema Converter Example
+
+Demonstrates how to convert Python functions to MCP-compatible schemas.
+
+Usage:
+    python mcp-schema-converter.py
+"""
+
+from typing import List, Dict, Any, Optional
+from praisonaiagents.mcp import function_to_mcp_schema, get_tool_metadata
+
+
+# Example functions with various type annotations
+
+def simple_search(query: str) -> str:
+    """Search for information."""
+    return f"Results for {query}"
+
+
+def advanced_search(
+    query: str,
+    max_results: int = 10,
+    include_images: bool = False,
+    filters: Optional[Dict[str, str]] = None
+) -> Dict[str, Any]:
+    """Advanced search with multiple options.
+    
+    Args:
+        query: The search query
+        max_results: Maximum results to return
+        include_images: Whether to include images
+        filters: Optional filters to apply
+    """
+    return {}
+
+
+def process_items(items: List[str], batch_size: int = 5) -> List[Dict[str, Any]]:
+    """Process a list of items.
+    
+    Args:
+        items: List of items to process
+        batch_size: Size of each batch
+    """
+    return []
+
+
+async def async_fetch(url: str, timeout: float = 30.0) -> Dict[str, Any]:
+    """Fetch data from URL asynchronously.
+    
+    Args:
+        url: The URL to fetch
+        timeout: Request timeout in seconds
+    """
+    return {}
+
+
+def main():
+    functions = [simple_search, advanced_search, process_items, async_fetch]
+    
+    print("=" * 60)
+    print("MCP Schema Converter Demo")
+    print("=" * 60)
+    
+    for func in functions:
+        print(f"\n### Function: {func.__name__}")
+        
+        # Get metadata
+        metadata = get_tool_metadata(func)
+        print(f"Name: {metadata['name']}")
+        print(f"Description: {metadata['description']}")
+        
+        # Get full schema
+        schema = function_to_mcp_schema(func)
+        
+        print("\nMCP Schema:")
+        import json
+        print(json.dumps(schema, indent=2))
+        print("-" * 40)
+
+
+if __name__ == "__main__":
+    main()

examples/python/mcp/mcp-security.py

@@ -0,0 +1,79 @@
+"""
+MCP Security Example
+
+Demonstrates security features for MCP transports.
+These features help prevent attacks like DNS rebinding.
+
+Features:
+- Origin header validation
+- DNS rebinding prevention
+- Localhost binding for local servers
+- Authentication header support
+- Secure session ID generation
+
+Protocol: MCP 2025-11-25
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # Agent with authentication
+# agent = Agent(
+#     name="Secure Assistant",
+#     tools=MCP(
+#         "https://api.example.com/mcp",
+#         headers={"Authorization": "Bearer your-token"}
+#     )
+# )
+#
+# # WebSocket with auth token
+# agent_ws = Agent(
+#     name="Secure WebSocket Assistant",
+#     tools=MCP(
+#         "wss://api.example.com/mcp",
+#         auth_token="Bearer your-secret-token"
+#     )
+# )
+
+# Using security utilities directly (no server required)
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_security import (
+        is_valid_origin,
+        create_auth_header,
+        generate_secure_session_id,
+        SecurityConfig
+    )
+    
+    print("MCP Security Example")
+    print("=" * 40)
+    
+    # Origin validation (DNS rebinding prevention)
+    print("\n1. Origin Validation:")
+    allowed = ["localhost", "127.0.0.1", "example.com"]
+    print(f"   Allowed origins: {allowed}")
+    print(f"   'http://localhost:8080' valid: {is_valid_origin('http://localhost:8080', allowed)}")
+    print(f"   'https://evil.com' valid: {is_valid_origin('https://evil.com', allowed)}")
+    
+    # Authentication headers
+    print("\n2. Authentication Headers:")
+    bearer = create_auth_header("my-token", auth_type="bearer")
+    print(f"   Bearer: {bearer}")
+    basic = create_auth_header("user:pass", auth_type="basic")
+    print(f"   Basic: {basic}")
+    
+    # Secure session IDs
+    print("\n3. Secure Session IDs:")
+    session_id = generate_secure_session_id()
+    print(f"   Generated: {session_id}")
+    print(f"   Length: {len(session_id)} chars")
+    
+    # Security config
+    print("\n4. Security Configuration:")
+    config = SecurityConfig(
+        allowed_origins=["localhost", "example.com"],
+        require_auth=True
+    )
+    print(f"   Validate origin: {config.validate_origin}")
+    print(f"   Require auth: {config.require_auth}")
+    print(f"   Bind address: {config.get_bind_address()}")

examples/python/mcp/mcp-session-management.py

@@ -0,0 +1,44 @@
+"""
+MCP Session Management Example
+
+Demonstrates session management features for MCP transports.
+Sessions allow stateful interactions with MCP servers.
+
+Features:
+- Automatic session ID handling
+- Session expiration detection (HTTP 404)
+- Session termination via HTTP DELETE
+- Protocol version negotiation
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic agent with automatic session management
+agent = Agent(
+    name="Session Assistant",
+    instructions="You are a helpful assistant with session support.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# Session management is automatic - the MCP client:
+# 1. Receives Mcp-Session-Id from server during initialization
+# 2. Includes session ID in all subsequent requests
+# 3. Handles HTTP 404 (session expired) by reinitializing
+# 4. Can terminate session explicitly when done
+
+if __name__ == "__main__":
+    print("MCP Session Management Example")
+    print("=" * 40)
+    print()
+    print("Session Lifecycle:")
+    print("1. Client sends InitializeRequest")
+    print("2. Server returns InitializeResult with Mcp-Session-Id header")
+    print("3. Client includes Mcp-Session-Id in all subsequent requests")
+    print("4. If HTTP 404 received, client reinitializes session")
+    print("5. Client can send HTTP DELETE to terminate session")
+    print()
+    print("Headers used:")
+    print("- Mcp-Session-Id: Session identifier")
+    print("- Mcp-Protocol-Version: Protocol version (e.g., 2025-03-26)")

examples/python/mcp/mcp-tools-server-async.py

@@ -0,0 +1,79 @@
+"""MCP Tools Server with Async Functions
+
+Example showing how to expose async Python functions as MCP tools.
+
+Usage:
+    python mcp-tools-server-async.py
+"""
+
+import asyncio
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+async def async_search(query: str, delay: float = 0.1) -> dict:
+    """Async search function.
+    
+    Args:
+        query: The search query
+        delay: Simulated delay in seconds
+    """
+    await asyncio.sleep(delay)  # Simulate async operation
+    return {
+        "query": query,
+        "results": [f"Async result for {query}"]
+    }
+
+
+async def async_fetch_url(url: str) -> dict:
+    """Fetch content from a URL asynchronously.
+    
+    Args:
+        url: The URL to fetch
+    """
+    # Mock implementation - use aiohttp in production
+    await asyncio.sleep(0.1)
+    return {
+        "url": url,
+        "status": 200,
+        "content": f"Content from {url}"
+    }
+
+
+async def async_process_data(data: str, iterations: int = 3) -> dict:
+    """Process data asynchronously with multiple iterations.
+    
+    Args:
+        data: The data to process
+        iterations: Number of processing iterations
+    """
+    results = []
+    for i in range(iterations):
+        await asyncio.sleep(0.05)
+        results.append(f"Iteration {i+1}: processed {data}")
+    
+    return {
+        "input": data,
+        "iterations": iterations,
+        "results": results
+    }
+
+
+# Sync function can also be mixed with async
+def sync_calculate(a: int, b: int) -> dict:
+    """Synchronous calculation (can be mixed with async tools)."""
+    return {"sum": a + b, "product": a * b}
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="async-tools-server")
+    
+    # Register both async and sync tools
+    server.register_tools([
+        async_search,
+        async_fetch_url,
+        async_process_data,
+        sync_calculate
+    ])
+    
+    print(f"Registered tools: {server.get_tool_names()}")
+    server.run()

examples/python/mcp/mcp-tools-server-builtin.py

@@ -0,0 +1,27 @@
+"""MCP Server with Built-in PraisonAI Tools
+
+Expose PraisonAI's built-in tools as an MCP server.
+
+Usage:
+    # Set required API keys first
+    export TAVILY_API_KEY=your_key
+    
+    python mcp-tools-server-builtin.py
+"""
+
+from praisonaiagents.mcp import launch_tools_mcp_server
+
+
+if __name__ == "__main__":
+    # Expose built-in PraisonAI tools as MCP server
+    # This allows external MCP clients to use these tools
+    
+    launch_tools_mcp_server(
+        tool_names=[
+            "tavily_search",      # Web search via Tavily
+            "duckduckgo_search",  # Web search via DuckDuckGo
+            # Add more built-in tools as needed
+        ],
+        name="praisonai-builtin-tools",
+        transport="stdio"  # Use "sse" for web clients
+    )

examples/python/mcp/mcp-tools-server-simple.py

@@ -0,0 +1,25 @@
+"""Simple MCP Tools Server Example
+
+Minimal example of exposing Python functions as MCP tools.
+
+Usage:
+    python mcp-tools-server-simple.py
+"""
+
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+def search(query: str) -> dict:
+    """Search for information."""
+    return {"query": query, "results": [f"Result for {query}"]}
+
+
+def add(a: int, b: int) -> dict:
+    """Add two numbers."""
+    return {"result": a + b}
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="simple-tools")
+    server.register_tools([search, add])
+    server.run()

examples/python/mcp/mcp-tools-server-sse.py

@@ -0,0 +1,65 @@
+"""MCP Tools Server with SSE Transport
+
+Expose Python functions as MCP tools via Server-Sent Events (SSE).
+This is useful for web-based clients and remote access.
+
+Usage:
+    python mcp-tools-server-sse.py
+    
+    # Then connect from another agent:
+    # agent = Agent(tools=MCP("http://localhost:8080/sse"))
+"""
+
+from praisonaiagents.mcp import ToolsMCPServer
+
+
+def search_web(query: str, max_results: int = 5) -> dict:
+    """Search the web for information.
+    
+    Args:
+        query: The search query
+        max_results: Maximum results to return
+    """
+    return {
+        "query": query,
+        "results": [
+            {"title": f"Result {i+1}", "url": f"https://example.com/{i+1}"}
+            for i in range(max_results)
+        ]
+    }
+
+
+def calculate(expression: str) -> dict:
+    """Evaluate a mathematical expression.
+    
+    Args:
+        expression: Math expression (e.g., "2 + 2 * 3")
+    """
+    try:
+        allowed = set("0123456789+-*/.() ")
+        if not all(c in allowed for c in expression):
+            return {"error": "Invalid characters"}
+        return {"expression": expression, "result": eval(expression)}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def get_time() -> dict:
+    """Get the current time."""
+    from datetime import datetime
+    now = datetime.now()
+    return {
+        "time": now.strftime("%H:%M:%S"),
+        "date": now.strftime("%Y-%m-%d"),
+        "timestamp": now.isoformat()
+    }
+
+
+if __name__ == "__main__":
+    server = ToolsMCPServer(name="sse-tools-server")
+    server.register_tools([search_web, calculate, get_time])
+    
+    print("Starting SSE MCP Server...")
+    print("Connect with: MCP('http://localhost:8080/sse')")
+    
+    server.run_sse(host="0.0.0.0", port=8080)

examples/python/mcp/mcp-tools-server.py

@@ -0,0 +1,140 @@
+"""MCP Tools Server Example
+
+Expose Python functions as MCP tools for external clients like Claude Desktop, Cursor, etc.
+
+Usage:
+    # Run as stdio server (for Claude Desktop)
+    python mcp-tools-server.py
+    
+    # Run as SSE server (for web clients)
+    python mcp-tools-server.py --sse --port 8080
+"""
+
+import argparse
+from typing import List, Dict, Any
+
+
+# Define your custom tools as regular Python functions
+# Type hints and docstrings are used to generate MCP schemas
+
+def search_web(query: str, max_results: int = 5) -> Dict[str, Any]:
+    """Search the web for information.
+    
+    Args:
+        query: The search query string
+        max_results: Maximum number of results to return (default: 5)
+    
+    Returns:
+        Search results with titles and URLs
+    """
+    # Mock implementation - replace with actual search logic
+    return {
+        "query": query,
+        "results": [
+            {"title": f"Result {i+1} for '{query}'", "url": f"https://example.com/{i+1}"}
+            for i in range(max_results)
+        ]
+    }
+
+
+def calculate(expression: str) -> Dict[str, Any]:
+    """Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2 * 3")
+    
+    Returns:
+        The result of the calculation
+    """
+    try:
+        # Safe evaluation of mathematical expressions
+        allowed_chars = set("0123456789+-*/.() ")
+        if not all(c in allowed_chars for c in expression):
+            return {"error": "Invalid characters in expression"}
+        
+        result = eval(expression)  # Use safer alternative in production
+        return {"expression": expression, "result": result}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+def get_weather(city: str, units: str = "celsius") -> Dict[str, Any]:
+    """Get current weather for a city.
+    
+    Args:
+        city: Name of the city
+        units: Temperature units - "celsius" or "fahrenheit" (default: celsius)
+    
+    Returns:
+        Weather information for the city
+    """
+    # Mock implementation - replace with actual weather API
+    return {
+        "city": city,
+        "temperature": 22 if units == "celsius" else 72,
+        "units": units,
+        "condition": "Sunny",
+        "humidity": 45
+    }
+
+
+def list_files(directory: str = ".", pattern: str = "*") -> List[str]:
+    """List files in a directory.
+    
+    Args:
+        directory: Directory path to list (default: current directory)
+        pattern: Glob pattern to filter files (default: *)
+    
+    Returns:
+        List of file names matching the pattern
+    """
+    import glob
+    import os
+    
+    try:
+        full_pattern = os.path.join(directory, pattern)
+        files = glob.glob(full_pattern)
+        return [os.path.basename(f) for f in files]
+    except Exception as e:
+        return [f"Error: {str(e)}"]
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Run PraisonAI Tools as MCP Server")
+    parser.add_argument("--sse", action="store_true", help="Use SSE transport instead of stdio")
+    parser.add_argument("--port", type=int, default=8080, help="Port for SSE server (default: 8080)")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host for SSE server")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args()
+    
+    from praisonaiagents.mcp import ToolsMCPServer
+    
+    # Create server with custom name
+    server = ToolsMCPServer(
+        name="praisonai-custom-tools",
+        debug=args.debug
+    )
+    
+    # Register all tools
+    server.register_tools([
+        search_web,
+        calculate,
+        get_weather,
+        list_files
+    ])
+    
+    # Print registered tools
+    print(f"📦 Registered {len(server.tools)} tools:")
+    for name in server.get_tool_names():
+        print(f"   - {name}")
+    print()
+    
+    # Run the server
+    if args.sse:
+        server.run_sse(host=args.host, port=args.port)
+    else:
+        server.run_stdio()
+
+
+if __name__ == "__main__":
+    main()

examples/python/mcp/mcp-transports-overview.py

@@ -0,0 +1,91 @@
+"""
+MCP Transports Overview Example
+
+Demonstrates all MCP transport types and auto-detection.
+The MCP class automatically selects the appropriate transport
+based on the URL pattern.
+
+Transport Types:
+- stdio: Command strings (local subprocess)
+- Streamable HTTP: http:// or https:// URLs
+- WebSocket: ws:// or wss:// URLs
+- SSE (Legacy): URLs ending in /sse
+
+Protocol: MCP 2025-11-25
+"""
+
+# Example code (requires running MCP servers):
+#
+# from praisonaiagents import Agent, MCP
+#
+# # 1. stdio Transport - Local subprocess
+# agent_stdio = Agent(
+#     name="Stdio Assistant",
+#     tools=MCP("npx @modelcontextprotocol/server-memory")
+# )
+#
+# # 2. Streamable HTTP Transport
+# agent_http = Agent(
+#     name="HTTP Assistant",
+#     tools=MCP("https://api.example.com/mcp")
+# )
+#
+# # 3. WebSocket Transport
+# agent_ws = Agent(
+#     name="WebSocket Assistant",
+#     tools=MCP("wss://api.example.com/mcp")
+# )
+#
+# # 4. SSE Transport (Legacy)
+# agent_sse = Agent(
+#     name="SSE Assistant",
+#     tools=MCP("http://localhost:8080/sse")
+# )
+
+if __name__ == "__main__":
+    from praisonaiagents.mcp.mcp_transport import get_transport_type
+    
+    print("MCP Transports Overview")
+    print("=" * 50)
+    print()
+    print("Transport Auto-Detection:")
+    print("-" * 50)
+    
+    examples = [
+        ("npx @mcp/server-memory", "stdio"),
+        ("python3 server.py", "stdio"),
+        ("https://api.example.com/mcp", "http_stream"),
+        ("http://localhost:8080/mcp", "http_stream"),
+        ("ws://localhost:8080/mcp", "websocket"),
+        ("wss://api.example.com/mcp", "websocket"),
+        ("http://localhost:8080/sse", "sse"),
+        ("https://api.example.com/sse", "sse"),
+    ]
+    
+    for url, expected in examples:
+        detected = get_transport_type(url)
+        status = "✓" if detected == expected else "✗"
+        print(f"  {status} '{url}'")
+        print(f"      → {detected}")
+    
+    print()
+    print("Transport Features:")
+    print("-" * 50)
+    print("  stdio:")
+    print("    - Local subprocess communication")
+    print("    - Newline-delimited JSON-RPC")
+    print("    - Environment variable support")
+    print()
+    print("  Streamable HTTP:")
+    print("    - Session management (Mcp-Session-Id)")
+    print("    - Protocol versioning (Mcp-Protocol-Version)")
+    print("    - SSE streaming with resumability")
+    print()
+    print("  WebSocket:")
+    print("    - Bidirectional real-time")
+    print("    - Auto-reconnect with exponential backoff")
+    print("    - Authentication token support")
+    print()
+    print("  SSE (Legacy):")
+    print("    - Backward compatibility")
+    print("    - Protocol version 2024-11-05")

examples/python/mcp/multiple-mcp-servers.py

@@ -0,0 +1,108 @@
+"""
+Multiple MCP Servers Example
+
+This example demonstrates how to use multiple MCP servers with a single agent.
+You can combine different MCP servers (time, memory, filesystem, etc.) along
+with regular Python functions as tools.
+
+Requirements:
+- pip install praisonaiagents
+- uvx (for mcp-server-time)
+- npx (for @modelcontextprotocol servers)
+"""
+
+from praisonaiagents import Agent
+from praisonaiagents.mcp import MCP
+
+
+def my_custom_tool(query: str) -> str:
+    """
+    A custom Python function that can be used alongside MCP tools.
+    
+    Args:
+        query: The search query
+        
+    Returns:
+        A formatted result string
+    """
+    return f"Custom tool result for: {query}"
+
+
+def main():
+    # Example 1: Single MCP server (basic usage)
+    print("=" * 60)
+    print("Example 1: Single MCP Server")
+    print("=" * 60)
+    
+    agent_single = Agent(
+        name="TimeAgent",
+        instructions="You are a helpful assistant that can tell time.",
+        tools=MCP("uvx mcp-server-time")
+    )
+    
+    response = agent_single.start("What time is it in Tokyo?")
+    print(f"Response: {response}\n")
+    
+    # Example 2: Multiple MCP servers
+    print("=" * 60)
+    print("Example 2: Multiple MCP Servers")
+    print("=" * 60)
+    
+    agent_multi = Agent(
+        name="MultiMCPAgent",
+        instructions="""You are a helpful assistant with access to multiple tools:
+        - Time tools for getting current time and converting timezones
+        - Memory tools for storing and retrieving information
+        Use the appropriate tool based on the user's request.""",
+        tools=[
+            MCP("uvx mcp-server-time"),                     # Time tools
+            MCP("npx @modelcontextprotocol/server-memory"), # Memory tools
+        ]
+    )
+    
+    response = agent_multi.start("What time is it in New York and London?")
+    print(f"Response: {response}\n")
+    
+    # Example 3: Multiple MCP servers + custom functions
+    print("=" * 60)
+    print("Example 3: MCP Servers + Custom Functions")
+    print("=" * 60)
+    
+    agent_mixed = Agent(
+        name="MixedToolsAgent",
+        instructions="""You are a helpful assistant with access to:
+        - Time tools for timezone operations
+        - A custom search tool for general queries
+        Choose the right tool for each task.""",
+        tools=[
+            MCP("uvx mcp-server-time"),  # MCP server
+            my_custom_tool                # Regular Python function
+        ]
+    )
+    
+    response = agent_mixed.start("What time is it in Paris?")
+    print(f"Response: {response}\n")
+    
+    # Example 4: MCP with environment variables
+    print("=" * 60)
+    print("Example 4: MCP with Environment Variables")
+    print("=" * 60)
+    
+    # Note: Replace with your actual API key
+    # agent_with_env = Agent(
+    #     name="SearchAgent",
+    #     instructions="You can search the web for information.",
+    #     tools=[
+    #         MCP(
+    #             command="npx",
+    #             args=["-y", "@modelcontextprotocol/server-brave-search"],
+    #             env={"BRAVE_API_KEY": "your-api-key-here"}
+    #         ),
+    #         MCP("uvx mcp-server-time")
+    #     ]
+    # )
+    print("(Skipped - requires BRAVE_API_KEY)")
+
+
+if __name__ == "__main__":
+    main()

examples/python/mcp/streamable-http-mcp.py

@@ -0,0 +1,56 @@
+"""
+MCP Streamable HTTP Transport Example
+
+Demonstrates connecting to MCP servers via Streamable HTTP transport.
+This is the current standard transport (Protocol Revision 2025-11-25).
+
+Features:
+- Single MCP endpoint for all communication
+- Session management via Mcp-Session-Id header
+- Protocol versioning via Mcp-Protocol-Version header
+- SSE streaming with resumability
+- Session termination via HTTP DELETE
+
+Protocol: MCP 2025-11-25
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic Streamable HTTP connection
+agent = Agent(
+    name="HTTP Stream Assistant",
+    instructions="You are a helpful assistant connected via Streamable HTTP.",
+    tools=MCP("https://api.example.com/mcp")
+)
+
+# With authentication headers
+agent_auth = Agent(
+    name="Authenticated Assistant",
+    instructions="You are a helpful assistant with authenticated connection.",
+    tools=MCP(
+        "https://api.example.com/mcp",
+        headers={"Authorization": "Bearer your-token"}
+    )
+)
+
+# With timeout and debug
+agent_debug = Agent(
+    name="Debug Assistant",
+    tools=MCP(
+        "https://api.example.com/mcp",
+        timeout=120,
+        debug=True
+    )
+)
+
+if __name__ == "__main__":
+    print("Streamable HTTP MCP Transport Example")
+    print("=" * 40)
+    print("This example requires a Streamable HTTP MCP server running.")
+    print("URL pattern: https://host:port/mcp")
+    print()
+    print("Features enabled:")
+    print("- Mcp-Protocol-Version header (default: 2025-03-26)")
+    print("- Mcp-Session-Id header (automatic)")
+    print("- SSE streaming support")
+    print("- Resumability via Last-Event-ID")

examples/python/mcp/websocket-mcp.py

@@ -0,0 +1,55 @@
+"""
+MCP WebSocket Transport Example
+
+Demonstrates connecting to MCP servers via WebSocket (ws:// or wss://).
+WebSocket transport provides bidirectional real-time communication,
+ideal for cloud deployments and long-lived connections.
+
+Features:
+- Auto-detection of ws:// and wss:// URLs
+- Authentication token support
+- Auto-reconnect with exponential backoff
+- Ping/pong keepalive
+
+Protocol: SEP-1288 (WebSocket Transport)
+"""
+
+from praisonaiagents import Agent, MCP
+
+# Basic WebSocket connection
+agent = Agent(
+    name="WebSocket Assistant",
+    instructions="You are a helpful assistant connected via WebSocket.",
+    tools=MCP("ws://localhost:8080/mcp")
+)
+
+# Secure WebSocket with authentication
+agent_secure = Agent(
+    name="Secure WebSocket Assistant",
+    instructions="You are a helpful assistant with secure WebSocket connection.",
+    tools=MCP(
+        "wss://api.example.com/mcp",
+        auth_token="Bearer your-secret-token",
+        timeout=60
+    )
+)
+
+# WebSocket with custom options
+agent_custom = Agent(
+    name="Custom WebSocket Assistant",
+    tools=MCP(
+        "wss://api.example.com/mcp",
+        auth_token="your-token",
+        timeout=120,
+        debug=True
+    )
+)
+
+if __name__ == "__main__":
+    # Note: Requires a running WebSocket MCP server
+    # Example server: https://github.com/modelcontextprotocol/servers
+    
+    print("WebSocket MCP Transport Example")
+    print("=" * 40)
+    print("This example requires a WebSocket MCP server running.")
+    print("URL patterns: ws://host:port/path or wss://host:port/path")

examples/python/tools/e2b/agents.yaml

@@ -1,8 +1,8 @@
 framework: praisonai
 topic: crawl and extract all data from each url from this page https://news.ycombinator.com/
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   web_scraper:
-    backstory: An expert in data extraction from websites, adept at navigating and
+    instructions:  # Canonical An expert in data extraction from websites, adept at navigating and
       retrieving detailed information.
     goal: Extract URLs from the source page
     role: Web Scraper
@@ -15,7 +15,7 @@ roles:
     tools:
     - 'code_interpret'
   url_data_extractor:
-    backstory: Specializes in crawling websites to gather comprehensive data, ensuring
+    instructions:  # Canonical Specializes in crawling websites to gather comprehensive data, ensuring
       nothing is missed from each link.
     goal: Crawl each URL for data extraction
     role: URL Data Extractor
@@ -29,7 +29,7 @@ roles:
     tools:
     - 'code_interpret'
   data_organizer:
-    backstory: Known for keen attention to detail, capable of structuring vast amounts
+    instructions:  # Canonical Known for keen attention to detail, capable of structuring vast amounts
       of information into usable formats efficiently.
     goal: Organize extracted data into a structured format
     role: Data Organizer

examples/python/tools/exa-tool/rag_examples/agentic_rag/rag_agent.py

@@ -0,0 +1,44 @@
+from praisonaiagents import Agent
+import os
+
+# Set OpenAI API key if not already set
+if not os.getenv("OPENAI_API_KEY"):
+    print("Please set your OpenAI API key: export OPENAI_API_KEY='your-api-key-here'")
+    exit(1)
+
+# Create the RAG agent with web search capabilities
+rag_agent = Agent(
+    instructions="""You are a helpful AI assistant specialized in Thai recipes and cooking.
+
+    You have access to a PDF knowledge base about Thai recipes from: https://phi-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf
+    
+    You can also search the web for additional information about Thai cooking, ingredients, and techniques.
+    
+    When answering questions:
+    1. Use your knowledge about Thai cuisine to provide helpful information
+    2. If needed, search the web for additional details, current information, or clarification
+    3. Provide comprehensive, helpful answers about Thai cuisine
+    4. Always be informative and helpful about Thai cooking!
+    
+    You can use the internet_search function to search the web when needed.""",
+    llm="gpt-4o",
+    markdown=True,
+    verbose=True
+)
+
+if __name__ == "__main__":
+    print("🤖 Thai Recipe RAG Agent is ready!")
+    print("Ask me anything about Thai recipes or cooking!")
+    print("Type 'quit' to exit.\n")
+    
+    while True:
+        user_input = input("You: ")
+        if user_input.lower() in ['quit', 'exit', 'bye']:
+            print("👋 Goodbye! Happy cooking!")
+            break
+        
+        try:
+            response = rag_agent.start(user_input)
+            print(f"\n🤖 Assistant: {response}\n")
+        except Exception as e:
+            print(f"❌ Error: {e}\n")

examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/README.md

@@ -0,0 +1,154 @@
+# 🧠 Agentic RAG with GPT-5
+
+An agentic RAG application built with the PraisonAI Agents framework, featuring GPT-5 and built-in vector search for efficient knowledge retrieval and question answering.
+
+## ✨ Features
+
+- **🤖 GPT-5**: Latest OpenAI model for intelligent responses
+- **🗄️ Built-in Vector Search**: ChromaDB integration for fast similarity search
+- **🔍 Agentic RAG**: Intelligent retrieval augmented generation
+- **📝 Markdown Formatting**: Beautiful, structured responses
+- **🌐 Dynamic Knowledge**: Add URLs to expand knowledge base
+- **⚡ Real-time Responses**: Fast answer generation- **🎯 Clean Interface**: Simplified UI without configuration complexity
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- OpenAI API key with GPT-5 access
+
+### Installation
+
+1. **Clone and navigate to the project**
+   ```bash
+   cd rag_examples/agentic_rag_gpt5
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up your OpenAI API key**
+   ```bash
+   export OPENAI_API_KEY="your-api-key-here"
+   ```
+   Or create a `.env` file:
+   ```
+   OPENAI_API_KEY=your-api-key-here
+   ```
+
+4. **Run the application**
+   ```bash
+   streamlit run agentic_rag_gpt5.py
+   ```
+
+## 🎯 How to Use
+
+1. **Enter your OpenAI API key** in the sidebar
+2. **Add knowledge sources** by entering URLs in the sidebar
+3. **Ask questions** using the text area or suggested prompts
+4. **Get answers** with markdown formatting
+
+### Suggested Questions
+
+- **"What is PraisonAI?"** - Learn about the PraisonAI Agents framework
+- **"Teams in PraisonAI"** - Understand how teams work in PraisonAI
+- **"Build RAG system"** - Get a step-by-step guide to building RAG systems
+
+## 🏗️ Architecture
+
+### Core Components
+
+- **`Agent`**: PraisonAI Agents framework for intelligent Q&A
+- **`knowledge`**: Built-in knowledge base that handles URLs and documents
+- **`llm`**: OpenAI GPT-5-nano for generating responses
+- **Built-in Vector Search**: Automatic similarity search without external setup
+
+### Data Flow
+
+1. **Knowledge Loading**: URLs are processed and stored in the built-in vector database
+2. **Vector Search**: OpenAI embeddings enable semantic search
+3. **Response Generation**: GPT-5-nano processes information and generates answers
+4. **Formatted Output**: Markdown-formatted responses
+
+## 🔧 Configuration
+
+### Database Settings
+- **Vector DB**: Built-in vector database with automatic indexing
+- **Storage**: Local storage managed by PraisonAI Agents
+- **Search**: Automatic similarity search
+
+### Model Configuration
+- **LLM**: OpenAI GPT-5-nano
+- **Embeddings**: Automatic handling by PraisonAI Agents
+- **Vector Store**: Built-in with automatic document processing
+
+## 📚 Knowledge Management
+
+### Adding Sources
+- Use the sidebar to add new URLs
+- Sources are automatically processed and indexed
+- Current sources are displayed as numbered list
+
+### Default Knowledge
+- Starts with PraisonAI documentation: `https://docs.praisonai.com/introduction/agents.md`
+- Expandable with any web-based documentation
+
+## 🎨 UI Features
+
+### Sidebar
+- **API Key Management**: Secure input for OpenAI credentials
+- **URL Addition**: Dynamic knowledge base expansion
+- **Current Sources**: Numbered list of loaded URLs
+
+### Main Interface
+- **Suggested Prompts**: Quick access to common questions
+- **Query Input**: Large text area for custom questions
+- **Fast Responses**: Quick answer generation
+- **Markdown Rendering**: Beautiful formatted responses
+
+## 🛠️ Technical Details
+
+### Dependencies
+```
+streamlit>=1.28.0
+praisonaiagents>=0.1.0
+openai>=1.0.0
+python-dotenv>=1.0.0
+```
+
+### Key Features
+- **Built-in Knowledge Base**: Automatic document processing and indexing
+- **Vector Search**: Efficient similarity search with built-in database
+- **Caching**: Efficient resource loading with Streamlit caching
+- **Error Handling**: Graceful handling of API and processing errors
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+**Knowledge base not loading**
+- Check OpenAI API key is valid
+- Ensure URLs are accessible
+- Verify internet connection
+
+**Agent initialization errors**
+- Check if PraisonAI Agents is properly installed
+- Verify OpenAI API key has sufficient credits
+- Ensure Python version is 3.11+
+
+### Performance Tips
+- **Cache Resources**: Knowledge base and agent are cached for efficiency
+- **Built-in Vector Search**: Fast similarity search without external setup
+- **Local Storage**: Optimized local storage for optimal performance
+
+## 🎯 Use Cases
+
+- **Documentation Q&A**: Ask questions about technical documentation
+- **Research Assistant**: Get answers from multiple knowledge sources
+- **Learning Tool**: Interactive exploration of complex topics
+- **Content Discovery**: Find relevant information across multiple sources
+
+**Built with ❤️ using PraisonAI Agents and GPT-5**

examples/python/tools/exa-tool/rag_examples/agentic_rag_gpt5/agentic_rag_gpt5.py

@@ -0,0 +1,201 @@
+import streamlit as st
+import os
+from praisonaiagents import Agent
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Page configuration
+st.set_page_config(
+    page_title="Agentic RAG with GPT-5",
+    page_icon="🧠",
+    layout="wide"
+)
+
+# Main title and description
+st.title("🧠 Agentic RAG with GPT-5")
+st.markdown("""
+This app demonstrates an intelligent AI agent that:
+1. **Answers** your questions clearly and concisely using GPT-5
+
+⚠️ **Note**: Knowledge base functionality is temporarily disabled due to a compatibility issue with the current version of PraisonAI Agents.
+
+Enter your OpenAI API key in the sidebar to get started!
+""")
+
+# Sidebar for API key and settings
+with st.sidebar:
+    st.header("🔧 Configuration")
+    
+    # OpenAI API Key
+    openai_key = st.text_input(
+        "OpenAI API Key",
+        type="password",
+        value=os.getenv("OPENAI_API_KEY", ""),
+        help="Get your key from https://platform.openai.com/"
+    )
+
+    # Add URLs to knowledge base
+    st.subheader("🌐 Add Knowledge Sources")
+    st.info("⚠️ Knowledge base functionality is temporarily disabled due to compatibility issues.")
+    new_url = st.text_input(
+        "Add URL",
+        placeholder="https://docs.praisonai.com/introduction",
+        help="Enter a URL to add to the knowledge base (currently disabled)"
+    )
+    
+    if st.button("➕ Add URL", type="primary", disabled=True):
+        st.info("Knowledge base functionality is temporarily disabled.")
+
+# Check if API key is provided
+if openai_key:
+    # Initialize knowledge base (cached to avoid reloading)
+    @st.cache_resource(show_spinner="📚 Loading knowledge base...")
+    def load_knowledge() -> list:
+        """Load and initialize the knowledge base with default URL"""
+        return ["https://docs.praisonai.com/introduction/agents.md"]  # Default URL
+
+    # Initialize agent (cached to avoid reloading)
+    @st.cache_resource(show_spinner="🤖 Loading agent...")
+    def load_agent(_knowledge: list) -> Agent:
+        """Create an agent with reasoning capabilities"""
+        # Note: Temporarily removed knowledge parameter to avoid rerank error
+        # TODO: Re-enable when PraisonAI Agents knowledge issue is resolved
+        return Agent(
+            name="Knowledge Agent",
+            instructions=[
+                "You are a helpful AI assistant. Answer questions based on your general knowledge.",
+                "Provide clear, well-structured answers in markdown format.",
+                "Use proper markdown formatting with headers, lists, and emphasis where appropriate.",
+                "Structure your response with clear sections and bullet points when helpful.",
+            ],
+            llm="gpt-5-nano
+            markdown=True,
+            verbose=True
+        )
+
+    # Load knowledge and agent
+    knowledge = load_knowledge()
+    agent = load_agent(knowledge)
+    
+    # Display current URLs in knowledge base
+    if knowledge:
+        st.sidebar.subheader("📚 Current Knowledge Sources")
+        for i, url in enumerate(knowledge, 1):
+            st.sidebar.markdown(f"{i}. {url}")
+    
+    # Handle URL additions
+    if hasattr(st.session_state, 'urls_to_add') and st.session_state.urls_to_add:
+        with st.spinner("📥 Loading new documents..."):
+            knowledge.append(st.session_state.urls_to_add)
+            # Reinitialize agent with new knowledge
+            agent = load_agent(knowledge)
+        st.success(f"✅ Added: {st.session_state.urls_to_add}")
+        del st.session_state.urls_to_add
+        st.rerun()
+
+    # Main query section
+    st.divider()
+    st.subheader("🤔 Ask a Question")
+    
+    # Suggested prompts
+    st.markdown("**Try these prompts:**")
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        if st.button("What is PraisonAI?", use_container_width=True):
+            st.session_state.query = "What is PraisonAI and how do Agents work?"
+    with col2:
+        if st.button("Teams in PraisonAI", use_container_width=True):
+            st.session_state.query = "What are Teams in PraisonAI and how do they work?"
+    with col3:
+        if st.button("Build RAG system", use_container_width=True):
+            st.session_state.query = "Give me a step-by-step guide to building a RAG system."
+    
+    # Query input
+    query = st.text_area(
+        "Your question:",
+        value=st.session_state.get("query", "What are AI Agents?"),
+        height=100,
+        help="Ask anything about the loaded knowledge sources"
+    )
+    
+    # Run button
+    if st.button("🚀 Get Answer", type="primary"):
+        if query:
+            # Create container for answer
+            st.markdown("### 💡 Answer")
+            answer_container = st.container()
+            answer_placeholder = answer_container.empty()
+            
+            # Get the agent's response
+            with st.spinner("🔍 Searching and generating answer..."):
+                try:
+                    st.info("🤖 Agent is processing your question...")
+                    response = agent.start(query)
+                    answer_placeholder.markdown(
+                        response, 
+                        unsafe_allow_html=True
+                    )
+                except Exception as e:
+                    st.error(f"Error getting response: {str(e)}")
+                    st.error(f"Error type: {type(e).__name__}")
+                    st.error(f"Full error details: {repr(e)}")
+                    # Try to provide a helpful response
+                    answer_placeholder.markdown("""
+                    **⚠️ Error occurred while processing your question.**
+                    
+                    This might be due to:
+                    - Knowledge base configuration issues
+                    - Model access problems
+                    - Network connectivity issues
+                    
+                    Please try again or check your OpenAI API key.
+                    """)
+        else:
+            st.error("Please enter a question")
+
+else:
+    # Show instructions if API key is missing
+    st.info("""
+    👋 **Welcome! To use this app, you need:**
+    
+    - **OpenAI API Key** (set it in the sidebar)
+      - Sign up at [platform.openai.com](https://platform.openai.com/)
+      - Generate a new API key
+    
+    Once you enter the key, the app will load the knowledge base and agent.
+    """)
+
+# Footer with explanation
+st.divider()
+with st.expander("📖 How This Works"):
+    st.markdown("""
+    **This app uses the PraisonAI Agents framework to create an intelligent Q&A system:**
+    
+    ⚠️ **Current Status**: Knowledge base functionality is temporarily disabled due to compatibility issues with the current version of PraisonAI Agents (v0.0.157).
+    
+    **What Works Now:**
+    1. **GPT-5 Integration**: OpenAI's GPT-5 model for generating intelligent responses
+    2. **Markdown Formatting**: Beautiful, structured responses
+    3. **Agent Framework**: PraisonAI Agents for orchestration
+    
+    **What's Temporarily Disabled:**
+    - URL-based knowledge base
+    - Vector search and retrieval
+    - Document processing
+    
+    **Key Components:**
+    - `Agent`: PraisonAI Agents framework for creating intelligent agents
+    - `llm`: OpenAI GPT-5-nano for generating responses
+    
+    **Why PraisonAI Agents?**
+    - Easy-to-use agent framework
+    - Built-in error handling
+    - Clean API design
+    - Perfect for prototyping and production applications
+    
+    **Next Steps:**
+    - Monitor PraisonAI Agents updates for knowledge base fixes
+    - Re-enable knowledge functionality when compatible version is available
+    """)

examples/python/workflows/simple_workflow.py

@@ -0,0 +1,38 @@
+"""
+Simple Agentic Workflow Example
+
+Demonstrates using Agent instances directly as workflow steps.
+Each agent processes the input and passes output to the next agent.
+"""
+
+from praisonaiagents import Agent, Workflow
+
+# Create agents with specific roles
+researcher = Agent(
+    name="Researcher",
+    role="Research Analyst",
+    goal="Research and provide information about topics",
+    instructions="You are a research analyst. Provide concise, factual information."
+)
+
+writer = Agent(
+    name="Writer", 
+    role="Content Writer",
+    goal="Write engaging content based on research",
+    instructions="You are a content writer. Write clear, engaging content based on the research provided."
+)
+
+# Create workflow with agents as steps
+workflow = Workflow(
+    name="Simple Agentic Pipeline",
+    steps=[researcher, writer]
+)
+
+if __name__ == "__main__":
+    # Run workflow - agents process sequentially
+    result = workflow.start(
+        "What are the key benefits of AI agents?",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")

examples/python/workflows/simple_workflow_non_agentic.py

@@ -0,0 +1,36 @@
+"""
+Simple Workflow Example
+
+The easiest way to create and run workflows in PraisonAI.
+Just pass functions or agents as steps - no complex configuration needed!
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+
+# Define simple handler functions
+def validate(ctx: WorkflowContext) -> StepResult:
+    """Validate the input data."""
+    if not ctx.input:
+        return StepResult(output="No input provided", stop_workflow=True)
+    return StepResult(output=f"Validated: {ctx.input}")
+
+def process(ctx: WorkflowContext) -> StepResult:
+    """Process the validated data."""
+    return StepResult(output=f"Processed: {ctx.previous_result}")
+
+def format_output(ctx: WorkflowContext) -> StepResult:
+    """Format the final output."""
+    return StepResult(output=f"✅ Final: {ctx.previous_result}")
+
+# Create workflow - just list your functions!
+workflow = Workflow(
+    name="Simple Pipeline",
+    steps=[validate, process, format_output]
+)
+
+if __name__ == "__main__":
+    # Run the workflow - PraisonAI style uses .start()
+    result = workflow.start("Hello, World!", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Steps completed: {len(result['steps'])}")

examples/python/workflows/task_callbacks.py

@@ -0,0 +1,57 @@
+"""
+Task Callbacks Example
+
+Demonstrates using on_task_start and on_task_complete callbacks
+with PraisonAIAgents for workflow monitoring and logging.
+"""
+
+from praisonaiagents import Agent, Task, PraisonAIAgents
+
+# Create an agent
+researcher = Agent(
+    name="Researcher",
+    role="Research Assistant",
+    goal="Find and summarize information",
+    llm="gpt-4o-mini"
+)
+
+# Create tasks with variables
+task1 = Task(
+    name="research",
+    description="Research the topic: {{topic}}",
+    expected_output="A brief summary of the topic",
+    agent=researcher,
+    variables={"topic": "artificial intelligence"}
+)
+
+task2 = Task(
+    name="summarize",
+    description="Create a one-paragraph summary of the research.",
+    expected_output="A concise summary",
+    agent=researcher
+)
+
+# Define callbacks
+def on_start(task, task_id):
+    """Called before each task starts."""
+    print(f"🚀 Starting task: {task.name} (ID: {task_id})")
+
+def on_complete(task, output):
+    """Called after each task completes."""
+    print(f"✅ Completed task: {task.name}")
+    print(f"   Output preview: {str(output)[:100]}...")
+
+if __name__ == "__main__":
+    # Create agents with callbacks
+    agents = PraisonAIAgents(
+        agents=[researcher],
+        tasks=[task1, task2],
+        process="workflow",
+        on_task_start=on_start,
+        on_task_complete=on_complete,
+        variables={"global_var": "shared_value"}  # Global variables
+    )
+    
+    # Run the workflow
+    result = agents.start()
+    print("\n🎉 Workflow completed!")

examples/python/workflows/workflow_branching.py

@@ -0,0 +1,48 @@
+"""
+Workflow Branching Example
+
+Demonstrates conditional branching in workflows where steps can route
+to different next steps based on output content.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a workflow with branching
+workflow = Workflow(
+    name="Decision Workflow",
+    description="A workflow that branches based on validation result",
+    steps=[
+        WorkflowStep(
+            name="validate",
+            action="Check if the number 42 is positive. Reply with 'valid' or 'invalid'.",
+            next_steps=["success_handler", "error_handler"],
+            branch_condition={
+                "valid": ["success_handler"],
+                "invalid": ["error_handler"]
+            }
+        ),
+        WorkflowStep(
+            name="success_handler",
+            action="The validation passed! Generate a success message."
+        ),
+        WorkflowStep(
+            name="error_handler",
+            action="The validation failed. Generate an error message."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    # Create manager and register workflow
+    manager = WorkflowManager()
+    manager.workflows["Decision Workflow"] = workflow
+    
+    # Execute - will branch to success_handler since 42 is positive
+    result = manager.execute(
+        "Decision Workflow",
+        default_llm="gpt-4o-mini"
+    )
+    
+    print("Workflow completed!")
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")

examples/python/workflows/workflow_checkpoints.py

@@ -0,0 +1,63 @@
+"""
+Workflow Checkpoints Example
+
+Demonstrates saving and resuming workflow execution using checkpoints.
+Useful for long-running workflows that may be interrupted.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a multi-step workflow
+workflow = Workflow(
+    name="Long Process",
+    description="A workflow with checkpoints for resumability",
+    steps=[
+        WorkflowStep(
+            name="step1",
+            action="Initialize the process and prepare data."
+        ),
+        WorkflowStep(
+            name="step2", 
+            action="Process the first batch of data."
+        ),
+        WorkflowStep(
+            name="step3",
+            action="Process the second batch of data."
+        ),
+        WorkflowStep(
+            name="step4",
+            action="Finalize and generate report."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    manager = WorkflowManager()
+    manager.workflows["Long Process"] = workflow
+    
+    # Execute with checkpoint - saves after each step
+    print("=== Starting workflow with checkpoint ===")
+    result = manager.execute(
+        "Long Process",
+        default_llm="gpt-4o-mini",
+        checkpoint="my-checkpoint"  # Saves progress after each step
+    )
+    
+    print(f"Completed {len(result['results'])} steps")
+    
+    # List available checkpoints
+    print("\n=== Available checkpoints ===")
+    checkpoints = manager.list_checkpoints()
+    for cp in checkpoints:
+        print(f"  {cp['name']}: {cp['completed_steps']} steps completed")
+    
+    # Resume from checkpoint (if workflow was interrupted)
+    # result = manager.execute(
+    #     "Long Process",
+    #     default_llm="gpt-4o-mini",
+    #     resume="my-checkpoint"  # Resumes from last saved state
+    # )
+    
+    # Clean up checkpoint
+    manager.delete_checkpoint("my-checkpoint")
+    print("\n✅ Checkpoint deleted")

examples/python/workflows/workflow_conditional.py

@@ -0,0 +1,83 @@
+"""
+Agentic Conditional Workflow Example
+
+Demonstrates using should_run to conditionally execute agent steps
+based on input or previous results.
+"""
+
+from praisonaiagents import Agent, Workflow, WorkflowStep
+
+# Condition functions
+def is_technical(ctx) -> bool:
+    """Only run technical review for technical content."""
+    keywords = ["code", "programming", "algorithm", "database", "api"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
+
+def needs_creative(ctx) -> bool:
+    """Only run creative enhancement for creative content."""
+    keywords = ["story", "poem", "creative", "write", "narrative"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
+
+# Create agents
+analyzer = Agent(
+    name="Analyzer",
+    role="Content Analyzer",
+    goal="Analyze and process content",
+    instructions="Analyze the given content and provide insights."
+)
+
+tech_reviewer = Agent(
+    name="TechReviewer",
+    role="Technical Reviewer",
+    goal="Review technical content",
+    instructions="Review the technical aspects and provide technical feedback."
+)
+
+creative_enhancer = Agent(
+    name="CreativeEnhancer",
+    role="Creative Enhancer",
+    goal="Enhance creative content",
+    instructions="Enhance the creative aspects and make it more engaging."
+)
+
+finalizer = Agent(
+    name="Finalizer",
+    role="Content Finalizer",
+    goal="Finalize the content",
+    instructions="Provide the final polished version of the content."
+)
+
+# Create workflow with conditional steps
+workflow = Workflow(
+    name="Conditional Agentic Pipeline",
+    steps=[
+        analyzer,  # Always runs
+        WorkflowStep(
+            name="tech_review",
+            agent=tech_reviewer,
+            should_run=is_technical  # Only runs for technical content
+        ),
+        WorkflowStep(
+            name="creative_enhance",
+            agent=creative_enhancer,
+            should_run=needs_creative  # Only runs for creative content
+        ),
+        finalizer  # Always runs
+    ]
+)
+
+if __name__ == "__main__":
+    # Test 1: Technical content
+    print("=== Test 1: Technical Content ===")
+    result = workflow.start("Review this Python code for best practices", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
+    
+    # Test 2: Creative content
+    print("=== Test 2: Creative Content ===")
+    result = workflow.start("Write a short story about a robot", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
+    
+    # Test 3: General content (neither technical nor creative)
+    print("=== Test 3: General Content ===")
+    result = workflow.start("What is the weather like today?", verbose=True)
+    print(f"Output: {result['output'][:200]}...")

examples/python/workflows/workflow_conditional_non_agentic.py

@@ -0,0 +1,68 @@
+"""
+Workflow Conditional Execution Example
+
+Demonstrates using should_run to conditionally execute steps
+based on input or previous results.
+"""
+
+from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult
+
+# Condition functions - return True to run the step, False to skip
+def is_sensitive_content(ctx: WorkflowContext) -> bool:
+    """Only run compliance check for sensitive topics."""
+    sensitive_keywords = ["legal", "medical", "financial", "security"]
+    return any(keyword in ctx.input.lower() for keyword in sensitive_keywords)
+
+def needs_translation(ctx: WorkflowContext) -> bool:
+    """Only translate if content is not in English."""
+    return ctx.variables.get("language", "en") != "en"
+
+# Handler functions
+def process_content(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"Processed: {ctx.input}")
+
+def compliance_check(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"✅ Compliance verified for: {ctx.previous_result}")
+
+def translate(ctx: WorkflowContext) -> StepResult:
+    lang = ctx.variables.get("language", "unknown")
+    return StepResult(output=f"🌐 Translated to {lang}: {ctx.previous_result}")
+
+def finalize(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"📄 Final: {ctx.previous_result}")
+
+# Create workflow with conditional steps
+workflow = Workflow(
+    name="Conditional Pipeline",
+    steps=[
+        WorkflowStep(name="process", handler=process_content),
+        WorkflowStep(
+            name="compliance",
+            handler=compliance_check,
+            should_run=is_sensitive_content  # Only runs for sensitive content
+        ),
+        WorkflowStep(
+            name="translate",
+            handler=translate,
+            should_run=needs_translation  # Only runs if language != "en"
+        ),
+        WorkflowStep(name="finalize", handler=finalize)
+    ]
+)
+
+if __name__ == "__main__":
+    # Test 1: Normal content (skips compliance)
+    print("=== Test 1: Normal content ===")
+    result = workflow.start("Hello world", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 2: Sensitive content (runs compliance)
+    print("=== Test 2: Legal content ===")
+    result = workflow.start("Review this legal document", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 3: Non-English content (runs translation)
+    print("=== Test 3: Non-English content ===")
+    workflow.variables = {"language": "es"}
+    result = workflow.start("Hola mundo", verbose=True)
+    print(f"Output: {result['output']}")

examples/python/workflows/workflow_early_stop.py

@@ -0,0 +1,69 @@
+"""
+Workflow Early Stop Example
+
+Demonstrates how to stop a workflow early using custom handler
+functions that return StepResult with stop_workflow=True.
+"""
+
+from praisonaiagents.memory.workflows import (
+    WorkflowManager, WorkflowStep, Workflow,
+    WorkflowContext, StepResult
+)
+
+# Custom validator that can stop the workflow
+def validate_data(context: WorkflowContext) -> StepResult:
+    """Check if data is valid and stop workflow if not."""
+    data = context.variables.get("data", {})
+    
+    if data.get("value", 0) < 0:
+        return StepResult(
+            output="❌ Validation failed: negative value detected. Stopping workflow.",
+            stop_workflow=True  # This stops the entire workflow
+        )
+    
+    return StepResult(
+        output="✅ Validation passed: data is valid.",
+        stop_workflow=False  # Continue to next step
+    )
+
+# Create workflow with early stop capability
+workflow = Workflow(
+    name="Data Processing",
+    description="Process data with validation gate",
+    variables={
+        "data": {"value": -5}  # Invalid data - will trigger early stop
+    },
+    steps=[
+        WorkflowStep(
+            name="validate",
+            handler=validate_data  # Custom function
+        ),
+        WorkflowStep(
+            name="process",
+            action="Process the validated data."  # Won't run if validation fails
+        ),
+        WorkflowStep(
+            name="report",
+            action="Generate final report."  # Won't run if validation fails
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    manager = WorkflowManager()
+    manager.workflows["Data Processing"] = workflow
+    
+    # Test with invalid data (will stop early)
+    print("=== Testing with invalid data ===")
+    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
+    
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['output']}")
+    
+    # Test with valid data (will complete)
+    print("\n=== Testing with valid data ===")
+    workflow.variables["data"] = {"value": 42}
+    result = manager.execute("Data Processing", default_llm="gpt-4o-mini")
+    
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")

examples/python/workflows/workflow_loop_csv.py

@@ -0,0 +1,59 @@
+"""
+Agentic Loop with CSV Workflow Example
+
+Demonstrates iterating over a CSV file with an agent processing each row.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file content
+csv_content = """topic,description
+AI Ethics,Ethical considerations in artificial intelligence
+Machine Learning,Algorithms that learn from data
+Neural Networks,Computing systems inspired by biological neural networks
+Natural Language Processing,AI understanding human language"""
+
+# Create processor agent
+processor = Agent(
+    name="TopicProcessor",
+    role="Topic Analyst",
+    goal="Analyze and explain topics",
+    instructions="Provide a brief, insightful analysis of the given topic."
+)
+
+# Create summarizer agent
+summarizer = Agent(
+    name="Summarizer",
+    role="Results Summarizer",
+    goal="Summarize all processed results",
+    instructions="Create a comprehensive summary of all the analyzed topics."
+)
+
+if __name__ == "__main__":
+    # Create temp CSV file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(csv_content)
+        csv_path = f.name
+    
+    try:
+        print("=== Testing Agentic Loop with CSV ===\n")
+        print(f"Processing CSV: {csv_path}\n")
+        
+        # Create workflow with loop over CSV
+        workflow = Workflow(
+            name="CSV Topic Processor",
+            steps=[
+                loop(processor, from_csv=csv_path),
+                summarizer
+            ]
+        )
+        
+        result = workflow.start("Analyze these AI topics", verbose=True)
+        
+        print(f"\nFinal Summary:\n{result['output']}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_csv_non_agentic.py

@@ -0,0 +1,55 @@
+"""
+Workflow Loop with CSV Example
+
+Demonstrates iterating over a CSV file, processing each row.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file
+csv_content = """name,email,task
+Alice,[email protected],Write documentation
+Bob,[email protected],Review pull requests
+Charlie,[email protected],Fix critical bug
+Diana,[email protected],Deploy to production"""
+
+# Processor for each CSV row
+def process_task(ctx: WorkflowContext) -> StepResult:
+    """Process a single task from CSV."""
+    item = ctx.variables.get("item", {})
+    name = item.get("name", "Unknown")
+    task = item.get("task", "No task")
+    index = ctx.variables.get("loop_index", 0)
+    
+    return StepResult(
+        output=f"[{index+1}] {name}: {task} ✅",
+        variables={"last_processed": name}
+    )
+
+if __name__ == "__main__":
+    # Create temp CSV file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(csv_content)
+        csv_path = f.name
+    
+    try:
+        print("=== Testing Loop with CSV ===\n")
+        print(f"CSV file: {csv_path}\n")
+        
+        # Create workflow
+        workflow = Workflow(
+            name="CSV Task Processor",
+            steps=[loop(process_task, from_csv=csv_path)]
+        )
+        
+        result = workflow.start("Process all tasks", verbose=True)
+        
+        print(f"\nAll outputs:\n{result['output']}")
+        print(f"\nProcessed {len(result['variables']['loop_outputs'])} items")
+        print(f"Last processed: {result['variables'].get('last_processed')}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_list.py

@@ -0,0 +1,52 @@
+"""
+Workflow Loop with List Example
+
+Demonstrates iterating over a list of items, processing each one.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+
+# Sample data
+fruits = ["apple", "banana", "cherry", "date", "elderberry"]
+
+# Processor for each item
+def process_fruit(ctx: WorkflowContext) -> StepResult:
+    """Process a single fruit from the list."""
+    fruit = ctx.variables.get("item", "unknown")
+    index = ctx.variables.get("loop_index", 0)
+    
+    # Simulate processing
+    result = f"🍎 [{index + 1}] {fruit.upper()} - processed successfully"
+    
+    return StepResult(
+        output=result,
+        variables={"last_fruit": fruit}
+    )
+
+# Aggregator to summarize results
+def summarize(ctx: WorkflowContext) -> StepResult:
+    """Summarize all processed fruits."""
+    outputs = ctx.variables.get("loop_outputs", [])
+    summary = f"📊 Processed {len(outputs)} fruits:\n"
+    summary += "\n".join(f"  {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow
+workflow = Workflow(
+    name="Fruit Processor",
+    steps=[
+        loop(process_fruit, over="fruits"),
+        summarize
+    ],
+    variables={"fruits": fruits}
+)
+
+if __name__ == "__main__":
+    print("=== Testing Loop with List ===\n")
+    
+    result = workflow.start("Process all fruits", verbose=True)
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nLoop outputs count: {len(result['variables']['loop_outputs'])}")
+    print(f"Last processed: {result['variables'].get('last_fruit')}")

examples/python/workflows/workflow_loops.py

@@ -0,0 +1,46 @@
+"""
+Workflow Loops Example
+
+Demonstrates iterating over a list of items in a workflow step.
+Each item is processed individually with the loop variable.
+"""
+
+from praisonaiagents.memory.workflows import WorkflowManager, WorkflowStep, Workflow
+
+# Create a workflow with loop
+workflow = Workflow(
+    name="Process Items",
+    description="Process a list of items using loop",
+    variables={
+        "items": ["apple", "banana", "cherry"]  # List to iterate over
+    },
+    steps=[
+        WorkflowStep(
+            name="process_each",
+            action="Describe the fruit: {{item}}",
+            loop_over="items",  # Variable name containing the list
+            loop_var="item"     # Variable name for current item
+        ),
+        WorkflowStep(
+            name="summarize",
+            action="Summarize all the fruits that were processed."
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    # Create manager and register workflow
+    manager = WorkflowManager()
+    manager.workflows["Process Items"] = workflow
+    
+    # Execute - will process each fruit in the list
+    result = manager.execute(
+        "Process Items",
+        default_llm="gpt-4o-mini"
+    )
+    
+    print("Workflow completed!")
+    for step_result in result["results"]:
+        print(f"  {step_result['step']}: {step_result['status']}")
+        if isinstance(step_result.get("output"), list):
+            print(f"    Loop processed {len(step_result['output'])} items")

examples/python/workflows/workflow_mixed_steps.py

@@ -0,0 +1,68 @@
+"""
+Mixed Steps Workflow Example
+
+Demonstrates combining different step types in a single workflow:
+- Agent instances
+- Handler functions
+- WorkflowStep with action strings
+"""
+
+from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult, Agent
+
+# Create an agent
+analyzer = Agent(
+    name="Analyzer",
+    role="Data Analyst",
+    goal="Analyze and summarize data",
+    llm="gpt-4o-mini"
+)
+
+# Custom handler functions
+def validate_input(ctx: WorkflowContext) -> StepResult:
+    """Validate the input before processing."""
+    if len(ctx.input) < 5:
+        return StepResult(
+            output="Input too short. Minimum 5 characters required.",
+            stop_workflow=True
+        )
+    return StepResult(output=f"✅ Valid input: {ctx.input}")
+
+def format_output(ctx: WorkflowContext) -> StepResult:
+    """Format the final output."""
+    return StepResult(
+        output=f"📊 Report:\n{ctx.previous_result}",
+        variables={"report_generated": True}
+    )
+
+# Create workflow with mixed step types
+workflow = Workflow(
+    name="Mixed Pipeline",
+    steps=[
+        # Step 1: Function - validates input
+        validate_input,
+        
+        # Step 2: Agent - analyzes content
+        analyzer,
+        
+        # Step 3: WorkflowStep with action string
+        WorkflowStep(
+            name="enhance",
+            action="Add a conclusion to this analysis: {{previous_output}}"
+        ),
+        
+        # Step 4: Function - formats output
+        format_output
+    ],
+    default_llm="gpt-4o-mini"  # Used for action-based steps
+)
+
+if __name__ == "__main__":
+    # Test with valid input
+    print("=== Running mixed workflow ===")
+    result = workflow.start(
+        "Analyze the trends in AI adoption for 2024",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")
+    print(f"\nVariables: {result['variables']}")

examples/python/workflows/workflow_parallel.py

@@ -0,0 +1,56 @@
+"""
+Agentic Parallel Workflow Example
+
+Demonstrates running multiple agents concurrently and
+combining their results with an aggregator agent.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import parallel
+
+# Create parallel research agents
+market_researcher = Agent(
+    name="MarketResearcher",
+    role="Market Research Analyst",
+    goal="Research market trends and opportunities",
+    instructions="Analyze market trends. Provide concise market insights."
+)
+
+competitor_researcher = Agent(
+    name="CompetitorResearcher", 
+    role="Competitive Intelligence Analyst",
+    goal="Research competitor strategies",
+    instructions="Analyze competitors. Provide key competitive insights."
+)
+
+customer_researcher = Agent(
+    name="CustomerResearcher",
+    role="Customer Research Analyst", 
+    goal="Research customer needs and behaviors",
+    instructions="Analyze customer segments. Provide customer insights."
+)
+
+# Create aggregator agent
+aggregator = Agent(
+    name="Aggregator",
+    role="Research Synthesizer",
+    goal="Synthesize research findings",
+    instructions="Combine all research findings into a comprehensive summary."
+)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research Pipeline",
+    steps=[
+        parallel([market_researcher, competitor_researcher, customer_researcher]),
+        aggregator
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Parallel Workflow ===\n")
+    
+    # Run workflow - all researchers work in parallel, then aggregator summarizes
+    result = workflow.start("Research the AI industry", verbose=True)
+    
+    print(f"\nFinal Summary:\n{result['output']}")

examples/python/workflows/workflow_parallel_non_agentic.py

@@ -0,0 +1,53 @@
+"""
+Workflow Parallel Execution Example
+
+Demonstrates running multiple steps concurrently and
+combining their results.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import parallel
+import time
+
+# Parallel workers - each does independent work
+def research_market(ctx: WorkflowContext) -> StepResult:
+    """Research market trends."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="📊 Market: Growth expected 15% YoY")
+
+def research_competitors(ctx: WorkflowContext) -> StepResult:
+    """Research competitor analysis."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="🏢 Competitors: 3 major players identified")
+
+def research_customers(ctx: WorkflowContext) -> StepResult:
+    """Research customer feedback."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="👥 Customers: 85% satisfaction rate")
+
+# Aggregator - combines parallel results
+def summarize_research(ctx: WorkflowContext) -> StepResult:
+    """Summarize all research findings."""
+    outputs = ctx.variables.get("parallel_outputs", [])
+    summary = "📋 RESEARCH SUMMARY:\n" + "\n".join(f"  • {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research",
+    steps=[
+        parallel([research_market, research_competitors, research_customers]),
+        summarize_research
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Parallel Workflow ===\n")
+    
+    start_time = time.time()
+    result = workflow.start("Analyze the business landscape", verbose=True)
+    elapsed = time.time() - start_time
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nCompleted in {elapsed:.2f}s (parallel execution)")
+    print(f"Individual outputs: {len(result['variables']['parallel_outputs'])}")

examples/python/workflows/workflow_repeat.py

@@ -0,0 +1,53 @@
+"""
+Agentic Evaluator-Optimizer (Repeat) Workflow Example
+
+Demonstrates the evaluator-optimizer pattern where an agent
+generates content and another evaluates it, repeating until approved.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import repeat
+
+# Create generator agent
+generator = Agent(
+    name="Generator",
+    role="Content Generator",
+    goal="Generate high-quality content",
+    instructions="Generate content based on the topic. Improve based on feedback if provided."
+)
+
+# Create evaluator agent  
+evaluator = Agent(
+    name="Evaluator",
+    role="Content Evaluator",
+    goal="Evaluate and provide feedback on content",
+    instructions="Evaluate the content quality. If good, respond with 'APPROVED'. Otherwise provide specific feedback for improvement."
+)
+
+# Evaluation function to check if content is approved
+def is_approved(ctx) -> bool:
+    return "approved" in ctx.previous_result.lower()
+
+# Create workflow with evaluator-optimizer pattern
+workflow = Workflow(
+    name="Evaluator-Optimizer Pipeline",
+    steps=[
+        generator,  # First, generate content
+        repeat(
+            evaluator,  # Evaluate and provide feedback
+            until=is_approved,
+            max_iterations=3
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Evaluator-Optimizer Workflow ===\n")
+    
+    # Run optimization workflow
+    result = workflow.start(
+        "Write a compelling product description for an AI assistant",
+        verbose=True
+    )
+    
+    print(f"\nFinal Result:\n{result['output']}")

examples/python/workflows/workflow_repeat_non_agentic.py

@@ -0,0 +1,69 @@
+"""
+Workflow Repeat (Evaluator-Optimizer) Example
+
+Demonstrates repeating a step until a condition is met.
+This is useful for iterative improvement patterns.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import repeat
+
+# Simulated content generator that improves each iteration
+class ContentGenerator:
+    def __init__(self):
+        self.iteration = 0
+        self.content = []
+    
+    def generate(self, ctx: WorkflowContext) -> StepResult:
+        """Generate content, adding more each iteration."""
+        self.iteration += 1
+        
+        # Add new content each iteration
+        new_items = [
+            f"Point {self.iteration}.1: Key insight about the topic",
+            f"Point {self.iteration}.2: Supporting evidence"
+        ]
+        self.content.extend(new_items)
+        
+        output = f"Iteration {self.iteration}: Generated {len(self.content)} points total"
+        
+        return StepResult(
+            output=output,
+            variables={
+                "total_points": len(self.content),
+                "content": self.content.copy()
+            }
+        )
+
+# Condition: stop when we have enough content
+def has_enough_content(ctx: WorkflowContext) -> bool:
+    """Check if we have generated enough content."""
+    total = ctx.variables.get("total_points", 0)
+    return total >= 6  # Stop when we have 6+ points
+
+# Create generator instance
+generator = ContentGenerator()
+
+# Create workflow with repeat pattern
+workflow = Workflow(
+    name="Content Generator",
+    steps=[
+        repeat(
+            generator.generate,
+            until=has_enough_content,
+            max_iterations=10
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Repeat (Evaluator-Optimizer) Pattern ===\n")
+    
+    result = workflow.start("Generate comprehensive content", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Total iterations: {result['variables']['repeat_iterations']}")
+    print(f"Total points generated: {result['variables']['total_points']}")
+    print("\nGenerated content:")
+    for point in result['variables']['content']:
+        print(f"  • {point}")

examples/python/workflows/workflow_routing.py

@@ -0,0 +1,65 @@
+"""
+Agentic Routing Workflow Example
+
+Demonstrates decision-based routing where an agent classifier
+routes to specialized handler agents based on the request type.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import route
+
+# Create classifier agent
+classifier = Agent(
+    name="Classifier",
+    role="Request Classifier",
+    goal="Classify incoming requests",
+    instructions="Classify the request. Respond with ONLY 'technical', 'creative', or 'general'."
+)
+
+# Create specialized handler agents
+tech_agent = Agent(
+    name="TechExpert",
+    role="Technical Expert",
+    goal="Handle technical questions",
+    instructions="You are a technical expert. Provide detailed technical answers."
+)
+
+creative_agent = Agent(
+    name="CreativeWriter",
+    role="Creative Writer", 
+    goal="Handle creative requests",
+    instructions="You are a creative writer. Write engaging, creative content."
+)
+
+general_agent = Agent(
+    name="GeneralAssistant",
+    role="General Assistant",
+    goal="Handle general requests",
+    instructions="You are a helpful assistant. Provide clear, helpful responses."
+)
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Agentic Router",
+    steps=[
+        classifier,
+        route({
+            "technical": [tech_agent],
+            "creative": [creative_agent],
+            "default": [general_agent]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Routing Workflow ===\n")
+    
+    # Test 1: Technical question
+    print("--- Technical Request ---")
+    result = workflow.start("How does machine learning work?", verbose=True)
+    print(f"Result: {result['output'][:200]}...\n")
+    
+    # Test 2: Creative request
+    print("--- Creative Request ---")
+    result = workflow.start("Write a poem about the ocean", verbose=True)
+    print(f"Result: {result['output'][:200]}...")

examples/python/workflows/workflow_routing_non_agentic.py

@@ -0,0 +1,61 @@
+"""
+Workflow Routing Example
+
+Demonstrates decision-based routing where the workflow
+takes different paths based on the output of a decision step.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import route
+
+# Decision maker - determines which route to take
+def classify_request(ctx: WorkflowContext) -> StepResult:
+    """Classify the input and decide the route."""
+    input_lower = ctx.input.lower()
+    
+    if "urgent" in input_lower or "emergency" in input_lower:
+        return StepResult(output="priority: high")
+    elif "question" in input_lower or "help" in input_lower:
+        return StepResult(output="priority: support")
+    else:
+        return StepResult(output="priority: normal")
+
+# Route handlers
+def handle_high_priority(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="🚨 HIGH PRIORITY: Escalating to senior team immediately!")
+
+def handle_support(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="💬 SUPPORT: Routing to help desk for assistance.")
+
+def handle_normal(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="📋 NORMAL: Added to standard processing queue.")
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Request Router",
+    steps=[
+        classify_request,
+        route({
+            "high": [handle_high_priority],
+            "support": [handle_support],
+            "normal": [handle_normal],
+            "default": [handle_normal]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    # Test different inputs
+    print("=== Testing Routing Workflow ===\n")
+    
+    # Test 1: Urgent request
+    result = workflow.start("This is an URGENT matter!", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 2: Support request
+    result = workflow.start("I have a question about my account", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 3: Normal request
+    result = workflow.start("Please process my order", verbose=True)
+    print(f"Result: {result['output']}")

examples/python/workflows/workflow_with_agents.py

@@ -0,0 +1,45 @@
+"""
+Workflow with Agents Example
+
+Demonstrates using Agent instances directly as workflow steps.
+Agents are automatically wrapped and executed in sequence.
+"""
+
+from praisonaiagents import Workflow, Agent
+
+# Create agents
+researcher = Agent(
+    name="Researcher",
+    role="Research Specialist",
+    goal="Find accurate information",
+    llm="gpt-4o-mini"
+)
+
+writer = Agent(
+    name="Writer", 
+    role="Content Writer",
+    goal="Write engaging content",
+    llm="gpt-4o-mini"
+)
+
+editor = Agent(
+    name="Editor",
+    role="Content Editor", 
+    goal="Polish and improve content",
+    llm="gpt-4o-mini"
+)
+
+# Create workflow with agents as steps
+workflow = Workflow(
+    name="Content Pipeline",
+    steps=[researcher, writer, editor]
+)
+
+if __name__ == "__main__":
+    # Run the workflow
+    result = workflow.start(
+        "Write a short paragraph about artificial intelligence",
+        verbose=True
+    )
+    
+    print(f"\nFinal output:\n{result['output']}")

examples/yaml/agents_workflow.yaml

@@ -0,0 +1,117 @@
+# Extended agents.yaml with Workflow Patterns
+# This file demonstrates the extended agents.yaml format that supports
+# advanced workflow patterns while maintaining backward compatibility.
+#
+# Usage: praisonai agents_workflow.yaml
+#
+# Key differences from standard agents.yaml:
+# - process: workflow (triggers workflow mode)
+# - workflow: section for planning, reasoning, memory
+# - steps: section for workflow patterns (route, parallel, loop, repeat)
+
+framework: praisonai
+process: workflow
+input: "Research AI trends and create a comprehensive report"  # The input passed to {{input}} in steps
+
+# Workflow configuration (new)
+workflow:
+  planning: true
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+# Variables for template substitution
+variables:
+  topic: AI trends
+  topics:
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+# Agent definitions using familiar 'roles' format
+agents:  # Canonical: use 'agents' instead of 'roles'
+  classifier:
+    role: Request Classifier
+    instructions:  # Canonical |
+      You are an expert at classifying requests into categories.
+      Respond with ONLY one word: 'technical', 'creative', or 'research'.
+    goal: Classify incoming requests accurately
+    
+  researcher:
+    role: Research Analyst
+    instructions:  # Canonical |
+      You are a skilled research analyst with expertise in technology trends.
+      You provide concise, factual research findings with citations.
+    goal: Research topics thoroughly and provide insights
+    tools:
+      - tavily_search
+    llm:
+      model: gpt-4o-mini
+      
+  tech_expert:
+    role: Technical Expert
+    instructions:  # Canonical |
+      You are a technical expert with deep knowledge in AI and ML.
+      You provide detailed technical explanations.
+    goal: Handle technical questions with expertise
+    
+  creative_writer:
+    role: Creative Writer
+    instructions:  # Canonical |
+      You are a creative writer who can make complex topics engaging.
+      You write in a clear, accessible style.
+    goal: Create engaging content from research
+    
+  market_analyst:
+    role: Market Analyst
+    instructions:  # Canonical |
+      You analyze market trends and competitive landscapes.
+      You provide actionable business insights.
+    goal: Analyze market trends and opportunities
+    
+  aggregator:
+    role: Synthesizer
+    instructions:  # Canonical |
+      You combine findings from multiple sources into coherent reports.
+      You identify patterns and key insights.
+    goal: Synthesize all findings into comprehensive reports
+
+# Workflow steps with patterns (new)
+steps:
+  # Step 1: Classify the request
+  - agent: classifier
+    action: "Classify this request: {{topic}}"
+    
+  # Step 2: Route to appropriate handler based on classification
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [researcher]
+      
+  # Step 3: Parallel research on multiple aspects
+  - name: parallel_research
+    parallel:
+      - agent: researcher
+        action: "Research technology trends for {{topic}}"
+      - agent: market_analyst
+        action: "Analyze market opportunities for {{topic}}"
+        
+  # Step 4: Loop over specific topics
+  - agent: researcher
+    action: "Deep dive into {{item}}"
+    loop:
+      over: topics
+      
+  # Step 5: Aggregate all findings
+  - agent: aggregator
+    action: "Synthesize all research findings into a comprehensive report"
+    repeat:
+      until: "comprehensive"
+      max_iterations: 2
+
+# Optional callbacks
+callbacks:
+  on_step_complete: log_step

examples/yaml/workflows/complete_workflow.yaml

@@ -0,0 +1,116 @@
+# Complete Workflow Example
+# Demonstrates all workflow patterns in a single comprehensive workflow
+
+name: Complete Research Workflow
+description: A comprehensive workflow demonstrating all patterns - route, parallel, loop, repeat
+framework: praisonai
+
+workflow:
+  planning: true
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+variables:
+  topic: AI trends
+  topics:
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+agents:
+  classifier:
+    name: Classifier
+    role: Request Classifier
+    goal: Classify incoming requests
+    instructions: |
+      Classify the request. Respond with ONLY one word:
+      - 'technical' for technical questions
+      - 'creative' for creative requests
+      - 'research' for research tasks
+
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics thoroughly
+    instructions: "You are a research analyst. Provide concise, factual research findings."
+
+  tech_expert:
+    name: TechExpert
+    role: Technical Expert
+    goal: Handle technical questions
+    instructions: "You are a technical expert. Provide detailed technical answers."
+
+  creative_writer:
+    name: CreativeWriter
+    role: Creative Writer
+    goal: Handle creative requests
+    instructions: "You are a creative writer. Write engaging, creative content."
+
+  market_analyst:
+    name: MarketAnalyst
+    role: Market Analyst
+    goal: Analyze market trends
+    instructions: "You are a market analyst. Provide market insights."
+
+  competitor_analyst:
+    name: CompetitorAnalyst
+    role: Competitor Analyst
+    goal: Analyze competitors
+    instructions: "You are a competitor analyst. Provide competitive insights."
+
+  aggregator:
+    name: Aggregator
+    role: Synthesizer
+    goal: Combine and synthesize findings
+    instructions: "You are a synthesizer. Combine all findings into a comprehensive report."
+
+  evaluator:
+    name: Evaluator
+    role: Quality Evaluator
+    goal: Evaluate content quality
+    instructions: |
+      Evaluate the content. If it's comprehensive and well-structured, respond with "APPROVED".
+      Otherwise, provide specific feedback for improvement.
+
+steps:
+  # Step 1: Classify the request
+  - agent: classifier
+    action: "Classify: {{input}}"
+    
+  # Step 2: Route to appropriate handler
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [researcher]
+      
+  # Step 3: Parallel research
+  - name: parallel_research
+    parallel:
+      - agent: market_analyst
+        action: "Analyze market for {{topic}}"
+      - agent: competitor_analyst
+        action: "Analyze competitors for {{topic}}"
+        
+  # Step 4: Loop over topics
+  - agent: researcher
+    action: "Research {{item}}"
+    loop:
+      over: topics
+      
+  # Step 5: Aggregate findings
+  - agent: aggregator
+    action: "Synthesize all findings into a comprehensive report"
+    
+  # Step 6: Evaluator-optimizer
+  - agent: evaluator
+    action: "Evaluate the report quality"
+    repeat:
+      until: "approved"
+      max_iterations: 2
+
+callbacks:
+  on_step_complete: log_step

examples/yaml/workflows/evaluator_optimizer_workflow.yaml

@@ -0,0 +1,43 @@
+# Evaluator-Optimizer Workflow
+# Demonstrates the repeat() pattern for iterative improvement
+
+name: Evaluator Optimizer Workflow
+description: A generator creates content, an evaluator reviews it repeatedly until quality standards are met
+
+workflow:
+  verbose: true
+
+agents:
+  generator:
+    name: Generator
+    role: Content Generator
+    goal: Generate high-quality content
+    instructions: |
+      You are a content generator. Generate content based on the request.
+      If feedback is provided, improve your content based on that feedback.
+      Always strive for clarity, accuracy, and engagement.
+
+  evaluator:
+    name: Evaluator
+    role: Content Evaluator
+    goal: Evaluate content quality and provide feedback
+    instructions: |
+      You are a content evaluator. Review the content provided.
+      
+      If the content is high quality (clear, accurate, engaging), respond with:
+      "APPROVED: [brief reason]"
+      
+      If the content needs improvement, respond with:
+      "NEEDS IMPROVEMENT: [specific feedback for improvement]"
+      
+      Be constructive and specific in your feedback.
+
+steps:
+  - agent: generator
+    action: "Generate content for: {{input}}"
+    
+  - agent: evaluator
+    action: "Evaluate this content and provide feedback: {{previous_output}}"
+    repeat:
+      until: "approved"
+      max_iterations: 3

examples/yaml/workflows/example_usage.py

@@ -0,0 +1,152 @@
+"""
+Example usage of YAML Workflow Parser.
+
+This script demonstrates how to load and execute YAML workflow files.
+"""
+
+import os
+from pathlib import Path
+
+# Ensure OPENAI_API_KEY is set
+if not os.getenv("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    print("export OPENAI_API_KEY='your-api-key'")
+    exit(1)
+
+from praisonaiagents.workflows import YAMLWorkflowParser, WorkflowManager
+
+
+def example_1_parse_and_run():
+    """Example 1: Parse YAML and run workflow directly."""
+    print("=" * 60)
+    print("Example 1: Parse YAML and run workflow")
+    print("=" * 60)
+    
+    yaml_content = """
+name: Quick Research
+description: A quick research workflow
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide brief, factual information."
+
+steps:
+  - agent: researcher
+    action: "Research: {{input}}"
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print(f"Workflow Name: {workflow.name}")
+    print(f"Steps: {len(workflow.steps)}")
+    
+    # Run the workflow
+    result = workflow.start("What is Python?")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_2_load_yaml_file():
+    """Example 2: Load workflow from YAML file using WorkflowManager."""
+    print("=" * 60)
+    print("Example 2: Load YAML file with WorkflowManager")
+    print("=" * 60)
+    
+    # Get the directory of this script
+    script_dir = Path(__file__).parent
+    yaml_file = script_dir / "simple_workflow.yaml"
+    
+    if not yaml_file.exists():
+        print(f"YAML file not found: {yaml_file}")
+        return
+    
+    manager = WorkflowManager()
+    workflow = manager.load_yaml(yaml_file)
+    
+    print(f"Loaded workflow: {workflow.name}")
+    print(f"Steps: {len(workflow.steps)}")
+    
+    # Run the workflow
+    result = workflow.start("Benefits of renewable energy")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_3_execute_yaml_directly():
+    """Example 3: Execute YAML file directly with WorkflowManager."""
+    print("=" * 60)
+    print("Example 3: Execute YAML directly")
+    print("=" * 60)
+    
+    script_dir = Path(__file__).parent
+    yaml_file = script_dir / "simple_workflow.yaml"
+    
+    if not yaml_file.exists():
+        print(f"YAML file not found: {yaml_file}")
+        return
+    
+    manager = WorkflowManager()
+    result = manager.execute_yaml(
+        yaml_file,
+        input_data="The future of AI",
+        verbose=True
+    )
+    
+    print(f"Status: {result['status']}")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_4_with_variables():
+    """Example 4: YAML workflow with variables."""
+    print("=" * 60)
+    print("Example 4: Workflow with variables")
+    print("=" * 60)
+    
+    yaml_content = """
+name: Variable Workflow
+variables:
+  topic: Machine Learning
+  style: concise
+
+agents:
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write content
+    instructions: "Write {{style}} content about the topic."
+
+steps:
+  - agent: writer
+    action: "Write about {{topic}}"
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print(f"Variables: {workflow.variables}")
+    
+    # Run with default variables
+    result = workflow.start("")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+if __name__ == "__main__":
+    print("YAML Workflow Examples")
+    print("=" * 60)
+    print()
+    
+    # Run examples
+    example_1_parse_and_run()
+    example_2_load_yaml_file()
+    example_3_execute_yaml_directly()
+    example_4_with_variables()
+    
+    print("=" * 60)
+    print("All examples completed!")
+    print("=" * 60)

examples/yaml/workflows/loop_workflow.yaml

@@ -0,0 +1,42 @@
+# Loop Workflow
+# Demonstrates the loop() pattern for iterating over items
+
+name: Repetitive Processing Workflow
+description: An agent processes multiple items in a loop, then a summarizer combines results
+
+workflow:
+  verbose: true
+
+variables:
+  topics:
+    - Artificial Intelligence
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+agents:
+  processor:
+    name: Processor
+    role: Topic Processor
+    goal: Process and analyze each topic thoroughly
+    instructions: |
+      You are a topic processor. For each topic given, provide:
+      1. A brief definition
+      2. Key concepts
+      3. Real-world applications
+      Keep your response concise but informative.
+
+  summarizer:
+    name: Summarizer
+    role: Results Summarizer
+    goal: Summarize all processed results into a final report
+    instructions: "You are a summarizer. Combine all the processed topics into a cohesive final report."
+
+steps:
+  - agent: processor
+    action: "Analyze this topic: {{item}}"
+    loop:
+      over: topics
+      
+  - agent: summarizer
+    action: "Create a comprehensive summary of all the analyzed topics based on these results: {{previous_output}}"

examples/yaml/workflows/parallel_workflow.yaml

@@ -0,0 +1,47 @@
+# Parallel Workflow
+# Demonstrates the parallel() pattern for concurrent execution
+
+name: Parallel Research Workflow
+description: Multiple agents research different aspects concurrently, then an aggregator combines results
+input: "AI-powered customer service solutions"  # The input passed to {{input}} in steps
+
+workflow:
+  verbose: true
+
+agents:
+  market_researcher:
+    name: MarketResearcher
+    role: Market Research Analyst
+    goal: Research market trends and opportunities
+    instructions: "You are a market research analyst. Analyze market trends and provide concise insights."
+
+  competitor_researcher:
+    name: CompetitorResearcher
+    role: Competitive Intelligence Analyst
+    goal: Research competitor strategies and positioning
+    instructions: "You are a competitive intelligence analyst. Analyze competitors and provide key insights."
+
+  customer_researcher:
+    name: CustomerResearcher
+    role: Customer Research Analyst
+    goal: Research customer needs and behaviors
+    instructions: "You are a customer research analyst. Analyze customer segments and provide insights."
+
+  aggregator:
+    name: Aggregator
+    role: Research Synthesizer
+    goal: Synthesize all research findings into a comprehensive summary
+    instructions: "You are a research synthesizer. Combine all research findings into a clear, comprehensive summary."
+
+steps:
+  - name: parallel_research
+    parallel:
+      - agent: market_researcher
+        action: "Research market trends for: {{input}}"
+      - agent: competitor_researcher
+        action: "Research competitors for: {{input}}"
+      - agent: customer_researcher
+        action: "Research customer needs for: {{input}}"
+        
+  - agent: aggregator
+    action: "Synthesize all the research findings into a comprehensive report: {{previous_output}}"

examples/yaml/workflows/routing_workflow.yaml

@@ -0,0 +1,50 @@
+# Routing Workflow
+# Demonstrates the route() pattern for decision-based branching
+
+name: Agentic Routing Workflow
+description: A classifier agent routes requests to specialized handler agents
+input: "Write a poem about the ocean"  # The input passed to {{input}} in steps
+
+workflow:
+  verbose: true
+
+agents:
+  classifier:
+    name: Classifier
+    role: Request Classifier
+    goal: Classify incoming requests by type
+    instructions: |
+      You are a request classifier. Analyze the request and respond with ONLY one word:
+      - 'technical' for technical/coding questions
+      - 'creative' for creative writing requests
+      - 'general' for everything else
+      
+      Respond with ONLY the classification word, nothing else.
+
+  tech_expert:
+    name: TechExpert
+    role: Technical Expert
+    goal: Answer technical questions with expertise
+    instructions: "You are a technical expert. Provide detailed, accurate technical answers."
+
+  creative_writer:
+    name: CreativeWriter
+    role: Creative Writer
+    goal: Create engaging creative content
+    instructions: "You are a creative writer. Write engaging, imaginative content."
+
+  general_assistant:
+    name: GeneralAssistant
+    role: General Assistant
+    goal: Help with general requests
+    instructions: "You are a helpful assistant. Provide clear, helpful responses."
+
+steps:
+  - agent: classifier
+    action: "Classify this request: {{input}}"
+    
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [general_assistant]

examples/yaml/workflows/simple_workflow.yaml

@@ -0,0 +1,29 @@
+# Simple Sequential Workflow
+# Demonstrates basic agent-to-agent workflow
+
+name: Simple Research Workflow
+description: A simple workflow where a researcher gathers info and a writer summarizes it
+input: "The benefits of renewable energy"  # The input passed to {{input}} in steps
+
+workflow:
+  verbose: true
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research and gather information about topics
+    instructions: "You are a research analyst. Provide concise, factual information about the given topic."
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write clear and engaging summaries
+    instructions: "You are a content writer. Take the research provided and write a clear, engaging summary."
+
+steps:
+  - agent: researcher
+    action: "Research the following topic: {{input}}"
+    
+  - agent: writer
+    action: "Write a summary based on this research: {{previous_output}}"

src/praisonai-agents/.gitignore

@@ -86,3 +86,5 @@ build
 graph.py
 chroma_db/
 .qodo
+*_COMPARISON_ANALYSIS.md
+*_REPORT.md

src/praisonai-agents/README.md

@@ -1,83 +0,0 @@
-# MCP SSE Server and Client Implementation
-
-This project demonstrates a working pattern for SSE-based MCP (Model Context Protocol) servers and clients. It consists of three main components:
-
-1. **server.py**: An SSE-based MCP server that provides simple tools
-2. **client.py**: A standalone client that connects to the server and uses its tools with Claude
-3. **mcp-sse.py**: A client using praisonaiagents that connects to the server and uses its tools with OpenAI
-
-## Tools Provided by the Server
-
-The server implements two simple tools:
-
-- **get_greeting**: Returns a personalized greeting for a given name
-- **get_weather**: Returns simulated weather data for a given city
-
-## Setup and Usage
-
-### Prerequisites
-
-Make sure you have the required packages installed:
-
-```bash
-pip install praisonaiagents mcp httpx starlette uvicorn anthropic python-dotenv
-```
-
-### Running the Server
-
-First, start the MCP SSE server:
-
-```bash
-python server.py
-```
-
-By default, the server runs on 0.0.0.0:8080, but you can customize the host and port:
-
-```bash
-python server.py --host 127.0.0.1 --port 8081
-```
-
-### Running the Standalone Client
-
-The standalone client uses Claude to interact with the MCP server tools:
-
-```bash
-# Set your Anthropic API key
-export ANTHROPIC_API_KEY=your_api_key_here
-
-# Run the client
-python client.py http://0.0.0.0:8080/sse
-```
-
-You'll see a prompt where you can type queries for Claude to process using the MCP tools.
-
-### Running the praisonaiagents Client
-
-The praisonaiagents client uses OpenAI to interact with the MCP server tools:
-
-```bash
-# Set your OpenAI API key
-export OPENAI_API_KEY=your_api_key_here
-
-# Run the client
-python mcp-sse.py
-```
-
-This will automatically send a query about the weather in Paris to the agent.
-
-## How It Works
-
-1. The server exposes MCP tools via an SSE endpoint
-2. Clients connect to this endpoint and discover available tools
-3. When a user makes a query, the client:
-   - For client.py: Uses Claude to determine which tool to call
-   - For mcp-sse.py: Uses OpenAI to determine which tool to call
-4. The client executes the tool call against the server
-5. The result is returned to the user
-
-This pattern allows for decoupled processes where the MCP server can run independently of clients, making it suitable for cloud-native applications.
-
-## Customizing
-
-- To add more tools to the server, define new functions with the `@mcp.tool()` decorator in `server.py`
-- To change the client's behavior, update the instructions and query in `mcp-sse.py` 

src/praisonai-agents/README.md

@@ -0,0 +1 @@
+../../README.md

src/praisonai-agents/benchmarks/BENCHMARK_RESULTS.md

@@ -0,0 +1,35 @@
+# PraisonAI Agents - Benchmark Results
+
+**Generated:** 2025-12-18 14:40:22
+**Iterations:** 100
+**Test:** Agent instantiation (without tools)
+
+## Results
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **3.77** | **1.00x (fastest)** |
+| OpenAI Agents SDK | 5.26 | 1.39x |
+| Agno | 5.64 | 1.49x |
+| PraisonAI (LiteLLM) | 7.56 | 2.00x |
+| PydanticAI | 226.94 | 60.16x |
+| LangGraph | 4,558.71 | 1,209x |
+| CrewAI | 15,607.92 | 4,138x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| PydanticAI | 1.35.0 |
+| OpenAI Agents SDK | 0.6.3 |
+| LangGraph | 1.0.5 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```

src/praisonai-agents/benchmarks/EXECUTION_BENCHMARK_RESULTS.md

@@ -0,0 +1,31 @@
+# PraisonAI Agents - Real Execution Benchmark
+
+**Generated:** 2025-12-18 14:43:52
+**Model:** gpt-4o-mini
+**Iterations:** 3
+**Prompt:** "What is 2+2? Reply with just the number."
+
+## Results
+
+| Framework | Method | Avg Time | Relative |
+|-----------|--------|----------|----------|
+| **PraisonAI** | `agent.start()` | **0.45s** | **1.00x (fastest)** |
+| PraisonAI (LiteLLM) | `agent.start()` | 0.55s | 1.22x |
+| CrewAI | `crew.kickoff()` | 0.58s | 1.28x |
+| Agno | `agent.run()` | 0.92s | 2.05x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+export OPENAI_API_KEY=your_key
+cd praisonai-agents
+python benchmarks/execution_benchmark.py
+```

src/praisonai-agents/benchmarks/REAL_BENCHMARK_RESULTS.md

@@ -0,0 +1,72 @@
+# PraisonAI Agents - Real-World Execution Benchmark
+
+**Generated:** 2025-12-18 14:33:49
+**Model:** gpt-4o-mini
+**Iterations:** 3 per test
+
+## Results Summary
+
+| Test | PraisonAI (avg) | Agno (avg) | Difference |
+|------|-----------------|------------|------------|
+| Single Agent | 2.04s | 3.18s | PraisonAI 1.56x faster |
+| 2 Agents | 2.49s | 20.49s | PraisonAI 8.21x faster |
+| 3 Agents | 6.52s | 13.97s | PraisonAI 2.14x faster |
+
+## Detailed Results
+
+### praisonai_single
+- Average: 2.04s
+- Min: 1.95s
+- Max: 2.19s
+- Std Dev: 0.13s
+- Times: ['2.19s', '1.95s', '2.00s']
+
+### agno_single
+- Average: 3.18s
+- Min: 3.00s
+- Max: 3.51s
+- Std Dev: 0.28s
+- Times: ['3.51s', '3.00s', '3.04s']
+
+### praisonai_two_agents
+- Average: 2.49s
+- Min: 2.22s
+- Max: 2.65s
+- Std Dev: 0.24s
+- Times: ['2.65s', '2.22s', '2.62s']
+
+### agno_two_agents
+- Average: 20.49s
+- Min: 9.96s
+- Max: 35.05s
+- Std Dev: 13.02s
+- Times: ['16.46s', '9.96s', '35.05s']
+
+### praisonai_three_agents
+- Average: 6.52s
+- Min: 5.62s
+- Max: 7.39s
+- Std Dev: 0.88s
+- Times: ['5.62s', '6.54s', '7.39s']
+
+### agno_three_agents
+- Average: 13.97s
+- Min: 11.69s
+- Max: 15.32s
+- Std Dev: 1.99s
+- Times: ['14.91s', '11.69s', '15.32s']
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+
+## How to Reproduce
+
+```bash
+export OPENAI_API_KEY=your_key
+cd praisonai-agents
+python benchmarks/real_benchmark.py
+```