Release v2.3.38

Add performance comparison table to README showing PraisonAI as fastest framework for agent instantiation. Include benchmarks for LangGraph and CrewAI frameworks. Implement auto-save functionality to generate BENCHMARK_RESULTS.md and update README.md with latest benchmark results.

.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

README.md

@@ -30,7 +30,140 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
   </a>
 </div>
 
-## Key Features
+---
+
+## 📑 Table of Contents
+
+- [⚡ Performance](#-performance)
+- [🚀 Quick Start](#-quick-start)
+- [📦 Installation](#-installation)
+  - [Python SDK](#python-sdk)
+  - [JavaScript SDK](#javascript-sdk)
+- [💻 Usage](#-usage)
+  - [Python Code Examples](#python-code-examples)
+  - [CLI / No-Code Interface](#cli--no-code-interface)
+  - [JavaScript Code Examples](#javascript-code-examples)
+- [✨ Key Features](#-key-features)
+- [🌐 Supported Providers](#-supported-providers)
+- [🛠️ Custom Tools](#️-custom-tools)
+- [🔧 Configuration & Integration](#-configuration--integration)
+  - [Ollama Integration](#ollama-integration)
+  - [Groq Integration](#groq-integration)
+  - [100+ Models Support](#100-models-support)
+- [📋 Workflows](#-workflows)
+  - [Workflow Patterns](#workflow-patterns)
+  - [YAML Configuration](#yaml-configuration)
+  - [Agents Playbook](#agents-playbook)
+- [🧠 Memory & Context](#-memory--context)
+- [🔬 Advanced Features](#-advanced-features)
+  - [Research & Intelligence](#research--intelligence)
+  - [Planning & Workflows](#planning--workflows)
+  - [Specialised Agents](#specialised-agents)
+  - [MCP Protocol](#mcp-protocol)
+  - [Safety & Control](#safety--control)
+  - [Developer Tools](#developer-tools)
+- [📊 Process Types & Patterns](#-process-types--patterns)
+  - [Sequential Process](#sequential-process)
+  - [Hierarchical Process](#hierarchical-process)
+  - [Workflow Process](#workflow-process)
+  - [Agentic Patterns](#agentic-patterns)
+- [🎓 Video Tutorials](#-video-tutorials)
+- [⭐ Star History](#-star-history)
+- [👥 Contributing](#-contributing)
+- [🔧 Development](#-development)
+
+---
+
+## ⚡ Performance
+
+PraisonAI Agents is the **fastest AI agent framework** for agent instantiation.
+
+| 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 |
+
+<details>
+<summary>Run benchmarks yourself</summary>
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```
+
+</details>
+
+---
+
+## 🚀 Quick Start
+
+Get started with PraisonAI in under 1 minute:
+
+```bash
+# Install
+pip install praisonaiagents
+
+# Set API key
+export OPENAI_API_KEY=your_key_here
+
+# Create a simple agent
+python -c "from praisonaiagents import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"
+```
+
+---
+
+## 📦 Installation
+
+### Python SDK
+
+Lightweight package dedicated for coding:
+
+```bash
+pip install praisonaiagents
+```
+
+For the full framework with CLI support:
+
+```bash
+pip install praisonai
+```
+
+### JavaScript SDK
+
+```bash
+npm install praisonai
+```
+
+---
+
+## 💻 Usage
+
+### Python Code Examples
+
+- [📘 Complete Python Examples](#using-python-code)
+- [🔧 Custom Tools](#️-custom-tools)
+- [🧠 Memory Configuration](#-memory--context)
+
+### CLI / No-Code Interface
+
+- [🎯 Auto Mode](#auto-mode)
+- [🔬 Deep Research](#deep-research-cli)
+- [📋 Planning Mode](#planning-mode-cli)
+- [💾 Memory Management](#memory-cli)
+- [🔄 Workflow Execution](#workflow-cli)
+
+### JavaScript Code Examples
+
+- [💻 JavaScript Usage](#using-javascript-code)
+
+---
+
+## ✨ Key Features
 
 | Feature | Code | Docs |
 |---------|:----:|:----:|
@@ -114,7 +247,11 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | 💾 Auto-Save Sessions | [Example](#session-management-python) | [📖](https://docs.praison.ai/cli/session) |
 | 📜 History in Context | [Example](#session-management-python) | [📖](https://docs.praison.ai/cli/session) |
 
-## Supported Providers
+---
+
+## 🌐 Supported Providers
+
+PraisonAI supports 100+ LLM providers through seamless integration:
 
 | Provider | Example |
 |----------|:-------:|
@@ -143,14 +280,14 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | Moonshot | [Example](examples/python/providers/moonshot/moonshot_example.py) |
 | vLLM | [Example](examples/python/providers/vllm/vllm_example.py) |
 
-## Using Python Code
+---
+
+## 📘 Using Python Code
 
 Light weight package dedicated for coding:
-```bash
-pip install praisonaiagents
-```
 
 ```bash
+pip install praisonaiagents
 export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
 ```
 
@@ -605,6 +742,77 @@ result = manager.execute_yaml(
 )
 ```
 
+### Complete workflow.yaml Reference
+
+```yaml
+# workflow.yaml - Full feature reference
+name: Complete Workflow
+description: Demonstrates all workflow.yaml features
+framework: praisonai  # praisonai, crewai, autogen
+process: workflow     # sequential, hierarchical, workflow
+
+workflow:
+  planning: true
+  planning_llm: gpt-4o
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+variables:
+  topic: AI trends
+  items: [ML, NLP, Vision]
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics thoroughly
+    instructions: "Provide detailed research findings"
+    backstory: "Expert researcher with 10 years experience"  # alias for instructions
+    llm: gpt-4o-mini
+    function_calling_llm: gpt-4o      # For tool calls
+    max_rpm: 10                        # Rate limiting
+    max_execution_time: 300            # Timeout in seconds
+    reflect_llm: gpt-4o               # For self-reflection
+    min_reflect: 1
+    max_reflect: 3
+    system_template: "You are a helpful assistant"
+    tools:
+      - tavily_search
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write clear content
+    instructions: "Write engaging content"
+
+steps:
+  - name: research_step
+    agent: researcher
+    action: "Research {{topic}}"
+    expected_output: "Comprehensive research report"
+    output_file: "output/research.md"
+    create_directory: true
+    
+  - name: writing_step
+    agent: writer
+    action: "Write article based on research"
+    context:                          # Task dependencies
+      - research_step
+    output_json:                      # Structured output
+      type: object
+      properties:
+        title: { type: string }
+        content: { type: string }
+
+callbacks:
+  on_workflow_start: log_start
+  on_step_complete: log_step
+  on_workflow_complete: log_complete
+```
+
 ### 9. Hooks
 
 Configure in `.praison/hooks.json`:
@@ -621,9 +829,50 @@ hooks.register("pre_write_code", lambda ctx: print(f"Writing {ctx['file']}"))
 result = hooks.execute("pre_write_code", {"file": "main.py"})
 ```
 
-### 10. Extended agents.yaml with Workflow Patterns
+### 10. Field Names Reference (A-I-G-S)
 
-You can now use advanced workflow patterns directly in agents.yaml by setting `process: workflow`:
+PraisonAI accepts both old (agents.yaml) and new (workflow.yaml) field names. Use the **canonical names** for new projects:
+
+| Canonical (Recommended) | Alias (Also Works) | Purpose |
+|-------------------------|-------------------|---------|
+| `agents` | `roles` | Define agent personas |
+| `instructions` | `backstory` | Agent behavior/persona |
+| `action` | `description` | What the step does |
+| `steps` | `tasks` (nested) | Define work items |
+| `name` | `topic` | Workflow identifier |
+
+**A-I-G-S Mnemonic** - Easy to remember:
+- **A**gents - Who does the work
+- **I**nstructions - How they behave  
+- **G**oal - What they achieve
+- **S**teps - What they do
+
+```yaml
+# Quick Reference - Canonical Format
+name: My Workflow              # Workflow name (not 'topic')
+agents:                        # Define agents (not 'roles')
+  my_agent:
+    role: Job Title            # Agent's role
+    goal: What to achieve      # Agent's goal
+    instructions: How to act   # Agent's behavior (not 'backstory')
+    
+steps:                         # Define steps (not 'tasks')
+  - agent: my_agent
+    action: What to do         # Step action (not 'description')
+```
+
+> **Note:** The parser accepts both old and new names. Run `praisonai workflow validate <file.yaml>` to see suggestions for canonical names.
+
+### 11. Extended agents.yaml with Workflow Patterns
+
+**Feature Parity:** Both `agents.yaml` and `workflow.yaml` now support the same features:
+- All workflow patterns (route, parallel, loop, repeat)
+- All agent fields (function_calling_llm, max_rpm, max_execution_time, reflect_llm, templates)
+- All step fields (expected_output, context, output_json, create_directory, callback)
+- Framework support (praisonai, crewai, autogen)
+- Process types (sequential, hierarchical, workflow)
+
+You can use advanced workflow patterns directly in agents.yaml by setting `process: workflow`:
 
 ```yaml
 # agents.yaml with workflow patterns
@@ -639,15 +888,15 @@ workflow:
 variables:
   topic: AI trends
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   classifier:
     role: Request Classifier
-    backstory: "Classify requests into categories"
+    instructions: "Classify requests into categories"  # Canonical: use 'instructions' instead of 'backstory'
     goal: Classify requests
     
   researcher:
     role: Research Analyst
-    backstory: "Expert researcher"
+    instructions: "Expert researcher"  # Canonical: use 'instructions' instead of 'backstory'
     goal: Research topics
     tools:
       - tavily_search
@@ -690,9 +939,13 @@ Run with the same simple command:
 praisonai agents.yaml
 ```
 
-## Using No Code
+---
 
-### Auto Mode:
+## 🎯 CLI / No-Code Interface
+
+PraisonAI provides a powerful CLI for no-code automation and quick prototyping.
+
+### Auto Mode
 ```bash
 pip install praisonai
 export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
@@ -839,10 +1092,43 @@ praisonai "GPT-5" --workflow "Research:Search for info,Write:Write blog" --tools
 praisonai workflow help
 ```
 
+#### YAML Workflow Files:
+```bash
+# Run a YAML workflow file
+praisonai workflow run research.yaml
+
+# Run with variables
+praisonai workflow run research.yaml --var topic="AI trends"
+
+# Validate a YAML workflow
+praisonai workflow validate research.yaml
+
+# Create from template (simple, routing, parallel, loop, evaluator-optimizer)
+praisonai workflow template routing --output my_workflow.yaml
+```
+
+#### Auto-Generate Workflows:
+```bash
+# Auto-generate a sequential workflow from topic
+praisonai workflow auto "Research AI trends"
+
+# Generate parallel workflow (multiple agents work concurrently)
+praisonai workflow auto "Research AI trends" --pattern parallel
+
+# Generate routing workflow (classifier routes to specialists)
+praisonai workflow auto "Build a chatbot" --pattern routing
+
+# Specify output file
+praisonai workflow auto "Research AI" --pattern sequential --output my_workflow.yaml
+```
+
 **Workflow CLI Options:**
 | Flag | Description |
 |------|-------------|
 | `--workflow-var key=value` | Set workflow variable (can be repeated) |
+| `--var key=value` | Set variable for YAML workflows |
+| `--pattern <pattern>` | Pattern for auto-generation (sequential, parallel, routing, loop) |
+| `--output <file>` | Output file for auto-generation |
 | `--llm <model>` | LLM model (e.g., openai/gpt-4o-mini) |
 | `--tools <tools>` | Tools (comma-separated, e.g., tavily) |
 | `--planning` | Enable planning mode |
@@ -1133,6 +1419,36 @@ praisonai commit
 praisonai commit --push
 ```
 
+### Serve CLI (API Server):
+```bash
+# Start API server for agents defined in YAML
+praisonai serve agents.yaml
+
+# With custom port and host
+praisonai serve agents.yaml --port 8005 --host 0.0.0.0
+
+# Alternative flag style
+praisonai agents.yaml --serve
+
+# The server provides:
+# POST /agents          - Run all agents sequentially
+# POST /agents/{name}   - Run specific agent (e.g., /agents/researcher)
+# GET  /agents/list     - List available agents
+```
+
+### n8n Integration CLI:
+```bash
+# Export workflow to n8n and open in browser
+praisonai agents.yaml --n8n
+
+# With custom n8n URL
+praisonai agents.yaml --n8n --n8n-url http://localhost:5678
+
+# Set N8N_API_KEY for auto-import
+export N8N_API_KEY="your-api-key"
+praisonai agents.yaml --n8n
+```
+
 ### @Mentions in Prompts:
 ```bash
 # Include file content in prompt
@@ -1264,6 +1580,21 @@ agent = Agent(
         env={"BRAVE_API_KEY": "your-key"}
     )
 )
+
+# Multiple MCP servers + regular functions
+def my_custom_tool(query: str) -> str:
+    """Custom tool function."""
+    return f"Result: {query}"
+
+agent = Agent(
+    name="MultiToolAgent",
+    instructions="Agent with multiple MCP servers",
+    tools=[
+        MCP("uvx mcp-server-time"),                    # Time tools
+        MCP("npx @modelcontextprotocol/server-memory"), # Memory tools
+        my_custom_tool                                  # Regular function
+    ]
+)
 ```
 
 ### MCP Server (Expose Tools as MCP Server)
@@ -1297,6 +1628,48 @@ server.run()  # stdio for Claude Desktop
 | Security | Origin validation, DNS rebinding prevention |
 | WebSocket | Auto-reconnect with exponential backoff |
 
+## A2A (Agent2Agent Protocol)
+
+PraisonAI supports the [A2A Protocol](https://a2a-protocol.org) for agent-to-agent communication, enabling your agents to be discovered and collaborate with other AI agents.
+
+### A2A Server (Expose Agent as A2A Server)
+```python
+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"Results for: {query}"
+
+agent = Agent(
+    name="Research Assistant",
+    role="Research Analyst",
+    goal="Help users research topics",
+    tools=[search_web]
+)
+
+# Expose as A2A Server
+a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+
+app = FastAPI()
+app.include_router(a2a.get_router())
+
+# Run: uvicorn app:app --reload
+# Agent Card: GET /.well-known/agent.json
+# Status: GET /status
+```
+
+### A2A Features
+| Feature | Description |
+|---------|-------------|
+| Agent Card | JSON metadata for agent discovery |
+| Skills Extraction | Auto-generate skills from tools |
+| Task Management | Stateful task lifecycle |
+| Streaming | SSE streaming for real-time updates |
+
+> **Documentation**: [docs.praison.ai/a2a](https://docs.praison.ai/a2a) | **Examples**: [examples/python/a2a](https://github.com/MervinPraison/PraisonAI/tree/main/examples/python/a2a)
+
 ## CLI Features
 
 | Feature | Docs |
@@ -1328,7 +1701,9 @@ server.run()  # stdio for Claude Desktop
 | 📥 Web Fetch - URL content retrieval | [📖](https://docs.praison.ai/cli/web-fetch) |
 | 💾 Prompt Caching - Cost reduction | [📖](https://docs.praison.ai/cli/prompt-caching) |
 
-## Using JavaScript Code
+---
+
+## 💻 Using JavaScript Code
 
 ```bash
 npm install praisonai
@@ -1343,11 +1718,17 @@ agent.start('Write a movie script about a robot in Mars');
 
 ![PraisonAI CLI Demo](docs/demo/praisonai-cli-demo.gif)
 
-## Star History
+---
+
+## ⭐ Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=MervinPraison/PraisonAI&type=Date)](https://docs.praison.ai)
 
-## AI Agents Flow
+---
+
+## 📊 Process Types & Patterns
+
+### AI Agents Flow
 
 ```mermaid
 graph LR
@@ -1686,31 +2067,40 @@ flowchart LR
     style Out fill:#8B0000,color:#fff
 ```
 
-## Adding Models
+---
 
-<div align="center">
-  <a href="https://docs.praison.ai/models">
-    <p align="center">
-      <img src="https://img.shields.io/badge/%F0%9F%93%9A_Models-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Models" />
-    </p>
-  </a>
-</div>
+## 🔧 Configuration & Integration
+
+### Ollama Integration
 
-## Ollama Integration
 ```bash
 export OPENAI_BASE_URL=http://localhost:11434/v1
 ```
 
-## Groq Integration
+### Groq Integration
+
 Replace xxxx with Groq API KEY:
+
 ```bash
 export OPENAI_API_KEY=xxxxxxxxxxx
 export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 ```
 
-## No Code Options
+### 100+ Models Support
 
-## Agents Playbook
+PraisonAI supports 100+ LLM models from various providers. Visit our [models documentation](https://docs.praison.ai/models/) for the complete list.
+
+<div align="center">
+  <a href="https://docs.praison.ai/models">
+    <p align="center">
+      <img src="https://img.shields.io/badge/📚_Models_Documentation-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Models Documentation" />
+    </p>
+  </a>
+</div>
+
+---
+
+## 📋 Agents Playbook
 
 ### Simple Playbook Example
 
@@ -1719,9 +2109,9 @@ Create `agents.yaml` file and add the code below:
 ```yaml
 framework: praisonai
 topic: Artificial Intelligence
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   screenwriter:
-    backstory: "Skilled in crafting scripts with engaging dialogue about {topic}."
+    instructions: "Skilled in crafting scripts with engaging dialogue about {topic}."  # Canonical: use 'instructions' instead of 'backstory'
     goal: Create scripts from concepts.
     role: Screenwriter
     tasks:
@@ -1735,18 +2125,11 @@ roles:
 praisonai agents.yaml
 ```
 
-## Use 100+ Models
+---
 
-- https://docs.praison.ai/models/
-<div align="center">
-  <a href="https://docs.praison.ai">
-    <p align="center">
-      <img src="https://img.shields.io/badge/📚_Documentation-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Documentation" />
-    </p>
-  </a>
-</div>
+## 🛠️ Custom Tools / Create Plugins
 
-## Custom Tools
+PraisonAI supports multiple ways to create and integrate custom tools (plugins) into your agents.
 
 ### Using `@tool` Decorator
 
@@ -1819,276 +2202,96 @@ After `pip install`, tools are auto-discovered:
 agent = Agent(tools=["my_tool"])  # Works automatically!
 ```
 
+---
 
-## Prompt Expansion
+## 🧠 Memory & Context
 
-Expand short prompts into detailed, actionable prompts:
+PraisonAI provides zero-dependency persistent memory for agents. For detailed examples, see [section 6. Agent Memory](#6-agent-memory-zero-dependencies) in the Python Code Examples.
 
-### CLI Usage
+---
 
-```bash
-# Expand a short prompt into detailed prompt
-praisonai "write a movie script in 3 lines" --expand-prompt
+## 🔬 Advanced Features
 
-# With verbose output
-praisonai "blog about AI" --expand-prompt -v
+### Research & Intelligence
 
-# With tools for context gathering
-praisonai "latest AI trends" --expand-prompt --expand-tools tools.py
+- 🔬 **Deep Research Agents** - OpenAI & Gemini support for automated research
+- 🔄 **Query Rewriter Agent** - HyDE, Step-back, Multi-query strategies for RAG optimization
+- 🌐 **Native Web Search** - Real-time search via OpenAI, Gemini, Anthropic, xAI, Perplexity
+- 📥 **Web Fetch** - Retrieve full content from URLs (Anthropic)
+- 📝 **Prompt Expander Agent** - Expand short prompts into detailed instructions
 
-# Combine with query rewrite
-praisonai "AI news" --query-rewrite --expand-prompt
-```
+### Memory & Caching
 
-### Programmatic Usage
+- 💾 **Prompt Caching** - Reduce costs & latency (OpenAI, Anthropic, Bedrock, Deepseek)
+- 🧠 **Claude Memory Tool** - Persistent cross-conversation memory (Anthropic Beta)
+- 💾 **File-Based Memory** - Zero-dependency persistent memory for all agents
+- 🔍 **Built-in Search Tools** - Tavily, You.com, Exa for web search, news, content extraction
 
-```python
-from praisonaiagents import PromptExpanderAgent, ExpandStrategy
+### Planning & Workflows
 
-# Basic usage
-agent = PromptExpanderAgent()
-result = agent.expand("write a movie script in 3 lines")
-print(result.expanded_prompt)
+- 📋 **Planning Mode** - Plan before execution for agents & multi-agent systems
+- 🔧 **Planning Tools** - Research with tools during planning phase
+- 🧠 **Planning Reasoning** - Chain-of-thought planning for complex tasks
+- ⛓️ **Prompt Chaining** - Sequential prompt workflows with conditional gates
+- 🔍 **Evaluator Optimiser** - Generate and optimize through iterative feedback
+- 👷 **Orchestrator Workers** - Distribute tasks among specialised workers
+- ⚡ **Parallelisation** - Execute tasks in parallel for improved performance
+- 🔁 **Repetitive Agents** - Handle repetitive tasks through automated loops
+- 🤖 **Autonomous Workflow** - Monitor, act, adapt based on environment feedback
 
-# With specific strategy
-result = agent.expand("blog about AI", strategy=ExpandStrategy.DETAILED)
+### Specialised Agents
 
-# Available strategies: BASIC, DETAILED, STRUCTURED, CREATIVE, AUTO
-```
+- 🖼️ **Image Generation Agent** - Create images from text descriptions
+- 📷 **Image to Text Agent** - Extract text and descriptions from images
+- 🎬 **Video Agent** - Analyse and process video content
+- 📊 **Data Analyst Agent** - Analyse data and generate insights
+- 💰 **Finance Agent** - Financial analysis and recommendations
+- 🛒 **Shopping Agent** - Price comparison and shopping assistance
+- ⭐ **Recommendation Agent** - Personalised recommendations
+- 📖 **Wikipedia Agent** - Search and extract Wikipedia information
+- 💻 **Programming Agent** - Code development and analysis
+- 📝 **Markdown Agent** - Generate and format Markdown content
+- 🔀 **Router Agent** - Dynamic task routing with cost optimisation
 
-**Key Difference:**
-- `--query-rewrite`: Optimizes queries for **search/retrieval** (RAG)
-- `--expand-prompt`: Expands prompts for **detailed task execution**
+### MCP Protocol
 
+- 🔌 **MCP Transports** - stdio, Streamable HTTP, WebSocket, SSE (Protocol 2025-11-25)
+- 🌐 **WebSocket MCP** - Real-time bidirectional connections with auto-reconnect
+- 🔐 **MCP Security** - Origin validation, DNS rebinding prevention, secure sessions
+- 🔄 **MCP Resumability** - SSE stream recovery via Last-Event-ID
 
-## Web Search, Web Fetch & Prompt Caching
+### Safety & Control
 
-### CLI Usage
+- 🤝 **Agent Handoffs** - Transfer context between specialised agents
+- 🛡️ **Guardrails** - Input/output validation and safety checks
+- ✅ **Human Approval** - Require human confirmation for critical actions
+- 💬 **Sessions Management** - Isolated conversation contexts
+- 🔄 **Stateful Agents** - Maintain state across interactions
 
-```bash
-# Web Search - Get real-time information
-praisonai "What are the latest AI news today?" --web-search --llm openai/gpt-4o-search-preview
+### Developer Tools
 
-# Web Fetch - Retrieve and analyze URL content (Anthropic only)
-praisonai "Summarize https://docs.praison.ai" --web-fetch --llm anthropic/claude-sonnet-4-20250514
+- ⚡ **Fast Context** - Rapid parallel code search (10-20x faster)
+- 📜 **Rules & Instructions** - Auto-discover CLAUDE.md, AGENTS.md, GEMINI.md
+- 🪝 **Hooks** - Pre/post operation hooks for custom logic
+- 📈 **Telemetry** - Track agent performance and usage
+- 📹 **Camera Integration** - Capture and analyse camera input
 
-# Prompt Caching - Reduce costs for repeated prompts
-praisonai "Analyze this document..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514
-```
+### Other Features
 
-### Programmatic Usage
+- 🔄 **CrewAI & AG2 Integration** - Use CrewAI or AG2 (Formerly AutoGen) Framework
+- 💻 **Codebase Chat** - Chat with entire codebase
+- 🎨 **Interactive UIs** - Multiple interactive interfaces
+- 📄 **YAML Configuration** - YAML-based agent and workflow configuration
+- 🛠️ **Custom Tools** - Easy custom tool integration
+- 🔍 **Internet Search** - Multiple providers (Tavily, You.com, Exa, DuckDuckGo, Crawl4AI)
+- 🖼️ **VLM Support** - Vision Language Model support
+- 🎙️ **Voice Interaction** - Real-time voice interaction
 
-```python
-from praisonaiagents import Agent
+---
 
-# Web Search
-agent = Agent(
-    instructions="You are a research assistant",
-    llm="openai/gpt-4o-search-preview",
-    web_search=True
-)
+## 🎓 Video Tutorials
 
-# Web Fetch (Anthropic only)
-agent = Agent(
-    instructions="You are a content analyzer",
-    llm="anthropic/claude-sonnet-4-20250514",
-    web_fetch=True
-)
-
-# Prompt Caching
-agent = Agent(
-    instructions="You are an AI assistant..." * 50,  # Long system prompt
-    llm="anthropic/claude-sonnet-4-20250514",
-    prompt_caching=True
-)
-```
-
-**Supported Providers:**
-| Feature | Providers |
-|---------|-----------|
-| Web Search | OpenAI, Gemini, Anthropic, xAI, Perplexity |
-| Web Fetch | Anthropic |
-| Prompt Caching | OpenAI (auto), Anthropic, Bedrock, Deepseek |
-
-
-
-
-
-## MCP (Model Context Protocol)
-
-PraisonAI supports MCP Protocol Revision 2025-11-25 with multiple transports.
-
-### MCP Client (Consume MCP Servers)
-
-```python
-from praisonaiagents import Agent, MCP
-
-# stdio - Local NPX/Python servers
-agent = Agent(tools=MCP("npx @modelcontextprotocol/server-memory"))
-
-# Streamable HTTP - Production servers
-agent = Agent(tools=MCP("https://api.example.com/mcp"))
-
-# WebSocket - Real-time bidirectional
-agent = Agent(tools=MCP("wss://api.example.com/mcp", auth_token="token"))
-
-# SSE (Legacy) - Backward compatibility
-agent = Agent(tools=MCP("http://localhost:8080/sse"))
-
-# With environment variables
-agent = Agent(
-    tools=MCP(
-        command="npx",
-        args=["-y", "@modelcontextprotocol/server-brave-search"],
-        env={"BRAVE_API_KEY": "your-key"}
-    )
-)
-```
-
-### MCP Server (Expose Tools as MCP Server)
-
-Expose your Python functions as MCP tools for Claude Desktop, Cursor, and other MCP clients:
-
-```python
-from praisonaiagents.mcp import ToolsMCPServer
-
-def search_web(query: str, max_results: int = 5) -> dict:
-    """Search the web for information."""
-    return {"results": [f"Result for {query}"]}
-
-def calculate(expression: str) -> dict:
-    """Evaluate a mathematical expression."""
-    return {"result": eval(expression)}
-
-# Create and run MCP server
-server = ToolsMCPServer(name="my-tools")
-server.register_tools([search_web, calculate])
-server.run()  # stdio for Claude Desktop
-# server.run_sse(host="0.0.0.0", port=8080)  # SSE for web clients
-```
-
-### MCP Features
-
-| Feature | Description |
-|---------|-------------|
-| **Session Management** | Automatic `Mcp-Session-Id` handling |
-| **Protocol Versioning** | `Mcp-Protocol-Version` header |
-| **Resumability** | SSE stream recovery via `Last-Event-ID` |
-| **Security** | Origin validation, DNS rebinding prevention |
-| **WebSocket** | Auto-reconnect with exponential backoff |
-
-
-## Development:
-
-Below is used for development only.
-
-### Using uv
-```bash
-# Install uv if you haven't already
-pip install uv
-
-# Install from requirements
-uv pip install -r pyproject.toml
-
-# Install with extras
-uv pip install -r pyproject.toml --extra code
-uv pip install -r pyproject.toml --extra "crewai,autogen"
-```
-
-### Bump and Release
-
-```bash
-# From project root - bumps version and releases in one command
-python src/praisonai/scripts/bump_and_release.py 2.2.99
-
-# With praisonaiagents dependency
-python src/praisonai/scripts/bump_and_release.py 2.2.99 --agents 0.0.169
-
-# Then publish
-cd src/praisonai && uv publish
-```
-
-## Contributing
-
-- Fork on GitHub: Use the "Fork" button on the repository page.
-- Clone your fork: `git clone https://github.com/yourusername/praisonAI.git`
-- Create a branch: `git checkout -b new-feature`
-- Make changes and commit: `git commit -am "Add some feature"`
-- Push to your fork: `git push origin new-feature`
-- Submit a pull request via GitHub's web interface.
-- Await feedback from project maintainers.
-
-## Advanced Features
-
-**Research & Intelligence:**
-- 🔬 **Deep Research Agents** (OpenAI & Gemini)
-- 🔄 **Query Rewriter Agent** (HyDE, Step-back, Multi-query)
-- 🌐 **Native Web Search** (OpenAI, Gemini, Anthropic, xAI, Perplexity)
-- 📥 **Web Fetch** (Retrieve full content from URLs - Anthropic)
-- 📝 **Prompt Expander Agent** (Expand short prompts into detailed instructions)
-
-**Memory & Caching:**
-- 💾 **Prompt Caching** (Reduce costs & latency - OpenAI, Anthropic, Bedrock, Deepseek)
-- 🧠 **Claude Memory Tool** (Persistent cross-conversation memory - Anthropic Beta)
-- 💾 **File-Based Memory** (Zero-dependency persistent memory for all agents)
-- 🔍 **Built-in Search Tools** (Tavily, You.com, Exa - web search, news, content extraction)
-
-**Planning & Workflows:**
-- 📋 **Planning Mode** (Plan before execution - Agent & Multi-Agent)
-- 🔧 **Planning Tools** (Research with tools during planning)
-- 🧠 **Planning Reasoning** (Chain-of-thought planning)
-- ⛓️ **Prompt Chaining** (Sequential prompt workflows with gates)
-- 🔍 **Evaluator Optimiser** (Generate and optimize through iterative feedback)
-- 👷 **Orchestrator Workers** (Distribute tasks among specialized workers)
-- ⚡ **Parallelisation** (Execute tasks in parallel for improved performance)
-- 🔁 **Repetitive Agents** (Handle repetitive tasks through automated loops)
-- 🤖 **Autonomous Workflow** (Monitor, act, adapt based on environment feedback)
-
-**Agent Types:**
-- 🖼️ **Image Generation Agent** (Create images from text descriptions)
-- 📷 **Image to Text Agent** (Extract text and descriptions from images)
-- 🎬 **Video Agent** (Analyze and process video content)
-- 📊 **Data Analyst Agent** (Analyze data and generate insights)
-- 💰 **Finance Agent** (Financial analysis and recommendations)
-- 🛒 **Shopping Agent** (Price comparison and shopping assistance)
-- ⭐ **Recommendation Agent** (Personalized recommendations)
-- 📖 **Wikipedia Agent** (Search and extract Wikipedia information)
-- 💻 **Programming Agent** (Code development and analysis)
-- 📝 **Markdown Agent** (Generate and format Markdown content)
-- 🔀 **Router Agent** (Dynamic task routing with cost optimization)
-
-**MCP Protocol:**
-- 🔌 **MCP Transports** (stdio, Streamable HTTP, WebSocket, SSE - Protocol 2025-11-25)
-- 🌐 **WebSocket MCP** (Real-time bidirectional connections with auto-reconnect)
-- 🔐 **MCP Security** (Origin validation, DNS rebinding prevention, secure sessions)
-- 🔄 **MCP Resumability** (SSE stream recovery via Last-Event-ID)
-
-**Safety & Control:**
-- 🤝 **Agent Handoffs** (Transfer context between specialized agents)
-- 🛡️ **Guardrails** (Input/output validation and safety checks)
-- ✅ **Human Approval** (Require human confirmation for critical actions)
-- 💬 **Sessions Management** (Isolated conversation contexts)
-- 🔄 **Stateful Agents** (Maintain state across interactions)
-
-**Developer Tools:**
-- ⚡ **Fast Context** (Rapid parallel code search - 10-20x faster than traditional methods)
-- 📜 **Rules & Instructions** (Auto-discover CLAUDE.md, AGENTS.md, GEMINI.md)
-- 🪝 **Hooks** (Pre/post operation hooks for custom logic)
-- 📈 **Telemetry** (Track agent performance and usage)
-- 📹 **Camera Integration** (Capture and analyze camera input)
-
-## Other Features
-
-- 🔄 Use CrewAI or AG2 (Formerly AutoGen) Framework
-- 💻 Chat with ENTIRE Codebase
-- 🎨 Interactive UIs
-- 📄 YAML-based Configuration
-- 🛠️ Custom Tool Integration
-- 🔍 Internet Search Capability (Tavily, You.com, Exa, DuckDuckGo, Crawl4AI)
-- 🖼️ Vision Language Model (VLM) Support
-- 🎙️ Real-time Voice Interaction
-
-## Video Tutorials
+Learn PraisonAI through our comprehensive video series:
 
 | Topic | Video |
 |-------|--------|
@@ -2115,3 +2318,58 @@ cd src/praisonai && uv publish
 | Call Interface | [![Call](https://img.youtube.com/vi/m1cwrUG2iAk/0.jpg)](https://www.youtube.com/watch?v=m1cwrUG2iAk) |
 | Reasoning Extract Agents | [![Reasoning Extract](https://img.youtube.com/vi/2PPamsADjJA/0.jpg)](https://www.youtube.com/watch?v=2PPamsADjJA) |
 
+---
+
+## 👥 Contributing
+
+We welcome contributions from the community! Here's how you can contribute:
+
+1. **Fork on GitHub** - Use the "Fork" button on the [repository page](https://github.com/MervinPraison/PraisonAI)
+2. **Clone your fork** - `git clone https://github.com/yourusername/praisonAI.git`
+3. **Create a branch** - `git checkout -b new-feature`
+4. **Make changes and commit** - `git commit -am "Add some feature"`
+5. **Push to your fork** - `git push origin new-feature`
+6. **Submit a pull request** - Via GitHub's web interface
+7. **Await feedback** - From project maintainers
+
+---
+
+## 🔧 Development
+
+### Using uv
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Install from requirements
+uv pip install -r pyproject.toml
+
+# Install with extras
+uv pip install -r pyproject.toml --extra code
+uv pip install -r pyproject.toml --extra "crewai,autogen"
+```
+
+### Bump and Release
+
+```bash
+# From project root - bumps version and releases in one command
+python src/praisonai/scripts/bump_and_release.py 2.2.99
+
+# With praisonaiagents dependency
+python src/praisonai/scripts/bump_and_release.py 2.2.99 --agents 0.0.169
+
+# Then publish
+cd src/praisonai && uv publish
+```
+
+---
+
+<div align="center">
+  <p><strong>Made with ❤️ by the PraisonAI Team</strong></p>
+  <p>
+    <a href="https://docs.praison.ai">Documentation</a> •
+    <a href="https://github.com/MervinPraison/PraisonAI">GitHub</a> •
+    <a href="https://github.com/MervinPraison/PraisonAI/issues">Issues</a>
+  </p>
+</div>

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.3.26" \
+    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.3.26" \
+    "praisonai>=2.3.38" \
     "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.3.26" \
+    "praisonai>=2.3.38" \
     "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.3.26" \
+    "praisonai>=2.3.38" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

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/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/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/yaml/agents_workflow.yaml

@@ -11,7 +11,7 @@
 
 framework: praisonai
 process: workflow
-topic: "Research AI trends and create a comprehensive report"
+input: "Research AI trends and create a comprehensive report"  # The input passed to {{input}} in steps
 
 # Workflow configuration (new)
 workflow:
@@ -31,17 +31,17 @@ variables:
     - Natural Language Processing
 
 # Agent definitions using familiar 'roles' format
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   classifier:
     role: Request Classifier
-    backstory: |
+    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
-    backstory: |
+    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
@@ -52,28 +52,28 @@ roles:
       
   tech_expert:
     role: Technical Expert
-    backstory: |
+    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
-    backstory: |
+    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
-    backstory: |
+    instructions:  # Canonical |
       You analyze market trends and competitive landscapes.
       You provide actionable business insights.
     goal: Analyze market trends and opportunities
     
   aggregator:
     role: Synthesizer
-    backstory: |
+    instructions:  # Canonical |
       You combine findings from multiple sources into coherent reports.
       You identify patterns and key insights.
     goal: Synthesize all findings into comprehensive reports

examples/yaml/workflows/loop_workflow.yaml

@@ -39,4 +39,4 @@ steps:
       over: topics
       
   - agent: summarizer
-    action: "Create a comprehensive summary of all the analyzed topics"
+    action: "Create a comprehensive summary of all the analyzed topics based on these results: {{previous_output}}"

examples/yaml/workflows/parallel_workflow.yaml

@@ -3,6 +3,7 @@
 
 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
@@ -43,4 +44,4 @@ steps:
         action: "Research customer needs for: {{input}}"
         
   - agent: aggregator
-    action: "Synthesize all the research findings into a comprehensive report"
+    action: "Synthesize all the research findings into a comprehensive report: {{previous_output}}"

examples/yaml/workflows/routing_workflow.yaml

@@ -3,6 +3,7 @@
 
 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

examples/yaml/workflows/simple_workflow.yaml

@@ -3,6 +3,7 @@
 
 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

src/praisonai-agents/.gitignore

@@ -87,3 +87,4 @@ graph.py
 chroma_db/
 .qodo
 *_COMPARISON_ANALYSIS.md
+*_REPORT.md

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
+```

src/praisonai-agents/benchmarks/SIMPLE_BENCHMARK_RESULTS.md

@@ -0,0 +1,22 @@
+# PraisonAI Agents - Benchmark Results
+
+**Generated:** 2025-12-18 13:23:43
+
+## Agent Instantiation Time
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **4.16** | **1.00x (fastest)** |
+| OpenAI Agents SDK | 5.55 | 1.33x |
+| Agno | 5.58 | 1.34x |
+| PraisonAI (LiteLLM) | 8.52 | 2.05x |
+| PydanticAI | 225.87 | 54.25x |
+| LangGraph | 4,349.54 | 1,045x |
+| CrewAI | 15,911.11 | 3,821x |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```

src/praisonai-agents/benchmarks/TOOLS_BENCHMARK_RESULTS.md

@@ -0,0 +1,33 @@
+# PraisonAI Agents - Tools Benchmark Results
+
+**Generated:** 2025-12-18 14:40:35
+**Iterations:** 100
+**Test:** Agent instantiation WITH TOOLS
+
+## Results
+
+| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+| **PraisonAI** | **3.24** | **1.00x (fastest)** |
+| Agno | 5.12 | 1.58x |
+| PraisonAI (LiteLLM) | 8.59 | 2.65x |
+| OpenAI Agents SDK | 279.95 | 86.44x |
+| LangGraph | 2,310.82 | 713x |
+| CrewAI | 15,773.44 | 4,870x |
+
+## Package Versions
+
+| Package | Version |
+|---------|--------|
+| PraisonAI | 0.1.5 |
+| Agno | 2.3.14 |
+| OpenAI Agents SDK | 0.6.3 |
+| LangGraph | 1.0.5 |
+| CrewAI | 1.6.1 |
+
+## How to Reproduce
+
+```bash
+cd praisonai-agents
+python benchmarks/tools_benchmark.py
+```

src/praisonai-agents/benchmarks/deep_profiling.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Deep Profiling Benchmark
+
+Profiles each step of agent initialization to identify performance bottlenecks.
+
+Key Optimizations Applied:
+1. Lazy RulesManager - filesystem operations deferred until first access
+2. Lazy os.getcwd() - fast_context_path resolved only when needed
+3. Lazy console initialization - Rich Console created on demand
+
+Usage:
+    python benchmarks/deep_profiling.py
+"""
+
+import time
+import tracemalloc
+import cProfile
+import pstats
+import io
+from typing import Literal, Callable, Dict, List
+from dataclasses import dataclass
+
+# ============================================================================
+# Timing Utilities
+# ============================================================================
+
+@dataclass
+class StepTiming:
+    name: str
+    duration_us: float  # microseconds
+    memory_kb: float    # kilobytes
+
+
+class StepProfiler:
+    """Profile individual steps during initialization"""
+    
+    def __init__(self):
+        self.steps: List[StepTiming] = []
+        self._start_time = None
+        self._start_memory = None
+    
+    def start_step(self, name: str):
+        tracemalloc.start()
+        self._start_time = time.perf_counter()
+        self._step_name = name
+    
+    def end_step(self):
+        end_time = time.perf_counter()
+        current, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        
+        duration_us = (end_time - self._start_time) * 1_000_000
+        memory_kb = peak / 1024
+        
+        self.steps.append(StepTiming(
+            name=self._step_name,
+            duration_us=duration_us,
+            memory_kb=memory_kb
+        ))
+    
+    def print_report(self, title: str):
+        print(f"\n{'='*70}")
+        print(f"STEP-BY-STEP PROFILING: {title}")
+        print(f"{'='*70}")
+        
+        total_time = sum(s.duration_us for s in self.steps)
+        total_memory = sum(s.memory_kb for s in self.steps)
+        
+        print(f"\n{'Step':<40} {'Time (μs)':<15} {'Memory (KB)':<15} {'% Time':<10}")
+        print("-" * 80)
+        
+        for step in sorted(self.steps, key=lambda x: x.duration_us, reverse=True):
+            pct = (step.duration_us / total_time * 100) if total_time > 0 else 0
+            print(f"{step.name:<40} {step.duration_us:<15.2f} {step.memory_kb:<15.2f} {pct:<10.1f}%")
+        
+        print("-" * 80)
+        print(f"{'TOTAL':<40} {total_time:<15.2f} {total_memory:<15.2f} {'100.0':<10}%")
+
+
+def time_function(func: Callable, iterations: int = 100) -> Dict:
+    """Time a function with detailed statistics"""
+    times = []
+    
+    # Warmup
+    for _ in range(10):
+        func()
+    
+    # Measure
+    for _ in range(iterations):
+        start = time.perf_counter()
+        func()
+        end = time.perf_counter()
+        times.append((end - start) * 1_000_000)  # Convert to microseconds
+    
+    return {
+        'avg': sum(times) / len(times),
+        'min': min(times),
+        'max': max(times),
+        'median': sorted(times)[len(times)//2]
+    }
+
+
+# ============================================================================
+# Profile PraisonAI Agent Initialization - Step by Step
+# ============================================================================
+
+def profile_praisonai_detailed():
+    """Profile each step of PraisonAI Agent initialization"""
+    print("\n" + "="*70)
+    print("DETAILED PROFILING: PraisonAI Agent")
+    print("="*70)
+    
+    profiler = StepProfiler()
+    
+    # Step 1: Import
+    profiler.start_step("1. Import praisonaiagents")
+    from praisonaiagents import Agent as PraisonAgent
+    profiler.end_step()
+    
+    # Step 2: Define tool
+    profiler.start_step("2. Define tool function")
+    def get_weather(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    profiler.end_step()
+    
+    # Step 3: Full instantiation
+    profiler.start_step("3. Full Agent instantiation")
+    agent = PraisonAgent(
+        name="Test Agent",
+        instructions="Be concise, reply with one sentence.",
+        llm="gpt-4o-mini",
+        tools=tools,
+        verbose=False
+    )
+    profiler.end_step()
+    
+    profiler.print_report("PraisonAI Agent")
+    
+    # Now profile the __init__ internals using cProfile
+    print("\n" + "="*70)
+    print("cProfile ANALYSIS: PraisonAI Agent.__init__")
+    print("="*70)
+    
+    pr = cProfile.Profile()
+    pr.enable()
+    
+    for _ in range(100):
+        agent = PraisonAgent(
+            name="Test Agent",
+            instructions="Be concise, reply with one sentence.",
+            llm="gpt-4o-mini",
+            tools=tools,
+            verbose=False
+        )
+    
+    pr.disable()
+    
+    # Print top 30 functions by cumulative time
+    s = io.StringIO()
+    ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
+    ps.print_stats(30)
+    print(s.getvalue())
+    
+    return agent
+
+
+# ============================================================================
+# Profile Agno Agent Initialization - Step by Step
+# ============================================================================
+
+def profile_agno_detailed():
+    """Profile each step of Agno Agent initialization"""
+    print("\n" + "="*70)
+    print("DETAILED PROFILING: Agno Agent")
+    print("="*70)
+    
+    profiler = StepProfiler()
+    
+    # Step 1: Import
+    profiler.start_step("1. Import agno")
+    from agno.agent import Agent as AgnoAgent
+    from agno.models.openai import OpenAIChat
+    profiler.end_step()
+    
+    # Step 2: Define tool
+    profiler.start_step("2. Define tool function")
+    def get_weather(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    profiler.end_step()
+    
+    # Step 3: Full instantiation
+    profiler.start_step("3. Full Agent instantiation")
+    agent = AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    profiler.end_step()
+    
+    profiler.print_report("Agno Agent")
+    
+    # Now profile the __init__ internals using cProfile
+    print("\n" + "="*70)
+    print("cProfile ANALYSIS: Agno Agent.__init__")
+    print("="*70)
+    
+    pr = cProfile.Profile()
+    pr.enable()
+    
+    for _ in range(100):
+        agent = AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    
+    pr.disable()
+    
+    # Print top 30 functions by cumulative time
+    s = io.StringIO()
+    ps = pstats.Stats(pr, stream=s).sort_stats('cumulative')
+    ps.print_stats(30)
+    print(s.getvalue())
+    
+    return agent
+
+
+# ============================================================================
+# Profile Individual Components of PraisonAI
+# ============================================================================
+
+def profile_praisonai_components():
+    """Profile individual components of PraisonAI Agent initialization"""
+    print("\n" + "="*70)
+    print("COMPONENT-LEVEL PROFILING: PraisonAI Agent")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    
+    def get_weather(city: Literal["nyc", "sf"]):
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    
+    # Test different configurations
+    configs = [
+        ("Minimal (no tools, no llm)", {"name": "Test", "verbose": False}),
+        ("With name only", {"name": "Test Agent", "verbose": False}),
+        ("With instructions", {"name": "Test", "instructions": "Be concise", "verbose": False}),
+        ("With llm (gpt-4o-mini)", {"name": "Test", "llm": "gpt-4o-mini", "verbose": False}),
+        ("With llm (openai/gpt-4o-mini)", {"name": "Test", "llm": "openai/gpt-4o-mini", "verbose": False}),
+        ("With tools", {"name": "Test", "tools": tools, "verbose": False}),
+        ("Full config (OpenAI SDK)", {"name": "Test", "instructions": "Be concise", "llm": "gpt-4o-mini", "tools": tools, "verbose": False}),
+        ("Full config (LiteLLM)", {"name": "Test", "instructions": "Be concise", "llm": "openai/gpt-4o-mini", "tools": tools, "verbose": False}),
+    ]
+    
+    print(f"\n{'Configuration':<40} {'Avg Time (μs)':<15} {'Min (μs)':<15} {'Max (μs)':<15}")
+    print("-" * 85)
+    
+    for name, config in configs:
+        def create_agent():
+            return PraisonAgent(**config)
+        
+        stats = time_function(create_agent, iterations=100)
+        print(f"{name:<40} {stats['avg']:<15.2f} {stats['min']:<15.2f} {stats['max']:<15.2f}")
+
+
+# ============================================================================
+# Compare Specific Operations
+# ============================================================================
+
+def compare_specific_operations():
+    """Compare specific operations between PraisonAI and Agno"""
+    print("\n" + "="*70)
+    print("OPERATION COMPARISON: PraisonAI vs Agno")
+    print("="*70)
+    
+    from praisonaiagents import Agent as PraisonAgent
+    from agno.agent import Agent as AgnoAgent
+    from agno.models.openai import OpenAIChat
+    
+    def get_weather(city: Literal["nyc", "sf"]):
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    tools = [get_weather]
+    
+    operations = []
+    
+    # Operation 1: Bare minimum instantiation
+    def praisonai_minimal():
+        return PraisonAgent(name="Test", verbose=False)
+    
+    def agno_minimal():
+        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"))
+    
+    praison_stats = time_function(praisonai_minimal, 100)
+    agno_stats = time_function(agno_minimal, 100)
+    operations.append(("Minimal instantiation", praison_stats['avg'], agno_stats['avg']))
+    
+    # Operation 2: With tools
+    def praisonai_with_tools():
+        return PraisonAgent(name="Test", tools=tools, verbose=False)
+    
+    def agno_with_tools():
+        return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+    
+    praison_stats = time_function(praisonai_with_tools, 100)
+    agno_stats = time_function(agno_with_tools, 100)
+    operations.append(("With tools", praison_stats['avg'], agno_stats['avg']))
+    
+    # Operation 3: Full config
+    def praisonai_full():
+        return PraisonAgent(
+            name="Test Agent",
+            instructions="Be concise",
+            llm="gpt-4o-mini",
+            tools=tools,
+            verbose=False
+        )
+    
+    def agno_full():
+        return AgnoAgent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            tools=tools,
+            instructions=["Be concise"]
+        )
+    
+    praison_stats = time_function(praisonai_full, 100)
+    agno_stats = time_function(agno_full, 100)
+    operations.append(("Full config", praison_stats['avg'], agno_stats['avg']))
+    
+    print(f"\n{'Operation':<30} {'PraisonAI (μs)':<18} {'Agno (μs)':<18} {'Ratio':<10}")
+    print("-" * 76)
+    
+    for op_name, praison_time, agno_time in operations:
+        ratio = praison_time / agno_time if agno_time > 0 else 0
+        print(f"{op_name:<30} {praison_time:<18.2f} {agno_time:<18.2f} {ratio:<10.1f}x")
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    import os
+    os.environ.setdefault("OPENAI_API_KEY", "sk-test")
+    
+    print("="*70)
+    print("PraisonAI Agents - Deep Profiling Benchmark")
+    print("="*70)
+    print("\nThis analysis identifies performance bottlenecks in agent initialization.\n")
+    
+    # Run all profiling
+    profile_praisonai_detailed()
+    profile_agno_detailed()
+    profile_praisonai_components()
+    compare_specific_operations()
+    
+    print("\n" + "="*70)
+    print("PROFILING COMPLETE")
+    print("="*70)

src/praisonai-agents/benchmarks/execution_benchmark.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Real Execution Benchmark
+
+Benchmarks ACTUAL agent execution with LLM API calls.
+Tests single agent running a simple task across frameworks.
+
+Usage:
+    export OPENAI_API_KEY=your_key
+    python benchmarks/execution_benchmark.py
+    python benchmarks/execution_benchmark.py --no-save
+    python benchmarks/execution_benchmark.py --iterations 5
+    python benchmarks/execution_benchmark.py --model gpt-4o --iterations 10
+"""
+
+import time
+import os
+import argparse
+from importlib.metadata import version as get_version
+
+# Defaults (can be overridden via CLI)
+DEFAULT_MODEL = "gpt-4o-mini"
+DEFAULT_ITERATIONS = 3
+DEFAULT_PROMPT = "What is 2+2? Reply with just the number."
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'CrewAI': 'crewai',
+    }
+    versions = {}
+    for name, pkg in packages.items():
+        try:
+            versions[name] = get_version(pkg)
+        except:
+            versions[name] = 'not installed'
+    return versions
+
+
+def benchmark_praisonai(model, iterations, prompt):
+    """Benchmark PraisonAI agent execution using agent.start()"""
+    from praisonaiagents import Agent
+    
+    print("\n--- PraisonAI ---")
+    print("Method: agent.start()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            name="Calculator",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm=model,
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_praisonai_litellm(model, iterations, prompt):
+    """Benchmark PraisonAI with LiteLLM backend using agent.start()"""
+    from praisonaiagents import Agent
+    
+    print("\n--- PraisonAI (LiteLLM) ---")
+    print("Method: agent.start()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            name="Calculator",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm=f"openai/{model}",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_agno(model, iterations, prompt):
+    """Benchmark Agno agent execution using agent.run()"""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    print("\n--- Agno ---")
+    print("Method: agent.run()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            model=OpenAIChat(id=model),
+            instructions=["You are a helpful assistant. Be very brief."],
+        )
+        
+        start = time.perf_counter()
+        response = agent.run(prompt)
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        # Extract content from response
+        content = str(response.content)[:50] if hasattr(response, 'content') else str(response)[:50]
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {content}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def benchmark_crewai(model, iterations, prompt):
+    """Benchmark CrewAI agent execution using crew.kickoff()"""
+    from crewai import Agent, Task, Crew
+    
+    print("\n--- CrewAI ---")
+    print("Method: crew.kickoff()")
+    
+    times = []
+    for i in range(iterations):
+        agent = Agent(
+            role="Calculator",
+            goal="Answer math questions",
+            backstory="You are a helpful assistant.",
+            llm=model,
+            verbose=False
+        )
+        
+        task = Task(
+            description=prompt,
+            expected_output="A number",
+            agent=agent
+        )
+        
+        crew = Crew(
+            agents=[agent],
+            tasks=[task],
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = crew.kickoff()
+        elapsed = time.perf_counter() - start
+        
+        times.append(elapsed)
+        print(f"  Run {i+1}: {elapsed:.2f}s - Response: {str(response)[:50]}")
+    
+    avg = sum(times) / len(times)
+    print(f"  Average: {avg:.2f}s")
+    return avg
+
+
+def save_results(results: dict, model: str, iterations: int, prompt: str):
+    """Save results to markdown file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), 'EXECUTION_BENCHMARK_RESULTS.md')
+    versions = get_package_versions()
+    
+    # Sort by time
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest = sorted_results[0][1]
+    
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Real Execution Benchmark\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Model:** {model}\n')
+        f.write(f'**Iterations:** {iterations}\n')
+        f.write(f'**Prompt:** "{prompt}"\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Method | Avg Time | Relative |\n')
+        f.write('|-----------|--------|----------|----------|\n')
+        
+        methods = {
+            'PraisonAI': 'agent.start()',
+            'PraisonAI (LiteLLM)': 'agent.start()',
+            'Agno': 'agent.run()',
+            'CrewAI': 'crew.kickoff()',
+        }
+        
+        for name, avg in sorted_results:
+            ratio = avg / fastest
+            method = methods.get(name, 'unknown')
+            if ratio == 1.0:
+                f.write(f'| **{name}** | `{method}` | **{avg:.2f}s** | **1.00x (fastest)** |\n')
+            else:
+                f.write(f'| {name} | `{method}` | {avg:.2f}s | {ratio:.2f}x |\n')
+        
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('export OPENAI_API_KEY=your_key\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/execution_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description='PraisonAI Agents - Real Execution Benchmark')
+    parser.add_argument('--no-save', action='store_true', help='Do not save results to file')
+    parser.add_argument('--model', '-m', type=str, default=DEFAULT_MODEL, help=f'Model to use (default: {DEFAULT_MODEL})')
+    parser.add_argument('--iterations', '-i', type=int, default=DEFAULT_ITERATIONS, help=f'Number of iterations (default: {DEFAULT_ITERATIONS})')
+    parser.add_argument('--prompt', '-p', type=str, default=DEFAULT_PROMPT, help=f'Prompt to use (default: "{DEFAULT_PROMPT}")')
+    args = parser.parse_args()
+    
+    # Check API key
+    if not os.environ.get('OPENAI_API_KEY'):
+        print("ERROR: Set OPENAI_API_KEY environment variable")
+        exit(1)
+    
+    model = args.model
+    iterations = args.iterations
+    prompt = args.prompt
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Real Execution Benchmark')
+    print('=' * 60)
+    print(f'\nModel: {model}')
+    print(f'Iterations: {iterations}')
+    print(f'Prompt: "{prompt}"')
+    
+    versions = get_package_versions()
+    print('\nPackage versions:')
+    for pkg, ver in versions.items():
+        print(f'  {pkg}: {ver}')
+    
+    results = {}
+    
+    # Run benchmarks
+    try:
+        results['PraisonAI'] = benchmark_praisonai(model, iterations, prompt)
+    except Exception as e:
+        print(f"PraisonAI error: {e}")
+    
+    try:
+        results['PraisonAI (LiteLLM)'] = benchmark_praisonai_litellm(model, iterations, prompt)
+    except Exception as e:
+        print(f"PraisonAI (LiteLLM) error: {e}")
+    
+    try:
+        results['Agno'] = benchmark_agno(model, iterations, prompt)
+    except Exception as e:
+        print(f"Agno error: {e}")
+    
+    try:
+        results['CrewAI'] = benchmark_crewai(model, iterations, prompt)
+    except Exception as e:
+        print(f"CrewAI error: {e}")
+    
+    # Summary
+    print('\n' + '=' * 60)
+    print('SUMMARY')
+    print('=' * 60)
+    
+    if results:
+        sorted_results = sorted(results.items(), key=lambda x: x[1])
+        fastest = sorted_results[0][1]
+        
+        print(f"\n{'Framework':<25} {'Avg Time':<12} {'Relative':<10}")
+        print('-' * 47)
+        
+        for name, avg in sorted_results:
+            ratio = avg / fastest
+            print(f'{name:<25} {avg:<12.2f}s {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    
+    # Save results (unless --no-save)
+    if results and not args.no_save:
+        save_results(results, model, iterations, prompt)
+    elif args.no_save:
+        print('\nResults not saved (--no-save flag used)')

src/praisonai-agents/benchmarks/performance_benchmark.py

@@ -0,0 +1,523 @@
+"""
+PraisonAI Agents - Comprehensive Performance Benchmark
+
+Measures agent instantiation time and memory footprint across
+multiple AI agent frameworks using industry-standard methodology.
+
+Usage:
+    python benchmarks/performance_benchmark.py
+"""
+
+import gc
+import time
+import tracemalloc
+import statistics
+from typing import Literal, List, Callable
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PerformanceResult:
+    """Performance measurement results"""
+    run_times: List[float] = field(default_factory=list)
+    memory_usages: List[float] = field(default_factory=list)
+    
+    @property
+    def avg_run_time(self) -> float:
+        return statistics.mean(self.run_times) if self.run_times else 0
+    
+    @property
+    def avg_memory_usage(self) -> float:
+        return statistics.mean(self.memory_usages) if self.memory_usages else 0
+    
+    @property
+    def min_run_time(self) -> float:
+        return min(self.run_times) if self.run_times else 0
+    
+    @property
+    def max_run_time(self) -> float:
+        return max(self.run_times) if self.run_times else 0
+    
+    @property
+    def std_dev_run_time(self) -> float:
+        return statistics.stdev(self.run_times) if len(self.run_times) > 1 else 0
+    
+    @property
+    def median_run_time(self) -> float:
+        return statistics.median(self.run_times) if self.run_times else 0
+
+
+def compute_tracemalloc_baseline(samples: int = 3) -> float:
+    """Compute baseline memory usage for tracemalloc"""
+    def empty_func():
+        return
+    
+    results = []
+    for _ in range(samples):
+        gc.collect()
+        tracemalloc.start()
+        empty_func()
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        results.append(peak / 1024 / 1024)  # Convert to MiB
+    
+    return sum(results) / len(results) if results else 0
+
+
+def measure_time(func: Callable, iterations: int = 1000, warmup: int = 10) -> List[float]:
+    """Measure execution time for a function"""
+    # Warmup runs
+    for _ in range(warmup):
+        func()
+    
+    # Measured runs
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        func()
+        end = time.perf_counter()
+        times.append(end - start)
+    
+    return times
+
+
+def measure_memory(func: Callable, iterations: int = 1000, warmup: int = 10) -> List[float]:
+    """Measure memory usage for a function"""
+    baseline = compute_tracemalloc_baseline()
+    
+    # Warmup runs
+    for _ in range(warmup):
+        func()
+    
+    # Measured runs
+    memory_usages = []
+    for _ in range(iterations):
+        gc.collect()
+        tracemalloc.start()
+        func()
+        _, peak = tracemalloc.get_traced_memory()
+        tracemalloc.stop()
+        
+        peak_mib = peak / 1024 / 1024
+        adjusted = max(0, peak_mib - baseline)
+        memory_usages.append(adjusted)
+    
+    return memory_usages
+
+
+def run_benchmark(func: Callable, name: str, iterations: int = 1000, warmup: int = 10) -> PerformanceResult:
+    """Run full benchmark for a function"""
+    print(f"\n{'='*60}")
+    print(f"Benchmarking: {name}")
+    print(f"{'='*60}")
+    print(f"Warmup runs: {warmup}")
+    print(f"Measured iterations: {iterations}")
+    
+    print("\nMeasuring runtime...")
+    run_times = measure_time(func, iterations, warmup)
+    
+    print("Measuring memory...")
+    memory_usages = measure_memory(func, iterations, warmup)
+    
+    result = PerformanceResult(run_times=run_times, memory_usages=memory_usages)
+    
+    print(f"\nResults for {name}:")
+    print(f"  Average Time: {result.avg_run_time:.6f} seconds ({result.avg_run_time * 1_000_000:.2f} μs)")
+    print(f"  Min Time:     {result.min_run_time:.6f} seconds")
+    print(f"  Max Time:     {result.max_run_time:.6f} seconds")
+    print(f"  Std Dev:      {result.std_dev_run_time:.6f} seconds")
+    print(f"  Median Time:  {result.median_run_time:.6f} seconds")
+    print(f"  Avg Memory:   {result.avg_memory_usage:.6f} MiB ({result.avg_memory_usage * 1024:.2f} KiB)")
+    
+    return result
+
+
+# ============================================================================
+# Framework Imports
+# ============================================================================
+from praisonaiagents import Agent as PraisonAgent
+from agno.agent import Agent as AgnoAgent
+from agno.models.openai import OpenAIChat
+
+# Additional frameworks for comparison
+try:
+    from pydantic_ai import Agent as PydanticAgent
+    PYDANTIC_AVAILABLE = True
+except ImportError:
+    PYDANTIC_AVAILABLE = False
+
+try:
+    from crewai.agent import Agent as CrewAgent
+    from crewai.tools import tool as crewai_tool
+    CREWAI_AVAILABLE = True
+except ImportError:
+    CREWAI_AVAILABLE = False
+
+try:
+    from langchain_core.tools import tool as langchain_tool
+    from langchain_openai import ChatOpenAI
+    from langgraph.prebuilt import create_react_agent
+    LANGGRAPH_AVAILABLE = True
+except ImportError:
+    LANGGRAPH_AVAILABLE = False
+
+try:
+    from agents import Agent as OpenAIAgent, function_tool
+    OPENAI_AGENTS_AVAILABLE = True
+except ImportError:
+    OPENAI_AGENTS_AVAILABLE = False
+
+
+def get_weather(city: Literal["nyc", "sf"]):
+    """Use this to get weather information."""
+    if city == "nyc":
+        return "It might be cloudy in nyc"
+    elif city == "sf":
+        return "It's always sunny in sf"
+
+
+tools = [get_weather]
+
+
+def instantiate_praisonai_agent():
+    """Instantiate a PraisonAI agent with one tool."""
+    return PraisonAgent(
+        name="Test Agent",
+        instructions="Be concise, reply with one sentence.",
+        llm="gpt-4o-mini",
+        tools=tools,
+        verbose=False
+    )
+
+
+def instantiate_praisonai_litellm_agent():
+    """Instantiate a PraisonAI agent with LiteLLM backend."""
+    return PraisonAgent(
+        name="Test Agent",
+        instructions="Be concise, reply with one sentence.",
+        llm="openai/gpt-4o-mini",
+        tools=tools,
+        verbose=False
+    )
+
+
+def instantiate_agno_agent():
+    """Instantiate an Agno agent with one tool."""
+    return AgnoAgent(model=OpenAIChat(id="gpt-4o-mini"), tools=tools)
+
+
+def instantiate_pydantic_agent():
+    """Instantiate a PydanticAI agent with one tool."""
+    agent = PydanticAgent("openai:gpt-4o-mini", system_prompt="Be concise, reply with one sentence.")
+    @agent.tool_plain
+    def get_weather_pydantic(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    return agent
+
+
+def instantiate_openai_agents():
+    """Instantiate an OpenAI Agents SDK agent with one tool."""
+    return OpenAIAgent(
+        name="Test agent",
+        instructions="Be concise, reply with one sentence.",
+        model="gpt-4o-mini",
+        tools=[function_tool(get_weather)],
+    )
+
+
+def instantiate_langgraph_agent():
+    """Instantiate a LangGraph agent with one tool."""
+    @langchain_tool
+    def get_weather_lg(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    return create_react_agent(model=ChatOpenAI(model="gpt-4o-mini"), tools=[get_weather_lg])
+
+
+def instantiate_crewai_agent():
+    """Instantiate a CrewAI agent with one tool."""
+    @crewai_tool("Weather Tool")
+    def get_weather_crew(city: Literal["nyc", "sf"]):
+        """Use this to get weather information."""
+        if city == "nyc":
+            return "It might be cloudy in nyc"
+        elif city == "sf":
+            return "It's always sunny in sf"
+    return CrewAgent(
+        llm="gpt-4o-mini",
+        role="Test Agent",
+        goal="Be concise, reply with one sentence.",
+        tools=[get_weather_crew],
+        backstory="Test",
+    )
+
+
+def get_package_versions():
+    """Get version numbers for all benchmarked packages."""
+    from importlib.metadata import version as get_version
+    
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'PydanticAI': 'pydantic-ai',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_benchmark_results(results: dict, baseline):
+    """Save benchmark results to BENCHMARK_RESULTS.md and update README.md"""
+    import os
+    import re
+    from datetime import datetime
+    
+    benchmarks_dir = os.path.dirname(__file__)
+    filepath = os.path.join(benchmarks_dir, 'BENCHMARK_RESULTS.md')
+    
+    # Get package versions
+    versions = get_package_versions()
+    
+    display_names = {
+        'agno': 'Agno',
+        'praisonai': 'PraisonAI',
+        'praisonai_litellm': 'PraisonAI (LiteLLM)',
+        'pydantic': 'PydanticAI',
+        'openai_agents': 'OpenAI Agents SDK',
+        'langgraph': 'LangGraph',
+        'crewai': 'CrewAI'
+    }
+    
+    # Build table rows
+    table_rows = []
+    sorted_results = sorted(results.items(), key=lambda x: x[1].avg_run_time)
+    
+    for name, result in sorted_results:
+        display_name = display_names.get(name, name)
+        avg_us = result.avg_run_time * 1e6
+        ratio = result.avg_run_time / baseline.avg_run_time if baseline.avg_run_time > 0 else 0
+        
+        if name == 'praisonai':
+            table_rows.append(f'| **{display_name}** | **{avg_us:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg_us:,.2f}' if avg_us >= 1000 else f'{avg_us:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {display_name} | {avg_str} | {ratio_str} |')
+    
+    # Save to BENCHMARK_RESULTS.md
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write('**Methodology:** 10 warmup runs + 1000 measured iterations\n\n')
+        f.write('## Agent Instantiation Time\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/performance_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    
+    # Update README.md
+    readme_path = os.path.join(benchmarks_dir, '..', '..', '..', 'README.md')
+    if os.path.exists(readme_path):
+        with open(readme_path, 'r') as f:
+            content = f.read()
+        
+        new_table = '''| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+''' + '\n'.join(table_rows)
+        
+        pattern = r'(\| Framework \| Avg Time \(μs\) \| Relative \|\n\|[-|]+\|\n)(\|[^\n]+\|\n)+'
+        
+        if re.search(pattern, content):
+            content = re.sub(pattern, new_table + '\n', content)
+            
+            with open(readme_path, 'w') as f:
+                f.write(content)
+            
+            print(f'README.md updated: {readme_path}')
+
+
+if __name__ == "__main__":
+    print("="*70)
+    print("PraisonAI Agents - Comprehensive Performance Benchmark")
+    print("="*70)
+    print("\nThis benchmark measures:")
+    print("  1. Agent instantiation time (how fast an agent object is created)")
+    print("  2. Memory footprint (how much memory an agent uses)")
+    print("\nMethodology:")
+    print("  - 10 warmup runs (not measured)")
+    print("  - 1000 measured iterations")
+    print("  - tracemalloc for memory measurement")
+    print("  - Baseline subtraction for accuracy")
+    print("\nFrameworks available:")
+    print("  - PraisonAI: ✅")
+    print(f"  - Agno: ✅")
+    print(f"  - PydanticAI: {'✅' if PYDANTIC_AVAILABLE else '❌'}")
+    print(f"  - OpenAI Agents SDK: {'✅' if OPENAI_AGENTS_AVAILABLE else '❌'}")
+    print(f"  - LangGraph: {'✅' if LANGGRAPH_AVAILABLE else '❌'}")
+    print(f"  - CrewAI: {'✅' if CREWAI_AVAILABLE else '❌'}")
+    
+    results = {}
+    
+    # Test PraisonAI first
+    try:
+        print("\n" + "="*70)
+        print("Testing PraisonAI Agents")
+        print("="*70)
+        results['praisonai'] = run_benchmark(
+            instantiate_praisonai_agent,
+            "PraisonAI",
+            iterations=1000,
+            warmup=10
+        )
+    except Exception as e:
+        print(f"Error testing PraisonAI: {e}")
+    
+    try:
+        print("\n" + "="*70)
+        print("Testing PraisonAI Agents (LiteLLM)")
+        print("="*70)
+        results['praisonai_litellm'] = run_benchmark(
+            instantiate_praisonai_litellm_agent,
+            "PraisonAI (LiteLLM)",
+            iterations=1000,
+            warmup=10
+        )
+    except Exception as e:
+        print(f"Error testing PraisonAI (LiteLLM): {e}")
+    
+    # Test Agno
+    try:
+        print("\n" + "="*70)
+        print("Testing Agno")
+        print("="*70)
+        results['agno'] = run_benchmark(
+            instantiate_agno_agent,
+            "Agno",
+            iterations=1000,
+            warmup=10
+        )
+    except Exception as e:
+        print(f"Error testing Agno: {e}")
+    
+    # Test PydanticAI
+    if PYDANTIC_AVAILABLE:
+        try:
+            print("\n" + "="*70)
+            print("Testing PydanticAI")
+            print("="*70)
+            results['pydantic'] = run_benchmark(
+                instantiate_pydantic_agent,
+                "PydanticAI Agent Instantiation",
+                iterations=1000,
+                warmup=10
+            )
+        except Exception as e:
+            print(f"Error testing PydanticAI: {e}")
+    
+    # Test OpenAI Agents SDK
+    if OPENAI_AGENTS_AVAILABLE:
+        try:
+            print("\n" + "="*70)
+            print("Testing OpenAI Agents SDK")
+            print("="*70)
+            results['openai_agents'] = run_benchmark(
+                instantiate_openai_agents,
+                "OpenAI Agents SDK Instantiation",
+                iterations=1000,
+                warmup=10
+            )
+        except Exception as e:
+            print(f"Error testing OpenAI Agents SDK: {e}")
+    
+    # Test LangGraph
+    if LANGGRAPH_AVAILABLE:
+        try:
+            print("\n" + "="*70)
+            print("Testing LangGraph")
+            print("="*70)
+            results['langgraph'] = run_benchmark(
+                instantiate_langgraph_agent,
+                "LangGraph Agent Instantiation",
+                iterations=1000,
+                warmup=10
+            )
+        except Exception as e:
+            print(f"Error testing LangGraph: {e}")
+    
+    # Test CrewAI
+    if CREWAI_AVAILABLE:
+        try:
+            print("\n" + "="*70)
+            print("Testing CrewAI")
+            print("="*70)
+            results['crewai'] = run_benchmark(
+                instantiate_crewai_agent,
+                "CrewAI Agent Instantiation",
+                iterations=1000,
+                warmup=10
+            )
+        except Exception as e:
+            print(f"Error testing CrewAI: {e}")
+    
+    # Final Comparison Table
+    print("\n" + "="*70)
+    print("RESULTS SUMMARY")
+    print("="*70)
+    
+    if 'praisonai' in results:
+        baseline = results['praisonai']
+        
+        print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Avg Memory (KiB)':<18} {'Relative':<15}")
+        print("-" * 73)
+        
+        # Sort by time
+        sorted_results = sorted(results.items(), key=lambda x: x[1].avg_run_time)
+        
+        for name, result in sorted_results:
+            time_ratio = result.avg_run_time / baseline.avg_run_time if baseline.avg_run_time > 0 else 0
+            
+            time_str = f"{time_ratio:.2f}x"
+            
+            display_name = {
+                'agno': 'Agno',
+                'praisonai': 'PraisonAI',
+                'praisonai_litellm': 'PraisonAI (LiteLLM)',
+                'pydantic': 'PydanticAI',
+                'openai_agents': 'OpenAI Agents SDK',
+                'langgraph': 'LangGraph',
+                'crewai': 'CrewAI'
+            }.get(name, name)
+            
+            print(f"{display_name:<25} {result.avg_run_time*1e6:<15.2f} {result.avg_memory_usage*1024:<18.2f} {time_str:<15}")
+        
+        print("\n" + "="*70)
+        
+        # Save results to files
+        save_benchmark_results(results, baseline)

src/praisonai-agents/benchmarks/real_benchmark.py

@@ -0,0 +1,481 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Real-World Execution Benchmark
+
+Benchmarks actual agent execution with LLM calls across frameworks.
+Tests single agent, 2-agent, and 3-agent workflows.
+
+Usage:
+    python benchmarks/real_benchmark.py
+"""
+
+import time
+import statistics
+import os
+from typing import Literal, List
+from dataclasses import dataclass, field
+from importlib.metadata import version as get_version
+
+# Ensure API key is set
+if not os.environ.get('OPENAI_API_KEY'):
+    print("ERROR: OPENAI_API_KEY environment variable not set")
+    exit(1)
+
+
+@dataclass
+class ExecutionResult:
+    """Execution benchmark results"""
+    times: List[float] = field(default_factory=list)
+    
+    @property
+    def avg_time(self) -> float:
+        return statistics.mean(self.times) if self.times else 0
+    
+    @property
+    def min_time(self) -> float:
+        return min(self.times) if self.times else 0
+    
+    @property
+    def max_time(self) -> float:
+        return max(self.times) if self.times else 0
+    
+    @property
+    def std_dev(self) -> float:
+        return statistics.stdev(self.times) if len(self.times) > 1 else 0
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+    }
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    return versions
+
+
+# ============================================================================
+# Tool Definitions
+# ============================================================================
+
+def get_weather(city: Literal["nyc", "sf"]) -> str:
+    """Get weather information for a city."""
+    if city == "nyc":
+        return "New York: Cloudy, 45°F, 60% humidity"
+    return "San Francisco: Sunny, 72°F, 40% humidity"
+
+
+def get_time(timezone: Literal["est", "pst"]) -> str:
+    """Get current time in a timezone."""
+    if timezone == "est":
+        return "Eastern Time: 2:30 PM"
+    return "Pacific Time: 11:30 AM"
+
+
+def calculate(expression: str) -> str:
+    """Calculate a math expression."""
+    try:
+        result = eval(expression)
+        return f"Result: {result}"
+    except Exception:
+        return "Error: Invalid expression"
+
+
+# ============================================================================
+# PraisonAI Benchmarks
+# ============================================================================
+
+def benchmark_praisonai_single(iterations: int = 3) -> ExecutionResult:
+    """Benchmark single PraisonAI agent execution."""
+    from praisonaiagents import Agent
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI single agent iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            name="Assistant",
+            instructions="You are a helpful assistant. Be very brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start("What's the weather in NYC? Reply in one sentence.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_praisonai_two_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 2 PraisonAI agents working together."""
+    from praisonaiagents import Agent, PraisonAIAgents
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI 2-agent iteration {i+1}/{iterations}...")
+        
+        researcher = Agent(
+            name="Researcher",
+            role="Research Assistant",
+            goal="Gather weather information",
+            instructions="Get weather data and pass to reporter. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        reporter = Agent(
+            name="Reporter",
+            role="News Reporter",
+            goal="Create weather report",
+            instructions="Create a one-sentence weather summary.",
+            llm="gpt-4o-mini",
+            verbose=False
+        )
+        
+        agents = PraisonAIAgents(
+            agents=[researcher, reporter],
+            process="sequential",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agents.start("Get NYC weather and create a brief report.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_praisonai_three_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 3 PraisonAI agents working together."""
+    from praisonaiagents import Agent, PraisonAIAgents
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI 3-agent iteration {i+1}/{iterations}...")
+        
+        weather_agent = Agent(
+            name="WeatherAgent",
+            role="Weather Specialist",
+            goal="Get weather data",
+            instructions="Fetch weather information. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        time_agent = Agent(
+            name="TimeAgent",
+            role="Time Specialist",
+            goal="Get time information",
+            instructions="Fetch timezone information. Be brief.",
+            llm="gpt-4o-mini",
+            tools=[get_time],
+            verbose=False
+        )
+        
+        summarizer = Agent(
+            name="Summarizer",
+            role="Summary Writer",
+            goal="Combine information",
+            instructions="Create a one-sentence summary combining weather and time.",
+            llm="gpt-4o-mini",
+            verbose=False
+        )
+        
+        agents = PraisonAIAgents(
+            agents=[weather_agent, time_agent, summarizer],
+            process="sequential",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agents.start("Get NYC weather and EST time, then summarize.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+# ============================================================================
+# Agno Benchmarks
+# ============================================================================
+
+def benchmark_agno_single(iterations: int = 3) -> ExecutionResult:
+    """Benchmark single Agno agent execution."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno single agent iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["You are a helpful assistant. Be very brief."],
+            tools=[get_weather],
+        )
+        
+        start = time.perf_counter()
+        response = agent.run("What's the weather in NYC? Reply in one sentence.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_agno_two_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 2 Agno agents working together (using Team)."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    from agno.team import Team
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno 2-agent iteration {i+1}/{iterations}...")
+        
+        researcher = Agent(
+            name="Researcher",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Get weather data. Be brief."],
+            tools=[get_weather],
+        )
+        
+        reporter = Agent(
+            name="Reporter",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Create a one-sentence weather summary."],
+        )
+        
+        team = Team(
+            members=[researcher, reporter],
+            model=OpenAIChat(id="gpt-4o-mini"),
+        )
+        
+        start = time.perf_counter()
+        response = team.run("Get NYC weather and create a brief report.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+def benchmark_agno_three_agents(iterations: int = 3) -> ExecutionResult:
+    """Benchmark 3 Agno agents working together."""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    from agno.team import Team
+    
+    result = ExecutionResult()
+    
+    for i in range(iterations):
+        print(f"  Agno 3-agent iteration {i+1}/{iterations}...")
+        
+        weather_agent = Agent(
+            name="WeatherAgent",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Fetch weather information. Be brief."],
+            tools=[get_weather],
+        )
+        
+        time_agent = Agent(
+            name="TimeAgent",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Fetch timezone information. Be brief."],
+            tools=[get_time],
+        )
+        
+        summarizer = Agent(
+            name="Summarizer",
+            model=OpenAIChat(id="gpt-4o-mini"),
+            instructions=["Create a one-sentence summary combining weather and time."],
+        )
+        
+        team = Team(
+            members=[weather_agent, time_agent, summarizer],
+            model=OpenAIChat(id="gpt-4o-mini"),
+        )
+        
+        start = time.perf_counter()
+        response = team.run("Get NYC weather and EST time, then summarize.")
+        elapsed = time.perf_counter() - start
+        
+        result.times.append(elapsed)
+        print(f"    Time: {elapsed:.2f}s")
+    
+    return result
+
+
+# ============================================================================
+# Save Results
+# ============================================================================
+
+def save_results(results: dict, versions: dict):
+    """Save benchmark results to file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), 'REAL_BENCHMARK_RESULTS.md')
+    
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Real-World Execution Benchmark\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write('**Model:** gpt-4o-mini\n')
+        f.write('**Iterations:** 3 per test\n\n')
+        
+        f.write('## Results Summary\n\n')
+        f.write('| Test | PraisonAI (avg) | Agno (avg) | Difference |\n')
+        f.write('|------|-----------------|------------|------------|\n')
+        
+        tests = ['single', 'two_agents', 'three_agents']
+        test_names = ['Single Agent', '2 Agents', '3 Agents']
+        
+        for test, name in zip(tests, test_names):
+            praison_key = f'praisonai_{test}'
+            agno_key = f'agno_{test}'
+            
+            if praison_key in results and agno_key in results:
+                praison_avg = results[praison_key].avg_time
+                agno_avg = results[agno_key].avg_time
+                
+                if praison_avg < agno_avg:
+                    diff = f'PraisonAI {agno_avg/praison_avg:.2f}x faster'
+                else:
+                    diff = f'Agno {praison_avg/agno_avg:.2f}x faster'
+                
+                f.write(f'| {name} | {praison_avg:.2f}s | {agno_avg:.2f}s | {diff} |\n')
+        
+        f.write('\n## Detailed Results\n\n')
+        
+        for key, result in results.items():
+            f.write(f'### {key}\n')
+            f.write(f'- Average: {result.avg_time:.2f}s\n')
+            f.write(f'- Min: {result.min_time:.2f}s\n')
+            f.write(f'- Max: {result.max_time:.2f}s\n')
+            f.write(f'- Std Dev: {result.std_dev:.2f}s\n')
+            f.write(f'- Times: {[f"{t:.2f}s" for t in result.times]}\n\n')
+        
+        f.write('## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('export OPENAI_API_KEY=your_key\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/real_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+if __name__ == "__main__":
+    print("="*70)
+    print("PraisonAI Agents - Real-World Execution Benchmark")
+    print("="*70)
+    print("\nThis benchmark measures actual agent execution time including:")
+    print("  - LLM API calls")
+    print("  - Tool execution")
+    print("  - Multi-agent coordination")
+    print("\nModel: gpt-4o-mini")
+    print("Iterations: 3 per test")
+    
+    versions = get_package_versions()
+    print(f"\nPackage versions:")
+    for pkg, ver in versions.items():
+        print(f"  {pkg}: {ver}")
+    
+    results = {}
+    
+    # Single Agent Tests
+    print("\n" + "="*70)
+    print("SINGLE AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI single agent...")
+    results['praisonai_single'] = benchmark_praisonai_single()
+    
+    print("\nTesting Agno single agent...")
+    results['agno_single'] = benchmark_agno_single()
+    
+    # 2-Agent Tests
+    print("\n" + "="*70)
+    print("2-AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI 2 agents...")
+    results['praisonai_two_agents'] = benchmark_praisonai_two_agents()
+    
+    print("\nTesting Agno 2 agents (Team)...")
+    results['agno_two_agents'] = benchmark_agno_two_agents()
+    
+    # 3-Agent Tests
+    print("\n" + "="*70)
+    print("3-AGENT BENCHMARK")
+    print("="*70)
+    
+    print("\nTesting PraisonAI 3 agents...")
+    results['praisonai_three_agents'] = benchmark_praisonai_three_agents()
+    
+    print("\nTesting Agno 3 agents (Team)...")
+    results['agno_three_agents'] = benchmark_agno_three_agents()
+    
+    # Summary
+    print("\n" + "="*70)
+    print("RESULTS SUMMARY")
+    print("="*70)
+    
+    print(f"\n{'Test':<20} {'PraisonAI (avg)':<18} {'Agno (avg)':<15} {'Difference':<20}")
+    print("-" * 73)
+    
+    tests = [
+        ('Single Agent', 'praisonai_single', 'agno_single'),
+        ('2 Agents', 'praisonai_two_agents', 'agno_two_agents'),
+        ('3 Agents', 'praisonai_three_agents', 'agno_three_agents'),
+    ]
+    
+    for name, praison_key, agno_key in tests:
+        praison_avg = results[praison_key].avg_time
+        agno_avg = results[agno_key].avg_time
+        
+        if praison_avg < agno_avg:
+            diff = f'PraisonAI {agno_avg/praison_avg:.2f}x faster'
+        else:
+            diff = f'Agno {praison_avg/agno_avg:.2f}x faster'
+        
+        print(f"{name:<20} {praison_avg:<18.2f}s {agno_avg:<15.2f}s {diff:<20}")
+    
+    print("\n" + "="*70)
+    
+    # Save results
+    save_results(results, versions)

src/praisonai-agents/benchmarks/response_benchmark.py

@@ -0,0 +1,235 @@
+"""
+PraisonAI Agents - Response Time Benchmark
+
+Measures actual LLM response time with gpt-4o-mini across frameworks.
+
+Usage:
+    python benchmarks/response_benchmark.py
+"""
+
+import time
+import statistics
+import os
+from typing import List, Literal
+from dataclasses import dataclass, field
+
+# Ensure we use gpt-4o-mini
+os.environ['OPENAI_MODEL_NAME'] = 'gpt-4o-mini'
+
+
+@dataclass
+class ResponseResult:
+    """Response time measurement results"""
+    response_times: List[float] = field(default_factory=list)
+    
+    @property
+    def avg_time(self) -> float:
+        return statistics.mean(self.response_times) if self.response_times else 0
+    
+    @property
+    def min_time(self) -> float:
+        return min(self.response_times) if self.response_times else 0
+    
+    @property
+    def max_time(self) -> float:
+        return max(self.response_times) if self.response_times else 0
+    
+    @property
+    def std_dev(self) -> float:
+        return statistics.stdev(self.response_times) if len(self.response_times) > 1 else 0
+
+
+def get_weather(city: Literal["nyc", "sf"]):
+    """Use this to get weather information."""
+    if city == "nyc":
+        return "It might be cloudy in nyc"
+    elif city == "sf":
+        return "It's always sunny in sf"
+
+
+def benchmark_praisonai_response(iterations: int = 5) -> ResponseResult:
+    """Benchmark PraisonAI agent response time"""
+    from praisonaiagents import Agent
+    
+    result = ResponseResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI iteration {i+1}/{iterations}...")
+        
+        # Create fresh agent each time
+        agent = Agent(
+            name="Test Agent",
+            instructions="Be concise, reply with one sentence.",
+            llm="gpt-4o-mini",
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start("What is the capital of France?")
+        end = time.perf_counter()
+        
+        result.response_times.append(end - start)
+        print(f"    Response time: {end - start:.3f}s")
+    
+    return result
+
+
+def benchmark_agno_response(iterations: int = 5) -> ResponseResult:
+    """Benchmark Agno agent response time"""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    result = ResponseResult()
+    
+    for i in range(iterations):
+        print(f"  Agno iteration {i+1}/{iterations}...")
+        
+        # Create fresh agent each time
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            system_message="Be concise, reply with one sentence.",
+        )
+        
+        start = time.perf_counter()
+        response = agent.run("What is the capital of France?")
+        end = time.perf_counter()
+        
+        result.response_times.append(end - start)
+        print(f"    Response time: {end - start:.3f}s")
+    
+    return result
+
+
+def benchmark_praisonai_with_tool(iterations: int = 5) -> ResponseResult:
+    """Benchmark PraisonAI agent response time with tool calling"""
+    from praisonaiagents import Agent
+    
+    result = ResponseResult()
+    
+    for i in range(iterations):
+        print(f"  PraisonAI (with tool) iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            name="Weather Agent",
+            instructions="You are a weather assistant. Use the get_weather tool to answer questions.",
+            llm="gpt-4o-mini",
+            tools=[get_weather],
+            verbose=False
+        )
+        
+        start = time.perf_counter()
+        response = agent.start("What's the weather in NYC?")
+        end = time.perf_counter()
+        
+        result.response_times.append(end - start)
+        print(f"    Response time: {end - start:.3f}s")
+    
+    return result
+
+
+def benchmark_agno_with_tool(iterations: int = 5) -> ResponseResult:
+    """Benchmark Agno agent response time with tool calling"""
+    from agno.agent import Agent
+    from agno.models.openai import OpenAIChat
+    
+    result = ResponseResult()
+    
+    for i in range(iterations):
+        print(f"  Agno (with tool) iteration {i+1}/{iterations}...")
+        
+        agent = Agent(
+            model=OpenAIChat(id="gpt-4o-mini"),
+            system_message="You are a weather assistant. Use the get_weather tool to answer questions.",
+            tools=[get_weather],
+        )
+        
+        start = time.perf_counter()
+        response = agent.run("What's the weather in NYC?")
+        end = time.perf_counter()
+        
+        result.response_times.append(end - start)
+        print(f"    Response time: {end - start:.3f}s")
+    
+    return result
+
+
+if __name__ == "__main__":
+    print("="*70)
+    print("PraisonAI Agents - Response Time Benchmark")
+    print("="*70)
+    print("\nModel: gpt-4o-mini")
+    print("Measures end-to-end response time including:")
+    print("  - Agent instantiation")
+    print("  - API call to OpenAI")
+    print("  - Response processing")
+    
+    iterations = 5
+    results = {}
+    
+    # Test 1: Simple response (no tools)
+    print("\n" + "="*70)
+    print("TEST 1: Simple Response (No Tools)")
+    print("="*70)
+    
+    print("\nBenchmarking PraisonAI...")
+    try:
+        results['praisonai_simple'] = benchmark_praisonai_response(iterations)
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    print("\nBenchmarking Agno...")
+    try:
+        results['agno_simple'] = benchmark_agno_response(iterations)
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    # Test 2: Response with tool calling
+    print("\n" + "="*70)
+    print("TEST 2: Response with Tool Calling")
+    print("="*70)
+    
+    print("\nBenchmarking PraisonAI with tool...")
+    try:
+        results['praisonai_tool'] = benchmark_praisonai_with_tool(iterations)
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    print("\nBenchmarking Agno with tool...")
+    try:
+        results['agno_tool'] = benchmark_agno_with_tool(iterations)
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    # Summary
+    print("\n" + "="*70)
+    print("SUMMARY RESULTS")
+    print("="*70)
+    
+    print(f"\n{'Test':<30} {'PraisonAI (avg)':<20} {'Agno (avg)':<20} {'Ratio':<15}")
+    print("-" * 85)
+    
+    if 'praisonai_simple' in results and 'agno_simple' in results:
+        p_time = results['praisonai_simple'].avg_time
+        a_time = results['agno_simple'].avg_time
+        ratio = p_time / a_time if a_time > 0 else float('inf')
+        print(f"{'Simple Response':<30} {p_time:<20.3f}s {a_time:<20.3f}s {ratio:.2f}x")
+    
+    if 'praisonai_tool' in results and 'agno_tool' in results:
+        p_time = results['praisonai_tool'].avg_time
+        a_time = results['agno_tool'].avg_time
+        ratio = p_time / a_time if a_time > 0 else float('inf')
+        print(f"{'With Tool Calling':<30} {p_time:<20.3f}s {a_time:<20.3f}s {ratio:.2f}x")
+    
+    print("\n" + "="*70)
+    print("NOTE")
+    print("="*70)
+    print("\nResponse time is dominated by OpenAI API latency.")
+    print("Agent instantiation overhead is negligible in real-world usage.")

src/praisonai-agents/benchmarks/results.console

@@ -0,0 +1,194 @@
+❯ python benchmarks/performance_benchmark.py
+/Users/praison/praisonai-package/src/praisonai-agents/praisonaiagents/_warning_patch.py:47: UserWarning: Mixing V1 models and V2 models (or constructs, like `TypeAdapter`) is not supported. Please upgrade `Settings` to V2.
+  _original_warn(message, category, stacklevel, source)
+[13:04:15] INFO     [13:04:15]          config.py:50
+                    config.py:50 INFO               
+                    Using config path:              
+                    /Users/praison/.con             
+                    fig/crewai/settings             
+                    .json                           
+======================================================================
+PraisonAI Agents - Comprehensive Performance Benchmark
+======================================================================
+
+This benchmark measures:
+  1. Agent instantiation time (how fast an agent object is created)
+  2. Memory footprint (how much memory an agent uses)
+
+Methodology:
+  - 10 warmup runs (not measured)
+  - 1000 measured iterations
+  - tracemalloc for memory measurement
+  - Baseline subtraction for accuracy
+
+Frameworks available:
+  - PraisonAI: ✅
+  - Agno: ✅
+  - PydanticAI: ✅
+  - OpenAI Agents SDK: ✅
+  - LangGraph: ✅
+  - CrewAI: ✅
+
+======================================================================
+Testing PraisonAI Agents
+======================================================================
+
+============================================================
+Benchmarking: PraisonAI
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PraisonAI:
+  Average Time: 0.000003 seconds (3.20 μs)
+  Min Time:     0.000003 seconds
+  Max Time:     0.000025 seconds
+  Std Dev:      0.000001 seconds
+  Median Time:  0.000003 seconds
+  Avg Memory:   0.003678 MiB (3.77 KiB)
+
+======================================================================
+Testing PraisonAI Agents (LiteLLM)
+======================================================================
+
+============================================================
+Benchmarking: PraisonAI (LiteLLM)
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PraisonAI (LiteLLM):
+  Average Time: 0.000007 seconds (7.31 μs)
+  Min Time:     0.000007 seconds
+  Max Time:     0.000060 seconds
+  Std Dev:      0.000002 seconds
+  Median Time:  0.000007 seconds
+  Avg Memory:   0.006419 MiB (6.57 KiB)
+
+======================================================================
+Testing Agno
+======================================================================
+
+============================================================
+Benchmarking: Agno
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for Agno:
+  Average Time: 0.000005 seconds (5.30 μs)
+  Min Time:     0.000005 seconds
+  Max Time:     0.000039 seconds
+  Std Dev:      0.000002 seconds
+  Median Time:  0.000005 seconds
+  Avg Memory:   0.006599 MiB (6.76 KiB)
+
+======================================================================
+Testing PydanticAI
+======================================================================
+
+============================================================
+Benchmarking: PydanticAI Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for PydanticAI Agent Instantiation:
+  Average Time: 0.000247 seconds (247.34 μs)
+  Min Time:     0.000218 seconds
+  Max Time:     0.000552 seconds
+  Std Dev:      0.000031 seconds
+  Median Time:  0.000237 seconds
+  Avg Memory:   0.028486 MiB (29.17 KiB)
+
+======================================================================
+Testing OpenAI Agents SDK
+======================================================================
+
+============================================================
+Benchmarking: OpenAI Agents SDK Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for OpenAI Agents SDK Instantiation:
+  Average Time: 0.000282 seconds (282.25 μs)
+  Min Time:     0.000247 seconds
+  Max Time:     0.001110 seconds
+  Std Dev:      0.000055 seconds
+  Median Time:  0.000263 seconds
+  Avg Memory:   0.029032 MiB (29.73 KiB)
+
+======================================================================
+Testing LangGraph
+======================================================================
+
+============================================================
+Benchmarking: LangGraph Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for LangGraph Agent Instantiation:
+  Average Time: 0.003200 seconds (3200.15 μs)
+  Min Time:     0.002808 seconds
+  Max Time:     0.116363 seconds
+  Std Dev:      0.003628 seconds
+  Median Time:  0.002972 seconds
+  Avg Memory:   0.207509 MiB (212.49 KiB)
+
+======================================================================
+Testing CrewAI
+======================================================================
+
+============================================================
+Benchmarking: CrewAI Agent Instantiation
+============================================================
+Warmup runs: 10
+Measured iterations: 1000
+
+Measuring runtime...
+Measuring memory...
+
+Results for CrewAI Agent Instantiation:
+  Average Time: 0.016772 seconds (16771.69 μs)
+  Min Time:     0.014404 seconds
+  Max Time:     0.091841 seconds
+  Std Dev:      0.003445 seconds
+  Median Time:  0.015816 seconds
+  Avg Memory:   0.065050 MiB (66.61 KiB)
+
+======================================================================
+RESULTS SUMMARY
+======================================================================
+
+Framework                 Avg Time (μs)   Avg Memory (KiB)   Relative       
+-------------------------------------------------------------------------
+PraisonAI                 3.20            3.77               1.00x          
+Agno                      5.30            6.76               1.66x          
+PraisonAI (LiteLLM)       7.31            6.57               2.28x          
+PydanticAI                247.34          29.17              77.25x         
+OpenAI Agents SDK         282.25          29.73              88.15x         
+LangGraph                 3200.15         212.49             999.46x        
+CrewAI                    16771.69        66.61              5238.06x       
+
+======================================================================
+❯ 

src/praisonai-agents/benchmarks/simple_benchmark.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Performance Benchmark
+
+Compares agent instantiation times across popular AI agent frameworks.
+
+Usage:
+    python benchmarks/simple_benchmark.py
+"""
+
+import time
+from typing import Literal
+
+
+ITERATIONS = 100
+
+
+def sample_tool(city: Literal['nyc', 'sf']):
+    """Sample tool for benchmark testing."""
+    if city == 'nyc':
+        return 'cloudy'
+    return 'sunny'
+
+
+def measure_instantiation(create_fn, iterations=ITERATIONS):
+    """Measure average instantiation time in microseconds."""
+    times = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        create_fn()
+        times.append((time.perf_counter() - start) * 1_000_000)
+    return sum(times) / len(times)
+
+
+def run_benchmark():
+    """Run the benchmark across all available frameworks (without tools)."""
+    results = {}
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Performance Benchmark')
+    print('=' * 60)
+    print(f'\nIterations: {ITERATIONS}')
+    print('Metric: Agent instantiation time (microseconds)\n')
+    
+    # PraisonAI (without tools)
+    print("Testing PraisonAI...")
+    from praisonaiagents import Agent as PraisonAgent
+    
+    results['PraisonAI'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='gpt-4o-mini', verbose=False)
+    )
+    
+    results['PraisonAI (LiteLLM)'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='openai/gpt-4o-mini', verbose=False)
+    )
+    
+    # Other frameworks for comparison
+    print("Testing other frameworks...")
+    
+    try:
+        from agno.agent import Agent as AgnoAgent
+        from agno.models.openai import OpenAIChat
+        results['Agno'] = measure_instantiation(
+            lambda: AgnoAgent(model=OpenAIChat(id='gpt-4o-mini'))
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from pydantic_ai import Agent as PydanticAgent
+        results['PydanticAI'] = measure_instantiation(
+            lambda: PydanticAgent('openai:gpt-4o-mini')
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from agents import Agent as OpenAIAgent
+        results['OpenAI Agents SDK'] = measure_instantiation(
+            lambda: OpenAIAgent(name='Test', model='gpt-4o-mini')
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from langchain_core.tools import tool as langchain_tool
+        from langchain_openai import ChatOpenAI
+        from langgraph.prebuilt import create_react_agent
+        
+        @langchain_tool
+        def get_weather_lg(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['LangGraph'] = measure_instantiation(
+            lambda: create_react_agent(model=ChatOpenAI(model='gpt-4o-mini'), tools=[get_weather_lg])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from crewai.agent import Agent as CrewAgent
+        from crewai.tools import tool as crewai_tool
+        
+        @crewai_tool("Weather Tool")
+        def get_weather_crew(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['CrewAI'] = measure_instantiation(
+            lambda: CrewAgent(
+                role='Weather Agent',
+                goal='Provide weather info',
+                backstory='A weather expert',
+                tools=[get_weather_crew],
+                verbose=False
+            )
+        )
+    except ImportError:
+        pass
+    
+    # Print results
+    print('\n' + '=' * 60)
+    print('RESULTS')
+    print('=' * 60)
+    
+    baseline = results.get('PraisonAI', 1)
+    print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Relative':<10}")
+    print('-' * 50)
+    
+    for name, avg in sorted(results.items(), key=lambda x: x[1]):
+        ratio = avg / baseline
+        print(f'{name:<25} {avg:<15.2f} {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    return results
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    from importlib.metadata import version as get_version
+    
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'PydanticAI': 'pydantic-ai',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_results(results: dict, filename: str = 'BENCHMARK_RESULTS.md'):
+    """Save benchmark results to a markdown file and update README."""
+    import os
+    import re
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), filename)
+    versions = get_package_versions()
+    
+    # Find the fastest result (baseline)
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest_time = sorted_results[0][1] if sorted_results else 1
+    
+    # Build the table rows
+    table_rows = []
+    for name, avg in sorted_results:
+        ratio = avg / fastest_time
+        if ratio == 1.0:
+            table_rows.append(f'| **{name}** | **{avg:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg:,.2f}' if avg >= 1000 else f'{avg:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {name} | {avg_str} | {ratio_str} |')
+    
+    # Save to BENCHMARK_RESULTS.md
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Iterations:** {ITERATIONS}\n')
+        f.write('**Test:** Agent instantiation (without tools)\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/simple_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    
+    # Also update the main README.md
+    readme_path = os.path.join(os.path.dirname(__file__), '..', '..', '..', 'README.md')
+    if os.path.exists(readme_path):
+        update_readme(readme_path, table_rows)
+    
+    return filepath
+
+
+def update_readme(readme_path: str, table_rows: list):
+    """Update the performance section in README.md with latest results."""
+    import re
+    
+    with open(readme_path, 'r') as f:
+        content = f.read()
+    
+    # Build the new table
+    new_table = '''| Framework | Avg Time (μs) | Relative |
+|-----------|---------------|----------|
+''' + '\n'.join(table_rows)
+    
+    # Pattern to match the performance table
+    pattern = r'(\| Framework \| Avg Time \(μs\) \| Relative \|\n\|[-|]+\|\n)(\|[^\n]+\|\n)+'
+    
+    if re.search(pattern, content):
+        content = re.sub(pattern, new_table + '\n', content)
+        
+        with open(readme_path, 'w') as f:
+            f.write(content)
+        
+        print(f'README.md updated: {readme_path}')
+
+
+if __name__ == '__main__':
+    results = run_benchmark()
+    save_results(results)

src/praisonai-agents/benchmarks/tools_benchmark.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+PraisonAI Agents - Tools Benchmark
+
+Compares agent instantiation times WITH TOOLS across frameworks.
+
+Usage:
+    python benchmarks/tools_benchmark.py
+"""
+
+import time
+from typing import Literal
+from importlib.metadata import version as get_version
+
+
+ITERATIONS = 100
+
+
+def sample_tool(city: Literal['nyc', 'sf']):
+    """Sample tool for benchmark testing."""
+    if city == 'nyc':
+        return 'cloudy'
+    return 'sunny'
+
+
+def measure_instantiation(create_fn, iterations=ITERATIONS):
+    """Measure average instantiation time in microseconds."""
+    times = []
+    
+    # Warmup
+    for _ in range(10):
+        create_fn()
+    
+    # Measure
+    for _ in range(iterations):
+        start = time.perf_counter()
+        create_fn()
+        elapsed = time.perf_counter() - start
+        times.append(elapsed * 1_000_000)  # Convert to microseconds
+    
+    return sum(times) / len(times)
+
+
+def run_benchmark():
+    """Run the benchmark across all available frameworks WITH TOOLS."""
+    tools = [sample_tool]
+    results = {}
+    
+    print('=' * 60)
+    print('PraisonAI Agents - Tools Benchmark')
+    print('=' * 60)
+    print(f'\nIterations: {ITERATIONS}')
+    print('Metric: Agent instantiation time WITH TOOLS (microseconds)\n')
+    
+    # PraisonAI with tools
+    print("Testing PraisonAI...")
+    from praisonaiagents import Agent as PraisonAgent
+    
+    results['PraisonAI'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='gpt-4o-mini', tools=tools, verbose=False)
+    )
+    
+    results['PraisonAI (LiteLLM)'] = measure_instantiation(
+        lambda: PraisonAgent(name='Test', llm='openai/gpt-4o-mini', tools=tools, verbose=False)
+    )
+    
+    # Other frameworks with tools
+    print("Testing other frameworks...")
+    
+    try:
+        from agno.agent import Agent as AgnoAgent
+        from agno.models.openai import OpenAIChat
+        results['Agno'] = measure_instantiation(
+            lambda: AgnoAgent(model=OpenAIChat(id='gpt-4o-mini'), tools=tools)
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from agents import Agent as OpenAIAgent, function_tool
+        results['OpenAI Agents SDK'] = measure_instantiation(
+            lambda: OpenAIAgent(name='Test', model='gpt-4o-mini', tools=[function_tool(sample_tool)])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from langchain_core.tools import tool as langchain_tool
+        from langchain_openai import ChatOpenAI
+        from langgraph.prebuilt import create_react_agent
+        
+        @langchain_tool
+        def get_weather_lg(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['LangGraph'] = measure_instantiation(
+            lambda: create_react_agent(model=ChatOpenAI(model='gpt-4o-mini'), tools=[get_weather_lg])
+        )
+    except ImportError:
+        pass
+    
+    try:
+        from crewai.agent import Agent as CrewAgent
+        from crewai.tools import tool as crewai_tool
+        
+        @crewai_tool("Weather Tool")
+        def get_weather_crew(city: Literal['nyc', 'sf']):
+            """Get weather info."""
+            return 'sunny' if city == 'sf' else 'cloudy'
+        
+        results['CrewAI'] = measure_instantiation(
+            lambda: CrewAgent(
+                role='Weather Agent',
+                goal='Provide weather info',
+                backstory='A weather expert',
+                tools=[get_weather_crew],
+                verbose=False
+            )
+        )
+    except ImportError:
+        pass
+    
+    # Print results
+    print('\n' + '=' * 60)
+    print('RESULTS (WITH TOOLS)')
+    print('=' * 60)
+    
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    baseline = sorted_results[0][1] if sorted_results else 1
+    
+    print(f"\n{'Framework':<25} {'Avg Time (μs)':<15} {'Relative':<10}")
+    print('-' * 50)
+    
+    for name, avg in sorted_results:
+        ratio = avg / baseline
+        print(f'{name:<25} {avg:<15.2f} {ratio:.2f}x')
+    
+    print('\n' + '=' * 60)
+    return results
+
+
+def get_package_versions():
+    """Get version numbers for benchmarked packages."""
+    packages = {
+        'PraisonAI': 'praisonaiagents',
+        'Agno': 'agno',
+        'OpenAI Agents SDK': 'openai-agents',
+        'LangGraph': 'langgraph',
+        'CrewAI': 'crewai'
+    }
+    
+    versions = {}
+    for display_name, pkg_name in packages.items():
+        try:
+            versions[display_name] = get_version(pkg_name)
+        except Exception:
+            versions[display_name] = 'not installed'
+    
+    return versions
+
+
+def save_results(results: dict, filename: str = 'TOOLS_BENCHMARK_RESULTS.md'):
+    """Save benchmark results to a markdown file."""
+    import os
+    from datetime import datetime
+    
+    filepath = os.path.join(os.path.dirname(__file__), filename)
+    versions = get_package_versions()
+    
+    # Find the fastest result (baseline)
+    sorted_results = sorted(results.items(), key=lambda x: x[1])
+    fastest_time = sorted_results[0][1] if sorted_results else 1
+    
+    # Build the table rows
+    table_rows = []
+    for name, avg in sorted_results:
+        ratio = avg / fastest_time
+        if ratio == 1.0:
+            table_rows.append(f'| **{name}** | **{avg:.2f}** | **1.00x (fastest)** |')
+        else:
+            avg_str = f'{avg:,.2f}' if avg >= 1000 else f'{avg:.2f}'
+            ratio_str = f'{ratio:,.0f}x' if ratio >= 100 else f'{ratio:.2f}x'
+            table_rows.append(f'| {name} | {avg_str} | {ratio_str} |')
+    
+    # Save to file
+    with open(filepath, 'w') as f:
+        f.write('# PraisonAI Agents - Tools Benchmark Results\n\n')
+        f.write(f'**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+        f.write(f'**Iterations:** {ITERATIONS}\n')
+        f.write('**Test:** Agent instantiation WITH TOOLS\n\n')
+        f.write('## Results\n\n')
+        f.write('| Framework | Avg Time (μs) | Relative |\n')
+        f.write('|-----------|---------------|----------|\n')
+        f.write('\n'.join(table_rows) + '\n')
+        f.write('\n## Package Versions\n\n')
+        f.write('| Package | Version |\n')
+        f.write('|---------|--------|\n')
+        for pkg, ver in versions.items():
+            f.write(f'| {pkg} | {ver} |\n')
+        f.write('\n## How to Reproduce\n\n')
+        f.write('```bash\n')
+        f.write('cd praisonai-agents\n')
+        f.write('python benchmarks/tools_benchmark.py\n')
+        f.write('```\n')
+    
+    print(f'\nResults saved to: {filepath}')
+    return filepath
+
+
+if __name__ == '__main__':
+    results = run_benchmark()
+    save_results(results)

src/praisonai-agents/callback_test_log.txt

@@ -0,0 +1,9 @@
+Starting test with verbose=False
+CALLBACK EXECUTED!
+Message: 
+You need to do the following task: Say hello world.
+Expected Output: A greeting.
+Please provide only the final result of your work. Do not add any conversation or extra explanation.
+Response: Hello, World!
+Other kwargs: {'markdown': True, 'generation_time': 2.685833215713501, 'agent_name': 'TestAgent', 'agent_role': 'Assistant', 'agent_tools': None, 'task_name': 'simple_task', 'task_description': 'Say hello world', 'task_id': 0}
+--------------------------------------------------

src/praisonai-agents/praisonaiagents/__init__.py

@@ -305,3 +305,21 @@ __all__.extend([
     'LineRange'
 ])
 
+# AG-UI support (optional, lazy loaded)
+try:
+    from praisonaiagents.ui.agui import AGUI
+    __all__.append('AGUI')
+    _agui_available = True
+except ImportError:
+    _agui_available = False
+    AGUI = None
+
+# A2A support (optional, lazy loaded)
+try:
+    from praisonaiagents.ui.a2a import A2A
+    __all__.append('A2A')
+    _a2a_available = True
+except ImportError:
+    _a2a_available = False
+    A2A = None
+

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -551,8 +551,9 @@ Your Goal: {self.goal}
         self.auto_save = auto_save  # Session name for auto-saving
         
         # Initialize rules manager for persistent context (like Cursor/Windsurf)
+        # NOTE: Lazy initialization - rules are loaded only when accessed (performance optimization)
         self._rules_manager = None
-        self._init_rules_manager()
+        self._rules_manager_initialized = False
         
         # Handle web_search fallback: inject DuckDuckGo tool for unsupported models
         if web_search and not self._model_supports_web_search():
@@ -599,7 +600,7 @@ Your Goal: {self.goal}
 
         # Fast Context configuration (lazy loaded)
         self.fast_context_enabled = fast_context
-        self.fast_context_path = fast_context_path or os.getcwd()
+        self._fast_context_path = fast_context_path  # Store raw, resolve lazily
         self.fast_context_model = fast_context_model
         self.fast_context_max_turns = fast_context_max_turns
         self.fast_context_parallelism = fast_context_parallelism
@@ -614,6 +615,17 @@ Your Goal: {self.goal}
             self._console = Console()
         return self._console
     
+    @property
+    def fast_context_path(self):
+        """Lazily resolve fast_context_path - avoids os.getcwd() on every init."""
+        if self._fast_context_path is None:
+            self._fast_context_path = os.getcwd()
+        return self._fast_context_path
+    
+    @fast_context_path.setter
+    def fast_context_path(self, value):
+        self._fast_context_path = value
+    
     @property
     def _openai_client(self):
         """Lazily initialize OpenAI client only when needed."""
@@ -785,6 +797,21 @@ Your Goal: {self.goal}
             logging.warning(f"FastContext search failed: {e}")
             return None
     
+    @property
+    def rules_manager(self):
+        """
+        Lazy-initialized RulesManager for persistent rules/instructions.
+        
+        This property initializes the RulesManager only when first accessed,
+        avoiding expensive filesystem operations during agent instantiation.
+        
+        Returns:
+            RulesManager instance or None if not available
+        """
+        if not self._rules_manager_initialized:
+            self._init_rules_manager()
+        return self._rules_manager
+    
     def _init_rules_manager(self):
         """
         Initialize RulesManager for persistent rules/instructions.
@@ -793,7 +820,10 @@ Your Goal: {self.goal}
         - ~/.praison/rules/ (global)
         - .praison/rules/ (workspace)
         - Subdirectory rules
+        
+        NOTE: This is called lazily via the rules_manager property for performance.
         """
+        self._rules_manager_initialized = True
         try:
             from ..memory.rules_manager import RulesManager
             import os
@@ -828,10 +858,10 @@ Your Goal: {self.goal}
         Returns:
             Formatted rules context string
         """
-        if not self._rules_manager:
+        if not self.rules_manager:
             return ""
         
-        return self._rules_manager.build_rules_context(
+        return self.rules_manager.build_rules_context(
             file_path=file_path,
             include_manual=include_manual
         )
@@ -1239,8 +1269,8 @@ Your Goal: {self.goal}
 Your Role: {self.role}\n
 Your Goal: {self.goal}"""
         
-        # Add rules context if rules manager is enabled
-        if self._rules_manager:
+        # Add rules context if rules manager is enabled (lazy initialization)
+        if self._rules_manager_initialized and self._rules_manager:
             rules_context = self.get_rules_context()
             if rules_context:
                 system_prompt += f"\n\n## Rules (Guidelines you must follow)\n{rules_context}"
@@ -1539,23 +1569,54 @@ Your Goal: {self.goal}"""
         # Special handling for MCP tools
         # Check if tools is an MCP instance with the requested function name
         from ..mcp.mcp import MCP
+        
+        # Helper function to execute MCP tool
+        def _execute_mcp_tool(mcp_instance, func_name, args):
+            """Execute a tool from an MCP instance."""
+            # Handle SSE MCP client
+            if hasattr(mcp_instance, 'is_sse') and mcp_instance.is_sse:
+                if hasattr(mcp_instance, 'sse_client'):
+                    for tool in mcp_instance.sse_client.tools:
+                        if tool.name == func_name:
+                            logging.debug(f"Found matching SSE MCP tool: {func_name}")
+                            return True, tool(**args)
+            # Handle HTTP Stream MCP client
+            if hasattr(mcp_instance, 'is_http_stream') and mcp_instance.is_http_stream:
+                if hasattr(mcp_instance, 'http_stream_client'):
+                    for tool in mcp_instance.http_stream_client.tools:
+                        if tool.name == func_name:
+                            logging.debug(f"Found matching HTTP Stream MCP tool: {func_name}")
+                            return True, tool(**args)
+            # Handle WebSocket MCP client
+            if hasattr(mcp_instance, 'is_websocket') and mcp_instance.is_websocket:
+                if hasattr(mcp_instance, 'websocket_client'):
+                    for tool in mcp_instance.websocket_client.tools:
+                        if tool.name == func_name:
+                            logging.debug(f"Found matching WebSocket MCP tool: {func_name}")
+                            return True, tool(**args)
+            # Handle stdio MCP client
+            if hasattr(mcp_instance, 'runner'):
+                for mcp_tool in mcp_instance.runner.tools:
+                    if hasattr(mcp_tool, 'name') and mcp_tool.name == func_name:
+                        logging.debug(f"Found matching MCP tool: {func_name}")
+                        return True, mcp_instance.runner.call_tool(func_name, args)
+            return False, None
+        
+        # Check if tools is a single MCP instance
         if isinstance(self.tools, MCP):
             logging.debug(f"Looking for MCP tool {function_name}")
-            
-            # Handle SSE MCP client
-            if hasattr(self.tools, 'is_sse') and self.tools.is_sse:
-                if hasattr(self.tools, 'sse_client'):
-                    for tool in self.tools.sse_client.tools:
-                        if tool.name == function_name:
-                            logging.debug(f"Found matching SSE MCP tool: {function_name}")
-                            return tool(**arguments)
-            # Handle stdio MCP client
-            elif hasattr(self.tools, 'runner'):
-                # Check if any of the MCP tools match the function name
-                for mcp_tool in self.tools.runner.tools:
-                    if hasattr(mcp_tool, 'name') and mcp_tool.name == function_name:
-                        logging.debug(f"Found matching MCP tool: {function_name}")
-                        return self.tools.runner.call_tool(function_name, arguments)
+            found, result = _execute_mcp_tool(self.tools, function_name, arguments)
+            if found:
+                return result
+        
+        # Check if tools is a list that may contain MCP instances
+        if isinstance(self.tools, (list, tuple)):
+            for tool in self.tools:
+                if isinstance(tool, MCP):
+                    logging.debug(f"Looking for MCP tool {function_name} in MCP instance")
+                    found, result = _execute_mcp_tool(tool, function_name, arguments)
+                    if found:
+                        return result
 
         # Try to find the function in the agent's tools list first
         func = None
@@ -1870,7 +1931,8 @@ Your Goal: {self.goal}"""
                 if tool_param is not None:
                     from ..mcp.mcp import MCP
                     if isinstance(tool_param, MCP) and hasattr(tool_param, 'to_openai_tool'):
-                        logging.debug("Converting MCP tool to OpenAI format")
+                        # Single MCP instance
+                        logging.debug("Converting single MCP tool to OpenAI format")
                         openai_tool = tool_param.to_openai_tool()
                         if openai_tool:
                             # Handle both single tool and list of tools
@@ -1879,6 +1941,22 @@ Your Goal: {self.goal}"""
                             else:
                                 tool_param = [openai_tool]
                             logging.debug(f"Converted MCP tool: {tool_param}")
+                    elif isinstance(tool_param, (list, tuple)):
+                        # List that may contain MCP instances - convert each MCP to OpenAI format
+                        converted_tools = []
+                        for t in tool_param:
+                            if isinstance(t, MCP) and hasattr(t, 'to_openai_tool'):
+                                logging.debug("Converting MCP instance in list to OpenAI format")
+                                openai_tools = t.to_openai_tool()
+                                if isinstance(openai_tools, list):
+                                    converted_tools.extend(openai_tools)
+                                elif openai_tools:
+                                    converted_tools.append(openai_tools)
+                            else:
+                                # Keep non-MCP tools as-is
+                                converted_tools.append(t)
+                        tool_param = converted_tools
+                        logging.debug(f"Converted {len(converted_tools)} tools from list")
                 
                 # Store chat history length for potential rollback
                 chat_history_length = len(self.chat_history)

src/praisonai-agents/praisonaiagents/agents/agents.py

@@ -1370,6 +1370,61 @@ Context:
             agent_names = ", ".join([agent.name for agent in self.agents])
             print(f"📊 Available agents for this endpoint ({len(self.agents)}): {agent_names}")
             
+            # Create per-agent endpoints for individual agent access
+            # This allows n8n and other tools to call specific agents
+            agents_dict = {agent.name.lower().replace(' ', '_'): agent for agent in self.agents}
+            
+            # Add GET endpoint to list available agents
+            @_agents_shared_apps[port].get(f"{path}/list")
+            async def list_agents():
+                return {
+                    "agents": [
+                        {"name": agent.name, "id": agent.name.lower().replace(' ', '_')}
+                        for agent in self.agents
+                    ]
+                }
+            
+            # Add per-agent POST endpoints
+            for agent_id, agent_instance in agents_dict.items():
+                agent_path = f"{path}/{agent_id}"
+                
+                # Create a closure to capture the agent instance
+                def create_agent_handler(agent):
+                    async def handle_single_agent(request: Request):
+                        try:
+                            request_data = await request.json()
+                            query = request_data.get("query", "")
+                            if not query:
+                                raise HTTPException(status_code=400, detail="Missing 'query' field")
+                        except:
+                            raise HTTPException(status_code=400, detail="Invalid JSON body")
+                        
+                        try:
+                            if asyncio.iscoroutinefunction(agent.chat):
+                                response = await agent.achat(query)
+                            else:
+                                loop = asyncio.get_running_loop()
+                                response = await loop.run_in_executor(None, lambda q=query: agent.chat(q))
+                            
+                            return {
+                                "agent": agent.name,
+                                "query": query,
+                                "response": response
+                            }
+                        except Exception as e:
+                            logging.error(f"Error with agent {agent.name}: {str(e)}", exc_info=True)
+                            return JSONResponse(
+                                status_code=500,
+                                content={"error": f"Agent error: {str(e)}"}
+                            )
+                    return handle_single_agent
+                
+                # Register the endpoint
+                _agents_shared_apps[port].post(agent_path)(create_agent_handler(agent_instance))
+                _agents_registered_endpoints[port][agent_path] = f"{endpoint_id}_{agent_id}"
+            
+            print(f"🔗 Per-agent endpoints: {', '.join([f'{path}/{aid}' for aid in agents_dict.keys()])}")
+            
             # Start the server if it's not already running for this port
             if not _agents_server_started.get(port, False):
                 # Mark the server as started first to prevent duplicate starts

src/praisonai-agents/praisonaiagents/memory/workflows.py

@@ -440,7 +440,7 @@ class Workflow:
             previous_output = output
             
             if verbose:
-                print(f"✅ {step.name}: {str(output)[:100]}...")
+                print(f"✅ {step.name}: {str(output)}")
             
             # Handle early stop
             if stop:
@@ -571,7 +571,7 @@ class Workflow:
                 output = f"Error: {e}"
         
         if verbose:
-            print(f"✅ {normalized.name}: {str(output)[:100]}...")
+            print(f"✅ {normalized.name}: {str(output)}")
         
         return {
             "step": normalized.name,

src/praisonai-agents/praisonaiagents/ui/__init__.py

@@ -0,0 +1,13 @@
+"""
+UI Integrations for PraisonAI Agents
+
+This module provides UI protocol integrations for exposing PraisonAI Agents
+via various frontend protocols.
+
+Available integrations:
+- agui: AG-UI (Agent-User Interface) protocol for CopilotKit and compatible frontends
+"""
+
+from praisonaiagents.ui.agui import AGUI
+
+__all__ = ["AGUI"]

src/praisonai-agents/praisonaiagents/ui/a2a/__init__.py

@@ -0,0 +1,74 @@
+"""
+A2A Protocol Integration for PraisonAI Agents
+
+This module provides A2A (Agent2Agent) protocol support,
+enabling PraisonAI Agents to be exposed as A2A Servers
+for agent-to-agent communication.
+
+Usage:
+    from praisonaiagents import Agent
+    from praisonaiagents.ui.a2a import A2A
+    from fastapi import FastAPI
+
+    agent = Agent(name="Assistant", role="Helper", goal="Help users")
+    a2a = A2A(agent=agent)
+
+    app = FastAPI()
+    app.include_router(a2a.get_router())
+    
+    # Agent Card available at: GET /.well-known/agent.json
+    # A2A endpoint at: POST /a2a (JSON-RPC)
+"""
+
+from praisonaiagents.ui.a2a.a2a import A2A
+from praisonaiagents.ui.a2a.types import (
+    # Enums
+    TaskState,
+    Role,
+    # Part types
+    TextPart,
+    FilePart,
+    DataPart,
+    # Core types
+    Message,
+    TaskStatus,
+    Task,
+    Artifact,
+    # Agent Card types
+    AgentSkill,
+    AgentCapabilities,
+    AgentCard,
+    # Request/Response types
+    MessageConfig,
+    SendMessageRequest,
+    # Streaming events
+    TaskStatusUpdateEvent,
+    TaskArtifactUpdateEvent,
+)
+
+__all__ = [
+    # Main class
+    "A2A",
+    # Enums
+    "TaskState",
+    "Role",
+    # Part types
+    "TextPart",
+    "FilePart",
+    "DataPart",
+    # Core types
+    "Message",
+    "TaskStatus",
+    "Task",
+    "Artifact",
+    # Agent Card types
+    "AgentSkill",
+    "AgentCapabilities",
+    "AgentCard",
+    # Request/Response types
+    "MessageConfig",
+    "SendMessageRequest",
+    # Streaming events
+    "TaskStatusUpdateEvent",
+    "TaskArtifactUpdateEvent",
+]

src/praisonai-agents/praisonaiagents/ui/a2a/a2a.py

@@ -0,0 +1,154 @@
+"""
+A2A - Main A2A Interface Class
+
+Exposes PraisonAI Agents via the A2A (Agent2Agent) protocol.
+"""
+
+import logging
+from typing import List, Optional, TYPE_CHECKING
+
+from praisonaiagents.ui.a2a.types import AgentCard
+from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+from praisonaiagents.ui.a2a.task_store import TaskStore
+
+if TYPE_CHECKING:
+    from praisonaiagents import Agent, PraisonAIAgents
+    from fastapi import APIRouter
+
+logger = logging.getLogger(__name__)
+
+
+class A2A:
+    """
+    A2A Interface for PraisonAI Agents.
+    
+    Exposes a PraisonAI Agent or PraisonAIAgents workflow via the A2A protocol,
+    enabling agent-to-agent communication with other A2A-compatible systems.
+    
+    Usage:
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Assistant", role="Helper", goal="Help users")
+        a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+        
+        app = FastAPI()
+        app.include_router(a2a.get_router())
+        
+        # Agent Card at: GET /.well-known/agent.json
+        # A2A endpoint at: POST /a2a
+    
+    Args:
+        agent: Single PraisonAI Agent instance
+        agents: PraisonAIAgents instance for multi-agent workflows
+        name: Name for the A2A endpoint (defaults to agent name)
+        description: Description of the agent
+        url: URL where the A2A endpoint is hosted
+        version: Version string for the agent
+        prefix: URL prefix for the router
+        tags: OpenAPI tags for the router
+    """
+    
+    def __init__(
+        self,
+        agent: Optional["Agent"] = None,
+        agents: Optional["PraisonAIAgents"] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        url: str = "http://localhost:8000/a2a",
+        version: str = "1.0.0",
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+    ):
+        if agent is None and agents is None:
+            raise ValueError("A2A requires an agent or agents instance")
+        
+        self.agent = agent
+        self.agents = agents
+        self.url = url
+        self.version = version
+        self.prefix = prefix
+        self.tags = tags or ["A2A"]
+        
+        # Set name from agent if not provided
+        if name:
+            self.name = name
+        elif agent and hasattr(agent, 'name'):
+            self.name = agent.name
+        elif agents and hasattr(agents, 'name'):
+            self.name = agents.name
+        else:
+            self.name = "PraisonAI Agent"
+        
+        # Set description
+        if description:
+            self.description = description
+        elif agent and hasattr(agent, 'role'):
+            self.description = agent.role
+        else:
+            self.description = "PraisonAI Agent via A2A"
+        
+        # Initialize task store
+        self.task_store = TaskStore()
+        
+        # Router cache
+        self._router: Optional["APIRouter"] = None
+        self._agent_card: Optional[AgentCard] = None
+    
+    def get_agent_card(self) -> AgentCard:
+        """
+        Get the Agent Card for this A2A instance.
+        
+        Returns:
+            AgentCard object for A2A discovery
+        """
+        if self._agent_card is None:
+            self._agent_card = generate_agent_card(
+                agent=self.agent,
+                url=self.url,
+                version=self.version,
+                streaming=True,
+            )
+        return self._agent_card
+    
+    def get_router(self) -> "APIRouter":
+        """
+        Get the FastAPI router for this A2A instance.
+        
+        Returns:
+            FastAPI APIRouter with A2A endpoints
+        """
+        if self._router is None:
+            self._router = self._create_router()
+        return self._router
+    
+    def _create_router(self) -> "APIRouter":
+        """Create FastAPI router with A2A endpoints."""
+        from fastapi import APIRouter
+        from fastapi.responses import JSONResponse
+        
+        router = APIRouter(prefix=self.prefix, tags=self.tags)
+        
+        # Agent Card endpoint (well-known URI)
+        @router.get("/.well-known/agent.json")
+        async def get_agent_card():
+            """Return the Agent Card for discovery."""
+            card = self.get_agent_card()
+            return JSONResponse(content=card.model_dump(by_alias=True, exclude_none=True))
+        
+        # Status endpoint
+        @router.get("/status")
+        async def get_status():
+            """Return server status."""
+            return {
+                "status": "ok",
+                "name": self.name,
+                "version": self.version,
+            }
+        
+        # TODO: Add JSON-RPC endpoint for message/send
+        # TODO: Add streaming endpoint for message/stream
+        # TODO: Add task management endpoints
+        
+        return router

src/praisonai-agents/praisonaiagents/ui/a2a/agent_card.py

@@ -0,0 +1,123 @@
+"""
+A2A Agent Card Generation
+
+Generate Agent Cards from PraisonAI Agents for A2A discovery.
+"""
+
+import inspect
+from typing import TYPE_CHECKING, List, Optional
+
+from praisonaiagents.ui.a2a.types import (
+    AgentCard,
+    AgentCapabilities,
+    AgentSkill,
+)
+
+if TYPE_CHECKING:
+    from praisonaiagents import Agent
+
+
+def extract_skills_from_tools(tools: Optional[List]) -> List[AgentSkill]:
+    """
+    Extract AgentSkill objects from a list of tools.
+    
+    Args:
+        tools: List of tool functions or objects
+        
+    Returns:
+        List of AgentSkill objects
+    """
+    if not tools:
+        return []
+    
+    skills = []
+    
+    for tool in tools:
+        # Skip non-callable items
+        if not callable(tool):
+            continue
+        
+        # Get function name
+        name = getattr(tool, '__name__', None)
+        if not name:
+            continue
+        
+        # Get description from docstring
+        docstring = inspect.getdoc(tool)
+        description = docstring.split('\n')[0] if docstring else f"Tool: {name}"
+        
+        # Create skill
+        skill = AgentSkill(
+            id=name,
+            name=name,
+            description=description,
+            tags=["tool"],
+        )
+        skills.append(skill)
+    
+    return skills
+
+
+def generate_agent_card(
+    agent: "Agent",
+    url: str,
+    version: str = "1.0.0",
+    streaming: bool = False,
+    push_notifications: bool = False,
+) -> AgentCard:
+    """
+    Generate an A2A Agent Card from a PraisonAI Agent.
+    
+    Args:
+        agent: PraisonAI Agent instance
+        url: URL where the A2A endpoint is hosted
+        version: Version string for the agent
+        streaming: Whether streaming is supported
+        push_notifications: Whether push notifications are supported
+        
+    Returns:
+        AgentCard object for A2A discovery
+    """
+    # Get agent name
+    name = getattr(agent, 'name', None) or "PraisonAI Agent"
+    
+    # Build description from role, goal, or instructions
+    description_parts = []
+    
+    role = getattr(agent, 'role', None)
+    if role:
+        description_parts.append(role)
+    
+    goal = getattr(agent, 'goal', None)
+    if goal:
+        description_parts.append(goal)
+    
+    instructions = getattr(agent, 'instructions', None)
+    if instructions and not description_parts:
+        # Use first line of instructions if no role/goal
+        description_parts.append(instructions.split('\n')[0][:200])
+    
+    description = ". ".join(description_parts) if description_parts else "PraisonAI Agent"
+    
+    # Extract skills from tools
+    tools = getattr(agent, 'tools', None)
+    skills = extract_skills_from_tools(tools)
+    
+    # Build capabilities
+    capabilities = AgentCapabilities(
+        streaming=streaming,
+        push_notifications=push_notifications,
+    )
+    
+    # Create Agent Card
+    card = AgentCard(
+        name=name,
+        url=url,
+        version=version,
+        description=description,
+        capabilities=capabilities,
+        skills=skills if skills else None,
+        provider={"name": "PraisonAI"},
+    )
+    
+    return card

src/praisonai-agents/praisonaiagents/ui/a2a/conversion.py

@@ -0,0 +1,131 @@
+"""
+A2A Message Conversion
+
+Convert between A2A protocol messages and PraisonAI internal format.
+"""
+
+import uuid
+from typing import Any, Dict, List, Optional
+
+from praisonaiagents.ui.a2a.types import (
+    Message,
+    Role,
+    TextPart,
+    Artifact,
+)
+
+
+def a2a_to_praisonai_messages(messages: List[Message]) -> List[Dict[str, Any]]:
+    """
+    Convert A2A messages to PraisonAI/OpenAI chat format.
+    
+    Args:
+        messages: List of A2A Message objects
+        
+    Returns:
+        List of dicts in OpenAI chat format {"role": ..., "content": ...}
+    """
+    result = []
+    
+    for msg in messages:
+        # Map A2A role to OpenAI role
+        role = "user" if msg.role == Role.USER else "assistant"
+        
+        # Combine all text parts
+        content_parts = []
+        for part in msg.parts:
+            if isinstance(part, TextPart):
+                content_parts.append(part.text)
+            elif hasattr(part, 'text'):
+                content_parts.append(part.text)
+        
+        content = " ".join(content_parts)
+        
+        result.append({
+            "role": role,
+            "content": content,
+        })
+    
+    return result
+
+
+def praisonai_to_a2a_message(
+    response: str,
+    message_id: Optional[str] = None,
+    context_id: Optional[str] = None,
+    task_id: Optional[str] = None,
+) -> Message:
+    """
+    Convert PraisonAI response to A2A Message.
+    
+    Args:
+        response: Text response from agent
+        message_id: Optional message ID (auto-generated if not provided)
+        context_id: Optional context ID
+        task_id: Optional task ID
+        
+    Returns:
+        A2A Message object
+    """
+    msg_id = message_id or f"msg-{uuid.uuid4().hex[:12]}"
+    
+    return Message(
+        message_id=msg_id,
+        role=Role.AGENT,
+        parts=[TextPart(text=response)],
+        context_id=context_id,
+        task_id=task_id,
+    )
+
+
+def create_artifact(
+    content: str,
+    artifact_id: Optional[str] = None,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+) -> Artifact:
+    """
+    Create an A2A Artifact from response content.
+    
+    Args:
+        content: Text content for the artifact
+        artifact_id: Optional artifact ID (auto-generated if not provided)
+        name: Optional artifact name
+        description: Optional artifact description
+        
+    Returns:
+        A2A Artifact object
+    """
+    art_id = artifact_id or f"art-{uuid.uuid4().hex[:12]}"
+    
+    return Artifact(
+        artifact_id=art_id,
+        name=name,
+        description=description,
+        parts=[TextPart(text=content)],
+    )
+
+
+def extract_user_input(messages: List[Message]) -> str:
+    """
+    Extract the last user input from a list of messages.
+    
+    Args:
+        messages: List of A2A Message objects
+        
+    Returns:
+        Text content of the last user message, or empty string if none
+    """
+    # Find the last user message
+    for msg in reversed(messages):
+        if msg.role == Role.USER:
+            # Combine text parts
+            content_parts = []
+            for part in msg.parts:
+                if isinstance(part, TextPart):
+                    content_parts.append(part.text)
+                elif hasattr(part, 'text'):
+                    content_parts.append(part.text)
+            return " ".join(content_parts)
+    
+    return ""

src/praisonai-agents/praisonaiagents/ui/a2a/streaming.py

@@ -0,0 +1,189 @@
+"""
+A2A Streaming Events
+
+SSE streaming support for A2A task updates.
+"""
+
+import json
+from typing import AsyncIterator, Optional
+
+from praisonaiagents.ui.a2a.types import (
+    Task,
+    TaskState,
+    TaskStatus,
+    TaskStatusUpdateEvent,
+    TaskArtifactUpdateEvent,
+    Artifact,
+    TextPart,
+)
+
+
+class A2AEventEncoder:
+    """Encode A2A events for SSE streaming."""
+    
+    @staticmethod
+    def encode_event(event_type: str, data: dict) -> str:
+        """
+        Encode an event for SSE streaming.
+        
+        Args:
+            event_type: Type of event (e.g., "task.status", "task.artifact")
+            data: Event data as dict
+            
+        Returns:
+            SSE-formatted string
+        """
+        json_data = json.dumps(data, default=str)
+        return f"event: {event_type}\ndata: {json_data}\n\n"
+    
+    @staticmethod
+    def encode_task_status(event: TaskStatusUpdateEvent) -> str:
+        """Encode TaskStatusUpdateEvent for SSE."""
+        data = event.model_dump(by_alias=True, exclude_none=True)
+        return A2AEventEncoder.encode_event("task.status", data)
+    
+    @staticmethod
+    def encode_task_artifact(event: TaskArtifactUpdateEvent) -> str:
+        """Encode TaskArtifactUpdateEvent for SSE."""
+        data = event.model_dump(by_alias=True, exclude_none=True)
+        return A2AEventEncoder.encode_event("task.artifact", data)
+    
+    @staticmethod
+    def encode_task(task: Task) -> str:
+        """Encode Task object for SSE."""
+        data = task.model_dump(by_alias=True, exclude_none=True)
+        return A2AEventEncoder.encode_event("task", data)
+    
+    @staticmethod
+    def encode_done() -> str:
+        """Encode stream completion event."""
+        return "event: done\ndata: {}\n\n"
+
+
+def create_status_event(
+    task_id: str,
+    state: TaskState,
+    context_id: Optional[str] = None,
+    final: bool = False,
+) -> TaskStatusUpdateEvent:
+    """
+    Create a TaskStatusUpdateEvent.
+    
+    Args:
+        task_id: Task ID
+        state: New task state
+        context_id: Optional context ID
+        final: Whether this is the final event
+        
+    Returns:
+        TaskStatusUpdateEvent
+    """
+    return TaskStatusUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        status=TaskStatus(state=state),
+        final=final,
+    )
+
+
+def create_artifact_event(
+    task_id: str,
+    content: str,
+    artifact_id: Optional[str] = None,
+    context_id: Optional[str] = None,
+    append: bool = False,
+    last_chunk: bool = False,
+) -> TaskArtifactUpdateEvent:
+    """
+    Create a TaskArtifactUpdateEvent.
+    
+    Args:
+        task_id: Task ID
+        content: Artifact content
+        artifact_id: Optional artifact ID
+        context_id: Optional context ID
+        append: Whether to append to existing artifact
+        last_chunk: Whether this is the last chunk
+        
+    Returns:
+        TaskArtifactUpdateEvent
+    """
+    import uuid
+    art_id = artifact_id or f"art-{uuid.uuid4().hex[:12]}"
+    
+    artifact = Artifact(
+        artifact_id=art_id,
+        parts=[TextPart(text=content)],
+    )
+    
+    return TaskArtifactUpdateEvent(
+        task_id=task_id,
+        context_id=context_id,
+        artifact=artifact,
+        append=append,
+        last_chunk=last_chunk,
+    )
+
+
+async def stream_agent_response(
+    agent,
+    user_input: str,
+    task_id: str,
+    context_id: Optional[str] = None,
+) -> AsyncIterator[str]:
+    """
+    Stream agent response as A2A events.
+    
+    Args:
+        agent: PraisonAI Agent instance
+        user_input: User input text
+        task_id: Task ID
+        context_id: Optional context ID
+        
+    Yields:
+        SSE-formatted event strings
+    """
+    encoder = A2AEventEncoder()
+    
+    # Emit working status
+    working_event = create_status_event(
+        task_id=task_id,
+        state=TaskState.WORKING,
+        context_id=context_id,
+    )
+    yield encoder.encode_task_status(working_event)
+    
+    try:
+        # Get response from agent
+        response = agent.chat(user_input)
+        
+        # Emit artifact with response
+        artifact_event = create_artifact_event(
+            task_id=task_id,
+            content=str(response),
+            context_id=context_id,
+            last_chunk=True,
+        )
+        yield encoder.encode_task_artifact(artifact_event)
+        
+        # Emit completed status
+        completed_event = create_status_event(
+            task_id=task_id,
+            state=TaskState.COMPLETED,
+            context_id=context_id,
+            final=True,
+        )
+        yield encoder.encode_task_status(completed_event)
+        
+    except Exception:
+        # Emit failed status
+        failed_event = create_status_event(
+            task_id=task_id,
+            state=TaskState.FAILED,
+            context_id=context_id,
+            final=True,
+        )
+        yield encoder.encode_task_status(failed_event)
+    
+    # Emit done
+    yield encoder.encode_done()

src/praisonai-agents/praisonaiagents/ui/a2a/task_store.py

@@ -0,0 +1,209 @@
+"""
+A2A Task Store
+
+In-memory storage for A2A Task lifecycle management.
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from praisonaiagents.ui.a2a.types import (
+    Task,
+    TaskState,
+    TaskStatus,
+    Message,
+    Artifact,
+)
+
+
+class TaskStore:
+    """
+    In-memory store for A2A Tasks.
+    
+    Manages task lifecycle including creation, status updates,
+    artifact storage, and message history.
+    """
+    
+    def __init__(self):
+        """Initialize empty task store."""
+        self._tasks: Dict[str, Task] = {}
+    
+    def create_task(self, message: Message, context_id: Optional[str] = None) -> Task:
+        """
+        Create a new task from an incoming message.
+        
+        Args:
+            message: The initial message that triggers the task
+            context_id: Optional context ID (uses message's context_id if not provided)
+            
+        Returns:
+            Newly created Task in SUBMITTED state
+        """
+        task_id = f"task-{uuid.uuid4().hex[:12]}"
+        ctx_id = context_id or message.context_id
+        
+        # Create initial status
+        status = TaskStatus(
+            state=TaskState.SUBMITTED,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+        
+        # Create task with initial message in history
+        task = Task(
+            id=task_id,
+            context_id=ctx_id,
+            status=status,
+            history=[message],
+            artifacts=None,
+        )
+        
+        self._tasks[task_id] = task
+        return task
+    
+    def get_task(self, task_id: str) -> Optional[Task]:
+        """
+        Retrieve a task by its ID.
+        
+        Args:
+            task_id: The task ID to look up
+            
+        Returns:
+            Task if found, None otherwise
+        """
+        return self._tasks.get(task_id)
+    
+    def update_status(
+        self, 
+        task_id: str, 
+        state: TaskState,
+        message: Optional[Message] = None,
+    ) -> Optional[Task]:
+        """
+        Update the status of a task.
+        
+        Args:
+            task_id: The task ID to update
+            state: New task state
+            message: Optional status message
+            
+        Returns:
+            Updated Task if found, None otherwise
+        """
+        task = self._tasks.get(task_id)
+        if not task:
+            return None
+        
+        # Create new status
+        new_status = TaskStatus(
+            state=state,
+            message=message,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+        
+        # Update task (create new instance for immutability)
+        updated = Task(
+            id=task.id,
+            context_id=task.context_id,
+            status=new_status,
+            artifacts=task.artifacts,
+            history=task.history,
+            metadata=task.metadata,
+        )
+        
+        self._tasks[task_id] = updated
+        return updated
+    
+    def add_artifact(self, task_id: str, artifact: Artifact) -> Optional[Task]:
+        """
+        Add an artifact to a task.
+        
+        Args:
+            task_id: The task ID to update
+            artifact: Artifact to add
+            
+        Returns:
+            Updated Task if found, None otherwise
+        """
+        task = self._tasks.get(task_id)
+        if not task:
+            return None
+        
+        # Get existing artifacts or create new list
+        artifacts = list(task.artifacts) if task.artifacts else []
+        artifacts.append(artifact)
+        
+        # Update task
+        updated = Task(
+            id=task.id,
+            context_id=task.context_id,
+            status=task.status,
+            artifacts=artifacts,
+            history=task.history,
+            metadata=task.metadata,
+        )
+        
+        self._tasks[task_id] = updated
+        return updated
+    
+    def add_to_history(self, task_id: str, message: Message) -> Optional[Task]:
+        """
+        Add a message to task history.
+        
+        Args:
+            task_id: The task ID to update
+            message: Message to add to history
+            
+        Returns:
+            Updated Task if found, None otherwise
+        """
+        task = self._tasks.get(task_id)
+        if not task:
+            return None
+        
+        # Get existing history or create new list
+        history = list(task.history) if task.history else []
+        history.append(message)
+        
+        # Update task
+        updated = Task(
+            id=task.id,
+            context_id=task.context_id,
+            status=task.status,
+            artifacts=task.artifacts,
+            history=history,
+            metadata=task.metadata,
+        )
+        
+        self._tasks[task_id] = updated
+        return updated
+    
+    def list_tasks(self, context_id: Optional[str] = None) -> List[Task]:
+        """
+        List all tasks, optionally filtered by context.
+        
+        Args:
+            context_id: Optional context ID to filter by
+            
+        Returns:
+            List of tasks
+        """
+        if context_id:
+            return [t for t in self._tasks.values() if t.context_id == context_id]
+        return list(self._tasks.values())
+    
+    def cancel_task(self, task_id: str) -> Optional[Task]:
+        """
+        Cancel a task.
+        
+        Args:
+            task_id: The task ID to cancel
+            
+        Returns:
+            Updated Task if found, None otherwise
+        """
+        return self.update_status(task_id, TaskState.CANCELLED)
+    
+    def clear(self):
+        """Clear all tasks from the store."""
+        self._tasks.clear()

src/praisonai-agents/praisonaiagents/ui/a2a/types.py

@@ -0,0 +1,266 @@
+"""
+A2A Protocol Types
+
+Pydantic models for the Agent2Agent (A2A) protocol.
+Based on the A2A Protocol Specification v1.0.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+class TaskState(str, Enum):
+    """
+    Defines the possible lifecycle states of a Task.
+    
+    Based on A2A Protocol Specification Section 4.1.3.
+    """
+    SUBMITTED = "submitted"
+    WORKING = "working"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    INPUT_REQUIRED = "input_required"
+    AUTH_REQUIRED = "auth_required"
+
+
+class Role(str, Enum):
+    """
+    Defines the sender of a message in A2A protocol communication.
+    
+    Based on A2A Protocol Specification Section 4.1.5.
+    """
+    USER = "user"
+    AGENT = "agent"
+
+
+# =============================================================================
+# Part Types
+# =============================================================================
+
+class TextPart(BaseModel):
+    """
+    A text content part.
+    
+    Based on A2A Protocol Specification Section 4.1.6.
+    """
+    text: str
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class FilePart(BaseModel):
+    """
+    A file content part.
+    
+    Can contain either a URI reference or inline bytes.
+    Based on A2A Protocol Specification Section 4.1.7.
+    """
+    file_uri: Optional[str] = Field(default=None, alias="fileWithUri")
+    file_bytes: Optional[bytes] = Field(default=None, alias="fileWithBytes")
+    media_type: Optional[str] = Field(default=None, alias="mediaType")
+    name: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+    
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class DataPart(BaseModel):
+    """
+    A structured data part (JSON blob).
+    
+    Based on A2A Protocol Specification Section 4.1.8.
+    """
+    data: Dict[str, Any]
+    metadata: Optional[Dict[str, Any]] = None
+
+
+# Union type for all Part types
+Part = Union[TextPart, FilePart, DataPart]
+
+
+# =============================================================================
+# Core Types
+# =============================================================================
+
+class Message(BaseModel):
+    """
+    A communication turn between client and server.
+    
+    Based on A2A Protocol Specification Section 4.1.4.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    message_id: str = Field(alias="messageId")
+    role: Role
+    parts: List[Part]
+    context_id: Optional[str] = Field(default=None, alias="contextId")
+    task_id: Optional[str] = Field(default=None, alias="taskId")
+    metadata: Optional[Dict[str, Any]] = None
+    extensions: Optional[Dict[str, str]] = None
+    reference_task_ids: Optional[List[str]] = Field(default=None, alias="referenceTaskIds")
+
+
+class TaskStatus(BaseModel):
+    """
+    Container for the status of a task.
+    
+    Based on A2A Protocol Specification Section 4.1.2.
+    """
+    state: TaskState
+    message: Optional[Message] = None
+    timestamp: Optional[str] = None
+
+
+class Artifact(BaseModel):
+    """
+    An output generated by the agent as a result of a task.
+    
+    Based on A2A Protocol Specification Section 4.1.9.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    artifact_id: str = Field(alias="artifactId")
+    name: Optional[str] = None
+    description: Optional[str] = None
+    parts: List[Part]
+    metadata: Optional[Dict[str, Any]] = None
+    extensions: Optional[Dict[str, str]] = None
+
+
+class Task(BaseModel):
+    """
+    The core unit of action for A2A.
+    
+    Based on A2A Protocol Specification Section 4.1.1.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    id: str
+    context_id: Optional[str] = Field(default=None, alias="contextId")
+    status: TaskStatus
+    artifacts: Optional[List[Artifact]] = None
+    history: Optional[List[Message]] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+# =============================================================================
+# Agent Card Types
+# =============================================================================
+
+class AgentSkill(BaseModel):
+    """
+    Describes a skill/capability of an agent.
+    
+    Based on A2A Protocol Specification Section 4.4.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    id: str
+    name: str
+    description: str
+    tags: Optional[List[str]] = None
+    examples: Optional[List[str]] = None
+    input_modes: Optional[List[str]] = Field(default=None, alias="inputModes")
+    output_modes: Optional[List[str]] = Field(default=None, alias="outputModes")
+
+
+class AgentCapabilities(BaseModel):
+    """
+    Describes the capabilities of an agent.
+    
+    Based on A2A Protocol Specification Section 4.4.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    streaming: bool = False
+    push_notifications: bool = Field(default=False, alias="pushNotifications")
+    state_transition_history: bool = Field(default=False, alias="stateTransitionHistory")
+
+
+class AgentCard(BaseModel):
+    """
+    JSON metadata document describing an agent.
+    
+    Published by an A2A Server for discovery.
+    Based on A2A Protocol Specification Section 8.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    name: str
+    url: str
+    version: str
+    description: Optional[str] = None
+    capabilities: AgentCapabilities
+    skills: Optional[List[AgentSkill]] = None
+    default_input_modes: Optional[List[str]] = Field(default=None, alias="defaultInputModes")
+    default_output_modes: Optional[List[str]] = Field(default=None, alias="defaultOutputModes")
+    provider: Optional[Dict[str, str]] = None
+    documentation_url: Optional[str] = Field(default=None, alias="documentationUrl")
+
+
+# =============================================================================
+# Request/Response Types
+# =============================================================================
+
+class MessageConfig(BaseModel):
+    """
+    Configuration for message sending.
+    
+    Based on A2A Protocol Specification Section 3.2.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    accept_content_types: Optional[List[str]] = Field(default=None, alias="acceptContentTypes")
+    blocking: Optional[bool] = None
+    history_length: Optional[int] = Field(default=None, alias="historyLength")
+
+
+class SendMessageRequest(BaseModel):
+    """
+    Request to send a message to an agent.
+    
+    Based on A2A Protocol Specification Section 3.1.1.
+    """
+    message: Message
+    configuration: Optional[MessageConfig] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+# =============================================================================
+# Streaming Event Types
+# =============================================================================
+
+class TaskStatusUpdateEvent(BaseModel):
+    """
+    Event sent by agent to notify client of task status change.
+    
+    Based on A2A Protocol Specification Section 4.2.1.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    task_id: str = Field(alias="taskId")
+    context_id: Optional[str] = Field(default=None, alias="contextId")
+    status: TaskStatus
+    final: bool = False
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class TaskArtifactUpdateEvent(BaseModel):
+    """
+    Event sent when an artifact is generated.
+    
+    Based on A2A Protocol Specification Section 4.2.2.
+    """
+    model_config = ConfigDict(populate_by_name=True)
+    
+    task_id: str = Field(alias="taskId")
+    context_id: Optional[str] = Field(default=None, alias="contextId")
+    artifact: Artifact
+    append: bool = False
+    last_chunk: bool = Field(default=False, alias="lastChunk")
+    metadata: Optional[Dict[str, Any]] = None

src/praisonai-agents/praisonaiagents/ui/agui/__init__.py

@@ -0,0 +1,22 @@
+"""
+AG-UI Protocol Integration for PraisonAI Agents
+
+This module provides AG-UI (Agent-User Interface) protocol support,
+enabling PraisonAI Agents to be exposed via a standardized streaming API
+compatible with CopilotKit and other AG-UI frontends.
+
+Usage:
+    from praisonaiagents import Agent
+    from praisonaiagents.ui.agui import AGUI
+    from fastapi import FastAPI
+
+    agent = Agent(name="Assistant", role="Helper", goal="Help users")
+    agui = AGUI(agent=agent)
+
+    app = FastAPI()
+    app.include_router(agui.get_router())
+"""
+
+from praisonaiagents.ui.agui.agui import AGUI
+
+__all__ = ["AGUI"]

src/praisonai-agents/praisonaiagents/ui/agui/agui.py

@@ -0,0 +1,203 @@
+"""
+AGUI - Main AG-UI Interface Class
+
+Exposes PraisonAI Agents via the AG-UI protocol.
+"""
+
+import logging
+import uuid
+from typing import AsyncIterator, List, Optional, TYPE_CHECKING
+
+from praisonaiagents.ui.agui.types import (
+    BaseEvent,
+    RunAgentInput,
+)
+from praisonaiagents.ui.agui.conversion import (
+    agui_messages_to_praisonai,
+    validate_state,
+    extract_user_input,
+)
+from praisonaiagents.ui.agui.streaming import (
+    create_run_error_event,
+    async_stream_agent_response,
+    async_stream_agents_response,
+)
+from praisonaiagents.ui.agui.encoder import EventEncoder
+
+if TYPE_CHECKING:
+    from praisonaiagents import Agent, PraisonAIAgents
+    from fastapi import APIRouter
+
+logger = logging.getLogger(__name__)
+
+
+class AGUI:
+    """
+    AG-UI Interface for PraisonAI Agents.
+    
+    Exposes a PraisonAI Agent or PraisonAIAgents workflow via the AG-UI protocol,
+    enabling integration with CopilotKit and other AG-UI compatible frontends.
+    
+    Usage:
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.agui import AGUI
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Assistant", role="Helper", goal="Help users")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+    
+    Args:
+        agent: Single PraisonAI Agent instance
+        agents: PraisonAIAgents instance for multi-agent workflows
+        name: Name for the AG-UI endpoint (defaults to agent name)
+        description: Description of the agent
+        prefix: URL prefix for the router (e.g., "/api/v1")
+        tags: OpenAPI tags for the router
+    """
+    
+    def __init__(
+        self,
+        agent: Optional["Agent"] = None,
+        agents: Optional["PraisonAIAgents"] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        prefix: str = "",
+        tags: Optional[List[str]] = None,
+    ):
+        if agent is None and agents is None:
+            raise ValueError("AGUI requires an agent or agents instance")
+        
+        self.agent = agent
+        self.agents = agents
+        self.prefix = prefix
+        self.tags = tags or ["AGUI"]
+        
+        # Set name from agent if not provided
+        if name:
+            self.name = name
+        elif agent and hasattr(agent, 'name'):
+            self.name = agent.name
+        elif agents and hasattr(agents, 'name'):
+            self.name = agents.name
+        else:
+            self.name = "PraisonAI Agent"
+        
+        # Set description
+        if description:
+            self.description = description
+        elif agent and hasattr(agent, 'role'):
+            self.description = agent.role
+        else:
+            self.description = "PraisonAI Agent via AG-UI"
+        
+        self._router: Optional["APIRouter"] = None
+    
+    def get_router(self) -> "APIRouter":
+        """
+        Get the FastAPI router for this AGUI instance.
+        
+        Returns:
+            FastAPI APIRouter with AG-UI endpoints
+        """
+        from fastapi import APIRouter
+        from fastapi.responses import StreamingResponse
+        
+        if self._router is not None:
+            return self._router
+        
+        self._router = APIRouter(prefix=self.prefix, tags=self.tags)
+        
+        # Attach routes
+        self._attach_routes(self._router)
+        
+        return self._router
+    
+    def _attach_routes(self, router: "APIRouter") -> None:
+        """Attach AG-UI routes to the router."""
+        from fastapi.responses import StreamingResponse
+        
+        encoder = EventEncoder()
+        
+        @router.post("/agui")
+        async def run_agent_agui(run_input: RunAgentInput):
+            """Run the agent via AG-UI protocol."""
+            async def event_generator():
+                async for event in self._run_agent(run_input):
+                    yield encoder.encode(event)
+            
+            return StreamingResponse(
+                event_generator(),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                    "Access-Control-Allow-Origin": "*",
+                    "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
+                    "Access-Control-Allow-Headers": "*",
+                },
+            )
+        
+        @router.get("/status")
+        async def get_status():
+            """Get agent status."""
+            return {"status": "available"}
+    
+    async def _run_agent(self, run_input: RunAgentInput) -> AsyncIterator[BaseEvent]:
+        """
+        Run the agent with the given input.
+        
+        Args:
+            run_input: AG-UI run input
+            
+        Yields:
+            AG-UI events
+        """
+        run_id = run_input.run_id or str(uuid.uuid4())
+        thread_id = run_input.thread_id
+        
+        try:
+            # Convert messages
+            messages = run_input.messages or []
+            
+            # Extract user input
+            user_input = extract_user_input(messages)
+            
+            # Validate state
+            session_state = validate_state(run_input.state, thread_id)
+            
+            # Get user_id from forwarded_props if available
+            user_id = None
+            if run_input.forwarded_props and isinstance(run_input.forwarded_props, dict):
+                user_id = run_input.forwarded_props.get("user_id")
+            
+            # Run appropriate handler
+            if self.agent:
+                async for event in async_stream_agent_response(
+                    agent=self.agent,
+                    user_input=user_input,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                    session_state=session_state,
+                    messages=agui_messages_to_praisonai(messages),
+                ):
+                    yield event
+            
+            elif self.agents:
+                async for event in async_stream_agents_response(
+                    agents=self.agents,
+                    user_input=user_input,
+                    thread_id=thread_id,
+                    run_id=run_id,
+                    session_state=session_state,
+                ):
+                    yield event
+            
+            else:
+                yield create_run_error_event("No agent or agents configured")
+        
+        except Exception as e:
+            logger.error(f"Error running agent: {e}", exc_info=True)
+            yield create_run_error_event(str(e))

src/praisonai-agents/praisonaiagents/ui/agui/conversion.py

@@ -0,0 +1,211 @@
+"""
+AG-UI Message Conversion
+
+Converts between AG-UI message format and PraisonAI message format.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Set
+
+from pydantic import BaseModel
+
+from praisonaiagents.ui.agui.types import Message, ToolCall, FunctionCall
+
+logger = logging.getLogger(__name__)
+
+
+def agui_messages_to_praisonai(messages: List[Message]) -> List[Dict[str, Any]]:
+    """
+    Convert AG-UI messages to PraisonAI format.
+    
+    Args:
+        messages: List of AG-UI Message objects
+        
+    Returns:
+        List of message dictionaries in PraisonAI format
+    """
+    if not messages:
+        return []
+    
+    # Track tool_call_ids that have results to avoid duplicates
+    tool_call_ids_with_results: Set[str] = set()
+    for msg in messages:
+        if msg.role == "tool" and msg.tool_call_id:
+            tool_call_ids_with_results.add(msg.tool_call_id)
+    
+    result: List[Dict[str, Any]] = []
+    seen_tool_call_ids: Set[str] = set()
+    
+    for msg in messages:
+        # Skip system messages - agent builds its own
+        if msg.role == "system":
+            continue
+        
+        if msg.role == "tool":
+            # Deduplicate tool results
+            if msg.tool_call_id in seen_tool_call_ids:
+                logger.debug(f"Skipping duplicate tool result: {msg.tool_call_id}")
+                continue
+            if msg.tool_call_id:
+                seen_tool_call_ids.add(msg.tool_call_id)
+            
+            result.append({
+                "role": "tool",
+                "content": msg.content or "",
+                "tool_call_id": msg.tool_call_id,
+            })
+        
+        elif msg.role == "assistant":
+            msg_dict: Dict[str, Any] = {
+                "role": "assistant",
+                "content": msg.content or "",
+            }
+            
+            if msg.tool_calls:
+                # Include all tool_calls (filtering only when there are results to match)
+                tool_calls_list = [
+                    {
+                        "id": tc.id,
+                        "function": {
+                            "name": tc.function.name,
+                            "arguments": tc.function.arguments,
+                        },
+                        "type": "function",
+                    }
+                    for tc in msg.tool_calls
+                ]
+                if tool_calls_list:
+                    msg_dict["tool_calls"] = tool_calls_list
+            
+            result.append(msg_dict)
+        
+        elif msg.role == "user":
+            result.append({
+                "role": "user",
+                "content": msg.content or "",
+            })
+        
+        else:
+            logger.warning(f"Unknown message role: {msg.role}")
+    
+    return result
+
+
+def praisonai_messages_to_agui(messages: List[Dict[str, Any]]) -> List[Message]:
+    """
+    Convert PraisonAI messages to AG-UI format.
+    
+    Args:
+        messages: List of message dictionaries in PraisonAI format
+        
+    Returns:
+        List of AG-UI Message objects
+    """
+    if not messages:
+        return []
+    
+    result: List[Message] = []
+    
+    for msg in messages:
+        role = msg.get("role", "user")
+        content = msg.get("content", "")
+        
+        if role == "tool":
+            result.append(Message(
+                role="tool",
+                content=content,
+                tool_call_id=msg.get("tool_call_id"),
+            ))
+        
+        elif role == "assistant":
+            tool_calls = None
+            if "tool_calls" in msg and msg["tool_calls"]:
+                tool_calls = [
+                    ToolCall(
+                        id=tc.get("id", ""),
+                        function=FunctionCall(
+                            name=tc.get("function", {}).get("name", ""),
+                            arguments=tc.get("function", {}).get("arguments", "{}"),
+                        ),
+                    )
+                    for tc in msg["tool_calls"]
+                ]
+            
+            result.append(Message(
+                role="assistant",
+                content=content,
+                tool_calls=tool_calls,
+            ))
+        
+        elif role == "user":
+            result.append(Message(
+                role="user",
+                content=content,
+            ))
+        
+        elif role == "system":
+            result.append(Message(
+                role="system",
+                content=content,
+            ))
+    
+    return result
+
+
+def validate_state(state: Any, thread_id: str) -> Optional[Dict[str, Any]]:
+    """
+    Validate and convert state to a dictionary.
+    
+    Args:
+        state: The state to validate (can be dict, Pydantic model, or other)
+        thread_id: Thread ID for logging
+        
+    Returns:
+        State as a dictionary, or None if invalid
+    """
+    if state is None:
+        return None
+    
+    if isinstance(state, dict):
+        return state
+    
+    if isinstance(state, BaseModel):
+        try:
+            return state.model_dump()
+        except Exception:
+            pass
+    
+    # Try to_dict method
+    if hasattr(state, "to_dict") and callable(getattr(state, "to_dict")):
+        try:
+            result = state.to_dict()
+            if isinstance(result, dict):
+                return result
+        except Exception:
+            pass
+    
+    logger.warning(
+        f"State must be a dict, got {type(state).__name__}. "
+        f"State will be ignored. Thread: {thread_id}"
+    )
+    return None
+
+
+def extract_user_input(messages: List[Message]) -> str:
+    """
+    Extract the last user message content.
+    
+    Args:
+        messages: List of AG-UI messages
+        
+    Returns:
+        Content of the last user message, or empty string
+    """
+    if not messages:
+        return ""
+    
+    for msg in reversed(messages):
+        if msg.role == "user" and msg.content:
+            return msg.content
+    
+    return ""

src/praisonai-agents/praisonaiagents/ui/agui/encoder.py

@@ -0,0 +1,30 @@
+"""
+AG-UI Event Encoder
+
+Encodes AG-UI events to Server-Sent Events (SSE) format.
+"""
+
+from praisonaiagents.ui.agui.types import BaseEvent
+
+
+class EventEncoder:
+    """Encodes AG-UI events to SSE format."""
+    
+    def __init__(self):
+        pass
+    
+    def get_content_type(self) -> str:
+        """Returns the content type for SSE."""
+        return "text/event-stream"
+    
+    def encode(self, event: BaseEvent) -> str:
+        """
+        Encode an event to SSE format.
+        
+        Args:
+            event: The event to encode
+            
+        Returns:
+            SSE formatted string
+        """
+        return f"data: {event.model_dump_json(by_alias=True, exclude_none=True)}\n\n"

src/praisonai-agents/praisonaiagents/ui/agui/streaming.py

@@ -0,0 +1,372 @@
+"""
+AG-UI Event Streaming
+
+Provides utilities for streaming PraisonAI agent responses as AG-UI events.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Set
+
+from praisonaiagents.ui.agui.types import (
+    BaseEvent,
+    TextMessageStartEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    ToolCallStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    RunStartedEvent,
+    RunFinishedEvent,
+    RunErrorEvent,
+    StepStartedEvent,
+    StepFinishedEvent,
+    StateSnapshotEvent,
+)
+
+
+@dataclass
+class EventBuffer:
+    """Buffer to manage event ordering constraints."""
+    
+    active_tool_call_ids: Set[str] = field(default_factory=set)
+    ended_tool_call_ids: Set[str] = field(default_factory=set)
+    current_text_message_id: str = ""
+    next_text_message_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    pending_tool_calls_parent_id: str = ""
+    
+    def start_tool_call(self, tool_call_id: str) -> None:
+        """Start a new tool call."""
+        self.active_tool_call_ids.add(tool_call_id)
+    
+    def end_tool_call(self, tool_call_id: str) -> None:
+        """End a tool call."""
+        self.active_tool_call_ids.discard(tool_call_id)
+        self.ended_tool_call_ids.add(tool_call_id)
+    
+    def start_text_message(self) -> str:
+        """Start a new text message and return its ID."""
+        self.current_text_message_id = self.next_text_message_id
+        self.next_text_message_id = str(uuid.uuid4())
+        return self.current_text_message_id
+    
+    def get_parent_message_id_for_tool_call(self) -> str:
+        """Get the message ID to use as parent for tool calls."""
+        if self.pending_tool_calls_parent_id:
+            return self.pending_tool_calls_parent_id
+        return self.current_text_message_id
+
+
+# Event Creation Functions
+
+def create_text_message_events(
+    content: str,
+    message_id: Optional[str] = None,
+    role: str = "assistant"
+) -> Iterator[BaseEvent]:
+    """
+    Create text message events for a complete message.
+    
+    Args:
+        content: The message content
+        message_id: Optional message ID (generated if not provided)
+        role: Message role (default: assistant)
+        
+    Yields:
+        TextMessageStartEvent, TextMessageContentEvent(s), TextMessageEndEvent
+    """
+    msg_id = message_id or str(uuid.uuid4())
+    
+    yield TextMessageStartEvent(message_id=msg_id, role=role)
+    
+    if content:
+        yield TextMessageContentEvent(message_id=msg_id, delta=content)
+    
+    yield TextMessageEndEvent(message_id=msg_id)
+
+
+def stream_text_chunks(
+    chunks: Iterator[str],
+    message_id: Optional[str] = None,
+    role: str = "assistant"
+) -> Iterator[BaseEvent]:
+    """
+    Stream text chunks as AG-UI events.
+    
+    Args:
+        chunks: Iterator of text chunks
+        message_id: Optional message ID
+        role: Message role
+        
+    Yields:
+        AG-UI events for the text stream
+    """
+    msg_id = message_id or str(uuid.uuid4())
+    
+    yield TextMessageStartEvent(message_id=msg_id, role=role)
+    
+    for chunk in chunks:
+        if chunk:
+            yield TextMessageContentEvent(message_id=msg_id, delta=chunk)
+    
+    yield TextMessageEndEvent(message_id=msg_id)
+
+
+def create_tool_call_events(
+    tool_call_id: str,
+    tool_name: str,
+    arguments: str,
+    parent_message_id: Optional[str] = None
+) -> Iterator[BaseEvent]:
+    """
+    Create tool call events.
+    
+    Args:
+        tool_call_id: Unique ID for the tool call
+        tool_name: Name of the tool being called
+        arguments: JSON string of arguments
+        parent_message_id: Optional parent message ID
+        
+    Yields:
+        ToolCallStartEvent, ToolCallArgsEvent, ToolCallEndEvent
+    """
+    yield ToolCallStartEvent(
+        tool_call_id=tool_call_id,
+        tool_call_name=tool_name,
+        parent_message_id=parent_message_id
+    )
+    
+    yield ToolCallArgsEvent(
+        tool_call_id=tool_call_id,
+        delta=arguments
+    )
+    
+    yield ToolCallEndEvent(tool_call_id=tool_call_id)
+
+
+def create_tool_result_event(
+    tool_call_id: str,
+    content: str,
+    message_id: Optional[str] = None
+) -> ToolCallResultEvent:
+    """
+    Create a tool result event.
+    
+    Args:
+        tool_call_id: ID of the tool call this is a result for
+        content: Result content
+        message_id: Optional message ID
+        
+    Returns:
+        ToolCallResultEvent
+    """
+    return ToolCallResultEvent(
+        message_id=message_id or str(uuid.uuid4()),
+        tool_call_id=tool_call_id,
+        content=content
+    )
+
+
+# Run Lifecycle Events
+
+def create_run_started_event(thread_id: str, run_id: str) -> RunStartedEvent:
+    """Create a run started event."""
+    return RunStartedEvent(thread_id=thread_id, run_id=run_id)
+
+
+def create_run_finished_event(
+    thread_id: str,
+    run_id: str,
+    result: Optional[Any] = None
+) -> RunFinishedEvent:
+    """Create a run finished event."""
+    return RunFinishedEvent(thread_id=thread_id, run_id=run_id, result=result)
+
+
+def create_run_error_event(
+    message: str,
+    code: Optional[str] = None
+) -> RunErrorEvent:
+    """Create a run error event."""
+    return RunErrorEvent(message=message, code=code)
+
+
+# Step Events
+
+def create_step_started_event(step_name: str) -> StepStartedEvent:
+    """Create a step started event."""
+    return StepStartedEvent(step_name=step_name)
+
+
+def create_step_finished_event(step_name: str) -> StepFinishedEvent:
+    """Create a step finished event."""
+    return StepFinishedEvent(step_name=step_name)
+
+
+# State Events
+
+def create_state_snapshot_event(state: Dict[str, Any]) -> StateSnapshotEvent:
+    """Create a state snapshot event."""
+    return StateSnapshotEvent(snapshot=state)
+
+
+# Async Streaming
+
+async def async_stream_response(
+    response_stream: AsyncIterator[str],
+    thread_id: str,
+    run_id: str
+) -> AsyncIterator[BaseEvent]:
+    """
+    Stream an async response as AG-UI events.
+    
+    Args:
+        response_stream: Async iterator of response chunks
+        thread_id: Thread ID
+        run_id: Run ID
+        
+    Yields:
+        AG-UI events
+    """
+    # Emit run started
+    yield create_run_started_event(thread_id, run_id)
+    
+    message_id = str(uuid.uuid4())
+    message_started = False
+    
+    try:
+        async for chunk in response_stream:
+            if not message_started:
+                yield TextMessageStartEvent(message_id=message_id, role="assistant")
+                message_started = True
+            
+            if chunk:
+                yield TextMessageContentEvent(message_id=message_id, delta=chunk)
+        
+        if message_started:
+            yield TextMessageEndEvent(message_id=message_id)
+        
+        # Emit run finished
+        yield create_run_finished_event(thread_id, run_id)
+        
+    except Exception as e:
+        if message_started:
+            yield TextMessageEndEvent(message_id=message_id)
+        yield create_run_error_event(str(e))
+
+
+async def async_stream_agent_response(
+    agent,
+    user_input: str,
+    thread_id: str,
+    run_id: str,
+    session_state: Optional[Dict[str, Any]] = None,
+    messages: Optional[List[Dict[str, Any]]] = None
+) -> AsyncIterator[BaseEvent]:
+    """
+    Stream an agent's response as AG-UI events.
+    
+    Args:
+        agent: PraisonAI Agent instance
+        user_input: User input string
+        thread_id: Thread ID
+        run_id: Run ID
+        session_state: Optional session state
+        messages: Optional message history
+        
+    Yields:
+        AG-UI events
+    """
+    import asyncio
+    
+    # Emit run started
+    yield create_run_started_event(thread_id, run_id)
+    
+    message_id = str(uuid.uuid4())
+    
+    try:
+        # Check if agent has async chat method
+        if hasattr(agent, 'achat'):
+            response = await agent.achat(user_input)
+        elif hasattr(agent, 'chat'):
+            # Run sync chat in executor
+            loop = asyncio.get_event_loop()
+            response = await loop.run_in_executor(None, agent.chat, user_input)
+        else:
+            raise ValueError("Agent must have 'chat' or 'achat' method")
+        
+        # Emit text message events
+        yield TextMessageStartEvent(message_id=message_id, role="assistant")
+        
+        if response:
+            yield TextMessageContentEvent(message_id=message_id, delta=str(response))
+        
+        yield TextMessageEndEvent(message_id=message_id)
+        
+        # Emit run finished
+        yield create_run_finished_event(thread_id, run_id)
+        
+    except Exception as e:
+        yield create_run_error_event(str(e))
+
+
+async def async_stream_agents_response(
+    agents,
+    user_input: str,
+    thread_id: str,
+    run_id: str,
+    session_state: Optional[Dict[str, Any]] = None
+) -> AsyncIterator[BaseEvent]:
+    """
+    Stream a PraisonAIAgents workflow response as AG-UI events.
+    
+    Args:
+        agents: PraisonAIAgents instance
+        user_input: User input string
+        thread_id: Thread ID
+        run_id: Run ID
+        session_state: Optional session state
+        
+    Yields:
+        AG-UI events
+    """
+    import asyncio
+    
+    # Emit run started
+    yield create_run_started_event(thread_id, run_id)
+    
+    message_id = str(uuid.uuid4())
+    
+    try:
+        # Check if agents has async start method
+        if hasattr(agents, 'astart'):
+            result = await agents.astart(user_input)
+        elif hasattr(agents, 'start'):
+            # Run sync start in executor
+            loop = asyncio.get_event_loop()
+            result = await loop.run_in_executor(None, agents.start, user_input)
+        else:
+            raise ValueError("Agents must have 'start' or 'astart' method")
+        
+        # Emit text message events with result
+        yield TextMessageStartEvent(message_id=message_id, role="assistant")
+        
+        if result:
+            # Handle different result types
+            if isinstance(result, dict):
+                content = result.get("output", str(result))
+            elif hasattr(result, "raw"):
+                content = result.raw
+            else:
+                content = str(result)
+            
+            yield TextMessageContentEvent(message_id=message_id, delta=content)
+        
+        yield TextMessageEndEvent(message_id=message_id)
+        
+        # Emit run finished
+        yield create_run_finished_event(thread_id, run_id)
+        
+    except Exception as e:
+        yield create_run_error_event(str(e))

src/praisonai-agents/praisonaiagents/ui/agui/types.py

@@ -0,0 +1,183 @@
+"""
+AG-UI Protocol Types
+
+This module defines the event types and message types for the AG-UI protocol,
+following the ag-ui-protocol specification.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, Field
+
+
+class EventType(str, Enum):
+    """AG-UI Event Types."""
+    TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
+    TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
+    TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
+    TOOL_CALL_START = "TOOL_CALL_START"
+    TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
+    TOOL_CALL_END = "TOOL_CALL_END"
+    TOOL_CALL_RESULT = "TOOL_CALL_RESULT"
+    STATE_SNAPSHOT = "STATE_SNAPSHOT"
+    STATE_DELTA = "STATE_DELTA"
+    RUN_STARTED = "RUN_STARTED"
+    RUN_FINISHED = "RUN_FINISHED"
+    RUN_ERROR = "RUN_ERROR"
+    STEP_STARTED = "STEP_STARTED"
+    STEP_FINISHED = "STEP_FINISHED"
+    CUSTOM = "CUSTOM"
+
+
+class BaseEvent(BaseModel):
+    """Base event for all AG-UI events."""
+    type: EventType
+    timestamp: Optional[int] = None
+    
+    model_config = {"use_enum_values": True}
+
+
+# Text Message Events
+class TextMessageStartEvent(BaseEvent):
+    """Event indicating the start of a text message."""
+    type: Literal["TEXT_MESSAGE_START"] = "TEXT_MESSAGE_START"
+    message_id: str
+    role: str = "assistant"
+
+
+class TextMessageContentEvent(BaseEvent):
+    """Event containing text message content."""
+    type: Literal["TEXT_MESSAGE_CONTENT"] = "TEXT_MESSAGE_CONTENT"
+    message_id: str
+    delta: str
+
+
+class TextMessageEndEvent(BaseEvent):
+    """Event indicating the end of a text message."""
+    type: Literal["TEXT_MESSAGE_END"] = "TEXT_MESSAGE_END"
+    message_id: str
+
+
+# Tool Call Events
+class ToolCallStartEvent(BaseEvent):
+    """Event indicating the start of a tool call."""
+    type: Literal["TOOL_CALL_START"] = "TOOL_CALL_START"
+    tool_call_id: str
+    tool_call_name: str
+    parent_message_id: Optional[str] = None
+
+
+class ToolCallArgsEvent(BaseEvent):
+    """Event containing tool call arguments."""
+    type: Literal["TOOL_CALL_ARGS"] = "TOOL_CALL_ARGS"
+    tool_call_id: str
+    delta: str
+
+
+class ToolCallEndEvent(BaseEvent):
+    """Event indicating the end of a tool call."""
+    type: Literal["TOOL_CALL_END"] = "TOOL_CALL_END"
+    tool_call_id: str
+
+
+class ToolCallResultEvent(BaseEvent):
+    """Event containing tool call result."""
+    type: Literal["TOOL_CALL_RESULT"] = "TOOL_CALL_RESULT"
+    message_id: str
+    tool_call_id: str
+    content: str
+    role: Optional[Literal["tool"]] = "tool"
+
+
+# Run Lifecycle Events
+class RunStartedEvent(BaseEvent):
+    """Event indicating a run has started."""
+    type: Literal["RUN_STARTED"] = "RUN_STARTED"
+    thread_id: str
+    run_id: str
+    parent_run_id: Optional[str] = None
+
+
+class RunFinishedEvent(BaseEvent):
+    """Event indicating a run has finished."""
+    type: Literal["RUN_FINISHED"] = "RUN_FINISHED"
+    thread_id: str
+    run_id: str
+    result: Optional[Any] = None
+
+
+class RunErrorEvent(BaseEvent):
+    """Event indicating a run error."""
+    type: Literal["RUN_ERROR"] = "RUN_ERROR"
+    message: str
+    code: Optional[str] = None
+
+
+# Step Events
+class StepStartedEvent(BaseEvent):
+    """Event indicating a step has started."""
+    type: Literal["STEP_STARTED"] = "STEP_STARTED"
+    step_name: str
+
+
+class StepFinishedEvent(BaseEvent):
+    """Event indicating a step has finished."""
+    type: Literal["STEP_FINISHED"] = "STEP_FINISHED"
+    step_name: str
+
+
+# State Events
+class StateSnapshotEvent(BaseEvent):
+    """Event containing a state snapshot."""
+    type: Literal["STATE_SNAPSHOT"] = "STATE_SNAPSHOT"
+    snapshot: Dict[str, Any]
+
+
+# Message Types
+class FunctionCall(BaseModel):
+    """Function call in a tool call."""
+    name: str
+    arguments: str
+
+
+class ToolCall(BaseModel):
+    """Tool call in a message."""
+    id: str
+    function: FunctionCall
+    type: str = "function"
+
+
+class Message(BaseModel):
+    """AG-UI Message type."""
+    role: Literal["user", "assistant", "system", "tool"]
+    content: Optional[str] = None
+    tool_calls: Optional[List[ToolCall]] = None
+    tool_call_id: Optional[str] = None
+    name: Optional[str] = None
+
+
+class RunAgentInput(BaseModel):
+    """Input for running an agent."""
+    thread_id: str
+    run_id: Optional[str] = None
+    messages: Optional[List[Message]] = Field(default_factory=list)
+    state: Optional[Dict[str, Any]] = None
+    forwarded_props: Optional[Dict[str, Any]] = None
+
+
+# Union type for all events
+Event = Union[
+    TextMessageStartEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    ToolCallStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    StateSnapshotEvent,
+    RunStartedEvent,
+    RunFinishedEvent,
+    RunErrorEvent,
+    StepStartedEvent,
+    StepFinishedEvent,
+]

src/praisonai-agents/praisonaiagents/workflows/workflows.py

@@ -286,6 +286,7 @@ class Workflow:
     planning_llm: Optional[str] = None  # LLM for planning
     reasoning: bool = False  # Enable chain-of-thought reasoning
     verbose: bool = False  # Enable verbose output
+    stream: bool = True  # Enable streaming responses (default True like PraisonAIAgents)
     
     # Callbacks (like process="workflow")
     on_workflow_start: Optional[Callable[['Workflow', str], None]] = None  # (workflow, input)
@@ -316,7 +317,8 @@ class Workflow:
         self,
         input: str = "",
         llm: Optional[str] = None,
-        verbose: bool = False
+        verbose: bool = False,
+        stream: bool = None
     ) -> Dict[str, Any]:
         """
         Run the workflow with the given input.
@@ -340,16 +342,22 @@ class Workflow:
             input: The input text/prompt for the workflow
             llm: LLM model to use (default: gpt-4o-mini)
             verbose: Print step outputs
+            stream: Enable streaming responses (default: use workflow's stream setting)
             
         Returns:
             Dict with 'output' (final result) and 'steps' (all step results)
         """
         # Use default LLM if not specified
         model = llm or self.default_llm or "gpt-4o-mini"
+        logger.debug(f"Workflow using model: {model} (llm={llm}, default_llm={self.default_llm})")
         
         # Use workflow verbose setting if not overridden
         verbose = verbose or self.verbose
         
+        # Use workflow stream setting if not overridden
+        if stream is None:
+            stream = self.stream
+        
         # Add input to variables
         all_variables = {**self.variables, "input": input}
         
@@ -382,7 +390,7 @@ class Workflow:
             if isinstance(step, Route):
                 # Decision-based routing
                 route_result = self._execute_route(
-                    step, previous_output, input, all_variables, model, verbose
+                    step, previous_output, input, all_variables, model, verbose, stream
                 )
                 results.extend(route_result["steps"])
                 previous_output = route_result["output"]
@@ -393,7 +401,7 @@ class Workflow:
             elif isinstance(step, Parallel):
                 # Parallel execution
                 parallel_result = self._execute_parallel(
-                    step, previous_output, input, all_variables, model, verbose
+                    step, previous_output, input, all_variables, model, verbose, stream
                 )
                 results.extend(parallel_result["steps"])
                 previous_output = parallel_result["output"]
@@ -404,7 +412,7 @@ class Workflow:
             elif isinstance(step, Loop):
                 # Loop over items
                 loop_result = self._execute_loop(
-                    step, previous_output, input, all_variables, model, verbose
+                    step, previous_output, input, all_variables, model, verbose, stream
                 )
                 results.extend(loop_result["steps"])
                 previous_output = loop_result["output"]
@@ -415,7 +423,7 @@ class Workflow:
             elif isinstance(step, Repeat):
                 # Repeat until condition
                 repeat_result = self._execute_repeat(
-                    step, previous_output, input, all_variables, model, verbose
+                    step, previous_output, input, all_variables, model, verbose, stream
                 )
                 results.extend(repeat_result["steps"])
                 previous_output = repeat_result["output"]
@@ -494,7 +502,11 @@ class Workflow:
                         for key, value in all_variables.items():
                             action = action.replace(f"{{{{{key}}}}}", str(value))
                         if previous_output:
-                            action = action.replace("{{previous_output}}", str(previous_output))
+                            if "{{previous_output}}" in action:
+                                action = action.replace("{{previous_output}}", str(previous_output))
+                            else:
+                                # Auto-append context if not explicitly referenced
+                                action = f"{action}\n\nContext from previous step:\n{previous_output}"
                         action = action.replace("{{input}}", input)
                         
                         # Add reasoning prompt if enabled
@@ -508,9 +520,9 @@ class Workflow:
                         # Handle images if present
                         step_images = getattr(step, 'images', None)
                         if step_images:
-                            output = step.agent.chat(action, images=step_images)
+                            output = step.agent.chat(action, images=step_images, stream=stream)
                         else:
-                            output = step.agent.chat(action)
+                            output = step.agent.chat(action, stream=stream)
                         
                         # Handle output_pydantic if present
                         output_pydantic = getattr(step, 'output_pydantic', None)
@@ -538,14 +550,19 @@ class Workflow:
                             llm=config.get("llm", model),
                             tools=step_tools if step_tools else None,
                             verbose=verbose,
-                            reasoning=self.reasoning
+                            reasoning=self.reasoning,
+                            stream=stream
                         )
                         # Substitute variables in action
                         action = step.action
                         for key, value in all_variables.items():
                             action = action.replace(f"{{{{{key}}}}}", str(value))
                         if previous_output:
-                            action = action.replace("{{previous_output}}", str(previous_output))
+                            if "{{previous_output}}" in action:
+                                action = action.replace("{{previous_output}}", str(previous_output))
+                            else:
+                                # Auto-append context if not explicitly referenced
+                                action = f"{action}\n\nContext from previous step:\n{previous_output}"
                         action = action.replace("{{input}}", input)
                         
                         # Add reasoning prompt if enabled
@@ -554,7 +571,8 @@ class Workflow:
                         
                         if validation_feedback:
                             action = f"{action}\n\nPrevious attempt feedback: {validation_feedback}"
-                        output = temp_agent.chat(action)
+                        
+                        output = temp_agent.chat(action, stream=stream)
                         
                 except Exception as e:
                     step_error = e
@@ -629,7 +647,7 @@ class Workflow:
             previous_output = output
             
             if verbose:
-                print(f"✅ {step.name}: {str(output)[:100]}...")
+                print(f"✅ {step.name}: {str(output)}")
             
             # Handle early stop
             if stop:
@@ -798,11 +816,16 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         elif hasattr(step, 'chat'):
             # It's an Agent - wrap with agent reference and preserve tools
             agent_tools = getattr(step, 'tools', None)
+            # Check for _yaml_action from YAML parser (canonical: action, alias: description)
+            yaml_action = getattr(step, '_yaml_action', None)
+            # Use yaml_action if set, otherwise fall back to previous_output/input
+            default_action = "{{previous_output}}" if index > 0 else "{{input}}"
+            action = yaml_action if yaml_action else default_action
             return WorkflowStep(
                 name=getattr(step, 'name', f'agent_{index+1}'),
                 agent=step,
                 tools=agent_tools,
-                action="{{previous_output}}" if index > 0 else "{{input}}"
+                action=action
             )
         elif callable(step):
             return WorkflowStep(
@@ -823,7 +846,8 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         all_variables: Dict[str, Any],
         model: str,
         verbose: bool,
-        index: int = 0
+        index: int = 0,
+        stream: bool = True
     ) -> Dict[str, Any]:
         """Execute a single step and return result."""
         normalized = self._normalize_single_step(step, index)
@@ -857,9 +881,13 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
                 for key, value in all_variables.items():
                     action = action.replace(f"{{{{{key}}}}}", str(value))
                 if previous_output:
-                    action = action.replace("{{previous_output}}", str(previous_output))
+                    if "{{previous_output}}" in action:
+                        action = action.replace("{{previous_output}}", str(previous_output))
+                    else:
+                        # Auto-append context if not explicitly referenced
+                        action = f"{action}\n\nContext from previous step:\n{previous_output}"
                 action = action.replace("{{input}}", input)
-                output = normalized.agent.chat(action)
+                output = normalized.agent.chat(action, stream=stream)
             except Exception as e:
                 output = f"Error: {e}"
         elif normalized.action:
@@ -871,19 +899,25 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
                     role=config.get("role", "Assistant"),
                     goal=config.get("goal", "Complete the task"),
                     llm=config.get("llm", model),
-                    verbose=verbose
+                    verbose=verbose,
+                    stream=stream
                 )
                 action = normalized.action
                 for key, value in all_variables.items():
                     action = action.replace(f"{{{{{key}}}}}", str(value))
                 if previous_output:
-                    action = action.replace("{{previous_output}}", str(previous_output))
-                output = temp_agent.chat(action)
+                    if "{{previous_output}}" in action:
+                        action = action.replace("{{previous_output}}", str(previous_output))
+                    else:
+                        # Auto-append context if not explicitly referenced
+                        action = f"{action}\n\nContext from previous step:\n{previous_output}"
+                
+                output = temp_agent.chat(action, stream=stream)
             except Exception as e:
                 output = f"Error: {e}"
         
         if verbose:
-            print(f"✅ {normalized.name}: {str(output)[:100]}...")
+            print(f"✅ {normalized.name}: {str(output)}")
         
         return {
             "step": normalized.name,
@@ -899,7 +933,8 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         input: str,
         all_variables: Dict[str, Any],
         model: str,
-        verbose: bool
+        verbose: bool,
+        stream: bool = True
     ) -> Dict[str, Any]:
         """Execute routing based on previous output."""
         results = []
@@ -925,7 +960,7 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         # Execute matched route steps
         for idx, step in enumerate(matched_route):
             step_result = self._execute_single_step_internal(
-                step, output, input, all_variables, model, verbose, idx
+                step, output, input, all_variables, model, verbose, idx, stream=stream
             )
             results.append({"step": step_result["step"], "output": step_result["output"]})
             output = step_result["output"]
@@ -943,7 +978,8 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         input: str,
         all_variables: Dict[str, Any],
         model: str,
-        verbose: bool
+        verbose: bool,
+        stream: bool = True
     ) -> Dict[str, Any]:
         """Execute steps in parallel (simulated with sequential for now)."""
         import concurrent.futures
@@ -960,7 +996,7 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
             for idx, step in enumerate(parallel_step.steps):
                 future = executor.submit(
                     self._execute_single_step_internal,
-                    step, previous_output, input, all_variables.copy(), model, False, idx
+                    step, previous_output, input, all_variables.copy(), model, False, idx, stream
                 )
                 futures.append((idx, future))
             
@@ -989,7 +1025,8 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         input: str,
         all_variables: Dict[str, Any],
         model: str,
-        verbose: bool
+        verbose: bool,
+        stream: bool = True
     ) -> Dict[str, Any]:
         """Execute step for each item in loop."""
         import csv
@@ -1029,7 +1066,7 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
             loop_vars["loop_index"] = idx
             
             step_result = self._execute_single_step_internal(
-                loop_step.step, previous_output, input, loop_vars, model, verbose, idx
+                loop_step.step, previous_output, input, loop_vars, model, verbose, idx, stream=stream
             )
             results.append({"step": f"{step_result['step']}_{idx}", "output": step_result["output"]})
             outputs.append(step_result["output"])
@@ -1047,7 +1084,8 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         input: str,
         all_variables: Dict[str, Any],
         model: str,
-        verbose: bool
+        verbose: bool,
+        stream: bool = True
     ) -> Dict[str, Any]:
         """Repeat step until condition is met."""
         results = []
@@ -1058,7 +1096,7 @@ Create a brief execution plan (2-3 sentences) describing how to best accomplish
         
         for iteration in range(repeat_step.max_iterations):
             step_result = self._execute_single_step_internal(
-                repeat_step.step, output, input, all_variables, model, verbose, iteration
+                repeat_step.step, output, input, all_variables, model, verbose, iteration, stream=stream
             )
             results.append({"step": f"{step_result['step']}_{iteration}", "output": step_result["output"]})
             output = step_result["output"]

src/praisonai-agents/praisonaiagents/workflows/yaml_parser.py

@@ -102,7 +102,112 @@ class YAMLWorkflowParser:
             Workflow object ready for execution
         """
         data = yaml.safe_load(yaml_content)
-        return self._parse_workflow_data(data)
+        # Normalize to canonical format (accept both old and new field names)
+        normalized_data = self._normalize_yaml_config(data)
+        return self._parse_workflow_data(normalized_data)
+    
+    def _normalize_yaml_config(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Normalize YAML config to canonical format.
+        
+        Accepts both old (agents.yaml) and new (workflow.yaml) field names.
+        This implements "Accept liberally, suggest canonically" principle.
+        
+        Canonical names (preferred):
+        - agents (not roles)
+        - instructions (not backstory)  
+        - action (not description)
+        - steps (not tasks)
+        - name (not topic)
+        
+        Args:
+            data: Raw parsed YAML data
+            
+        Returns:
+            Normalized data with canonical field names
+        """
+        if not data:
+            return data
+            
+        normalized = data.copy()
+        
+        # 1. Normalize workflow name: topic -> name (only if topic is used as name, not as input)
+        # Note: 'topic' is legacy, 'input' is canonical for workflow input data
+        if 'topic' in normalized and 'name' not in normalized and 'input' not in normalized:
+            # Legacy behavior: topic was used as both name and input
+            normalized['name'] = normalized.get('topic', 'Unnamed Workflow')
+        
+        # 2. Normalize workflow input: 'input' is canonical, 'topic' is alias
+        # Priority: input > topic (input takes precedence if both exist)
+        if 'input' not in normalized and 'topic' in normalized:
+            normalized['input'] = normalized['topic']
+        
+        # 3. Normalize container: roles -> agents
+        # Note: _convert_roles_to_agents handles backstory -> instructions
+        if 'roles' in normalized and 'agents' not in normalized:
+            normalized['agents'] = self._convert_roles_to_agents(normalized['roles'])
+            # Extract steps from tasks nested in roles if no steps defined
+            if 'steps' not in normalized:
+                normalized['steps'] = self._extract_steps_from_roles(normalized['roles'])
+        
+        # 4. Normalize agent fields: backstory -> instructions (for agents section)
+        if 'agents' in normalized:
+            for agent_id, agent_config in normalized['agents'].items():
+                if isinstance(agent_config, dict):
+                    # backstory -> instructions
+                    if 'backstory' in agent_config and 'instructions' not in agent_config:
+                        agent_config['instructions'] = agent_config['backstory']
+        
+        # 5. Normalize step fields: description -> action
+        if 'steps' in normalized:
+            for step in normalized['steps']:
+                if isinstance(step, dict):
+                    # description -> action
+                    if 'description' in step and 'action' not in step:
+                        step['action'] = step['description']
+                    
+                    # Handle parallel steps
+                    if 'parallel' in step:
+                        for parallel_step in step['parallel']:
+                            if isinstance(parallel_step, dict):
+                                if 'description' in parallel_step and 'action' not in parallel_step:
+                                    parallel_step['action'] = parallel_step['description']
+        
+        return normalized
+    
+    def _extract_steps_from_roles(self, roles: Dict[str, Dict]) -> List[Dict]:
+        """
+        Extract steps from tasks nested within roles (agents.yaml format).
+        
+        Args:
+            roles: The roles section from agents.yaml
+            
+        Returns:
+            List of step definitions
+        """
+        steps = []
+        for role_id, role_config in roles.items():
+            if 'tasks' in role_config:
+                for task_id, task_config in role_config['tasks'].items():
+                    step = {
+                        'name': task_id,
+                        'agent': role_id,
+                    }
+                    # description -> action
+                    if 'description' in task_config:
+                        step['action'] = task_config['description']
+                    elif 'action' in task_config:
+                        step['action'] = task_config['action']
+                    
+                    # Copy other task fields
+                    for field in ['expected_output', 'context', 'output_file', 
+                                  'output_json', 'create_directory', 'callback',
+                                  'async_execution', 'guardrail', 'max_retries']:
+                        if field in task_config:
+                            step[field] = task_config[field]
+                    
+                    steps.append(step)
+        return steps
     
     def _parse_workflow_data(self, data: Dict[str, Any]) -> Workflow:
         """
@@ -127,6 +232,7 @@ class YAMLWorkflowParser:
         workflow_config = data.get('workflow', {})
         planning = workflow_config.get('planning', False)
         planning_llm = workflow_config.get('planning_llm')
+        default_llm = workflow_config.get('default_llm')
         reasoning = workflow_config.get('reasoning', False)
         verbose = workflow_config.get('verbose', False)
         memory_config = workflow_config.get('memory_config')
@@ -156,6 +262,7 @@ class YAMLWorkflowParser:
             variables=variables,
             planning=planning,
             planning_llm=planning_llm,
+            default_llm=default_llm,
             reasoning=reasoning,
             verbose=verbose,
             memory_config=memory_config,
@@ -170,6 +277,10 @@ class YAMLWorkflowParser:
         workflow.process = process
         workflow.manager_llm = manager_llm
         
+        # Store workflow input (from 'input' or 'topic' field)
+        # This is the default input passed to workflow.start() if no input is provided
+        workflow.default_input = data.get('input', data.get('topic', ''))
+        
         return workflow
     
     def _convert_roles_to_agents(self, roles: Dict[str, Dict]) -> Dict[str, Dict]:

src/praisonai-agents/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.1.4"
+version = "0.1.16"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
+readme = "README.md"
 requires-python = ">=3.10"
 authors = [
     { name="Mervin Praison" }

src/praisonai-agents/tests/a2a/__init__.py

@@ -0,0 +1 @@
+"""A2A Protocol Tests"""

src/praisonai-agents/tests/a2a/test_a2a.py

@@ -0,0 +1,135 @@
+"""
+Tests for Main A2A Class
+
+TDD: Write tests first, then implement A2A class.
+"""
+
+
+class TestA2AClass:
+    """Tests for A2A main class."""
+    
+    def test_a2a_creation_with_agent(self):
+        """Test creating A2A with single agent."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent)
+        
+        assert a2a.agent is not None
+        assert a2a.name == "Test"
+    
+    def test_a2a_creation_with_custom_name(self):
+        """Test creating A2A with custom name."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent, name="Custom Name")
+        
+        assert a2a.name == "Custom Name"
+    
+    def test_a2a_requires_agent(self):
+        """Test A2A requires agent or agents."""
+        from praisonaiagents.ui.a2a import A2A
+        import pytest
+        
+        with pytest.raises(ValueError):
+            A2A()
+    
+    def test_a2a_get_agent_card(self):
+        """Test getting Agent Card from A2A."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Card Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+        
+        card = a2a.get_agent_card()
+        
+        assert card.name == "Card Test"
+        assert card.url == "http://localhost:8000/a2a"
+    
+    def test_a2a_get_router(self):
+        """Test getting FastAPI router from A2A."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Router Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent)
+        
+        router = a2a.get_router()
+        
+        assert router is not None
+        # Check router has routes
+        assert len(router.routes) > 0
+
+
+class TestA2ARouter:
+    """Tests for A2A FastAPI router endpoints."""
+    
+    def test_agent_card_endpoint(self):
+        """Test /.well-known/agent.json endpoint."""
+        from fastapi.testclient import TestClient
+        from fastapi import FastAPI
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Endpoint Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+        
+        app = FastAPI()
+        app.include_router(a2a.get_router())
+        
+        client = TestClient(app)
+        response = client.get("/.well-known/agent.json")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["name"] == "Endpoint Test"
+    
+    def test_status_endpoint(self):
+        """Test /status endpoint."""
+        from fastapi.testclient import TestClient
+        from fastapi import FastAPI
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        agent = Agent(name="Status Test", role="Tester", goal="Test")
+        a2a = A2A(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(a2a.get_router())
+        
+        client = TestClient(app)
+        response = client.get("/status")
+        
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "ok"
+
+
+class TestA2AWithTools:
+    """Tests for A2A with agent tools."""
+    
+    def test_a2a_agent_card_includes_skills(self):
+        """Test Agent Card includes skills from tools."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a import A2A
+        
+        def my_tool(x: str) -> str:
+            """A test tool."""
+            return x
+        
+        agent = Agent(
+            name="Tool Agent",
+            role="Helper",
+            goal="Help",
+            tools=[my_tool]
+        )
+        a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+        
+        card = a2a.get_agent_card()
+        
+        assert card.skills is not None
+        assert len(card.skills) >= 1

src/praisonai-agents/tests/a2a/test_agent_card.py

@@ -0,0 +1,200 @@
+"""
+Tests for A2A Agent Card Generation
+
+TDD: Write tests first, then implement agent_card module.
+"""
+
+import json
+
+
+class TestAgentCardGeneration:
+    """Tests for generating Agent Card from PraisonAI Agent."""
+    
+    def test_generate_agent_card_basic(self):
+        """Test generating Agent Card from basic Agent."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(
+            name="Test Agent",
+            role="Test Role",
+            goal="Test Goal"
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        assert card.name == "Test Agent"
+        assert card.url == "http://localhost:8000/a2a"
+        assert card.version == "1.0.0"
+    
+    def test_generate_agent_card_with_description(self):
+        """Test Agent Card includes description from role."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(
+            name="Research Agent",
+            role="Research Analyst",
+            goal="Research topics thoroughly"
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        assert card.description is not None
+        assert "Research" in card.description
+    
+    def test_generate_agent_card_with_instructions(self):
+        """Test Agent Card from Agent with instructions."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(
+            instructions="You are a helpful assistant that answers questions."
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        assert card.name is not None
+        assert card.description is not None
+    
+    def test_generate_agent_card_capabilities(self):
+        """Test Agent Card has correct capabilities."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        
+        card = generate_agent_card(
+            agent, 
+            url="http://localhost:8000/a2a",
+            streaming=True
+        )
+        
+        assert card.capabilities.streaming is True
+
+
+class TestSkillsExtraction:
+    """Tests for extracting skills from Agent tools."""
+    
+    def test_extract_skills_from_function(self):
+        """Test extracting skill from a function tool."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        def search_web(query: str) -> str:
+            """Search the web for information."""
+            return f"Results for: {query}"
+        
+        agent = Agent(
+            name="Search Agent",
+            role="Searcher",
+            goal="Search the web",
+            tools=[search_web]
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        assert card.skills is not None
+        assert len(card.skills) >= 1
+        
+        skill_names = [s.name for s in card.skills]
+        assert "search_web" in skill_names
+    
+    def test_extract_skills_with_description(self):
+        """Test skill description comes from function docstring."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        def calculate(expression: str) -> str:
+            """Calculate a mathematical expression."""
+            return str(eval(expression))
+        
+        agent = Agent(
+            name="Calculator",
+            role="Math Helper",
+            goal="Do math",
+            tools=[calculate]
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        calc_skill = next((s for s in card.skills if s.name == "calculate"), None)
+        assert calc_skill is not None
+        assert "mathematical" in calc_skill.description.lower()
+    
+    def test_extract_skills_multiple_tools(self):
+        """Test extracting skills from multiple tools."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        def tool_one(x: str) -> str:
+            """First tool."""
+            return x
+        
+        def tool_two(y: str) -> str:
+            """Second tool."""
+            return y
+        
+        agent = Agent(
+            name="Multi Tool Agent",
+            role="Helper",
+            goal="Help",
+            tools=[tool_one, tool_two]
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        assert len(card.skills) >= 2
+    
+    def test_no_skills_when_no_tools(self):
+        """Test Agent Card with no tools has empty skills."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(
+            name="Simple Agent",
+            role="Helper",
+            goal="Help"
+        )
+        
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        # Skills should be None or empty list
+        assert card.skills is None or len(card.skills) == 0
+
+
+class TestAgentCardSerialization:
+    """Tests for Agent Card JSON serialization."""
+    
+    def test_agent_card_to_json(self):
+        """Test Agent Card can be serialized to JSON."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        card = generate_agent_card(agent, url="http://localhost:8000/a2a")
+        
+        json_str = card.model_dump_json()
+        data = json.loads(json_str)
+        
+        assert "name" in data
+        assert "url" in data
+        assert "capabilities" in data
+    
+    def test_agent_card_camel_case_keys(self):
+        """Test Agent Card JSON uses camelCase keys."""
+        from praisonaiagents import Agent
+        from praisonaiagents.ui.a2a.agent_card import generate_agent_card
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        card = generate_agent_card(
+            agent, 
+            url="http://localhost:8000/a2a",
+            streaming=True
+        )
+        
+        # Use by_alias to get camelCase
+        data = card.model_dump(by_alias=True)
+        
+        # Check capabilities uses camelCase
+        assert "pushNotifications" in data["capabilities"]

src/praisonai-agents/tests/a2a/test_conversion.py

@@ -0,0 +1,190 @@
+"""
+Tests for A2A Message Conversion
+
+TDD: Write tests first, then implement conversion module.
+"""
+
+
+class TestA2AToPraisonAI:
+    """Tests for converting A2A messages to PraisonAI format."""
+    
+    def test_convert_user_message(self):
+        """Test converting A2A user message to PraisonAI format."""
+        from praisonaiagents.ui.a2a.conversion import a2a_to_praisonai_messages
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        a2a_msg = Message(
+            message_id="msg-1",
+            role=Role.USER,
+            parts=[TextPart(text="Hello, how are you?")]
+        )
+        
+        result = a2a_to_praisonai_messages([a2a_msg])
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "user"
+        assert result[0]["content"] == "Hello, how are you?"
+    
+    def test_convert_agent_message(self):
+        """Test converting A2A agent message to PraisonAI format."""
+        from praisonaiagents.ui.a2a.conversion import a2a_to_praisonai_messages
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        a2a_msg = Message(
+            message_id="msg-2",
+            role=Role.AGENT,
+            parts=[TextPart(text="I'm doing well, thanks!")]
+        )
+        
+        result = a2a_to_praisonai_messages([a2a_msg])
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "assistant"
+        assert result[0]["content"] == "I'm doing well, thanks!"
+    
+    def test_convert_multiple_parts(self):
+        """Test converting message with multiple text parts."""
+        from praisonaiagents.ui.a2a.conversion import a2a_to_praisonai_messages
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        a2a_msg = Message(
+            message_id="msg-3",
+            role=Role.USER,
+            parts=[
+                TextPart(text="First part."),
+                TextPart(text="Second part.")
+            ]
+        )
+        
+        result = a2a_to_praisonai_messages([a2a_msg])
+        
+        assert "First part" in result[0]["content"]
+        assert "Second part" in result[0]["content"]
+    
+    def test_convert_conversation_history(self):
+        """Test converting full conversation history."""
+        from praisonaiagents.ui.a2a.conversion import a2a_to_praisonai_messages
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        messages = [
+            Message(message_id="m1", role=Role.USER, parts=[TextPart(text="Hi")]),
+            Message(message_id="m2", role=Role.AGENT, parts=[TextPart(text="Hello!")]),
+            Message(message_id="m3", role=Role.USER, parts=[TextPart(text="How are you?")]),
+        ]
+        
+        result = a2a_to_praisonai_messages(messages)
+        
+        assert len(result) == 3
+        assert result[0]["role"] == "user"
+        assert result[1]["role"] == "assistant"
+        assert result[2]["role"] == "user"
+
+
+class TestPraisonAIToA2A:
+    """Tests for converting PraisonAI responses to A2A format."""
+    
+    def test_convert_string_response(self):
+        """Test converting string response to A2A Message."""
+        from praisonaiagents.ui.a2a.conversion import praisonai_to_a2a_message
+        
+        response = "This is the agent's response."
+        
+        result = praisonai_to_a2a_message(response)
+        
+        assert result.role.value == "agent"
+        assert len(result.parts) == 1
+        assert result.parts[0].text == response
+    
+    def test_convert_response_with_context(self):
+        """Test converting response with context_id."""
+        from praisonaiagents.ui.a2a.conversion import praisonai_to_a2a_message
+        
+        response = "Response text"
+        
+        result = praisonai_to_a2a_message(response, context_id="ctx-123")
+        
+        assert result.context_id == "ctx-123"
+    
+    def test_convert_response_with_task(self):
+        """Test converting response with task_id."""
+        from praisonaiagents.ui.a2a.conversion import praisonai_to_a2a_message
+        
+        response = "Response text"
+        
+        result = praisonai_to_a2a_message(response, task_id="task-456")
+        
+        assert result.task_id == "task-456"
+
+
+class TestArtifactConversion:
+    """Tests for converting responses to A2A Artifacts."""
+    
+    def test_create_artifact_from_response(self):
+        """Test creating Artifact from response."""
+        from praisonaiagents.ui.a2a.conversion import create_artifact
+        
+        response = "Generated content here."
+        
+        artifact = create_artifact(response)
+        
+        assert artifact.artifact_id is not None
+        assert len(artifact.parts) == 1
+        assert artifact.parts[0].text == response
+    
+    def test_create_artifact_with_name(self):
+        """Test creating Artifact with name."""
+        from praisonaiagents.ui.a2a.conversion import create_artifact
+        
+        response = "Report content"
+        
+        artifact = create_artifact(response, name="Report", description="Generated report")
+        
+        assert artifact.name == "Report"
+        assert artifact.description == "Generated report"
+
+
+class TestExtractUserInput:
+    """Tests for extracting user input from A2A messages."""
+    
+    def test_extract_from_single_message(self):
+        """Test extracting user input from single message."""
+        from praisonaiagents.ui.a2a.conversion import extract_user_input
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        msg = Message(
+            message_id="m1",
+            role=Role.USER,
+            parts=[TextPart(text="What is AI?")]
+        )
+        
+        result = extract_user_input([msg])
+        
+        assert result == "What is AI?"
+    
+    def test_extract_from_conversation(self):
+        """Test extracting last user input from conversation."""
+        from praisonaiagents.ui.a2a.conversion import extract_user_input
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        messages = [
+            Message(message_id="m1", role=Role.USER, parts=[TextPart(text="First question")]),
+            Message(message_id="m2", role=Role.AGENT, parts=[TextPart(text="Answer")]),
+            Message(message_id="m3", role=Role.USER, parts=[TextPart(text="Follow up question")]),
+        ]
+        
+        result = extract_user_input(messages)
+        
+        assert result == "Follow up question"
+    
+    def test_extract_empty_when_no_user_message(self):
+        """Test extracting returns empty when no user message."""
+        from praisonaiagents.ui.a2a.conversion import extract_user_input
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        messages = [
+            Message(message_id="m1", role=Role.AGENT, parts=[TextPart(text="Hello")]),
+        ]
+        
+        result = extract_user_input(messages)
+        
+        assert result == ""

src/praisonai-agents/tests/a2a/test_streaming.py

@@ -0,0 +1,116 @@
+"""
+Tests for A2A Streaming Events
+"""
+
+
+class TestA2AEventEncoder:
+    """Tests for A2AEventEncoder."""
+    
+    def test_encode_event(self):
+        """Test encoding a generic event."""
+        from praisonaiagents.ui.a2a.streaming import A2AEventEncoder
+        
+        result = A2AEventEncoder.encode_event("test", {"key": "value"})
+        
+        assert "event: test" in result
+        assert "data:" in result
+        assert "key" in result
+    
+    def test_encode_task_status(self):
+        """Test encoding TaskStatusUpdateEvent."""
+        from praisonaiagents.ui.a2a.streaming import A2AEventEncoder
+        from praisonaiagents.ui.a2a.types import TaskStatusUpdateEvent, TaskStatus, TaskState
+        
+        event = TaskStatusUpdateEvent(
+            task_id="task-123",
+            status=TaskStatus(state=TaskState.WORKING),
+            final=False,
+        )
+        
+        result = A2AEventEncoder.encode_task_status(event)
+        
+        assert "event: task.status" in result
+        assert "task-123" in result
+    
+    def test_encode_task_artifact(self):
+        """Test encoding TaskArtifactUpdateEvent."""
+        from praisonaiagents.ui.a2a.streaming import A2AEventEncoder
+        from praisonaiagents.ui.a2a.types import TaskArtifactUpdateEvent, Artifact, TextPart
+        
+        artifact = Artifact(
+            artifact_id="art-1",
+            parts=[TextPart(text="Result")]
+        )
+        event = TaskArtifactUpdateEvent(
+            task_id="task-456",
+            artifact=artifact,
+            last_chunk=True,
+        )
+        
+        result = A2AEventEncoder.encode_task_artifact(event)
+        
+        assert "event: task.artifact" in result
+        assert "art-1" in result
+    
+    def test_encode_done(self):
+        """Test encoding done event."""
+        from praisonaiagents.ui.a2a.streaming import A2AEventEncoder
+        
+        result = A2AEventEncoder.encode_done()
+        
+        assert "event: done" in result
+
+
+class TestCreateEvents:
+    """Tests for event creation helpers."""
+    
+    def test_create_status_event(self):
+        """Test creating status event."""
+        from praisonaiagents.ui.a2a.streaming import create_status_event
+        from praisonaiagents.ui.a2a.types import TaskState
+        
+        event = create_status_event(
+            task_id="task-1",
+            state=TaskState.WORKING,
+        )
+        
+        assert event.task_id == "task-1"
+        assert event.status.state == TaskState.WORKING
+    
+    def test_create_status_event_final(self):
+        """Test creating final status event."""
+        from praisonaiagents.ui.a2a.streaming import create_status_event
+        from praisonaiagents.ui.a2a.types import TaskState
+        
+        event = create_status_event(
+            task_id="task-2",
+            state=TaskState.COMPLETED,
+            final=True,
+        )
+        
+        assert event.final is True
+    
+    def test_create_artifact_event(self):
+        """Test creating artifact event."""
+        from praisonaiagents.ui.a2a.streaming import create_artifact_event
+        
+        event = create_artifact_event(
+            task_id="task-3",
+            content="Generated content",
+        )
+        
+        assert event.task_id == "task-3"
+        assert event.artifact is not None
+        assert len(event.artifact.parts) == 1
+    
+    def test_create_artifact_event_last_chunk(self):
+        """Test creating last chunk artifact event."""
+        from praisonaiagents.ui.a2a.streaming import create_artifact_event
+        
+        event = create_artifact_event(
+            task_id="task-4",
+            content="Final content",
+            last_chunk=True,
+        )
+        
+        assert event.last_chunk is True

src/praisonai-agents/tests/a2a/test_task_store.py

@@ -0,0 +1,225 @@
+"""
+Tests for A2A Task Store
+
+TDD: Write tests first, then implement task_store module.
+"""
+
+
+class TestTaskStore:
+    """Tests for TaskStore class."""
+    
+    def test_create_task(self):
+        """Test creating a new task."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart, TaskState
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-1",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        task = store.create_task(msg)
+        
+        assert task.id is not None
+        assert task.status.state == TaskState.SUBMITTED
+    
+    def test_create_task_with_context(self):
+        """Test creating task with context_id."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-2",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")],
+            context_id="ctx-123"
+        )
+        
+        task = store.create_task(msg)
+        
+        assert task.context_id == "ctx-123"
+    
+    def test_get_task(self):
+        """Test retrieving a task by ID."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-3",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        created = store.create_task(msg)
+        retrieved = store.get_task(created.id)
+        
+        assert retrieved is not None
+        assert retrieved.id == created.id
+    
+    def test_get_task_not_found(self):
+        """Test getting non-existent task returns None."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        
+        store = TaskStore()
+        result = store.get_task("non-existent-id")
+        
+        assert result is None
+    
+    def test_update_status(self):
+        """Test updating task status."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart, TaskState
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-4",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        task = store.create_task(msg)
+        updated = store.update_status(task.id, TaskState.WORKING)
+        
+        assert updated.status.state == TaskState.WORKING
+    
+    def test_update_status_to_completed(self):
+        """Test updating task to completed state."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart, TaskState
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-5",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        task = store.create_task(msg)
+        store.update_status(task.id, TaskState.WORKING)
+        updated = store.update_status(task.id, TaskState.COMPLETED)
+        
+        assert updated.status.state == TaskState.COMPLETED
+    
+    def test_add_artifact(self):
+        """Test adding artifact to task."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart, Artifact
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-6",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        task = store.create_task(msg)
+        artifact = Artifact(
+            artifact_id="art-1",
+            parts=[TextPart(text="Result")]
+        )
+        
+        updated = store.add_artifact(task.id, artifact)
+        
+        assert updated.artifacts is not None
+        assert len(updated.artifacts) == 1
+    
+    def test_add_message_to_history(self):
+        """Test adding message to task history."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        store = TaskStore()
+        msg1 = Message(
+            message_id="msg-7",
+            role=Role.USER,
+            parts=[TextPart(text="Question")]
+        )
+        
+        task = store.create_task(msg1)
+        
+        msg2 = Message(
+            message_id="msg-8",
+            role=Role.AGENT,
+            parts=[TextPart(text="Answer")]
+        )
+        
+        updated = store.add_to_history(task.id, msg2)
+        
+        assert updated.history is not None
+        assert len(updated.history) >= 1
+    
+    def test_list_tasks(self):
+        """Test listing all tasks."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        store = TaskStore()
+        
+        for i in range(3):
+            msg = Message(
+                message_id=f"msg-{i}",
+                role=Role.USER,
+                parts=[TextPart(text=f"Message {i}")]
+            )
+            store.create_task(msg)
+        
+        tasks = store.list_tasks()
+        
+        assert len(tasks) == 3
+    
+    def test_cancel_task(self):
+        """Test cancelling a task."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart, TaskState
+        
+        store = TaskStore()
+        msg = Message(
+            message_id="msg-cancel",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        
+        task = store.create_task(msg)
+        cancelled = store.cancel_task(task.id)
+        
+        assert cancelled.status.state == TaskState.CANCELLED
+
+
+class TestTaskStoreContextManagement:
+    """Tests for context management in TaskStore."""
+    
+    def test_tasks_grouped_by_context(self):
+        """Test getting tasks by context_id."""
+        from praisonaiagents.ui.a2a.task_store import TaskStore
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        
+        store = TaskStore()
+        
+        # Create tasks in context A
+        for i in range(2):
+            msg = Message(
+                message_id=f"msg-a-{i}",
+                role=Role.USER,
+                parts=[TextPart(text=f"A{i}")],
+                context_id="context-a"
+            )
+            store.create_task(msg)
+        
+        # Create task in context B
+        msg_b = Message(
+            message_id="msg-b-1",
+            role=Role.USER,
+            parts=[TextPart(text="B1")],
+            context_id="context-b"
+        )
+        store.create_task(msg_b)
+        
+        tasks_a = store.list_tasks(context_id="context-a")
+        tasks_b = store.list_tasks(context_id="context-b")
+        
+        assert len(tasks_a) == 2
+        assert len(tasks_b) == 1

src/praisonai-agents/tests/a2a/test_types.py

@@ -0,0 +1,395 @@
+"""
+Tests for A2A Protocol Types
+
+TDD: Write tests first, then implement types.
+"""
+
+import json
+from datetime import datetime
+
+
+class TestTaskState:
+    """Tests for TaskState enum."""
+    
+    def test_task_state_submitted(self):
+        """Test SUBMITTED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.SUBMITTED == "submitted"
+    
+    def test_task_state_working(self):
+        """Test WORKING state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.WORKING == "working"
+    
+    def test_task_state_completed(self):
+        """Test COMPLETED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.COMPLETED == "completed"
+    
+    def test_task_state_failed(self):
+        """Test FAILED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.FAILED == "failed"
+    
+    def test_task_state_cancelled(self):
+        """Test CANCELLED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.CANCELLED == "cancelled"
+    
+    def test_task_state_input_required(self):
+        """Test INPUT_REQUIRED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.INPUT_REQUIRED == "input_required"
+    
+    def test_task_state_auth_required(self):
+        """Test AUTH_REQUIRED state exists."""
+        from praisonaiagents.ui.a2a.types import TaskState
+        assert TaskState.AUTH_REQUIRED == "auth_required"
+
+
+class TestRole:
+    """Tests for Role enum."""
+    
+    def test_role_user(self):
+        """Test USER role exists."""
+        from praisonaiagents.ui.a2a.types import Role
+        assert Role.USER == "user"
+    
+    def test_role_agent(self):
+        """Test AGENT role exists."""
+        from praisonaiagents.ui.a2a.types import Role
+        assert Role.AGENT == "agent"
+
+
+class TestPart:
+    """Tests for Part models."""
+    
+    def test_text_part_creation(self):
+        """Test TextPart can be created."""
+        from praisonaiagents.ui.a2a.types import TextPart
+        part = TextPart(text="Hello, world!")
+        assert part.text == "Hello, world!"
+    
+    def test_file_part_with_uri(self):
+        """Test FilePart with URI."""
+        from praisonaiagents.ui.a2a.types import FilePart
+        part = FilePart(
+            file_uri="https://example.com/file.pdf",
+            media_type="application/pdf",
+            name="document.pdf"
+        )
+        assert part.file_uri == "https://example.com/file.pdf"
+        assert part.media_type == "application/pdf"
+    
+    def test_file_part_with_bytes(self):
+        """Test FilePart with bytes."""
+        from praisonaiagents.ui.a2a.types import FilePart
+        part = FilePart(
+            file_bytes=b"file content",
+            media_type="text/plain",
+            name="test.txt"
+        )
+        assert part.file_bytes == b"file content"
+    
+    def test_data_part_creation(self):
+        """Test DataPart can be created."""
+        from praisonaiagents.ui.a2a.types import DataPart
+        part = DataPart(data={"key": "value", "count": 42})
+        assert part.data == {"key": "value", "count": 42}
+
+
+class TestMessage:
+    """Tests for Message model."""
+    
+    def test_message_creation(self):
+        """Test Message can be created."""
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        msg = Message(
+            message_id="msg-123",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        assert msg.message_id == "msg-123"
+        assert msg.role == Role.USER
+        assert len(msg.parts) == 1
+    
+    def test_message_with_context(self):
+        """Test Message with context_id."""
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        msg = Message(
+            message_id="msg-456",
+            role=Role.AGENT,
+            parts=[TextPart(text="Response")],
+            context_id="ctx-789"
+        )
+        assert msg.context_id == "ctx-789"
+    
+    def test_message_with_task(self):
+        """Test Message with task_id."""
+        from praisonaiagents.ui.a2a.types import Message, Role, TextPart
+        msg = Message(
+            message_id="msg-789",
+            role=Role.AGENT,
+            parts=[TextPart(text="Working on it")],
+            task_id="task-123"
+        )
+        assert msg.task_id == "task-123"
+
+
+class TestTaskStatus:
+    """Tests for TaskStatus model."""
+    
+    def test_task_status_creation(self):
+        """Test TaskStatus can be created."""
+        from praisonaiagents.ui.a2a.types import TaskStatus, TaskState
+        status = TaskStatus(state=TaskState.WORKING)
+        assert status.state == TaskState.WORKING
+    
+    def test_task_status_with_message(self):
+        """Test TaskStatus with message."""
+        from praisonaiagents.ui.a2a.types import TaskStatus, TaskState, Message, Role, TextPart
+        msg = Message(
+            message_id="msg-1",
+            role=Role.AGENT,
+            parts=[TextPart(text="Processing...")]
+        )
+        status = TaskStatus(state=TaskState.WORKING, message=msg)
+        assert status.message is not None
+    
+    def test_task_status_with_timestamp(self):
+        """Test TaskStatus with timestamp."""
+        from praisonaiagents.ui.a2a.types import TaskStatus, TaskState
+        ts = datetime.utcnow().isoformat()
+        status = TaskStatus(state=TaskState.COMPLETED, timestamp=ts)
+        assert status.timestamp == ts
+
+
+class TestTask:
+    """Tests for Task model."""
+    
+    def test_task_creation(self):
+        """Test Task can be created."""
+        from praisonaiagents.ui.a2a.types import Task, TaskStatus, TaskState
+        task = Task(
+            id="task-123",
+            status=TaskStatus(state=TaskState.SUBMITTED)
+        )
+        assert task.id == "task-123"
+        assert task.status.state == TaskState.SUBMITTED
+    
+    def test_task_with_context(self):
+        """Test Task with context_id."""
+        from praisonaiagents.ui.a2a.types import Task, TaskStatus, TaskState
+        task = Task(
+            id="task-456",
+            context_id="ctx-789",
+            status=TaskStatus(state=TaskState.WORKING)
+        )
+        assert task.context_id == "ctx-789"
+    
+    def test_task_with_artifacts(self):
+        """Test Task with artifacts."""
+        from praisonaiagents.ui.a2a.types import Task, TaskStatus, TaskState, Artifact, TextPart
+        artifact = Artifact(
+            artifact_id="art-1",
+            parts=[TextPart(text="Result")]
+        )
+        task = Task(
+            id="task-789",
+            status=TaskStatus(state=TaskState.COMPLETED),
+            artifacts=[artifact]
+        )
+        assert len(task.artifacts) == 1
+    
+    def test_task_with_history(self):
+        """Test Task with message history."""
+        from praisonaiagents.ui.a2a.types import Task, TaskStatus, TaskState, Message, Role, TextPart
+        msg1 = Message(message_id="m1", role=Role.USER, parts=[TextPart(text="Q")])
+        msg2 = Message(message_id="m2", role=Role.AGENT, parts=[TextPart(text="A")])
+        task = Task(
+            id="task-abc",
+            status=TaskStatus(state=TaskState.COMPLETED),
+            history=[msg1, msg2]
+        )
+        assert len(task.history) == 2
+
+
+class TestArtifact:
+    """Tests for Artifact model."""
+    
+    def test_artifact_creation(self):
+        """Test Artifact can be created."""
+        from praisonaiagents.ui.a2a.types import Artifact, TextPart
+        artifact = Artifact(
+            artifact_id="art-123",
+            parts=[TextPart(text="Generated content")]
+        )
+        assert artifact.artifact_id == "art-123"
+    
+    def test_artifact_with_name(self):
+        """Test Artifact with name and description."""
+        from praisonaiagents.ui.a2a.types import Artifact, TextPart
+        artifact = Artifact(
+            artifact_id="art-456",
+            name="Report",
+            description="Generated report",
+            parts=[TextPart(text="Report content")]
+        )
+        assert artifact.name == "Report"
+        assert artifact.description == "Generated report"
+
+
+class TestAgentSkill:
+    """Tests for AgentSkill model."""
+    
+    def test_agent_skill_creation(self):
+        """Test AgentSkill can be created."""
+        from praisonaiagents.ui.a2a.types import AgentSkill
+        skill = AgentSkill(
+            id="search",
+            name="Web Search",
+            description="Search the web for information"
+        )
+        assert skill.id == "search"
+        assert skill.name == "Web Search"
+    
+    def test_agent_skill_with_tags(self):
+        """Test AgentSkill with tags."""
+        from praisonaiagents.ui.a2a.types import AgentSkill
+        skill = AgentSkill(
+            id="calc",
+            name="Calculator",
+            description="Perform calculations",
+            tags=["math", "utility"]
+        )
+        assert skill.tags == ["math", "utility"]
+    
+    def test_agent_skill_with_examples(self):
+        """Test AgentSkill with examples."""
+        from praisonaiagents.ui.a2a.types import AgentSkill
+        skill = AgentSkill(
+            id="translate",
+            name="Translator",
+            description="Translate text",
+            examples=["Translate hello to Spanish", "What is bonjour in English?"]
+        )
+        assert len(skill.examples) == 2
+
+
+class TestAgentCapabilities:
+    """Tests for AgentCapabilities model."""
+    
+    def test_capabilities_creation(self):
+        """Test AgentCapabilities can be created."""
+        from praisonaiagents.ui.a2a.types import AgentCapabilities
+        caps = AgentCapabilities(streaming=True)
+        assert caps.streaming is True
+    
+    def test_capabilities_defaults(self):
+        """Test AgentCapabilities defaults."""
+        from praisonaiagents.ui.a2a.types import AgentCapabilities
+        caps = AgentCapabilities()
+        assert caps.streaming is False
+        assert caps.push_notifications is False
+
+
+class TestAgentCard:
+    """Tests for AgentCard model."""
+    
+    def test_agent_card_creation(self):
+        """Test AgentCard can be created."""
+        from praisonaiagents.ui.a2a.types import AgentCard, AgentCapabilities
+        card = AgentCard(
+            name="Research Agent",
+            url="http://localhost:8000/a2a",
+            version="1.0.0",
+            capabilities=AgentCapabilities(streaming=True)
+        )
+        assert card.name == "Research Agent"
+        assert card.url == "http://localhost:8000/a2a"
+    
+    def test_agent_card_with_skills(self):
+        """Test AgentCard with skills."""
+        from praisonaiagents.ui.a2a.types import AgentCard, AgentCapabilities, AgentSkill
+        skill = AgentSkill(id="search", name="Search", description="Search web")
+        card = AgentCard(
+            name="Search Agent",
+            url="http://localhost:8000/a2a",
+            version="1.0.0",
+            capabilities=AgentCapabilities(),
+            skills=[skill]
+        )
+        assert len(card.skills) == 1
+    
+    def test_agent_card_json_serialization(self):
+        """Test AgentCard can be serialized to JSON."""
+        from praisonaiagents.ui.a2a.types import AgentCard, AgentCapabilities
+        card = AgentCard(
+            name="Test Agent",
+            url="http://localhost:8000/a2a",
+            version="1.0.0",
+            capabilities=AgentCapabilities()
+        )
+        json_str = card.model_dump_json()
+        data = json.loads(json_str)
+        assert data["name"] == "Test Agent"
+
+
+class TestSendMessageRequest:
+    """Tests for SendMessageRequest model."""
+    
+    def test_send_message_request_creation(self):
+        """Test SendMessageRequest can be created."""
+        from praisonaiagents.ui.a2a.types import SendMessageRequest, Message, Role, TextPart
+        msg = Message(
+            message_id="msg-1",
+            role=Role.USER,
+            parts=[TextPart(text="Hello")]
+        )
+        req = SendMessageRequest(message=msg)
+        assert req.message.message_id == "msg-1"
+    
+    def test_send_message_request_with_config(self):
+        """Test SendMessageRequest with configuration."""
+        from praisonaiagents.ui.a2a.types import SendMessageRequest, Message, Role, TextPart, MessageConfig
+        msg = Message(
+            message_id="msg-2",
+            role=Role.USER,
+            parts=[TextPart(text="Search for AI")]
+        )
+        config = MessageConfig(
+            accept_content_types=["text/plain", "application/json"]
+        )
+        req = SendMessageRequest(message=msg, configuration=config)
+        assert req.configuration is not None
+
+
+class TestStreamingEvents:
+    """Tests for streaming event models."""
+    
+    def test_task_status_update_event(self):
+        """Test TaskStatusUpdateEvent creation."""
+        from praisonaiagents.ui.a2a.types import TaskStatusUpdateEvent, TaskStatus, TaskState
+        event = TaskStatusUpdateEvent(
+            task_id="task-123",
+            status=TaskStatus(state=TaskState.WORKING),
+            final=False
+        )
+        assert event.task_id == "task-123"
+        assert event.final is False
+    
+    def test_task_artifact_update_event(self):
+        """Test TaskArtifactUpdateEvent creation."""
+        from praisonaiagents.ui.a2a.types import TaskArtifactUpdateEvent, Artifact, TextPart
+        artifact = Artifact(
+            artifact_id="art-1",
+            parts=[TextPart(text="Partial result")]
+        )
+        event = TaskArtifactUpdateEvent(
+            task_id="task-456",
+            artifact=artifact,
+            append=True,
+            last_chunk=False
+        )
+        assert event.append is True
+        assert event.last_chunk is False

src/praisonai-agents/tests/agui/__init__.py

@@ -0,0 +1 @@
+"""Tests for AG-UI integration."""

src/praisonai-agents/tests/agui/test_agui.py

@@ -0,0 +1,188 @@
+"""
+Test AGUI Class - TDD Tests for Main Interface Class
+
+Phase 5: AGUI Class Tests
+- Test AGUI initialization with Agent
+- Test AGUI initialization with PraisonAIAgents
+- Test get_router returns FastAPI router
+- Test validation errors
+"""
+
+
+class TestAGUIInitialization:
+    """Test AGUI class initialization."""
+    
+    def test_agui_init_with_agent(self):
+        """Test AGUI initialization with single Agent."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        assert agui.agent == agent
+        assert agui.agents is None
+    
+    def test_agui_init_with_agents(self):
+        """Test AGUI initialization with PraisonAIAgents."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        task = Task(description="Test task", expected_output="Result", agent=agent)
+        agents = PraisonAIAgents(agents=[agent], tasks=[task])
+        
+        agui = AGUI(agents=agents)
+        
+        assert agui.agents == agents
+        assert agui.agent is None
+    
+    def test_agui_requires_agent_or_agents(self):
+        """Test AGUI raises error if neither agent nor agents provided."""
+        from praisonaiagents.ui.agui import AGUI
+        import pytest
+        
+        with pytest.raises(ValueError, match="requires an agent or agents"):
+            AGUI()
+    
+    def test_agui_custom_prefix(self):
+        """Test AGUI with custom prefix."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent, prefix="/api/v1")
+        
+        assert agui.prefix == "/api/v1"
+    
+    def test_agui_custom_tags(self):
+        """Test AGUI with custom tags."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent, tags=["Custom", "Tags"])
+        
+        assert agui.tags == ["Custom", "Tags"]
+    
+    def test_agui_default_tags(self):
+        """Test AGUI default tags."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        assert agui.tags == ["AGUI"]
+
+
+class TestAGUIRouter:
+    """Test AGUI router generation."""
+    
+    def test_get_router_returns_api_router(self):
+        """Test get_router returns FastAPI APIRouter."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import APIRouter
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        router = agui.get_router()
+        
+        assert isinstance(router, APIRouter)
+    
+    def test_router_has_agui_endpoint(self):
+        """Test router has /agui POST endpoint."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        router = agui.get_router()
+        
+        # Check routes
+        route_paths = [route.path for route in router.routes]
+        assert "/agui" in route_paths
+    
+    def test_router_has_status_endpoint(self):
+        """Test router has /status GET endpoint."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        router = agui.get_router()
+        
+        # Check routes
+        route_paths = [route.path for route in router.routes]
+        assert "/status" in route_paths
+    
+    def test_router_with_prefix(self):
+        """Test router respects prefix."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent, prefix="/api/v1")
+        
+        router = agui.get_router()
+        
+        assert router.prefix == "/api/v1"
+
+
+class TestAGUIIntegration:
+    """Test AGUI integration with FastAPI."""
+    
+    def test_include_router_in_fastapi(self):
+        """Test including AGUI router in FastAPI app."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        # Check app has routes
+        route_paths = [route.path for route in app.routes]
+        assert "/agui" in route_paths
+        assert "/status" in route_paths
+
+
+class TestAGUIName:
+    """Test AGUI name and description."""
+    
+    def test_agui_name(self):
+        """Test AGUI name property."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent, name="My Agent")
+        
+        assert agui.name == "My Agent"
+    
+    def test_agui_description(self):
+        """Test AGUI description property."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent, description="A test agent")
+        
+        assert agui.description == "A test agent"
+    
+    def test_agui_default_name_from_agent(self):
+        """Test AGUI uses agent name by default."""
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="TestAgent", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        assert agui.name == "TestAgent"

src/praisonai-agents/tests/agui/test_conversion.py

@@ -0,0 +1,286 @@
+"""
+Test AG-UI Message Conversion - TDD Tests for Message Format Conversion
+
+Phase 3: Message Conversion Tests
+- Test converting AG-UI messages to PraisonAI format
+- Test converting PraisonAI messages to AG-UI format
+- Test handling of tool calls
+- Test handling of tool results
+- Test edge cases (empty messages, missing fields)
+"""
+
+class TestAGUIToPraisonAIConversion:
+    """Test converting AG-UI messages to PraisonAI format."""
+    
+    def test_convert_user_message(self):
+        """Test converting a user message."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        agui_messages = [Message(role="user", content="Hello")]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "user"
+        assert result[0]["content"] == "Hello"
+    
+    def test_convert_assistant_message(self):
+        """Test converting an assistant message."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        agui_messages = [Message(role="assistant", content="Hi there!")]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "assistant"
+        assert result[0]["content"] == "Hi there!"
+    
+    def test_convert_tool_message(self):
+        """Test converting a tool result message."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        agui_messages = [Message(role="tool", content="Search results", tool_call_id="tc-123")]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "tool"
+        assert result[0]["content"] == "Search results"
+        assert result[0]["tool_call_id"] == "tc-123"
+    
+    def test_convert_assistant_with_tool_calls(self):
+        """Test converting assistant message with tool calls."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message, ToolCall, FunctionCall
+        
+        agui_messages = [
+            Message(
+                role="assistant",
+                content="",
+                tool_calls=[
+                    ToolCall(
+                        id="tc-123",
+                        function=FunctionCall(name="search", arguments='{"query": "test"}')
+                    )
+                ]
+            )
+        ]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        assert len(result) == 1
+        assert result[0]["role"] == "assistant"
+        assert "tool_calls" in result[0]
+        assert len(result[0]["tool_calls"]) == 1
+        assert result[0]["tool_calls"][0]["function"]["name"] == "search"
+    
+    def test_convert_multiple_messages(self):
+        """Test converting multiple messages."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        agui_messages = [
+            Message(role="user", content="Hello"),
+            Message(role="assistant", content="Hi!"),
+            Message(role="user", content="How are you?"),
+        ]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        assert len(result) == 3
+        assert result[0]["role"] == "user"
+        assert result[1]["role"] == "assistant"
+        assert result[2]["role"] == "user"
+    
+    def test_convert_empty_messages(self):
+        """Test converting empty message list."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        
+        result = agui_messages_to_praisonai([])
+        assert result == []
+    
+    def test_skip_system_messages(self):
+        """Test that system messages are skipped (agent builds its own)."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        agui_messages = [
+            Message(role="system", content="You are helpful"),
+            Message(role="user", content="Hello"),
+        ]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        # System message should be skipped
+        assert len(result) == 1
+        assert result[0]["role"] == "user"
+
+
+class TestPraisonAIToAGUIConversion:
+    """Test converting PraisonAI messages to AG-UI format."""
+    
+    def test_convert_user_message(self):
+        """Test converting a user message."""
+        from praisonaiagents.ui.agui.conversion import praisonai_messages_to_agui
+        
+        praison_messages = [{"role": "user", "content": "Hello"}]
+        result = praisonai_messages_to_agui(praison_messages)
+        
+        assert len(result) == 1
+        assert result[0].role == "user"
+        assert result[0].content == "Hello"
+    
+    def test_convert_assistant_message(self):
+        """Test converting an assistant message."""
+        from praisonaiagents.ui.agui.conversion import praisonai_messages_to_agui
+        
+        praison_messages = [{"role": "assistant", "content": "Hi there!"}]
+        result = praisonai_messages_to_agui(praison_messages)
+        
+        assert len(result) == 1
+        assert result[0].role == "assistant"
+        assert result[0].content == "Hi there!"
+    
+    def test_convert_tool_result(self):
+        """Test converting a tool result message."""
+        from praisonaiagents.ui.agui.conversion import praisonai_messages_to_agui
+        
+        praison_messages = [
+            {"role": "tool", "content": "Search results", "tool_call_id": "tc-123"}
+        ]
+        result = praisonai_messages_to_agui(praison_messages)
+        
+        assert len(result) == 1
+        assert result[0].role == "tool"
+        assert result[0].content == "Search results"
+        assert result[0].tool_call_id == "tc-123"
+    
+    def test_convert_assistant_with_tool_calls(self):
+        """Test converting assistant message with tool calls."""
+        from praisonaiagents.ui.agui.conversion import praisonai_messages_to_agui
+        
+        praison_messages = [
+            {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": [
+                    {
+                        "id": "tc-123",
+                        "function": {
+                            "name": "search",
+                            "arguments": '{"query": "test"}'
+                        }
+                    }
+                ]
+            }
+        ]
+        result = praisonai_messages_to_agui(praison_messages)
+        
+        assert len(result) == 1
+        assert result[0].role == "assistant"
+        assert result[0].tool_calls is not None
+        assert len(result[0].tool_calls) == 1
+        assert result[0].tool_calls[0].function.name == "search"
+    
+    def test_convert_empty_messages(self):
+        """Test converting empty message list."""
+        from praisonaiagents.ui.agui.conversion import praisonai_messages_to_agui
+        
+        result = praisonai_messages_to_agui([])
+        assert result == []
+
+
+class TestStateConversion:
+    """Test state conversion utilities."""
+    
+    def test_validate_dict_state(self):
+        """Test validating dict state."""
+        from praisonaiagents.ui.agui.conversion import validate_state
+        
+        state = {"key": "value"}
+        result = validate_state(state, "thread-123")
+        
+        assert result == {"key": "value"}
+    
+    def test_validate_none_state(self):
+        """Test validating None state."""
+        from praisonaiagents.ui.agui.conversion import validate_state
+        
+        result = validate_state(None, "thread-123")
+        assert result is None
+    
+    def test_validate_pydantic_state(self):
+        """Test validating Pydantic model state."""
+        from praisonaiagents.ui.agui.conversion import validate_state
+        from pydantic import BaseModel
+        
+        class TestState(BaseModel):
+            key: str = "value"
+        
+        state = TestState()
+        result = validate_state(state, "thread-123")
+        
+        assert result == {"key": "value"}
+    
+    def test_validate_invalid_state_returns_none(self):
+        """Test that invalid state returns None."""
+        from praisonaiagents.ui.agui.conversion import validate_state
+        
+        # A string is not a valid state
+        result = validate_state("invalid", "thread-123")
+        assert result is None
+
+
+class TestToolCallDeduplication:
+    """Test tool call deduplication logic."""
+    
+    def test_deduplicate_tool_results(self):
+        """Test that duplicate tool results are deduplicated."""
+        from praisonaiagents.ui.agui.conversion import agui_messages_to_praisonai
+        from praisonaiagents.ui.agui.types import Message
+        
+        # Same tool_call_id appearing twice
+        agui_messages = [
+            Message(role="tool", content="Result 1", tool_call_id="tc-123"),
+            Message(role="tool", content="Result 2", tool_call_id="tc-123"),  # Duplicate
+        ]
+        result = agui_messages_to_praisonai(agui_messages)
+        
+        # Should only have one result
+        assert len(result) == 1
+        assert result[0]["content"] == "Result 1"  # First one wins
+
+
+class TestExtractUserInput:
+    """Test extracting user input from messages."""
+    
+    def test_extract_last_user_message(self):
+        """Test extracting the last user message."""
+        from praisonaiagents.ui.agui.conversion import extract_user_input
+        from praisonaiagents.ui.agui.types import Message
+        
+        messages = [
+            Message(role="user", content="First message"),
+            Message(role="assistant", content="Response"),
+            Message(role="user", content="Last message"),
+        ]
+        result = extract_user_input(messages)
+        
+        assert result == "Last message"
+    
+    def test_extract_from_empty_messages(self):
+        """Test extracting from empty messages."""
+        from praisonaiagents.ui.agui.conversion import extract_user_input
+        
+        result = extract_user_input([])
+        assert result == ""
+    
+    def test_extract_no_user_messages(self):
+        """Test extracting when no user messages exist."""
+        from praisonaiagents.ui.agui.conversion import extract_user_input
+        from praisonaiagents.ui.agui.types import Message
+        
+        messages = [
+            Message(role="assistant", content="Hello"),
+        ]
+        result = extract_user_input(messages)
+        
+        assert result == ""

src/praisonai-agents/tests/agui/test_integration.py

@@ -0,0 +1,311 @@
+"""
+Test AG-UI Integration - TDD Tests for End-to-End Integration
+
+Phase 7: Integration Tests
+- Test full flow with single Agent
+- Test full flow with PraisonAIAgents
+- Test tool calling flow
+- Test error recovery
+- Test state persistence
+"""
+
+class TestSingleAgentIntegration:
+    """Test integration with single Agent."""
+    
+    def test_single_agent_chat_flow(self):
+        """Test complete chat flow with single agent."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        import json
+        
+        agent = Agent(
+            name="Assistant",
+            role="Helpful Assistant",
+            goal="Help users with their questions",
+            llm="gpt-4o-mini"
+        )
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        # Send a message
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [{"role": "user", "content": "Say hello"}]
+        })
+        
+        assert response.status_code == 200
+        
+        # Parse SSE events
+        events = []
+        for line in response.text.split("\n"):
+            if line.startswith("data: "):
+                event_data = json.loads(line[6:])
+                events.append(event_data)
+        
+        # Should have run started event
+        event_types = [e.get("type") for e in events]
+        assert "RUN_STARTED" in event_types
+        assert "RUN_FINISHED" in event_types or "RUN_ERROR" in event_types
+
+
+class TestMultiAgentIntegration:
+    """Test integration with PraisonAIAgents."""
+    
+    def test_multi_agent_workflow_flow(self):
+        """Test complete workflow with multiple agents."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent, Task, PraisonAIAgents
+        from fastapi import FastAPI
+        import json
+        
+        # Create agents
+        researcher = Agent(
+            name="Researcher",
+            role="Research Analyst",
+            goal="Research topics thoroughly",
+            llm="gpt-4o-mini"
+        )
+        writer = Agent(
+            name="Writer",
+            role="Content Writer",
+            goal="Write engaging content",
+            llm="gpt-4o-mini"
+        )
+        
+        # Create tasks
+        research_task = Task(
+            description="Research the topic: {topic}",
+            expected_output="Research findings",
+            agent=researcher
+        )
+        write_task = Task(
+            description="Write about the research",
+            expected_output="Written article",
+            agent=writer
+        )
+        
+        # Create PraisonAIAgents
+        agents = PraisonAIAgents(
+            agents=[researcher, writer],
+            tasks=[research_task, write_task]
+        )
+        
+        agui = AGUI(agents=agents)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [{"role": "user", "content": "Research AI"}]
+        })
+        
+        assert response.status_code == 200
+
+
+class TestToolCallingIntegration:
+    """Test integration with tool calling."""
+    
+    def test_agent_with_tools(self):
+        """Test agent with tools integration."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        import json
+        
+        def search_tool(query: str) -> str:
+            """Search for information."""
+            return f"Search results for: {query}"
+        
+        agent = Agent(
+            name="SearchAgent",
+            role="Search Assistant",
+            goal="Help users search for information",
+            tools=[search_tool],
+            llm="gpt-4o-mini"
+        )
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [{"role": "user", "content": "Search for Python tutorials"}]
+        })
+        
+        assert response.status_code == 200
+        
+        # Parse events
+        events = []
+        for line in response.text.split("\n"):
+            if line.startswith("data: "):
+                event_data = json.loads(line[6:])
+                events.append(event_data)
+        
+        # Check for tool call events (may or may not have them depending on LLM response)
+        event_types = [e.get("type") for e in events]
+        assert "RUN_STARTED" in event_types
+
+
+class TestStateManagement:
+    """Test state management in AG-UI."""
+    
+    def test_state_passed_to_agent(self):
+        """Test that state is passed to agent."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(
+            name="StatefulAgent",
+            role="Stateful Assistant",
+            goal="Remember context",
+            llm="gpt-4o-mini"
+        )
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [{"role": "user", "content": "Hello"}],
+            "state": {"user_name": "John", "preferences": {"language": "en"}}
+        })
+        
+        assert response.status_code == 200
+
+
+class TestConversationHistory:
+    """Test conversation history handling."""
+    
+    def test_multiple_messages_in_history(self):
+        """Test handling multiple messages in conversation history."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(
+            name="ChatAgent",
+            role="Chat Assistant",
+            goal="Have conversations",
+            llm="gpt-4o-mini"
+        )
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [
+                {"role": "user", "content": "My name is John"},
+                {"role": "assistant", "content": "Hello John!"},
+                {"role": "user", "content": "What is my name?"}
+            ]
+        })
+        
+        assert response.status_code == 200
+
+
+class TestErrorRecovery:
+    """Test error recovery scenarios."""
+    
+    def test_graceful_error_handling(self):
+        """Test graceful error handling."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        import json
+        
+        # Agent with invalid LLM should handle error gracefully
+        agent = Agent(
+            name="ErrorAgent",
+            role="Error Test",
+            goal="Test error handling",
+            llm="invalid-model-name"
+        )
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "test-thread",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Should not crash, should return error event
+        assert response.status_code == 200
+        
+        # Parse events
+        events = []
+        for line in response.text.split("\n"):
+            if line.startswith("data: "):
+                try:
+                    event_data = json.loads(line[6:])
+                    events.append(event_data)
+                except json.JSONDecodeError:
+                    pass
+        
+        # Should have error event
+        event_types = [e.get("type") for e in events]
+        assert "RUN_ERROR" in event_types or "RUN_FINISHED" in event_types
+
+
+class TestPerformance:
+    """Test performance - ensure no impact on existing functionality."""
+    
+    def test_agui_import_does_not_slow_package(self):
+        """Test that importing AGUI doesn't slow down package import."""
+        import time
+        
+        start = time.time()
+        from praisonaiagents.ui.agui import AGUI
+        import_time = time.time() - start
+        
+        # Import should be fast (< 1 second)
+        assert import_time < 1.0
+    
+    def test_agui_lazy_loading(self):
+        """Test that AGUI uses lazy loading where possible."""
+        # This test ensures we don't import heavy dependencies until needed
+        import sys
+        
+        # Remove agui from cache if present
+        modules_to_remove = [k for k in sys.modules.keys() if 'agui' in k]
+        for mod in modules_to_remove:
+            del sys.modules[mod]
+        
+        # Import should not load FastAPI until get_router is called
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        
+        agent = Agent(name="Test", role="Tester", goal="Test")
+        agui = AGUI(agent=agent)
+        
+        # FastAPI should be loaded when get_router is called
+        router = agui.get_router()
+        assert router is not None

src/praisonai-agents/tests/agui/test_router.py

@@ -0,0 +1,266 @@
+"""
+Test AG-UI Router - TDD Tests for FastAPI HTTP Endpoints
+
+Phase 6: FastAPI Router Tests
+- Test /agui POST endpoint
+- Test /status GET endpoint
+- Test request validation
+- Test streaming response
+- Test error handling
+"""
+
+class TestStatusEndpoint:
+    """Test /status endpoint."""
+    
+    def test_status_endpoint_returns_available(self):
+        """Test status endpoint returns available status."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        response = client.get("/status")
+        
+        assert response.status_code == 200
+        assert response.json() == {"status": "available"}
+
+
+class TestAGUIEndpoint:
+    """Test /agui POST endpoint."""
+    
+    def test_agui_endpoint_accepts_post(self):
+        """Test /agui endpoint accepts POST requests."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        # Minimal valid request
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Should return streaming response (200)
+        assert response.status_code == 200
+    
+    def test_agui_endpoint_returns_streaming_response(self):
+        """Test /agui endpoint returns streaming response."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Check content type is event-stream
+        assert "text/event-stream" in response.headers.get("content-type", "")
+    
+    def test_agui_endpoint_requires_thread_id(self):
+        """Test /agui endpoint requires thread_id."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        # Missing thread_id
+        response = client.post("/agui", json={
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Should return validation error
+        assert response.status_code == 422
+
+
+class TestAGUIEndpointWithState:
+    """Test /agui endpoint with state."""
+    
+    def test_agui_endpoint_accepts_state(self):
+        """Test /agui endpoint accepts state parameter."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}],
+            "state": {"custom_key": "custom_value"}
+        })
+        
+        assert response.status_code == 200
+
+
+class TestAGUIEndpointWithRunId:
+    """Test /agui endpoint with run_id."""
+    
+    def test_agui_endpoint_accepts_run_id(self):
+        """Test /agui endpoint accepts run_id parameter."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "run_id": "run-456",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        assert response.status_code == 200
+    
+    def test_agui_endpoint_generates_run_id_if_missing(self):
+        """Test /agui endpoint generates run_id if not provided."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Should succeed even without run_id
+        assert response.status_code == 200
+
+
+class TestAGUIEndpointCORS:
+    """Test /agui endpoint CORS headers."""
+    
+    def test_agui_endpoint_cors_headers(self):
+        """Test /agui endpoint includes CORS headers."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Check CORS headers
+        assert response.headers.get("access-control-allow-origin") == "*"
+
+
+class TestAGUIEndpointErrorHandling:
+    """Test /agui endpoint error handling."""
+    
+    def test_agui_endpoint_handles_agent_error(self):
+        """Test /agui endpoint handles agent errors gracefully."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        # Create agent that will fail
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        # This should not crash the server
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}]
+        })
+        
+        # Should return 200 with error event in stream
+        assert response.status_code == 200
+
+
+class TestAGUIEndpointWithForwardedProps:
+    """Test /agui endpoint with forwarded_props."""
+    
+    def test_agui_endpoint_accepts_forwarded_props(self):
+        """Test /agui endpoint accepts forwarded_props."""
+        from fastapi.testclient import TestClient
+        from praisonaiagents.ui.agui import AGUI
+        from praisonaiagents import Agent
+        from fastapi import FastAPI
+        
+        agent = Agent(name="Test", role="Tester", goal="Test things")
+        agui = AGUI(agent=agent)
+        
+        app = FastAPI()
+        app.include_router(agui.get_router())
+        
+        client = TestClient(app)
+        
+        response = client.post("/agui", json={
+            "thread_id": "thread-123",
+            "messages": [{"role": "user", "content": "Hello"}],
+            "forwarded_props": {"user_id": "user-123"}
+        })
+        
+        assert response.status_code == 200

src/praisonai-agents/tests/agui/test_streaming.py

@@ -0,0 +1,240 @@
+"""
+Test AG-UI Event Streaming - TDD Tests for Streaming PraisonAI Responses
+
+Phase 4: Event Streaming Tests
+- Test streaming text content as AG-UI events
+- Test streaming tool calls as AG-UI events
+- Test run lifecycle events (start, finish, error)
+- Test step events
+- Test event ordering
+"""
+
+import asyncio
+
+
+class TestTextMessageStreaming:
+    """Test streaming text messages."""
+    
+    def test_stream_simple_text(self):
+        """Test streaming simple text content."""
+        from praisonaiagents.ui.agui.streaming import create_text_message_events
+        
+        events = list(create_text_message_events(
+            content="Hello, world!",
+            message_id="msg-123"
+        ))
+        
+        # Should have start, content, end events
+        assert len(events) == 3
+        assert events[0].type == "TEXT_MESSAGE_START"
+        assert events[0].message_id == "msg-123"
+        assert events[1].type == "TEXT_MESSAGE_CONTENT"
+        assert events[1].delta == "Hello, world!"
+        assert events[2].type == "TEXT_MESSAGE_END"
+    
+    def test_stream_chunked_text(self):
+        """Test streaming text in chunks."""
+        from praisonaiagents.ui.agui.streaming import stream_text_chunks
+        
+        chunks = ["Hello", ", ", "world", "!"]
+        events = list(stream_text_chunks(chunks, message_id="msg-123"))
+        
+        # Should have start, 4 content events, end
+        assert len(events) == 6
+        assert events[0].type == "TEXT_MESSAGE_START"
+        assert events[1].delta == "Hello"
+        assert events[2].delta == ", "
+        assert events[3].delta == "world"
+        assert events[4].delta == "!"
+        assert events[5].type == "TEXT_MESSAGE_END"
+    
+    def test_stream_empty_text(self):
+        """Test streaming empty text."""
+        from praisonaiagents.ui.agui.streaming import create_text_message_events
+        
+        events = list(create_text_message_events(content="", message_id="msg-123"))
+        
+        # Should still have start and end, but no content
+        assert len(events) == 2
+        assert events[0].type == "TEXT_MESSAGE_START"
+        assert events[1].type == "TEXT_MESSAGE_END"
+
+
+class TestToolCallStreaming:
+    """Test streaming tool calls."""
+    
+    def test_stream_tool_call(self):
+        """Test streaming a tool call."""
+        from praisonaiagents.ui.agui.streaming import create_tool_call_events
+        
+        events = list(create_tool_call_events(
+            tool_call_id="tc-123",
+            tool_name="search",
+            arguments='{"query": "test"}',
+            parent_message_id="msg-123"
+        ))
+        
+        # Should have start, args, end events
+        assert len(events) == 3
+        assert events[0].type == "TOOL_CALL_START"
+        assert events[0].tool_call_id == "tc-123"
+        assert events[0].tool_call_name == "search"
+        assert events[1].type == "TOOL_CALL_ARGS"
+        assert events[1].delta == '{"query": "test"}'
+        assert events[2].type == "TOOL_CALL_END"
+    
+    def test_stream_tool_result(self):
+        """Test streaming a tool result."""
+        from praisonaiagents.ui.agui.streaming import create_tool_result_event
+        
+        event = create_tool_result_event(
+            tool_call_id="tc-123",
+            content="Search results...",
+            message_id="msg-456"
+        )
+        
+        assert event.type == "TOOL_CALL_RESULT"
+        assert event.tool_call_id == "tc-123"
+        assert event.content == "Search results..."
+
+
+class TestRunLifecycleEvents:
+    """Test run lifecycle events."""
+    
+    def test_create_run_started_event(self):
+        """Test creating run started event."""
+        from praisonaiagents.ui.agui.streaming import create_run_started_event
+        
+        event = create_run_started_event(thread_id="thread-123", run_id="run-456")
+        
+        assert event.type == "RUN_STARTED"
+        assert event.thread_id == "thread-123"
+        assert event.run_id == "run-456"
+    
+    def test_create_run_finished_event(self):
+        """Test creating run finished event."""
+        from praisonaiagents.ui.agui.streaming import create_run_finished_event
+        
+        event = create_run_finished_event(thread_id="thread-123", run_id="run-456")
+        
+        assert event.type == "RUN_FINISHED"
+        assert event.thread_id == "thread-123"
+        assert event.run_id == "run-456"
+    
+    def test_create_run_error_event(self):
+        """Test creating run error event."""
+        from praisonaiagents.ui.agui.streaming import create_run_error_event
+        
+        event = create_run_error_event(message="Something went wrong", code="ERR001")
+        
+        assert event.type == "RUN_ERROR"
+        assert event.message == "Something went wrong"
+        assert event.code == "ERR001"
+
+
+class TestStepEvents:
+    """Test step events."""
+    
+    def test_create_step_started_event(self):
+        """Test creating step started event."""
+        from praisonaiagents.ui.agui.streaming import create_step_started_event
+        
+        event = create_step_started_event(step_name="research")
+        
+        assert event.type == "STEP_STARTED"
+        assert event.step_name == "research"
+    
+    def test_create_step_finished_event(self):
+        """Test creating step finished event."""
+        from praisonaiagents.ui.agui.streaming import create_step_finished_event
+        
+        event = create_step_finished_event(step_name="research")
+        
+        assert event.type == "STEP_FINISHED"
+        assert event.step_name == "research"
+
+
+class TestEventBuffer:
+    """Test EventBuffer for managing event ordering."""
+    
+    def test_event_buffer_creation(self):
+        """Test EventBuffer creation."""
+        from praisonaiagents.ui.agui.streaming import EventBuffer
+        
+        buffer = EventBuffer()
+        assert buffer.active_tool_call_ids == set()
+        assert buffer.current_text_message_id == ""
+    
+    def test_event_buffer_start_tool_call(self):
+        """Test starting a tool call in buffer."""
+        from praisonaiagents.ui.agui.streaming import EventBuffer
+        
+        buffer = EventBuffer()
+        buffer.start_tool_call("tc-123")
+        
+        assert "tc-123" in buffer.active_tool_call_ids
+    
+    def test_event_buffer_end_tool_call(self):
+        """Test ending a tool call in buffer."""
+        from praisonaiagents.ui.agui.streaming import EventBuffer
+        
+        buffer = EventBuffer()
+        buffer.start_tool_call("tc-123")
+        buffer.end_tool_call("tc-123")
+        
+        assert "tc-123" not in buffer.active_tool_call_ids
+        assert "tc-123" in buffer.ended_tool_call_ids
+    
+    def test_event_buffer_start_text_message(self):
+        """Test starting a text message in buffer."""
+        from praisonaiagents.ui.agui.streaming import EventBuffer
+        
+        buffer = EventBuffer()
+        msg_id = buffer.start_text_message()
+        
+        assert msg_id != ""
+        assert buffer.current_text_message_id == msg_id
+
+
+class TestAsyncStreaming:
+    """Test async streaming functionality."""
+    
+    def test_async_stream_response(self):
+        """Test async streaming of agent response."""
+        async def run_test():
+            from praisonaiagents.ui.agui.streaming import async_stream_response
+            
+            # Mock response chunks
+            async def mock_chunks():
+                yield "Hello"
+                yield ", "
+                yield "world!"
+            
+            events = []
+            async for event in async_stream_response(
+                response_stream=mock_chunks(),
+                thread_id="thread-123",
+                run_id="run-456"
+            ):
+                events.append(event)
+            
+            # Should have run_started, text events, run_finished
+            assert len(events) > 0
+            assert events[0].type == "RUN_STARTED"
+            assert events[-1].type == "RUN_FINISHED"
+        
+        asyncio.run(run_test())
+
+
+class TestStateSnapshotEvents:
+    """Test state snapshot events."""
+    
+    def test_create_state_snapshot_event(self):
+        """Test creating state snapshot event."""
+        from praisonaiagents.ui.agui.streaming import create_state_snapshot_event
+        
+        state = {"task": "research", "progress": 50}
+        event = create_state_snapshot_event(state)
+        
+        assert event.type == "STATE_SNAPSHOT"
+        assert event.snapshot == state

src/praisonai-agents/tests/agui/test_types.py

@@ -0,0 +1,327 @@
+"""
+Test AG-UI Types - TDD Tests for Event and Message Types
+
+Phase 2: Core Types Tests
+- Test EventType enum values
+- Test BaseEvent creation
+- Test all event type classes
+- Test message type classes
+- Test RunAgentInput validation
+"""
+
+import json
+
+
+class TestEventType:
+    """Test EventType enum."""
+    
+    def test_event_type_text_message_start(self):
+        """Test TEXT_MESSAGE_START event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TEXT_MESSAGE_START == "TEXT_MESSAGE_START"
+    
+    def test_event_type_text_message_content(self):
+        """Test TEXT_MESSAGE_CONTENT event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TEXT_MESSAGE_CONTENT == "TEXT_MESSAGE_CONTENT"
+    
+    def test_event_type_text_message_end(self):
+        """Test TEXT_MESSAGE_END event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TEXT_MESSAGE_END == "TEXT_MESSAGE_END"
+    
+    def test_event_type_tool_call_start(self):
+        """Test TOOL_CALL_START event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TOOL_CALL_START == "TOOL_CALL_START"
+    
+    def test_event_type_tool_call_args(self):
+        """Test TOOL_CALL_ARGS event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TOOL_CALL_ARGS == "TOOL_CALL_ARGS"
+    
+    def test_event_type_tool_call_end(self):
+        """Test TOOL_CALL_END event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TOOL_CALL_END == "TOOL_CALL_END"
+    
+    def test_event_type_tool_call_result(self):
+        """Test TOOL_CALL_RESULT event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.TOOL_CALL_RESULT == "TOOL_CALL_RESULT"
+    
+    def test_event_type_run_started(self):
+        """Test RUN_STARTED event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.RUN_STARTED == "RUN_STARTED"
+    
+    def test_event_type_run_finished(self):
+        """Test RUN_FINISHED event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.RUN_FINISHED == "RUN_FINISHED"
+    
+    def test_event_type_run_error(self):
+        """Test RUN_ERROR event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.RUN_ERROR == "RUN_ERROR"
+    
+    def test_event_type_step_started(self):
+        """Test STEP_STARTED event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.STEP_STARTED == "STEP_STARTED"
+    
+    def test_event_type_step_finished(self):
+        """Test STEP_FINISHED event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.STEP_FINISHED == "STEP_FINISHED"
+    
+    def test_event_type_state_snapshot(self):
+        """Test STATE_SNAPSHOT event type exists."""
+        from praisonaiagents.ui.agui.types import EventType
+        assert EventType.STATE_SNAPSHOT == "STATE_SNAPSHOT"
+
+
+class TestBaseEvent:
+    """Test BaseEvent class."""
+    
+    def test_base_event_creation(self):
+        """Test BaseEvent can be created."""
+        from praisonaiagents.ui.agui.types import BaseEvent, EventType
+        event = BaseEvent(type=EventType.RUN_STARTED)
+        assert event.type == EventType.RUN_STARTED
+    
+    def test_base_event_timestamp_optional(self):
+        """Test BaseEvent timestamp is optional."""
+        from praisonaiagents.ui.agui.types import BaseEvent, EventType
+        event = BaseEvent(type=EventType.RUN_STARTED)
+        assert event.timestamp is None
+    
+    def test_base_event_to_dict(self):
+        """Test BaseEvent can be converted to dict."""
+        from praisonaiagents.ui.agui.types import BaseEvent, EventType
+        event = BaseEvent(type=EventType.RUN_STARTED)
+        data = event.model_dump()
+        assert data["type"] == "RUN_STARTED"
+
+
+class TestTextMessageEvents:
+    """Test text message event classes."""
+    
+    def test_text_message_start_event(self):
+        """Test TextMessageStartEvent creation."""
+        from praisonaiagents.ui.agui.types import TextMessageStartEvent
+        event = TextMessageStartEvent(message_id="msg-123", role="assistant")
+        assert event.message_id == "msg-123"
+        assert event.role == "assistant"
+        assert event.type == "TEXT_MESSAGE_START"
+    
+    def test_text_message_content_event(self):
+        """Test TextMessageContentEvent creation."""
+        from praisonaiagents.ui.agui.types import TextMessageContentEvent
+        event = TextMessageContentEvent(message_id="msg-123", delta="Hello")
+        assert event.message_id == "msg-123"
+        assert event.delta == "Hello"
+        assert event.type == "TEXT_MESSAGE_CONTENT"
+    
+    def test_text_message_end_event(self):
+        """Test TextMessageEndEvent creation."""
+        from praisonaiagents.ui.agui.types import TextMessageEndEvent
+        event = TextMessageEndEvent(message_id="msg-123")
+        assert event.message_id == "msg-123"
+        assert event.type == "TEXT_MESSAGE_END"
+
+
+class TestToolCallEvents:
+    """Test tool call event classes."""
+    
+    def test_tool_call_start_event(self):
+        """Test ToolCallStartEvent creation."""
+        from praisonaiagents.ui.agui.types import ToolCallStartEvent
+        event = ToolCallStartEvent(
+            tool_call_id="tc-123",
+            tool_call_name="search",
+            parent_message_id="msg-123"
+        )
+        assert event.tool_call_id == "tc-123"
+        assert event.tool_call_name == "search"
+        assert event.parent_message_id == "msg-123"
+        assert event.type == "TOOL_CALL_START"
+    
+    def test_tool_call_args_event(self):
+        """Test ToolCallArgsEvent creation."""
+        from praisonaiagents.ui.agui.types import ToolCallArgsEvent
+        event = ToolCallArgsEvent(tool_call_id="tc-123", delta='{"query": "test"}')
+        assert event.tool_call_id == "tc-123"
+        assert event.delta == '{"query": "test"}'
+        assert event.type == "TOOL_CALL_ARGS"
+    
+    def test_tool_call_end_event(self):
+        """Test ToolCallEndEvent creation."""
+        from praisonaiagents.ui.agui.types import ToolCallEndEvent
+        event = ToolCallEndEvent(tool_call_id="tc-123")
+        assert event.tool_call_id == "tc-123"
+        assert event.type == "TOOL_CALL_END"
+    
+    def test_tool_call_result_event(self):
+        """Test ToolCallResultEvent creation."""
+        from praisonaiagents.ui.agui.types import ToolCallResultEvent
+        event = ToolCallResultEvent(
+            message_id="msg-456",
+            tool_call_id="tc-123",
+            content="Search results..."
+        )
+        assert event.message_id == "msg-456"
+        assert event.tool_call_id == "tc-123"
+        assert event.content == "Search results..."
+        assert event.type == "TOOL_CALL_RESULT"
+
+
+class TestRunEvents:
+    """Test run lifecycle event classes."""
+    
+    def test_run_started_event(self):
+        """Test RunStartedEvent creation."""
+        from praisonaiagents.ui.agui.types import RunStartedEvent
+        event = RunStartedEvent(thread_id="thread-123", run_id="run-456")
+        assert event.thread_id == "thread-123"
+        assert event.run_id == "run-456"
+        assert event.type == "RUN_STARTED"
+    
+    def test_run_finished_event(self):
+        """Test RunFinishedEvent creation."""
+        from praisonaiagents.ui.agui.types import RunFinishedEvent
+        event = RunFinishedEvent(thread_id="thread-123", run_id="run-456")
+        assert event.thread_id == "thread-123"
+        assert event.run_id == "run-456"
+        assert event.type == "RUN_FINISHED"
+    
+    def test_run_error_event(self):
+        """Test RunErrorEvent creation."""
+        from praisonaiagents.ui.agui.types import RunErrorEvent
+        event = RunErrorEvent(message="Something went wrong")
+        assert event.message == "Something went wrong"
+        assert event.type == "RUN_ERROR"
+
+
+class TestStepEvents:
+    """Test step event classes."""
+    
+    def test_step_started_event(self):
+        """Test StepStartedEvent creation."""
+        from praisonaiagents.ui.agui.types import StepStartedEvent
+        event = StepStartedEvent(step_name="research")
+        assert event.step_name == "research"
+        assert event.type == "STEP_STARTED"
+    
+    def test_step_finished_event(self):
+        """Test StepFinishedEvent creation."""
+        from praisonaiagents.ui.agui.types import StepFinishedEvent
+        event = StepFinishedEvent(step_name="research")
+        assert event.step_name == "research"
+        assert event.type == "STEP_FINISHED"
+
+
+class TestStateEvents:
+    """Test state event classes."""
+    
+    def test_state_snapshot_event(self):
+        """Test StateSnapshotEvent creation."""
+        from praisonaiagents.ui.agui.types import StateSnapshotEvent
+        event = StateSnapshotEvent(snapshot={"key": "value"})
+        assert event.snapshot == {"key": "value"}
+        assert event.type == "STATE_SNAPSHOT"
+
+
+class TestMessageTypes:
+    """Test message type classes."""
+    
+    def test_user_message(self):
+        """Test UserMessage creation."""
+        from praisonaiagents.ui.agui.types import Message
+        msg = Message(role="user", content="Hello")
+        assert msg.role == "user"
+        assert msg.content == "Hello"
+    
+    def test_assistant_message(self):
+        """Test AssistantMessage creation."""
+        from praisonaiagents.ui.agui.types import Message
+        msg = Message(role="assistant", content="Hi there!")
+        assert msg.role == "assistant"
+        assert msg.content == "Hi there!"
+    
+    def test_tool_message(self):
+        """Test ToolMessage creation."""
+        from praisonaiagents.ui.agui.types import Message
+        msg = Message(role="tool", content="Result", tool_call_id="tc-123")
+        assert msg.role == "tool"
+        assert msg.content == "Result"
+        assert msg.tool_call_id == "tc-123"
+
+
+class TestToolCall:
+    """Test ToolCall type."""
+    
+    def test_tool_call_creation(self):
+        """Test ToolCall creation."""
+        from praisonaiagents.ui.agui.types import ToolCall, FunctionCall
+        tc = ToolCall(
+            id="tc-123",
+            function=FunctionCall(name="search", arguments='{"query": "test"}')
+        )
+        assert tc.id == "tc-123"
+        assert tc.function.name == "search"
+        assert tc.function.arguments == '{"query": "test"}'
+
+
+class TestRunAgentInput:
+    """Test RunAgentInput type."""
+    
+    def test_run_agent_input_creation(self):
+        """Test RunAgentInput creation."""
+        from praisonaiagents.ui.agui.types import RunAgentInput, Message
+        input_data = RunAgentInput(
+            thread_id="thread-123",
+            run_id="run-456",
+            messages=[Message(role="user", content="Hello")]
+        )
+        assert input_data.thread_id == "thread-123"
+        assert input_data.run_id == "run-456"
+        assert len(input_data.messages) == 1
+    
+    def test_run_agent_input_optional_fields(self):
+        """Test RunAgentInput optional fields."""
+        from praisonaiagents.ui.agui.types import RunAgentInput
+        input_data = RunAgentInput(thread_id="thread-123")
+        assert input_data.thread_id == "thread-123"
+        assert input_data.run_id is None
+        assert input_data.messages is None or len(input_data.messages) == 0
+        assert input_data.state is None
+
+
+class TestEventSerialization:
+    """Test event serialization to JSON."""
+    
+    def test_event_json_serialization(self):
+        """Test events can be serialized to JSON."""
+        from praisonaiagents.ui.agui.types import TextMessageStartEvent
+        event = TextMessageStartEvent(message_id="msg-123", role="assistant")
+        json_str = event.model_dump_json()
+        data = json.loads(json_str)
+        assert data["type"] == "TEXT_MESSAGE_START"
+        assert data["message_id"] == "msg-123"
+    
+    def test_event_sse_format(self):
+        """Test events can be formatted as SSE."""
+        from praisonaiagents.ui.agui.types import TextMessageStartEvent
+        from praisonaiagents.ui.agui.encoder import EventEncoder
+        
+        encoder = EventEncoder()
+        event = TextMessageStartEvent(message_id="msg-123", role="assistant")
+        sse = encoder.encode(event)
+        
+        assert sse.startswith("data: ")
+        assert sse.endswith("\n\n")
+        # Parse the JSON part
+        json_part = sse[6:-2]  # Remove "data: " prefix and "\n\n" suffix
+        data = json.loads(json_part)
+        assert data["type"] == "TEXT_MESSAGE_START"

src/praisonai-agents/tests/test_file_memory.py

@@ -493,17 +493,22 @@ class TestAgentIntegration:
     
     def test_agent_store_memory(self):
         """Test Agent store_memory method."""
+        import uuid
         from praisonaiagents import Agent
         
+        # Use unique user_id to avoid stale data from previous test runs
+        unique_user_id = f"test_user_{uuid.uuid4().hex[:8]}"
+        
         agent = Agent(
             name="Test Agent",
-            memory=True
+            memory=True,
+            user_id=unique_user_id
         )
         
         agent.store_memory("User prefers dark mode", memory_type="short_term")
         
         items = agent._memory_instance.get_short_term()
-        assert len(items) == 1
+        assert len(items) == 1, f"Expected 1 item, got {len(items)} items"
         assert items[0].content == "User prefers dark mode"
     
     def test_agent_get_memory_context(self):
@@ -658,10 +663,12 @@ class TestMultiAgentMemorySharing:
     
     def test_agents_share_memory_with_same_user_id(self):
         """Test that agents with same user_id share memory."""
+        import uuid
         from praisonaiagents import Agent
         
         with tempfile.TemporaryDirectory() as tmpdir:
-            user_id = "shared_user"
+            # Use unique user_id to avoid stale data from previous test runs
+            user_id = f"shared_user_{uuid.uuid4().hex[:8]}"
             base_path = f"{tmpdir}/memory"
             
             # Agent 1 stores memories
@@ -676,9 +683,9 @@ class TestMultiAgentMemorySharing:
             agent1._memory_instance.add_entity("Alice", "person", {"role": "developer"})
             
             # Verify Agent1 stored memories
-            assert len(agent1._memory_instance.get_short_term()) == 1
-            assert len(agent1._memory_instance.get_long_term()) == 1
-            assert len(agent1._memory_instance.get_all_entities()) == 1
+            assert len(agent1._memory_instance.get_short_term()) == 1, f"Expected 1 short_term, got {len(agent1._memory_instance.get_short_term())}"
+            assert len(agent1._memory_instance.get_long_term()) == 1, f"Expected 1 long_term, got {len(agent1._memory_instance.get_long_term())}"
+            assert len(agent1._memory_instance.get_all_entities()) == 1, f"Expected 1 entity, got {len(agent1._memory_instance.get_all_entities())}"
             
             # Agent 2 with same user_id should load memories
             agent2 = Agent(

src/praisonai-agents/tests/test_fix_comprehensive.py

@@ -6,6 +6,8 @@ The agent should:
 3. Return the final result (200)
 """
 
+import pytest
+import os
 from praisonaiagents import Agent
 
 def get_stock_price(company_name: str) -> str:
@@ -35,41 +37,60 @@ def multiply(a: int, b: int) -> int:
     print(f"[Tool Called] multiply({a}, {b})")
     return a * b
 
-# Test with Gemini
-print("=" * 60)
-print("Testing with Gemini model")
-print("=" * 60)
 
-agent_gemini = Agent(
-    instructions="You are a helpful assistant. You can use the tools provided to you to help the user. When asked to multiply a stock price, first get the stock price, then multiply it.",
-    llm="gemini/gemini-2.5-pro",
-    tools=[get_stock_price, multiply],
-    verbose=True
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
 )
+def test_sequential_tool_calling_gpt():
+    """Test sequential tool calling with GPT model"""
+    print("=" * 60)
+    print("Testing with GPT model")
+    print("=" * 60)
 
-result_gemini = agent_gemini.start("what is the stock price of Google? multiply the Google stock price with 2")
-print(f"\nFinal Result (Gemini): {result_gemini}")
+    agent_gpt = Agent(
+        instructions="You are a helpful assistant. When asked to multiply a stock price, first get the stock price, then multiply it.",
+        llm="gpt-4o-mini",
+        tools=[get_stock_price, multiply],
+        verbose=True
+    )
 
-# Test with GPT-4
-print("\n" + "=" * 60)
-print("Testing with GPT-4 model")
-print("=" * 60)
+    result = agent_gpt.start("what is the stock price of Google? multiply the Google stock price with 2")
+    print(f"\nFinal Result (GPT): {result}")
+    
+    # Verify result
+    assert result, "GPT returned empty result"
+    print(f"GPT result contains '200': {'200' in str(result)}")
 
-agent_gpt4 = Agent(
-    instructions="You are a helpful assistant. You can use the tools provided to you to help the user. When asked to multiply a stock price, first get the stock price, then multiply it.",
-    llm="gpt-5-nano",
-    tools=[get_stock_price, multiply],
-    verbose=True
+
+@pytest.mark.skipif(
+    not os.environ.get("GOOGLE_API_KEY"),
+    reason="GOOGLE_API_KEY not set - skipping integration test"
 )
+def test_sequential_tool_calling_gemini():
+    """Test sequential tool calling with Gemini model"""
+    print("=" * 60)
+    print("Testing with Gemini model")
+    print("=" * 60)
 
-result_gpt4 = agent_gpt4.start("what is the stock price of Google? multiply the Google stock price with 2")
-print(f"\nFinal Result (GPT-4): {result_gpt4}")
+    agent_gemini = Agent(
+        instructions="You are a helpful assistant. When asked to multiply a stock price, first get the stock price, then multiply it.",
+        llm="gemini/gemini-2.0-flash",
+        tools=[get_stock_price, multiply],
+        verbose=True
+    )
 
-# Verify results
-print("\n" + "=" * 60)
-print("Test Results Summary")
-print("=" * 60)
-print(f"Gemini result contains '200': {'200' in str(result_gemini) if result_gemini else False}")
-print(f"GPT-4 result contains '200': {'200' in str(result_gpt4) if result_gpt4 else False}")
-print(f"Gemini returned empty: {not result_gemini or result_gemini == ''}")
-print(f"GPT-4 returned empty: {not result_gpt4 or result_gpt4 == ''}")
+    result = agent_gemini.start("what is the stock price of Google? multiply the Google stock price with 2")
+    print(f"\nFinal Result (Gemini): {result}")
+    
+    # Verify result
+    assert result, "Gemini returned empty result"
+    print(f"Gemini result contains '200': {'200' in str(result)}")
+
+
+if __name__ == "__main__":
+    # Run tests manually
+    if os.environ.get("OPENAI_API_KEY"):
+        test_sequential_tool_calling_gpt()
+    if os.environ.get("GOOGLE_API_KEY"):
+        test_sequential_tool_calling_gemini()

src/praisonai-agents/tests/test_llm_self_reflection_direct.py

@@ -2,7 +2,23 @@
 """Test LLM class directly to verify self-reflection fix"""
 
 from praisonaiagents.llm import LLM
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2", "15 * 23")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_llm_direct():
     """Test LLM class directly with self-reflection and tools"""

src/praisonai-agents/tests/test_multiple_mcp_tools.py

@@ -0,0 +1,391 @@
+"""
+Test-Driven Development tests for Multiple MCP Tools support.
+
+This test file verifies that:
+1. Single MCP instance works (baseline)
+2. Multiple MCP instances in a list work for tool definition conversion
+3. Multiple MCP instances in a list work for tool execution
+4. Mixed tools (MCP + regular functions) work together
+
+Uses mcp-server-time as the test MCP server (simple, no API keys needed).
+"""
+
+import pytest
+import os
+import sys
+from unittest.mock import Mock
+
+# Add the package to path for testing
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from praisonaiagents.mcp.mcp import MCP
+from praisonaiagents.agent.agent import Agent
+
+
+# ============================================================================
+# Test Fixtures
+# ============================================================================
+
+@pytest.fixture
+def time_mcp():
+    """Create a Time MCP server instance."""
+    return MCP("uvx mcp-server-time", timeout=30)
+
+
+@pytest.fixture
+def mock_mcp_with_tools():
+    """Create a mock MCP instance with predefined tools."""
+    mock = Mock(spec=MCP)
+    mock.is_sse = False
+    mock.is_http_stream = False
+    mock.is_websocket = False
+    
+    # Create mock runner with tools
+    mock.runner = Mock()
+    mock_tool1 = Mock()
+    mock_tool1.name = "get_current_time"
+    mock_tool1.description = "Get current time in a timezone"
+    mock_tool1.inputSchema = {
+        "type": "object",
+        "properties": {
+            "timezone": {"type": "string", "description": "IANA timezone name"}
+        },
+        "required": ["timezone"]
+    }
+    
+    mock_tool2 = Mock()
+    mock_tool2.name = "convert_time"
+    mock_tool2.description = "Convert time between timezones"
+    mock_tool2.inputSchema = {
+        "type": "object",
+        "properties": {
+            "source_timezone": {"type": "string"},
+            "time": {"type": "string"},
+            "target_timezone": {"type": "string"}
+        },
+        "required": ["source_timezone", "time", "target_timezone"]
+    }
+    
+    mock.runner.tools = [mock_tool1, mock_tool2]
+    mock._tools = []
+    
+    # Mock to_openai_tool method
+    def to_openai_tool():
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_current_time",
+                    "description": "Get current time in a timezone",
+                    "parameters": mock_tool1.inputSchema
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "convert_time",
+                    "description": "Convert time between timezones",
+                    "parameters": mock_tool2.inputSchema
+                }
+            }
+        ]
+    mock.to_openai_tool = to_openai_tool
+    
+    # Mock __iter__ to return tool functions
+    def get_current_time(timezone: str) -> str:
+        return f"Time in {timezone}: 12:00"
+    def convert_time(source_timezone: str, time: str, target_timezone: str) -> str:
+        return f"Converted {time} from {source_timezone} to {target_timezone}"
+    get_current_time.__name__ = "get_current_time"
+    convert_time.__name__ = "convert_time"
+    mock._tools = [get_current_time, convert_time]
+    mock.__iter__ = lambda self: iter(self._tools)
+    
+    return mock
+
+
+@pytest.fixture
+def mock_mcp_filesystem():
+    """Create a mock MCP instance simulating filesystem server."""
+    mock = Mock(spec=MCP)
+    mock.is_sse = False
+    mock.is_http_stream = False
+    mock.is_websocket = False
+    
+    mock.runner = Mock()
+    mock_tool = Mock()
+    mock_tool.name = "read_file"
+    mock_tool.description = "Read a file"
+    mock_tool.inputSchema = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string"}
+        },
+        "required": ["path"]
+    }
+    mock.runner.tools = [mock_tool]
+    mock._tools = []
+    
+    def to_openai_tool():
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read a file",
+                    "parameters": mock_tool.inputSchema
+                }
+            }
+        ]
+    mock.to_openai_tool = to_openai_tool
+    
+    def read_file(path: str) -> str:
+        return f"Contents of {path}"
+    read_file.__name__ = "read_file"
+    mock._tools = [read_file]
+    mock.__iter__ = lambda self: iter(self._tools)
+    
+    return mock
+
+
+def sample_function(query: str) -> str:
+    """A sample regular function tool."""
+    return f"Result for: {query}"
+
+
+# ============================================================================
+# Test 1: Single MCP Instance (Baseline)
+# ============================================================================
+
+class TestSingleMCPInstance:
+    """Tests for single MCP instance - baseline functionality."""
+    
+    def test_single_mcp_creates_tools(self, mock_mcp_with_tools):
+        """Test that a single MCP instance properly exposes tools."""
+        tools = mock_mcp_with_tools.to_openai_tool()
+        assert isinstance(tools, list)
+        assert len(tools) == 2
+        assert tools[0]["function"]["name"] == "get_current_time"
+        assert tools[1]["function"]["name"] == "convert_time"
+    
+    def test_single_mcp_is_iterable(self, mock_mcp_with_tools):
+        """Test that MCP instance is iterable."""
+        tools_list = mock_mcp_with_tools._tools
+        assert len(tools_list) == 2
+        assert callable(tools_list[0])
+        assert callable(tools_list[1])
+    
+    def test_agent_accepts_single_mcp(self, mock_mcp_with_tools):
+        """Test that Agent accepts a single MCP instance as tools."""
+        # This should not raise an error
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=mock_mcp_with_tools
+        )
+        # Agent wraps tools in a list if not already a list
+        assert mock_mcp_with_tools in agent.tools or agent.tools == mock_mcp_with_tools
+
+
+# ============================================================================
+# Test 2: Multiple MCP Instances - Tool Definition Conversion
+# ============================================================================
+
+class TestMultipleMCPToolDefinition:
+    """Tests for multiple MCP instances - tool definition conversion."""
+    
+    def test_agent_accepts_multiple_mcp_in_list(self, mock_mcp_with_tools, mock_mcp_filesystem):
+        """Test that Agent accepts multiple MCP instances in a list."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, mock_mcp_filesystem]
+        )
+        assert isinstance(agent.tools, list)
+        assert len(agent.tools) == 2
+    
+    def test_format_tools_handles_multiple_mcp(self, mock_mcp_with_tools, mock_mcp_filesystem):
+        """Test that _format_tools_for_llm handles multiple MCP instances."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, mock_mcp_filesystem]
+        )
+        
+        # Call the internal method to format tools
+        formatted = agent._format_tools_for_completion(agent.tools)
+        
+        # Should have 3 tools total (2 from time + 1 from filesystem)
+        assert isinstance(formatted, list)
+        assert len(formatted) == 3
+        
+        # Check tool names
+        tool_names = [t["function"]["name"] for t in formatted]
+        assert "get_current_time" in tool_names
+        assert "convert_time" in tool_names
+        assert "read_file" in tool_names
+    
+    def test_system_prompt_includes_all_mcp_tools(self, mock_mcp_with_tools, mock_mcp_filesystem):
+        """Test that system prompt includes tools from all MCP instances."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, mock_mcp_filesystem]
+        )
+        
+        system_prompt = agent._build_system_prompt(agent.tools)
+        
+        # Should mention all tools
+        assert "get_current_time" in system_prompt
+        assert "convert_time" in system_prompt
+        assert "read_file" in system_prompt
+
+
+# ============================================================================
+# Test 3: Multiple MCP Instances - Tool Execution
+# ============================================================================
+
+class TestMultipleMCPToolExecution:
+    """Tests for multiple MCP instances - tool execution."""
+    
+    def test_execute_tool_finds_mcp_tool_in_list(self, mock_mcp_with_tools, mock_mcp_filesystem):
+        """Test that execute_tool_call finds tools from MCP instances in a list."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, mock_mcp_filesystem]
+        )
+        
+        # Mock the runner.call_tool method
+        mock_mcp_with_tools.runner.call_tool = Mock(return_value='{"timezone": "UTC", "datetime": "2024-01-01T12:00:00Z"}')
+        
+        # This should find and execute the tool from the first MCP instance
+        result = agent.execute_tool("get_current_time", {"timezone": "UTC"})
+        
+        # Verify the tool was called
+        mock_mcp_with_tools.runner.call_tool.assert_called_once_with("get_current_time", {"timezone": "UTC"})
+    
+    def test_execute_tool_finds_tool_from_second_mcp(self, mock_mcp_with_tools, mock_mcp_filesystem):
+        """Test that execute_tool_call finds tools from the second MCP instance."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, mock_mcp_filesystem]
+        )
+        
+        # Mock the runner.call_tool method
+        mock_mcp_filesystem.runner.call_tool = Mock(return_value='Contents of /test/file.txt')
+        
+        # This should find and execute the tool from the second MCP instance
+        result = agent.execute_tool("read_file", {"path": "/test/file.txt"})
+        
+        # Verify the tool was called
+        mock_mcp_filesystem.runner.call_tool.assert_called_once_with("read_file", {"path": "/test/file.txt"})
+
+
+# ============================================================================
+# Test 4: Mixed Tools (MCP + Regular Functions)
+# ============================================================================
+
+class TestMixedTools:
+    """Tests for mixed tools - MCP instances and regular functions."""
+    
+    def test_agent_accepts_mixed_tools(self, mock_mcp_with_tools):
+        """Test that Agent accepts a mix of MCP instances and regular functions."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, sample_function]
+        )
+        assert isinstance(agent.tools, list)
+        assert len(agent.tools) == 2
+    
+    def test_format_tools_handles_mixed(self, mock_mcp_with_tools):
+        """Test that _format_tools_for_llm handles mixed tools."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, sample_function]
+        )
+        
+        formatted = agent._format_tools_for_completion(agent.tools)
+        
+        # Should have 3 tools (2 from MCP + 1 regular function)
+        assert isinstance(formatted, list)
+        assert len(formatted) == 3
+        
+        tool_names = [t["function"]["name"] for t in formatted]
+        assert "get_current_time" in tool_names
+        assert "convert_time" in tool_names
+        assert "sample_function" in tool_names
+    
+    def test_execute_mixed_tools(self, mock_mcp_with_tools):
+        """Test executing both MCP tools and regular functions."""
+        agent = Agent(
+            name="TestAgent",
+            instructions="Test agent",
+            tools=[mock_mcp_with_tools, sample_function]
+        )
+        
+        # Execute regular function
+        result = agent.execute_tool("sample_function", {"query": "test"})
+        assert "Result for: test" in str(result)
+        
+        # Mock and execute MCP tool
+        mock_mcp_with_tools.runner.call_tool = Mock(return_value='{"timezone": "UTC"}')
+        result = agent.execute_tool("get_current_time", {"timezone": "UTC"})
+        mock_mcp_with_tools.runner.call_tool.assert_called_once()
+
+
+# ============================================================================
+# Integration Tests (requires actual MCP server)
+# ============================================================================
+
+@pytest.mark.integration
+@pytest.mark.skipif(
+    os.environ.get("SKIP_MCP_INTEGRATION") == "1",
+    reason="MCP integration tests skipped"
+)
+class TestMCPIntegration:
+    """Integration tests using actual MCP servers."""
+    
+    def test_real_time_mcp_server(self):
+        """Test with real mcp-server-time."""
+        try:
+            mcp = MCP("uvx mcp-server-time", timeout=30)
+            tools = mcp.to_openai_tool()
+            
+            assert isinstance(tools, list)
+            assert len(tools) >= 1
+            
+            tool_names = [t["function"]["name"] for t in tools]
+            assert "get_current_time" in tool_names
+        except Exception as e:
+            pytest.skip(f"MCP server not available: {e}")
+    
+    def test_multiple_real_mcp_servers(self):
+        """Test with multiple real MCP servers."""
+        try:
+            time_mcp = MCP("uvx mcp-server-time", timeout=30)
+            
+            # Create agent with multiple MCP instances
+            agent = Agent(
+                name="MultiMCPAgent",
+                instructions="Test agent with multiple MCP tools",
+                tools=[time_mcp]
+            )
+            
+            # Verify tools are available
+            formatted = agent._format_tools_for_completion(agent.tools)
+            assert len(formatted) >= 1
+            
+        except Exception as e:
+            pytest.skip(f"MCP servers not available: {e}")
+
+
+# ============================================================================
+# Run tests
+# ============================================================================
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "--tb=short"])

src/praisonai-agents/tests/test_ollama_async_fix.py

@@ -5,7 +5,9 @@ Test script to verify Ollama empty response fix for both sync and async methods.
 
 import asyncio
 import logging
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+import os
+import pytest
+from praisonaiagents import Agent, Task, PraisonAIAgents
 from typing import Dict, Any
 
 # Enable debug logging
@@ -25,8 +27,8 @@ def search_tool(query: str) -> Dict[str, Any]:
     logging.debug(f"[TEST] Search tool returning: {results}")
     return results
 
-# Test with both sync and async workflows
-async def test_model_async(model_name: str):
+# Helper async function to test a model
+async def _test_model_async_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing ASYNC with model: {model_name}")
     print('='*60)
@@ -78,7 +80,7 @@ async def test_model_async(model_name: str):
         traceback.print_exc()
         return False
 
-def test_model_sync(model_name: str):
+def _test_model_sync_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing SYNC with model: {model_name}")
     print('='*60)
@@ -130,18 +132,60 @@ def test_model_sync(model_name: str):
         traceback.print_exc()
         return False
 
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+@pytest.mark.asyncio
+async def test_ollama_async_openai():
+    """Test async with OpenAI model as baseline."""
+    result = await _test_model_async_helper("gpt-4o-mini")
+    assert result, "OpenAI async model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+def test_ollama_sync_openai():
+    """Test sync with OpenAI model as baseline."""
+    result = _test_model_sync_helper("gpt-4o-mini")
+    assert result, "OpenAI sync model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+@pytest.mark.asyncio
+async def test_ollama_async_ollama():
+    """Test async with Ollama model."""
+    result = await _test_model_async_helper("ollama/llama3.2")
+    assert result, "Ollama async model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+def test_ollama_sync_ollama():
+    """Test sync with Ollama model."""
+    result = _test_model_sync_helper("ollama/llama3.2")
+    assert result, "Ollama sync model test failed"
+
+
 async def main():
     print("Testing Ollama empty response fix for both sync and async...")
     
     # Test sync methods
     print("\n1. Testing SYNC methods:")
-    openai_sync_success = test_model_sync("openai/gpt-5-nano")
-    ollama_sync_success = test_model_sync("ollama/llama3.2")
+    openai_sync_success = _test_model_sync_helper("gpt-4o-mini")
+    ollama_sync_success = _test_model_sync_helper("ollama/llama3.2")
     
     # Test async methods
     print("\n2. Testing ASYNC methods:")
-    openai_async_success = await test_model_async("openai/gpt-5-nano")
-    ollama_async_success = await test_model_async("ollama/llama3.2")
+    openai_async_success = await _test_model_async_helper("gpt-4o-mini")
+    ollama_async_success = await _test_model_async_helper("ollama/llama3.2")
     
     # Summary
     print(f"\n{'='*60}")

src/praisonai-agents/tests/test_ollama_fix.py

@@ -4,7 +4,9 @@ Test script to verify Ollama empty response fix.
 """
 
 import logging
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+import os
+import pytest
+from praisonaiagents import Agent, Task, PraisonAIAgents
 from typing import Dict, Any
 
 # Enable debug logging
@@ -24,8 +26,8 @@ def search_tool(query: str) -> Dict[str, Any]:
     logging.debug(f"[TEST] Search tool returning: {results}")
     return results
 
-# Test with both OpenAI and Ollama models
-def test_model(model_name: str):
+# Helper function to test a model
+def _test_model_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing with model: {model_name}")
     print('='*60)
@@ -77,16 +79,36 @@ def test_model(model_name: str):
         traceback.print_exc()
         return False
 
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+def test_ollama_fix_openai():
+    """Test with OpenAI model as baseline."""
+    result = _test_model_helper("gpt-4o-mini")
+    assert result, "OpenAI model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+def test_ollama_fix_ollama():
+    """Test with Ollama model."""
+    result = _test_model_helper("ollama/llama3.2")
+    assert result, "Ollama model test failed"
+
+
 if __name__ == "__main__":
     print("Testing Ollama empty response fix...")
     
     # Test with OpenAI first (as baseline)
     print("\n1. Testing with OpenAI (baseline):")
-    openai_success = test_model("openai/gpt-5-nano")
+    openai_success = _test_model_helper("gpt-4o-mini")
     
     # Test with Ollama
     print("\n2. Testing with Ollama:")
-    ollama_success = test_model("ollama/llama3.2")
+    ollama_success = _test_model_helper("ollama/llama3.2")
     
     # Summary
     print(f"\n{'='*60}")

src/praisonai-agents/tests/test_ollama_sequential_fix.py

@@ -53,11 +53,14 @@ def test_ollama_argument_validation():
     print("\n2. Testing mixed arguments (the main issue):")
     mixed_args = {"a": "get_stock_price", "company_name": "Google", "b": "2"}
     filtered_args = llm._validate_and_filter_ollama_arguments("multiply", mixed_args, tools)
-    expected_filtered = {"a": "get_stock_price", "b": "2"}  # Should remove 'company_name'
+    # Note: The method may coerce "2" to int 2 based on type hints - both are acceptable
+    expected_filtered_str = {"a": "get_stock_price", "b": "2"}  # String version
+    expected_filtered_int = {"a": "get_stock_price", "b": 2}    # Int version (coerced)
     print(f"Original: {mixed_args}")
     print(f"Filtered: {filtered_args}")
-    print(f"Expected: {expected_filtered}")
-    assert filtered_args == expected_filtered, f"Expected {expected_filtered}, got {filtered_args}"
+    print(f"Expected: {expected_filtered_str} or {expected_filtered_int}")
+    assert filtered_args == expected_filtered_str or filtered_args == expected_filtered_int, \
+        f"Expected {expected_filtered_str} or {expected_filtered_int}, got {filtered_args}"
     print("✅ Mixed arguments filtering test passed")
     
     # Test case 3: All invalid arguments

src/praisonai-agents/tests/test_planning.py

@@ -704,7 +704,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value=json.dumps({
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value=json.dumps({
             "name": "Test Plan",
             "description": "A test plan",
             "steps": [
@@ -733,7 +734,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value=json.dumps({
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value=json.dumps({
             "name": "Refined Plan",
             "description": "Updated plan",
             "steps": [
@@ -765,7 +767,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value="Analysis: Python project with FastAPI")
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value="Analysis: Python project with FastAPI")
         
         planner._llm = mock_llm
         

src/praisonai-agents/tests/test_self_reflection_comprehensive.py

@@ -2,7 +2,29 @@
 """Comprehensive test script to verify self-reflection works with tools after the fix"""
 
 from praisonaiagents import Agent, Task, PraisonAIAgents
-from praisonaiagents.tools import duckduckgo_search
+
+# Define duckduckgo_search tool locally to avoid import issues
+def duckduckgo_search(query: str) -> str:
+    """
+    Search the web using DuckDuckGo.
+    
+    Args:
+        query: The search query string
+    
+    Returns:
+        Search results as a string
+    """
+    try:
+        from duckduckgo_search import DDGS
+        with DDGS() as ddgs:
+            results = list(ddgs.text(query, max_results=3))
+            if results:
+                return "\n".join([f"- {r.get('title', '')}: {r.get('body', '')}" for r in results])
+            return "No results found"
+    except ImportError:
+        return f"Mock search results for: {query}"
+    except Exception as e:
+        return f"Search error: {str(e)}"
 
 def test_self_reflection_with_tools():
     """Test self-reflection with tools - should work after the fix"""

src/praisonai-agents/tests/test_self_reflection_fix_simple.py

@@ -2,7 +2,23 @@
 """Simple test to verify the self-reflection fix works"""
 
 from praisonaiagents import Agent
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2", "25 * 17")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_self_reflection_fix():
     """Test that self-reflection works with tools after the fix"""

src/praisonai-agents/tests/test_self_reflection_fix_verification.py

@@ -2,7 +2,23 @@
 """Test to verify the self-reflection fix works with tools"""
 
 from praisonaiagents import Agent, Task, PraisonAIAgents
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "123 * 456")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_self_reflection_fix_verification():
     """Test that self-reflection now works with tools"""

src/praisonai-agents/tests/test_workflow_agents.py

@@ -319,7 +319,14 @@ class TestExecuteWithAgents:
         result = manager.execute("test_workflow")
         
         assert not result["success"]
-        assert "No executor available" in result.get("error", "")
+        # Error can be at top level or in results array
+        error_found = "No executor available" in result.get("error", "")
+        if not error_found and "results" in result:
+            error_found = any(
+                "No executor available" in r.get("error", "") 
+                for r in result.get("results", [])
+            )
+        assert error_found, f"Expected 'No executor available' error, got: {result}"
 
 
 class TestWorkflowLevelDefaults:

src/praisonai-agents/tests/test_workflow_patterns.py

@@ -1032,7 +1032,7 @@ class TestAgentWorkflows:
                 self.name = name
                 self.tools = tools or []
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return f"Response from {self.name}: {message}"
         
         agent = MockAgent("TestAgent", tools=["tool1", "tool2"])
@@ -1051,7 +1051,7 @@ class TestAgentWorkflows:
             def __init__(self, name):
                 self.name = name
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return f"Processed: {message}"
         
         agent = MockAgent("Processor")
@@ -1069,7 +1069,7 @@ class TestAgentWorkflows:
                 self.name = name
                 self.prefix = prefix
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return f"{self.prefix}: {message}"
         
         agent1 = MockAgent("Agent1", "First")
@@ -1090,7 +1090,7 @@ class TestAgentWorkflows:
                 self.name = name
                 self.output = output
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return self.output
         
         agent1 = MockAgent("Agent1", "Result A")
@@ -1116,7 +1116,7 @@ class TestAgentWorkflows:
                 self.name = name
                 self.output = output
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return self.output
         
         tech_agent = MockAgent("TechAgent", "Technical response")
@@ -1149,7 +1149,7 @@ class TestAgentWorkflows:
             def __init__(self, name):
                 self.name = name
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return f"Processed: {message}"
         
         processor = MockAgent("Processor")
@@ -1463,7 +1463,7 @@ class TestToolsPerStep:
                 self.name = name
                 self.tools = tools or []
             
-            def chat(self, message):
+            def chat(self, message, **kwargs):
                 return f"Response with {len(self.tools)} tools"
         
         def mock_tool():

src/praisonai-agents/tests/test_yaml_workflow_parser.py

@@ -1339,3 +1339,308 @@ steps:
         assert researcher is not None
         # backstory should be used as instructions
         assert researcher.backstory == "You are an experienced researcher with 10 years of experience."
+
+
+class TestFieldNameNormalization:
+    """Tests for field name normalization (Accept liberally, suggest canonically)."""
+    
+    def test_roles_normalized_to_agents(self):
+        """Test that 'roles' is normalized to 'agents'."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Roles Test
+roles:
+  researcher:
+    role: Research Analyst
+    goal: Research topics
+    backstory: "Expert researcher"
+
+steps:
+  - agent: researcher
+    action: "Research AI"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert 'researcher' in parser._agents
+    
+    def test_topic_normalized_to_name(self):
+        """Test that 'topic' is normalized to 'name'."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+topic: My Topic Workflow
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide research"
+
+steps:
+  - agent: researcher
+    action: "Research"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.name == "My Topic Workflow"
+    
+    def test_input_field_canonical(self):
+        """Test that 'input' field is the canonical way to specify workflow input."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Input Test Workflow
+input: "This is the workflow input"
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide research"
+
+steps:
+  - agent: researcher
+    action: "Research {{input}}"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.default_input == "This is the workflow input"
+    
+    def test_topic_as_input_alias(self):
+        """Test that 'topic' works as an alias for 'input' (backward compatibility)."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Topic Alias Test
+topic: "This is the topic as input"
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide research"
+
+steps:
+  - agent: researcher
+    action: "Research {{input}}"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.default_input == "This is the topic as input"
+    
+    def test_input_takes_precedence_over_topic(self):
+        """Test that 'input' takes precedence over 'topic' when both are present."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Precedence Test
+input: "Input value wins"
+topic: "Topic value loses"
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide research"
+
+steps:
+  - agent: researcher
+    action: "Research {{input}}"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.default_input == "Input value wins"
+    
+    def test_backstory_normalized_to_instructions(self):
+        """Test that 'backstory' is normalized to 'instructions'."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Backstory Test
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    backstory: "Expert researcher with 10 years experience"
+
+steps:
+  - agent: researcher
+    action: "Research AI"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        researcher = parser._agents.get('researcher')
+        assert researcher is not None
+    
+    def test_description_normalized_to_action(self):
+        """Test that 'description' is normalized to 'action'."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Description Test
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide research"
+
+steps:
+  - agent: researcher
+    description: "Research AI trends"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        # The step should have been parsed with action from description
+        researcher = parser._agents.get('researcher')
+        assert researcher is not None
+        assert hasattr(researcher, '_yaml_action')
+        assert researcher._yaml_action == "Research AI trends"
+    
+    def test_full_agents_yaml_format(self):
+        """Test that full agents.yaml format with roles, backstory, tasks is normalized."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+topic: AI Research
+framework: praisonai
+process: workflow
+
+workflow:
+  planning: true
+  verbose: true
+
+roles:
+  researcher:
+    role: Research Analyst
+    backstory: "Expert researcher"
+    goal: Research topics
+    
+  writer:
+    role: Content Writer
+    backstory: "Expert writer"
+    goal: Write content
+
+steps:
+  - agent: researcher
+    description: "Research AI trends"
+  - agent: writer
+    description: "Write summary"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.name == "AI Research"
+        assert 'researcher' in parser._agents
+        assert 'writer' in parser._agents
+    
+    def test_parallel_steps_description_normalized(self):
+        """Test that description in parallel steps is normalized to action."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Parallel Test
+agents:
+  researcher1:
+    name: Researcher1
+    role: Market Analyst
+    goal: Research market
+    instructions: "Provide market insights"
+  researcher2:
+    name: Researcher2
+    role: Tech Analyst
+    goal: Research tech
+    instructions: "Provide tech insights"
+
+steps:
+  - name: parallel_research
+    parallel:
+      - agent: researcher1
+        description: "Research market trends"
+      - agent: researcher2
+        description: "Research tech trends"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        # Both agents should have their actions set
+        researcher1 = parser._agents.get('researcher1')
+        researcher2 = parser._agents.get('researcher2')
+        assert researcher1 is not None
+        assert researcher2 is not None
+    
+    def test_canonical_names_work(self):
+        """Test that canonical names (agents, instructions, action, steps, name) work."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Canonical Test
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide detailed research"
+
+steps:
+  - agent: researcher
+    action: "Research AI trends"
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert workflow.name == "Canonical Test"
+        researcher = parser._agents.get('researcher')
+        assert researcher is not None
+        assert researcher._yaml_action == "Research AI trends"
+    
+    def test_mixed_old_and_new_names(self):
+        """Test that mixing old and new names works."""
+        from praisonaiagents.workflows import YAMLWorkflowParser
+        
+        yaml_content = """
+name: Mixed Test
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    backstory: "Expert researcher"  # Old name
+    
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write content
+    instructions: "Write clearly"  # New name
+
+steps:
+  - agent: researcher
+    action: "Research AI"  # New name
+  - agent: writer
+    description: "Write summary"  # Old name
+"""
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        assert workflow is not None
+        assert 'researcher' in parser._agents
+        assert 'writer' in parser._agents

src/praisonai-agents/uv.lock

@@ -2422,7 +2422,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.1.4"
+version = "0.1.16"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai/README.md

@@ -30,7 +30,140 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
   </a>
 </div>
 
-## Key Features
+---
+
+## 📑 Table of Contents
+
+- [⚡ Performance](#-performance)
+- [🚀 Quick Start](#-quick-start)
+- [📦 Installation](#-installation)
+  - [Python SDK](#python-sdk)
+  - [JavaScript SDK](#javascript-sdk)
+- [💻 Usage](#-usage)
+  - [Python Code Examples](#python-code-examples)
+  - [CLI / No-Code Interface](#cli--no-code-interface)
+  - [JavaScript Code Examples](#javascript-code-examples)
+- [✨ Key Features](#-key-features)
+- [🌐 Supported Providers](#-supported-providers)
+- [🛠️ Custom Tools](#️-custom-tools)
+- [🔧 Configuration & Integration](#-configuration--integration)
+  - [Ollama Integration](#ollama-integration)
+  - [Groq Integration](#groq-integration)
+  - [100+ Models Support](#100-models-support)
+- [📋 Workflows](#-workflows)
+  - [Workflow Patterns](#workflow-patterns)
+  - [YAML Configuration](#yaml-configuration)
+  - [Agents Playbook](#agents-playbook)
+- [🧠 Memory & Context](#-memory--context)
+- [🔬 Advanced Features](#-advanced-features)
+  - [Research & Intelligence](#research--intelligence)
+  - [Planning & Workflows](#planning--workflows)
+  - [Specialised Agents](#specialised-agents)
+  - [MCP Protocol](#mcp-protocol)
+  - [Safety & Control](#safety--control)
+  - [Developer Tools](#developer-tools)
+- [📊 Process Types & Patterns](#-process-types--patterns)
+  - [Sequential Process](#sequential-process)
+  - [Hierarchical Process](#hierarchical-process)
+  - [Workflow Process](#workflow-process)
+  - [Agentic Patterns](#agentic-patterns)
+- [🎓 Video Tutorials](#-video-tutorials)
+- [⭐ Star History](#-star-history)
+- [👥 Contributing](#-contributing)
+- [🔧 Development](#-development)
+
+---
+
+## ⚡ Performance
+
+PraisonAI Agents is the **fastest AI agent framework** for agent instantiation.
+
+| 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 |
+
+<details>
+<summary>Run benchmarks yourself</summary>
+
+```bash
+cd praisonai-agents
+python benchmarks/simple_benchmark.py
+```
+
+</details>
+
+---
+
+## 🚀 Quick Start
+
+Get started with PraisonAI in under 1 minute:
+
+```bash
+# Install
+pip install praisonaiagents
+
+# Set API key
+export OPENAI_API_KEY=your_key_here
+
+# Create a simple agent
+python -c "from praisonaiagents import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"
+```
+
+---
+
+## 📦 Installation
+
+### Python SDK
+
+Lightweight package dedicated for coding:
+
+```bash
+pip install praisonaiagents
+```
+
+For the full framework with CLI support:
+
+```bash
+pip install praisonai
+```
+
+### JavaScript SDK
+
+```bash
+npm install praisonai
+```
+
+---
+
+## 💻 Usage
+
+### Python Code Examples
+
+- [📘 Complete Python Examples](#using-python-code)
+- [🔧 Custom Tools](#️-custom-tools)
+- [🧠 Memory Configuration](#-memory--context)
+
+### CLI / No-Code Interface
+
+- [🎯 Auto Mode](#auto-mode)
+- [🔬 Deep Research](#deep-research-cli)
+- [📋 Planning Mode](#planning-mode-cli)
+- [💾 Memory Management](#memory-cli)
+- [🔄 Workflow Execution](#workflow-cli)
+
+### JavaScript Code Examples
+
+- [💻 JavaScript Usage](#using-javascript-code)
+
+---
+
+## ✨ Key Features
 
 | Feature | Code | Docs |
 |---------|:----:|:----:|
@@ -114,7 +247,11 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | 💾 Auto-Save Sessions | [Example](#session-management-python) | [📖](https://docs.praison.ai/cli/session) |
 | 📜 History in Context | [Example](#session-management-python) | [📖](https://docs.praison.ai/cli/session) |
 
-## Supported Providers
+---
+
+## 🌐 Supported Providers
+
+PraisonAI supports 100+ LLM providers through seamless integration:
 
 | Provider | Example |
 |----------|:-------:|
@@ -143,14 +280,14 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | Moonshot | [Example](examples/python/providers/moonshot/moonshot_example.py) |
 | vLLM | [Example](examples/python/providers/vllm/vllm_example.py) |
 
-## Using Python Code
+---
+
+## 📘 Using Python Code
 
 Light weight package dedicated for coding:
-```bash
-pip install praisonaiagents
-```
 
 ```bash
+pip install praisonaiagents
 export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
 ```
 
@@ -605,6 +742,77 @@ result = manager.execute_yaml(
 )
 ```
 
+### Complete workflow.yaml Reference
+
+```yaml
+# workflow.yaml - Full feature reference
+name: Complete Workflow
+description: Demonstrates all workflow.yaml features
+framework: praisonai  # praisonai, crewai, autogen
+process: workflow     # sequential, hierarchical, workflow
+
+workflow:
+  planning: true
+  planning_llm: gpt-4o
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+variables:
+  topic: AI trends
+  items: [ML, NLP, Vision]
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics thoroughly
+    instructions: "Provide detailed research findings"
+    backstory: "Expert researcher with 10 years experience"  # alias for instructions
+    llm: gpt-4o-mini
+    function_calling_llm: gpt-4o      # For tool calls
+    max_rpm: 10                        # Rate limiting
+    max_execution_time: 300            # Timeout in seconds
+    reflect_llm: gpt-4o               # For self-reflection
+    min_reflect: 1
+    max_reflect: 3
+    system_template: "You are a helpful assistant"
+    tools:
+      - tavily_search
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write clear content
+    instructions: "Write engaging content"
+
+steps:
+  - name: research_step
+    agent: researcher
+    action: "Research {{topic}}"
+    expected_output: "Comprehensive research report"
+    output_file: "output/research.md"
+    create_directory: true
+    
+  - name: writing_step
+    agent: writer
+    action: "Write article based on research"
+    context:                          # Task dependencies
+      - research_step
+    output_json:                      # Structured output
+      type: object
+      properties:
+        title: { type: string }
+        content: { type: string }
+
+callbacks:
+  on_workflow_start: log_start
+  on_step_complete: log_step
+  on_workflow_complete: log_complete
+```
+
 ### 9. Hooks
 
 Configure in `.praison/hooks.json`:
@@ -621,9 +829,50 @@ hooks.register("pre_write_code", lambda ctx: print(f"Writing {ctx['file']}"))
 result = hooks.execute("pre_write_code", {"file": "main.py"})
 ```
 
-### 10. Extended agents.yaml with Workflow Patterns
+### 10. Field Names Reference (A-I-G-S)
 
-You can now use advanced workflow patterns directly in agents.yaml by setting `process: workflow`:
+PraisonAI accepts both old (agents.yaml) and new (workflow.yaml) field names. Use the **canonical names** for new projects:
+
+| Canonical (Recommended) | Alias (Also Works) | Purpose |
+|-------------------------|-------------------|---------|
+| `agents` | `roles` | Define agent personas |
+| `instructions` | `backstory` | Agent behavior/persona |
+| `action` | `description` | What the step does |
+| `steps` | `tasks` (nested) | Define work items |
+| `name` | `topic` | Workflow identifier |
+
+**A-I-G-S Mnemonic** - Easy to remember:
+- **A**gents - Who does the work
+- **I**nstructions - How they behave  
+- **G**oal - What they achieve
+- **S**teps - What they do
+
+```yaml
+# Quick Reference - Canonical Format
+name: My Workflow              # Workflow name (not 'topic')
+agents:                        # Define agents (not 'roles')
+  my_agent:
+    role: Job Title            # Agent's role
+    goal: What to achieve      # Agent's goal
+    instructions: How to act   # Agent's behavior (not 'backstory')
+    
+steps:                         # Define steps (not 'tasks')
+  - agent: my_agent
+    action: What to do         # Step action (not 'description')
+```
+
+> **Note:** The parser accepts both old and new names. Run `praisonai workflow validate <file.yaml>` to see suggestions for canonical names.
+
+### 11. Extended agents.yaml with Workflow Patterns
+
+**Feature Parity:** Both `agents.yaml` and `workflow.yaml` now support the same features:
+- All workflow patterns (route, parallel, loop, repeat)
+- All agent fields (function_calling_llm, max_rpm, max_execution_time, reflect_llm, templates)
+- All step fields (expected_output, context, output_json, create_directory, callback)
+- Framework support (praisonai, crewai, autogen)
+- Process types (sequential, hierarchical, workflow)
+
+You can use advanced workflow patterns directly in agents.yaml by setting `process: workflow`:
 
 ```yaml
 # agents.yaml with workflow patterns
@@ -639,15 +888,15 @@ workflow:
 variables:
   topic: AI trends
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   classifier:
     role: Request Classifier
-    backstory: "Classify requests into categories"
+    instructions: "Classify requests into categories"  # Canonical: use 'instructions' instead of 'backstory'
     goal: Classify requests
     
   researcher:
     role: Research Analyst
-    backstory: "Expert researcher"
+    instructions: "Expert researcher"  # Canonical: use 'instructions' instead of 'backstory'
     goal: Research topics
     tools:
       - tavily_search
@@ -690,9 +939,13 @@ Run with the same simple command:
 praisonai agents.yaml
 ```
 
-## Using No Code
+---
 
-### Auto Mode:
+## 🎯 CLI / No-Code Interface
+
+PraisonAI provides a powerful CLI for no-code automation and quick prototyping.
+
+### Auto Mode
 ```bash
 pip install praisonai
 export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
@@ -839,10 +1092,43 @@ praisonai "GPT-5" --workflow "Research:Search for info,Write:Write blog" --tools
 praisonai workflow help
 ```
 
+#### YAML Workflow Files:
+```bash
+# Run a YAML workflow file
+praisonai workflow run research.yaml
+
+# Run with variables
+praisonai workflow run research.yaml --var topic="AI trends"
+
+# Validate a YAML workflow
+praisonai workflow validate research.yaml
+
+# Create from template (simple, routing, parallel, loop, evaluator-optimizer)
+praisonai workflow template routing --output my_workflow.yaml
+```
+
+#### Auto-Generate Workflows:
+```bash
+# Auto-generate a sequential workflow from topic
+praisonai workflow auto "Research AI trends"
+
+# Generate parallel workflow (multiple agents work concurrently)
+praisonai workflow auto "Research AI trends" --pattern parallel
+
+# Generate routing workflow (classifier routes to specialists)
+praisonai workflow auto "Build a chatbot" --pattern routing
+
+# Specify output file
+praisonai workflow auto "Research AI" --pattern sequential --output my_workflow.yaml
+```
+
 **Workflow CLI Options:**
 | Flag | Description |
 |------|-------------|
 | `--workflow-var key=value` | Set workflow variable (can be repeated) |
+| `--var key=value` | Set variable for YAML workflows |
+| `--pattern <pattern>` | Pattern for auto-generation (sequential, parallel, routing, loop) |
+| `--output <file>` | Output file for auto-generation |
 | `--llm <model>` | LLM model (e.g., openai/gpt-4o-mini) |
 | `--tools <tools>` | Tools (comma-separated, e.g., tavily) |
 | `--planning` | Enable planning mode |
@@ -1133,6 +1419,36 @@ praisonai commit
 praisonai commit --push
 ```
 
+### Serve CLI (API Server):
+```bash
+# Start API server for agents defined in YAML
+praisonai serve agents.yaml
+
+# With custom port and host
+praisonai serve agents.yaml --port 8005 --host 0.0.0.0
+
+# Alternative flag style
+praisonai agents.yaml --serve
+
+# The server provides:
+# POST /agents          - Run all agents sequentially
+# POST /agents/{name}   - Run specific agent (e.g., /agents/researcher)
+# GET  /agents/list     - List available agents
+```
+
+### n8n Integration CLI:
+```bash
+# Export workflow to n8n and open in browser
+praisonai agents.yaml --n8n
+
+# With custom n8n URL
+praisonai agents.yaml --n8n --n8n-url http://localhost:5678
+
+# Set N8N_API_KEY for auto-import
+export N8N_API_KEY="your-api-key"
+praisonai agents.yaml --n8n
+```
+
 ### @Mentions in Prompts:
 ```bash
 # Include file content in prompt
@@ -1264,6 +1580,21 @@ agent = Agent(
         env={"BRAVE_API_KEY": "your-key"}
     )
 )
+
+# Multiple MCP servers + regular functions
+def my_custom_tool(query: str) -> str:
+    """Custom tool function."""
+    return f"Result: {query}"
+
+agent = Agent(
+    name="MultiToolAgent",
+    instructions="Agent with multiple MCP servers",
+    tools=[
+        MCP("uvx mcp-server-time"),                    # Time tools
+        MCP("npx @modelcontextprotocol/server-memory"), # Memory tools
+        my_custom_tool                                  # Regular function
+    ]
+)
 ```
 
 ### MCP Server (Expose Tools as MCP Server)
@@ -1297,6 +1628,48 @@ server.run()  # stdio for Claude Desktop
 | Security | Origin validation, DNS rebinding prevention |
 | WebSocket | Auto-reconnect with exponential backoff |
 
+## A2A (Agent2Agent Protocol)
+
+PraisonAI supports the [A2A Protocol](https://a2a-protocol.org) for agent-to-agent communication, enabling your agents to be discovered and collaborate with other AI agents.
+
+### A2A Server (Expose Agent as A2A Server)
+```python
+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"Results for: {query}"
+
+agent = Agent(
+    name="Research Assistant",
+    role="Research Analyst",
+    goal="Help users research topics",
+    tools=[search_web]
+)
+
+# Expose as A2A Server
+a2a = A2A(agent=agent, url="http://localhost:8000/a2a")
+
+app = FastAPI()
+app.include_router(a2a.get_router())
+
+# Run: uvicorn app:app --reload
+# Agent Card: GET /.well-known/agent.json
+# Status: GET /status
+```
+
+### A2A Features
+| Feature | Description |
+|---------|-------------|
+| Agent Card | JSON metadata for agent discovery |
+| Skills Extraction | Auto-generate skills from tools |
+| Task Management | Stateful task lifecycle |
+| Streaming | SSE streaming for real-time updates |
+
+> **Documentation**: [docs.praison.ai/a2a](https://docs.praison.ai/a2a) | **Examples**: [examples/python/a2a](https://github.com/MervinPraison/PraisonAI/tree/main/examples/python/a2a)
+
 ## CLI Features
 
 | Feature | Docs |
@@ -1328,7 +1701,9 @@ server.run()  # stdio for Claude Desktop
 | 📥 Web Fetch - URL content retrieval | [📖](https://docs.praison.ai/cli/web-fetch) |
 | 💾 Prompt Caching - Cost reduction | [📖](https://docs.praison.ai/cli/prompt-caching) |
 
-## Using JavaScript Code
+---
+
+## 💻 Using JavaScript Code
 
 ```bash
 npm install praisonai
@@ -1343,11 +1718,17 @@ agent.start('Write a movie script about a robot in Mars');
 
 ![PraisonAI CLI Demo](docs/demo/praisonai-cli-demo.gif)
 
-## Star History
+---
+
+## ⭐ Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=MervinPraison/PraisonAI&type=Date)](https://docs.praison.ai)
 
-## AI Agents Flow
+---
+
+## 📊 Process Types & Patterns
+
+### AI Agents Flow
 
 ```mermaid
 graph LR
@@ -1686,31 +2067,40 @@ flowchart LR
     style Out fill:#8B0000,color:#fff
 ```
 
-## Adding Models
+---
 
-<div align="center">
-  <a href="https://docs.praison.ai/models">
-    <p align="center">
-      <img src="https://img.shields.io/badge/%F0%9F%93%9A_Models-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Models" />
-    </p>
-  </a>
-</div>
+## 🔧 Configuration & Integration
+
+### Ollama Integration
 
-## Ollama Integration
 ```bash
 export OPENAI_BASE_URL=http://localhost:11434/v1
 ```
 
-## Groq Integration
+### Groq Integration
+
 Replace xxxx with Groq API KEY:
+
 ```bash
 export OPENAI_API_KEY=xxxxxxxxxxx
 export OPENAI_BASE_URL=https://api.groq.com/openai/v1
 ```
 
-## No Code Options
+### 100+ Models Support
 
-## Agents Playbook
+PraisonAI supports 100+ LLM models from various providers. Visit our [models documentation](https://docs.praison.ai/models/) for the complete list.
+
+<div align="center">
+  <a href="https://docs.praison.ai/models">
+    <p align="center">
+      <img src="https://img.shields.io/badge/📚_Models_Documentation-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Models Documentation" />
+    </p>
+  </a>
+</div>
+
+---
+
+## 📋 Agents Playbook
 
 ### Simple Playbook Example
 
@@ -1719,9 +2109,9 @@ Create `agents.yaml` file and add the code below:
 ```yaml
 framework: praisonai
 topic: Artificial Intelligence
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   screenwriter:
-    backstory: "Skilled in crafting scripts with engaging dialogue about {topic}."
+    instructions: "Skilled in crafting scripts with engaging dialogue about {topic}."  # Canonical: use 'instructions' instead of 'backstory'
     goal: Create scripts from concepts.
     role: Screenwriter
     tasks:
@@ -1735,18 +2125,11 @@ roles:
 praisonai agents.yaml
 ```
 
-## Use 100+ Models
+---
 
-- https://docs.praison.ai/models/
-<div align="center">
-  <a href="https://docs.praison.ai">
-    <p align="center">
-      <img src="https://img.shields.io/badge/📚_Documentation-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white" alt="Documentation" />
-    </p>
-  </a>
-</div>
+## 🛠️ Custom Tools / Create Plugins
 
-## Custom Tools
+PraisonAI supports multiple ways to create and integrate custom tools (plugins) into your agents.
 
 ### Using `@tool` Decorator
 
@@ -1819,276 +2202,96 @@ After `pip install`, tools are auto-discovered:
 agent = Agent(tools=["my_tool"])  # Works automatically!
 ```
 
+---
 
-## Prompt Expansion
+## 🧠 Memory & Context
 
-Expand short prompts into detailed, actionable prompts:
+PraisonAI provides zero-dependency persistent memory for agents. For detailed examples, see [section 6. Agent Memory](#6-agent-memory-zero-dependencies) in the Python Code Examples.
 
-### CLI Usage
+---
 
-```bash
-# Expand a short prompt into detailed prompt
-praisonai "write a movie script in 3 lines" --expand-prompt
+## 🔬 Advanced Features
 
-# With verbose output
-praisonai "blog about AI" --expand-prompt -v
+### Research & Intelligence
 
-# With tools for context gathering
-praisonai "latest AI trends" --expand-prompt --expand-tools tools.py
+- 🔬 **Deep Research Agents** - OpenAI & Gemini support for automated research
+- 🔄 **Query Rewriter Agent** - HyDE, Step-back, Multi-query strategies for RAG optimization
+- 🌐 **Native Web Search** - Real-time search via OpenAI, Gemini, Anthropic, xAI, Perplexity
+- 📥 **Web Fetch** - Retrieve full content from URLs (Anthropic)
+- 📝 **Prompt Expander Agent** - Expand short prompts into detailed instructions
 
-# Combine with query rewrite
-praisonai "AI news" --query-rewrite --expand-prompt
-```
+### Memory & Caching
 
-### Programmatic Usage
+- 💾 **Prompt Caching** - Reduce costs & latency (OpenAI, Anthropic, Bedrock, Deepseek)
+- 🧠 **Claude Memory Tool** - Persistent cross-conversation memory (Anthropic Beta)
+- 💾 **File-Based Memory** - Zero-dependency persistent memory for all agents
+- 🔍 **Built-in Search Tools** - Tavily, You.com, Exa for web search, news, content extraction
 
-```python
-from praisonaiagents import PromptExpanderAgent, ExpandStrategy
+### Planning & Workflows
 
-# Basic usage
-agent = PromptExpanderAgent()
-result = agent.expand("write a movie script in 3 lines")
-print(result.expanded_prompt)
+- 📋 **Planning Mode** - Plan before execution for agents & multi-agent systems
+- 🔧 **Planning Tools** - Research with tools during planning phase
+- 🧠 **Planning Reasoning** - Chain-of-thought planning for complex tasks
+- ⛓️ **Prompt Chaining** - Sequential prompt workflows with conditional gates
+- 🔍 **Evaluator Optimiser** - Generate and optimize through iterative feedback
+- 👷 **Orchestrator Workers** - Distribute tasks among specialised workers
+- ⚡ **Parallelisation** - Execute tasks in parallel for improved performance
+- 🔁 **Repetitive Agents** - Handle repetitive tasks through automated loops
+- 🤖 **Autonomous Workflow** - Monitor, act, adapt based on environment feedback
 
-# With specific strategy
-result = agent.expand("blog about AI", strategy=ExpandStrategy.DETAILED)
+### Specialised Agents
 
-# Available strategies: BASIC, DETAILED, STRUCTURED, CREATIVE, AUTO
-```
+- 🖼️ **Image Generation Agent** - Create images from text descriptions
+- 📷 **Image to Text Agent** - Extract text and descriptions from images
+- 🎬 **Video Agent** - Analyse and process video content
+- 📊 **Data Analyst Agent** - Analyse data and generate insights
+- 💰 **Finance Agent** - Financial analysis and recommendations
+- 🛒 **Shopping Agent** - Price comparison and shopping assistance
+- ⭐ **Recommendation Agent** - Personalised recommendations
+- 📖 **Wikipedia Agent** - Search and extract Wikipedia information
+- 💻 **Programming Agent** - Code development and analysis
+- 📝 **Markdown Agent** - Generate and format Markdown content
+- 🔀 **Router Agent** - Dynamic task routing with cost optimisation
 
-**Key Difference:**
-- `--query-rewrite`: Optimizes queries for **search/retrieval** (RAG)
-- `--expand-prompt`: Expands prompts for **detailed task execution**
+### MCP Protocol
 
+- 🔌 **MCP Transports** - stdio, Streamable HTTP, WebSocket, SSE (Protocol 2025-11-25)
+- 🌐 **WebSocket MCP** - Real-time bidirectional connections with auto-reconnect
+- 🔐 **MCP Security** - Origin validation, DNS rebinding prevention, secure sessions
+- 🔄 **MCP Resumability** - SSE stream recovery via Last-Event-ID
 
-## Web Search, Web Fetch & Prompt Caching
+### Safety & Control
 
-### CLI Usage
+- 🤝 **Agent Handoffs** - Transfer context between specialised agents
+- 🛡️ **Guardrails** - Input/output validation and safety checks
+- ✅ **Human Approval** - Require human confirmation for critical actions
+- 💬 **Sessions Management** - Isolated conversation contexts
+- 🔄 **Stateful Agents** - Maintain state across interactions
 
-```bash
-# Web Search - Get real-time information
-praisonai "What are the latest AI news today?" --web-search --llm openai/gpt-4o-search-preview
+### Developer Tools
 
-# Web Fetch - Retrieve and analyze URL content (Anthropic only)
-praisonai "Summarize https://docs.praison.ai" --web-fetch --llm anthropic/claude-sonnet-4-20250514
+- ⚡ **Fast Context** - Rapid parallel code search (10-20x faster)
+- 📜 **Rules & Instructions** - Auto-discover CLAUDE.md, AGENTS.md, GEMINI.md
+- 🪝 **Hooks** - Pre/post operation hooks for custom logic
+- 📈 **Telemetry** - Track agent performance and usage
+- 📹 **Camera Integration** - Capture and analyse camera input
 
-# Prompt Caching - Reduce costs for repeated prompts
-praisonai "Analyze this document..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514
-```
+### Other Features
 
-### Programmatic Usage
+- 🔄 **CrewAI & AG2 Integration** - Use CrewAI or AG2 (Formerly AutoGen) Framework
+- 💻 **Codebase Chat** - Chat with entire codebase
+- 🎨 **Interactive UIs** - Multiple interactive interfaces
+- 📄 **YAML Configuration** - YAML-based agent and workflow configuration
+- 🛠️ **Custom Tools** - Easy custom tool integration
+- 🔍 **Internet Search** - Multiple providers (Tavily, You.com, Exa, DuckDuckGo, Crawl4AI)
+- 🖼️ **VLM Support** - Vision Language Model support
+- 🎙️ **Voice Interaction** - Real-time voice interaction
 
-```python
-from praisonaiagents import Agent
+---
 
-# Web Search
-agent = Agent(
-    instructions="You are a research assistant",
-    llm="openai/gpt-4o-search-preview",
-    web_search=True
-)
+## 🎓 Video Tutorials
 
-# Web Fetch (Anthropic only)
-agent = Agent(
-    instructions="You are a content analyzer",
-    llm="anthropic/claude-sonnet-4-20250514",
-    web_fetch=True
-)
-
-# Prompt Caching
-agent = Agent(
-    instructions="You are an AI assistant..." * 50,  # Long system prompt
-    llm="anthropic/claude-sonnet-4-20250514",
-    prompt_caching=True
-)
-```
-
-**Supported Providers:**
-| Feature | Providers |
-|---------|-----------|
-| Web Search | OpenAI, Gemini, Anthropic, xAI, Perplexity |
-| Web Fetch | Anthropic |
-| Prompt Caching | OpenAI (auto), Anthropic, Bedrock, Deepseek |
-
-
-
-
-
-## MCP (Model Context Protocol)
-
-PraisonAI supports MCP Protocol Revision 2025-11-25 with multiple transports.
-
-### MCP Client (Consume MCP Servers)
-
-```python
-from praisonaiagents import Agent, MCP
-
-# stdio - Local NPX/Python servers
-agent = Agent(tools=MCP("npx @modelcontextprotocol/server-memory"))
-
-# Streamable HTTP - Production servers
-agent = Agent(tools=MCP("https://api.example.com/mcp"))
-
-# WebSocket - Real-time bidirectional
-agent = Agent(tools=MCP("wss://api.example.com/mcp", auth_token="token"))
-
-# SSE (Legacy) - Backward compatibility
-agent = Agent(tools=MCP("http://localhost:8080/sse"))
-
-# With environment variables
-agent = Agent(
-    tools=MCP(
-        command="npx",
-        args=["-y", "@modelcontextprotocol/server-brave-search"],
-        env={"BRAVE_API_KEY": "your-key"}
-    )
-)
-```
-
-### MCP Server (Expose Tools as MCP Server)
-
-Expose your Python functions as MCP tools for Claude Desktop, Cursor, and other MCP clients:
-
-```python
-from praisonaiagents.mcp import ToolsMCPServer
-
-def search_web(query: str, max_results: int = 5) -> dict:
-    """Search the web for information."""
-    return {"results": [f"Result for {query}"]}
-
-def calculate(expression: str) -> dict:
-    """Evaluate a mathematical expression."""
-    return {"result": eval(expression)}
-
-# Create and run MCP server
-server = ToolsMCPServer(name="my-tools")
-server.register_tools([search_web, calculate])
-server.run()  # stdio for Claude Desktop
-# server.run_sse(host="0.0.0.0", port=8080)  # SSE for web clients
-```
-
-### MCP Features
-
-| Feature | Description |
-|---------|-------------|
-| **Session Management** | Automatic `Mcp-Session-Id` handling |
-| **Protocol Versioning** | `Mcp-Protocol-Version` header |
-| **Resumability** | SSE stream recovery via `Last-Event-ID` |
-| **Security** | Origin validation, DNS rebinding prevention |
-| **WebSocket** | Auto-reconnect with exponential backoff |
-
-
-## Development:
-
-Below is used for development only.
-
-### Using uv
-```bash
-# Install uv if you haven't already
-pip install uv
-
-# Install from requirements
-uv pip install -r pyproject.toml
-
-# Install with extras
-uv pip install -r pyproject.toml --extra code
-uv pip install -r pyproject.toml --extra "crewai,autogen"
-```
-
-### Bump and Release
-
-```bash
-# From project root - bumps version and releases in one command
-python src/praisonai/scripts/bump_and_release.py 2.2.99
-
-# With praisonaiagents dependency
-python src/praisonai/scripts/bump_and_release.py 2.2.99 --agents 0.0.169
-
-# Then publish
-cd src/praisonai && uv publish
-```
-
-## Contributing
-
-- Fork on GitHub: Use the "Fork" button on the repository page.
-- Clone your fork: `git clone https://github.com/yourusername/praisonAI.git`
-- Create a branch: `git checkout -b new-feature`
-- Make changes and commit: `git commit -am "Add some feature"`
-- Push to your fork: `git push origin new-feature`
-- Submit a pull request via GitHub's web interface.
-- Await feedback from project maintainers.
-
-## Advanced Features
-
-**Research & Intelligence:**
-- 🔬 **Deep Research Agents** (OpenAI & Gemini)
-- 🔄 **Query Rewriter Agent** (HyDE, Step-back, Multi-query)
-- 🌐 **Native Web Search** (OpenAI, Gemini, Anthropic, xAI, Perplexity)
-- 📥 **Web Fetch** (Retrieve full content from URLs - Anthropic)
-- 📝 **Prompt Expander Agent** (Expand short prompts into detailed instructions)
-
-**Memory & Caching:**
-- 💾 **Prompt Caching** (Reduce costs & latency - OpenAI, Anthropic, Bedrock, Deepseek)
-- 🧠 **Claude Memory Tool** (Persistent cross-conversation memory - Anthropic Beta)
-- 💾 **File-Based Memory** (Zero-dependency persistent memory for all agents)
-- 🔍 **Built-in Search Tools** (Tavily, You.com, Exa - web search, news, content extraction)
-
-**Planning & Workflows:**
-- 📋 **Planning Mode** (Plan before execution - Agent & Multi-Agent)
-- 🔧 **Planning Tools** (Research with tools during planning)
-- 🧠 **Planning Reasoning** (Chain-of-thought planning)
-- ⛓️ **Prompt Chaining** (Sequential prompt workflows with gates)
-- 🔍 **Evaluator Optimiser** (Generate and optimize through iterative feedback)
-- 👷 **Orchestrator Workers** (Distribute tasks among specialized workers)
-- ⚡ **Parallelisation** (Execute tasks in parallel for improved performance)
-- 🔁 **Repetitive Agents** (Handle repetitive tasks through automated loops)
-- 🤖 **Autonomous Workflow** (Monitor, act, adapt based on environment feedback)
-
-**Agent Types:**
-- 🖼️ **Image Generation Agent** (Create images from text descriptions)
-- 📷 **Image to Text Agent** (Extract text and descriptions from images)
-- 🎬 **Video Agent** (Analyze and process video content)
-- 📊 **Data Analyst Agent** (Analyze data and generate insights)
-- 💰 **Finance Agent** (Financial analysis and recommendations)
-- 🛒 **Shopping Agent** (Price comparison and shopping assistance)
-- ⭐ **Recommendation Agent** (Personalized recommendations)
-- 📖 **Wikipedia Agent** (Search and extract Wikipedia information)
-- 💻 **Programming Agent** (Code development and analysis)
-- 📝 **Markdown Agent** (Generate and format Markdown content)
-- 🔀 **Router Agent** (Dynamic task routing with cost optimization)
-
-**MCP Protocol:**
-- 🔌 **MCP Transports** (stdio, Streamable HTTP, WebSocket, SSE - Protocol 2025-11-25)
-- 🌐 **WebSocket MCP** (Real-time bidirectional connections with auto-reconnect)
-- 🔐 **MCP Security** (Origin validation, DNS rebinding prevention, secure sessions)
-- 🔄 **MCP Resumability** (SSE stream recovery via Last-Event-ID)
-
-**Safety & Control:**
-- 🤝 **Agent Handoffs** (Transfer context between specialized agents)
-- 🛡️ **Guardrails** (Input/output validation and safety checks)
-- ✅ **Human Approval** (Require human confirmation for critical actions)
-- 💬 **Sessions Management** (Isolated conversation contexts)
-- 🔄 **Stateful Agents** (Maintain state across interactions)
-
-**Developer Tools:**
-- ⚡ **Fast Context** (Rapid parallel code search - 10-20x faster than traditional methods)
-- 📜 **Rules & Instructions** (Auto-discover CLAUDE.md, AGENTS.md, GEMINI.md)
-- 🪝 **Hooks** (Pre/post operation hooks for custom logic)
-- 📈 **Telemetry** (Track agent performance and usage)
-- 📹 **Camera Integration** (Capture and analyze camera input)
-
-## Other Features
-
-- 🔄 Use CrewAI or AG2 (Formerly AutoGen) Framework
-- 💻 Chat with ENTIRE Codebase
-- 🎨 Interactive UIs
-- 📄 YAML-based Configuration
-- 🛠️ Custom Tool Integration
-- 🔍 Internet Search Capability (Tavily, You.com, Exa, DuckDuckGo, Crawl4AI)
-- 🖼️ Vision Language Model (VLM) Support
-- 🎙️ Real-time Voice Interaction
-
-## Video Tutorials
+Learn PraisonAI through our comprehensive video series:
 
 | Topic | Video |
 |-------|--------|
@@ -2115,3 +2318,58 @@ cd src/praisonai && uv publish
 | Call Interface | [![Call](https://img.youtube.com/vi/m1cwrUG2iAk/0.jpg)](https://www.youtube.com/watch?v=m1cwrUG2iAk) |
 | Reasoning Extract Agents | [![Reasoning Extract](https://img.youtube.com/vi/2PPamsADjJA/0.jpg)](https://www.youtube.com/watch?v=2PPamsADjJA) |
 
+---
+
+## 👥 Contributing
+
+We welcome contributions from the community! Here's how you can contribute:
+
+1. **Fork on GitHub** - Use the "Fork" button on the [repository page](https://github.com/MervinPraison/PraisonAI)
+2. **Clone your fork** - `git clone https://github.com/yourusername/praisonAI.git`
+3. **Create a branch** - `git checkout -b new-feature`
+4. **Make changes and commit** - `git commit -am "Add some feature"`
+5. **Push to your fork** - `git push origin new-feature`
+6. **Submit a pull request** - Via GitHub's web interface
+7. **Await feedback** - From project maintainers
+
+---
+
+## 🔧 Development
+
+### Using uv
+
+```bash
+# Install uv if you haven't already
+pip install uv
+
+# Install from requirements
+uv pip install -r pyproject.toml
+
+# Install with extras
+uv pip install -r pyproject.toml --extra code
+uv pip install -r pyproject.toml --extra "crewai,autogen"
+```
+
+### Bump and Release
+
+```bash
+# From project root - bumps version and releases in one command
+python src/praisonai/scripts/bump_and_release.py 2.2.99
+
+# With praisonaiagents dependency
+python src/praisonai/scripts/bump_and_release.py 2.2.99 --agents 0.0.169
+
+# Then publish
+cd src/praisonai && uv publish
+```
+
+---
+
+<div align="center">
+  <p><strong>Made with ❤️ by the PraisonAI Team</strong></p>
+  <p>
+    <a href="https://docs.praison.ai">Documentation</a> •
+    <a href="https://github.com/MervinPraison/PraisonAI">GitHub</a> •
+    <a href="https://github.com/MervinPraison/PraisonAI/issues">Issues</a>
+  </p>
+</div>

src/praisonai/agents.yaml

@@ -1,44 +1,49 @@
+# Movie Script Workflow - Cat in Mars
+# Uses the modern agents + steps format
+
+name: Create Movie Script About Cat in Mars
+description: A sequential workflow to research, design narrative, and write a movie script
 framework: praisonai
-process: sequential
-topic: create movie script about cat in mars
-memory: false
-roles:
+
+workflow:
+  verbose: true
+
+agents:
   researcher:
-    backstory: Skilled in research, with a focus on gathering accurate and relevant
-      information.
+    name: Researcher
+    role: Research Analyst
     goal: Gather information about Mars and cats
-    role: Researcher
-    min_reflect: 1
-    max_reflect: 2
-    tasks:
-      research_task:
-        description: Research about Mars, its environment, and the feasibility of
-          a cat being on Mars. Also, research about cat behavior and characteristics.
-        expected_output: Document with research findings on Mars and cats.
+    backstory: Skilled in research, with a focus on gathering accurate and relevant information.
+    instructions: |
+      Research about Mars, its environment, and the feasibility of a cat being on Mars.
+      Also, research about cat behavior and characteristics.
     tools:
-    - search_tool
+      - search_tool
+
   narrative_designer:
-    backstory: Skilled in narrative development, with a focus on creating engaging
-      stories.
+    name: Narrative Designer
+    role: Story Concept Developer
     goal: Create a story concept for a movie about a cat in Mars
-    role: Narrative Designer
-    tasks:
-      story_concept_development:
-        description: Use the research findings to craft a unique story concept for
-          a movie about a cat in Mars.
-        expected_output: Document with narrative arcs, character bios, and settings.
-    tools:
-    - ''
+    backstory: Skilled in narrative development, with a focus on creating engaging stories.
+    instructions: |
+      Use the research findings to craft a unique story concept for a movie about a cat in Mars.
+      Create narrative arcs, character bios, and settings.
+
   scriptwriter:
-    backstory: Expert in dialogue and script structure, translating concepts into
-      scripts.
+    name: Scriptwriter
+    role: Script Writer
     goal: Write a movie script about a cat in Mars
-    role: Scriptwriter
-    tasks:
-      scriptwriting_task:
-        description: Turn the story concept into a production-ready movie script,
-          including dialogue and scene details.
-        expected_output: Final movie script with dialogue and scene details.
-    tools:
-    - ''
-dependencies: []
+    backstory: Expert in dialogue and script structure, translating concepts into scripts.
+    instructions: |
+      Turn the story concept into a production-ready movie script,
+      including dialogue and scene details.
+
+steps:
+  - agent: researcher
+    action: "Research about Mars environment and cat behavior for the movie concept"
+
+  - agent: narrative_designer
+    action: "Create story concept based on research: {{previous_output}}"
+
+  - agent: scriptwriter
+    action: "Write the final movie script based on the story concept: {{previous_output}}"

src/praisonai/agents_n8n.json

@@ -0,0 +1,133 @@
+{
+  "id": "e022a3a1",
+  "name": "Create Movie Script About Cat in Mars",
+  "nodes": [
+    {
+      "id": "trigger",
+      "name": "Webhook",
+      "type": "n8n-nodes-base.webhook",
+      "typeVersion": 2,
+      "position": [
+        250,
+        300
+      ],
+      "webhookId": "dd7cf5cb72d19eae",
+      "parameters": {
+        "path": "create-movie-script-about-cat-in-mars",
+        "httpMethod": "POST",
+        "responseMode": "lastNode",
+        "options": {}
+      }
+    },
+    {
+      "id": "agent_0",
+      "name": "Researcher",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        450,
+        300
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "http://127.0.0.1:8005/agents/researcher",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ JSON.stringify({ query: $json.body?.query || $json.query || 'Research about Mars environment and cat behavior for the movie concept' }) }}",
+        "options": {
+          "timeout": 300000
+        }
+      },
+      "notes": "Agent: Researcher\nTask: Research about Mars environment and cat behavior for the movie concept"
+    },
+    {
+      "id": "agent_1",
+      "name": "Narrative Designer",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        700,
+        300
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "http://127.0.0.1:8005/agents/narrative_designer",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ JSON.stringify({ query: $json.response || 'Create story concept based on research: previous_output' }) }}",
+        "options": {
+          "timeout": 300000
+        }
+      },
+      "notes": "Agent: Narrative Designer\nTask: Create story concept based on research: {{previous_output}}"
+    },
+    {
+      "id": "agent_2",
+      "name": "Scriptwriter",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        950,
+        300
+      ],
+      "parameters": {
+        "method": "POST",
+        "url": "http://127.0.0.1:8005/agents/scriptwriter",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ JSON.stringify({ query: $json.response || 'Write the final movie script based on the story concept: previous_output' }) }}",
+        "options": {
+          "timeout": 300000
+        }
+      },
+      "notes": "Agent: Scriptwriter\nTask: Write the final movie script based on the story concept: {{previous_output}}"
+    }
+  ],
+  "connections": {
+    "Webhook": {
+      "main": [
+        [
+          {
+            "node": "Researcher",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Researcher": {
+      "main": [
+        [
+          {
+            "node": "Narrative Designer",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Narrative Designer": {
+      "main": [
+        [
+          {
+            "node": "Scriptwriter",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "active": false,
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "versionId": "1",
+  "pinData": {},
+  "meta": {
+    "instanceId": "praisonai-export",
+    "templateCredsSetupCompleted": true,
+    "description": "A sequential workflow to research, design narrative, and write a movie script"
+  },
+  "tags": []
+}

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.26.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.26.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.38.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.38.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/agents_generator.py

@@ -327,7 +327,8 @@ class AgentsGenerator:
             # Route to YAMLWorkflowParser for advanced workflow patterns
             return self._run_yaml_workflow(config)
 
-        topic = config.get('topic', '')
+        # Get workflow input: 'input' is canonical, 'topic' is alias for backward compatibility
+        topic = config.get('input', config.get('topic', ''))
         tools_dict = {}
         
         # Only try to use praisonai_tools if it's available and needed
@@ -441,6 +442,15 @@ class AgentsGenerator:
         if 'name' not in config:
             config['name'] = config.get('topic', 'Workflow')
         
+        # Pass model from config_list to workflow as default_llm
+        if self.config_list and self.config_list[0].get('model'):
+            model_from_cli = self.config_list[0]['model']
+            # Set default_llm in workflow config if not already set
+            if 'workflow' not in config:
+                config['workflow'] = {}
+            if 'default_llm' not in config['workflow']:
+                config['workflow']['default_llm'] = model_from_cli
+        
         # Convert config back to YAML string for parser
         # Note: YAMLWorkflowParser handles 'roles' to 'agents' conversion internally
         import yaml as yaml_module
@@ -450,11 +460,11 @@ class AgentsGenerator:
         parser = YAMLWorkflowParser()
         workflow = parser.parse_string(yaml_content)
         
-        # Get input from topic or variables
-        input_data = config.get('topic', '')
+        # Get input: 'input' is canonical, 'topic' is alias for backward compatibility
+        input_data = config.get('input', config.get('topic', ''))
         
         # Execute workflow
-        self.logger.info(f"Running workflow: {workflow.name}")
+        self.logger.debug(f"Running workflow: {workflow.name}")
         result = workflow.start(input_data)
         
         if result.get("status") == "completed":

src/praisonai/praisonai/cli/features/__init__.py

@@ -20,6 +20,7 @@ Features:
 - router: Smart model selection
 - flow_display: Visual workflow tracking
 - workflow: YAML workflow management
+- n8n: Export workflows to n8n visual editor
 """
 
 # Type hints available for IDE support
@@ -41,6 +42,7 @@ __all__ = [
     'RouterHandler',
     'FlowDisplayHandler',
     'WorkflowHandler',
+    'N8nHandler',
 ]
 
 def __getattr__(name):
@@ -90,4 +92,7 @@ def __getattr__(name):
     elif name == 'WorkflowHandler':
         from .workflow import WorkflowHandler
         return WorkflowHandler
+    elif name == 'N8nHandler':
+        from .n8n import N8nHandler
+        return N8nHandler
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai/praisonai/cli/features/flow_display.py

@@ -1,25 +1,31 @@
 """
 Flow Display Handler for CLI.
 
-Provides visual workflow tracking.
+Shows a visual flow diagram of the workflow WITHOUT executing it.
 Usage: praisonai agents.yaml --flow-display
 """
 
-from typing import Any, Dict, Tuple, List
+from typing import Any, Dict, Tuple
 from .base import FlagHandler
+import os
+import yaml
 
 
 class FlowDisplayHandler(FlagHandler):
     """
     Handler for --flow-display flag.
     
-    Enables visual workflow tracking for multi-agent executions.
+    Shows a visual flow diagram/chart of agents and tasks WITHOUT executing.
+    This allows users to preview the workflow structure before running it.
     
     Example:
         praisonai agents.yaml --flow-display
-        praisonai "Complex task" --flow-display
     """
     
+    def __init__(self, verbose: bool = False):
+        super().__init__(verbose)
+        self._console = None
+    
     @property
     def feature_name(self) -> str:
         return "flow_display"
@@ -30,160 +36,531 @@ class FlowDisplayHandler(FlagHandler):
     
     @property
     def flag_help(self) -> str:
-        return "Enable visual workflow tracking"
+        return "Show workflow flow diagram without executing"
+    
+    def _get_console(self):
+        """Get or create Rich Console."""
+        if self._console is None:
+            try:
+                from rich.console import Console
+                self._console = Console()
+            except ImportError:
+                pass
+        return self._console
     
     def check_dependencies(self) -> Tuple[bool, str]:
-        """Check if FlowDisplay is available."""
+        """Check if Rich is available."""
         try:
             import importlib.util
-            if importlib.util.find_spec("praisonaiagents") is not None:
-                return True, ""
-            return False, "praisonaiagents not installed"
+            rich_available = importlib.util.find_spec("rich") is not None
+            if not rich_available:
+                return False, "rich not installed. Install with: pip install rich"
+            return True, ""
         except ImportError:
-            return False, "praisonaiagents not installed. Install with: pip install praisonaiagents"
-    
-    def _get_flow_display(self):
-        """Get FlowDisplay class lazily."""
-        try:
-            from praisonaiagents import FlowDisplay
-            return FlowDisplay
-        except ImportError:
-            return None
-    
-    def create_flow_display(self, title: str = "Workflow") -> Any:
-        """
-        Create a FlowDisplay instance.
-        
-        Args:
-            title: Title for the workflow display
-            
-        Returns:
-            FlowDisplay instance or None
-        """
-        FlowDisplay = self._get_flow_display()
-        if not FlowDisplay:
-            self.print_status(
-                "FlowDisplay requires praisonaiagents. Install with: pip install praisonaiagents",
-                "error"
-            )
-            return None
-        
-        try:
-            return FlowDisplay(title=title)
-        except Exception as e:
-            self.log(f"Failed to create FlowDisplay: {e}", "error")
-            return None
+            return False, "rich not installed. Install with: pip install rich"
     
     def apply_to_agent_config(self, config: Dict[str, Any], flag_value: Any) -> Dict[str, Any]:
-        """
-        Apply flow display configuration.
-        
-        Args:
-            config: Agent configuration dictionary
-            flag_value: Boolean indicating flow display
-            
-        Returns:
-            Modified configuration
-        """
+        """Apply flow display configuration."""
         if flag_value:
             config['flow_display'] = True
         return config
     
-    def display_workflow_start(self, workflow_name: str, agents: List[str] = None):
+    def display_flow_diagram(self, yaml_file: str, show_footer: bool = True) -> bool:
         """
-        Display workflow start.
+        Display a visual flow diagram of the workflow from YAML file.
         
         Args:
-            workflow_name: Name of the workflow
-            agents: List of agent names
-        """
-        self.print_status(f"\n🚀 Starting Workflow: {workflow_name}", "info")
-        self.print_status("=" * 50, "info")
-        
-        if agents:
-            self.print_status("Agents:", "info")
-            for i, agent in enumerate(agents, 1):
-                self.print_status(f"  {i}. {agent}", "info")
-        
-        self.print_status("=" * 50, "info")
-    
-    def display_step(self, step_num: int, step_name: str, status: str = "running"):
-        """
-        Display a workflow step.
-        
-        Args:
-            step_num: Step number
-            step_name: Name of the step
-            status: Step status (running, completed, failed)
-        """
-        icons = {
-            'running': '⏳',
-            'completed': '✅',
-            'failed': '❌',
-            'pending': '⬜'
-        }
-        icon = icons.get(status, '•')
-        self.print_status(f"  {icon} Step {step_num}: {step_name}", "info")
-    
-    def display_workflow_end(self, success: bool = True, duration: float = None):
-        """
-        Display workflow end.
-        
-        Args:
-            success: Whether workflow completed successfully
-            duration: Workflow duration in seconds
-        """
-        self.print_status("=" * 50, "info")
-        
-        if success:
-            msg = "✅ Workflow completed successfully"
-        else:
-            msg = "❌ Workflow failed"
-        
-        if duration:
-            msg += f" ({duration:.2f}s)"
-        
-        self.print_status(msg, "success" if success else "error")
-    
-    def track_execution(self, func):
-        """
-        Decorator to track function execution in flow display.
-        
-        Args:
-            func: Function to track
+            yaml_file: Path to the agents.yaml file
+            show_footer: Whether to show the "run without --flow-display" footer
             
         Returns:
-            Wrapped function
+            True if displayed successfully, False otherwise
         """
-        import functools
+        console = self._get_console()
+        if not console:
+            print("Rich library not available for flow display")
+            return False
         
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            func_name = func.__name__
+        # Load YAML config
+        try:
+            if not os.path.exists(yaml_file):
+                console.print(f"[red]Error: File not found: {yaml_file}[/red]")
+                return False
             
-            self.display_step(1, func_name, "running")
+            with open(yaml_file, 'r') as f:
+                config = yaml.safe_load(f)
+        except Exception as e:
+            console.print(f"[red]Error loading YAML: {e}[/red]")
+            return False
+        
+        # Detect YAML format: 'roles' (old) or 'agents'+'steps' (new workflow)
+        has_roles = 'roles' in config and config['roles']
+        has_agents = 'agents' in config and config['agents']
+        has_steps = 'steps' in config and config['steps']
+        
+        if not has_roles and not has_agents:
+            console.print("[red]Error: Invalid YAML format. No 'roles' or 'agents' found.[/red]")
+            return False
+        
+        try:
+            from rich.panel import Panel
+            from rich.table import Table
+            from rich.text import Text
+            from rich import box
             
+            # Determine format type
+            is_workflow_format = has_agents and has_steps
+            
+            # Extract workflow info based on format
+            if is_workflow_format:
+                name = config.get('name', 'Workflow')
+                description = config.get('description', '')
+                framework = config.get('framework', 'praisonai')
+                workflow_config = config.get('workflow', {})
+                memory = workflow_config.get('memory_config', {}).get('persist', False)
+                num_agents = len(config['agents'])
+                num_steps = len(config['steps'])
+            else:
+                name = config.get('topic', 'Workflow')
+                description = ''
+                framework = config.get('framework', 'praisonai')
+                process = config.get('process', 'sequential')
+                memory = config.get('memory', False)
+                num_agents = len(config['roles'])
+                num_steps = sum(len(details.get('tasks', {})) for details in config['roles'].values())
+            
+            # Build the flow diagram
+            console.print()
+            
+            # === HEADER ===
+            header = Text()
+            header.append("📊 WORKFLOW FLOW DIAGRAM\n", style="bold cyan")
+            header.append("─" * 40, style="dim")
+            
+            header_panel = Panel(
+                header,
+                border_style="cyan",
+                box=box.DOUBLE_EDGE,
+                padding=(0, 2)
+            )
+            console.print(header_panel)
+            
+            # === WORKFLOW INFO ===
+            info_table = Table(show_header=False, box=None, padding=(0, 2))
+            info_table.add_column("Key", style="bold yellow")
+            info_table.add_column("Value", style="white")
+            
+            info_table.add_row("📋 Name:", name)
+            if description:
+                info_table.add_row("📝 Description:", description)
+            
+            # Show input if present ('input' is canonical, 'topic' is alias)
+            workflow_input = config.get('input', config.get('topic', ''))
+            if workflow_input:
+                info_table.add_row("💬 Input:", workflow_input)
+            
+            info_table.add_row("⚙️  Framework:", framework)
+            
+            if is_workflow_format:
+                info_table.add_row("🔄 Format:", "WORKFLOW (steps-based)")
+                planning = workflow_config.get('planning', False)
+                info_table.add_row("🧠 Planning:", "✅ Enabled" if planning else "❌ Disabled")
+            else:
+                info_table.add_row("🔄 Process:", process.upper())
+            
+            info_table.add_row("💾 Memory:", "✅ Enabled" if memory else "❌ Disabled")
+            info_table.add_row("👥 Agents:", str(num_agents))
+            info_table.add_row("📝 Steps:", str(num_steps))
+            
+            console.print(Panel(info_table, title="[bold white]Workflow Configuration[/bold white]", 
+                               border_style="blue", box=box.ROUNDED))
+            console.print()
+            
+            # === FLOW DIAGRAM ===
+            if is_workflow_format:
+                self._display_steps_flow(console, config)
+            else:
+                process = config.get('process', 'sequential')
+                if process == 'sequential':
+                    self._display_sequential_flow(console, config)
+                elif process == 'hierarchical':
+                    self._display_hierarchical_flow(console, config)
+                else:
+                    self._display_sequential_flow(console, config)
+            
+            # === DETAILED AGENT INFO ===
+            console.print()
+            if is_workflow_format:
+                self._display_workflow_agent_details(console, config)
+            else:
+                self._display_agent_details(console, config)
+            
+            # === FOOTER ===
+            if show_footer:
+                console.print()
+                footer = Text()
+                footer.append("💡 ", style="bold")
+                footer.append("To execute this workflow, run without --flow-display flag", style="dim italic")
+                console.print(Panel(footer, border_style="dim", box=box.ROUNDED))
+            console.print()
+            
+            return True
+            
+        except ImportError as e:
+            console.print(f"[red]Error: Rich components not available: {e}[/red]")
+            return False
+    
+    def _display_sequential_flow(self, console, config: Dict):
+        """Display sequential flow diagram."""
+        from rich.panel import Panel
+        from rich.text import Text
+        from rich import box
+        
+        roles = list(config['roles'].items())
+        
+        # Box width (content area)
+        BOX_WIDTH = 36
+        
+        def pad_line(content: str, width: int = BOX_WIDTH) -> str:
+            """Pad content to fixed width."""
+            padding = width - len(content)
+            if padding > 0:
+                return content + " " * padding
+            return content[:width]
+        
+        flow_text = Text()
+        flow_text.append("  SEQUENTIAL EXECUTION FLOW\n\n", style="bold magenta")
+        
+        for i, (role_key, details) in enumerate(roles):
+            role_name = details.get('role', role_key)
+            tasks = list(details.get('tasks', {}).keys())
+            
+            # Agent box
+            if i == 0:
+                flow_text.append("       ┌── START ──┐\n", style="green")
+                flow_text.append("             │\n", style="dim")
+                flow_text.append("             ▼\n", style="dim")
+            
+            # Agent node
+            flow_text.append("       ╔════════════════════════════════════╗\n", style="cyan")
+            line = f" Agent {i+1}: {role_name}"
+            flow_text.append(f"       ║{pad_line(line)}║\n", style="cyan")
+            
+            # Tasks
+            for task in tasks:
+                line = f"   -> {task}"
+                flow_text.append(f"       ║{pad_line(line)}║\n", style="dim white")
+            
+            flow_text.append("       ╚════════════════════════════════════╝\n", style="cyan")
+            
+            # Arrow to next
+            if i < len(roles) - 1:
+                flow_text.append("             │\n", style="dim")
+                flow_text.append("          output\n", style="dim italic")
+                flow_text.append("             ▼\n", style="dim")
+            else:
+                flow_text.append("             │\n", style="dim")
+                flow_text.append("             ▼\n", style="dim")
+                flow_text.append("       └── END ────┘\n", style="red")
+        
+        console.print(Panel(flow_text, border_style="magenta", box=box.DOUBLE_EDGE,
+                           title="[bold white]Execution Flow[/bold white]"))
+    
+    def _display_hierarchical_flow(self, console, config: Dict):
+        """Display hierarchical flow diagram."""
+        from rich.panel import Panel
+        from rich.text import Text
+        from rich import box
+        
+        manager_llm = config.get('manager_llm', 'default')
+        
+        flow_text = Text()
+        flow_text.append("👑 HIERARCHICAL EXECUTION FLOW\n\n", style="bold magenta")
+        
+        # Manager at top
+        flow_text.append("         ┌──────────────────────┐\n", style="yellow")
+        flow_text.append("         │  👑 MANAGER AGENT    │\n", style="bold yellow")
+        flow_text.append(f"         │  LLM: {manager_llm:<14}│\n", style="dim yellow")
+        flow_text.append("         └──────────┬───────────┘\n", style="yellow")
+        flow_text.append("                    │\n", style="dim")
+        flow_text.append("         ┌──────────┴───────────┐\n", style="dim")
+        flow_text.append("         │    delegates to      │\n", style="dim italic")
+        flow_text.append("         └──────────┬───────────┘\n", style="dim")
+        
+        roles = list(config['roles'].items())
+        num_agents = len(roles)
+        
+        # Draw branches
+        if num_agents > 0:
+            branch_line = "    "
+            for i in range(num_agents):
+                if i == 0:
+                    branch_line += "┌" + "─" * 8
+                elif i == num_agents - 1:
+                    branch_line += "┬" + "─" * 8 + "┐"
+                else:
+                    branch_line += "┬" + "─" * 8
+            flow_text.append(branch_line + "\n", style="dim")
+            
+            # Agent boxes
+            for i, (role_key, details) in enumerate(roles):
+                flow_text.append("\n    ╔═══════════════╗", style="cyan")
+            flow_text.append("\n")
+            
+            for i, (role_key, details) in enumerate(roles):
+                role_name = details.get('role', role_key)[:12]
+                flow_text.append(f"    ║ 🤖 {role_name:<10} ║", style="cyan")
+            flow_text.append("\n")
+            
+            for i, (role_key, details) in enumerate(roles):
+                flow_text.append("    ╚═══════════════╝", style="cyan")
+            flow_text.append("\n")
+        
+        console.print(Panel(flow_text, border_style="magenta", box=box.DOUBLE_EDGE,
+                           title="[bold white]Execution Flow[/bold white]"))
+    
+    def _display_agent_details(self, console, config: Dict):
+        """Display detailed agent information."""
+        from rich.table import Table
+        from rich import box
+        
+        table = Table(
+            title="[bold cyan]📋 Agent & Task Details[/bold cyan]",
+            box=box.ROUNDED,
+            show_header=True,
+            header_style="bold magenta",
+            border_style="blue",
+            padding=(0, 1),
+            expand=True
+        )
+        
+        table.add_column("#", style="dim", width=3, justify="center")
+        table.add_column("Agent", style="bold yellow", min_width=15)
+        table.add_column("Role", style="cyan", min_width=15)
+        table.add_column("Goal", style="white", min_width=25, overflow="fold")
+        table.add_column("Tasks", style="green", min_width=20)
+        table.add_column("Tools", style="magenta", min_width=15)
+        
+        for i, (role_key, details) in enumerate(config['roles'].items(), 1):
+            role_name = details.get('role', role_key)
+            goal = details.get('goal', '-')
+            if len(goal) > 50:
+                goal = goal[:47] + "..."
+            
+            tasks = list(details.get('tasks', {}).keys())
+            tasks_str = "\n".join(f"• {t}" for t in tasks) if tasks else "-"
+            
+            tools = details.get('tools', [])
+            tools_str = ", ".join(t for t in tools if t) if tools else "-"
+            
+            table.add_row(
+                str(i),
+                role_name,
+                role_key,
+                goal,
+                tasks_str,
+                tools_str
+            )
+        
+        console.print(table)
+    
+    def _display_steps_flow(self, console, config: Dict):
+        """Display steps-based workflow flow diagram."""
+        from rich.panel import Panel
+        from rich.text import Text
+        from rich import box
+        
+        steps = config.get('steps', [])
+        agents = config.get('agents', {})
+        
+        # Box width (content area)
+        BOX_WIDTH = 36
+        
+        def pad_line(content: str, width: int = BOX_WIDTH) -> str:
+            """Pad content to fixed width, accounting for emoji width."""
+            # Emojis typically take 2 character widths
+            emoji_count = sum(1 for c in content if ord(c) > 0x1F300)
+            actual_len = len(content) + emoji_count  # Add extra for emoji width
+            padding = width - actual_len
+            if padding > 0:
+                return content + " " * padding
+            return content[:width]
+        
+        flow_text = Text()
+        flow_text.append("  STEPS-BASED EXECUTION FLOW\n\n", style="bold magenta")
+        
+        flow_text.append("       ┌── START ──┐\n", style="green")
+        flow_text.append("             │\n", style="dim")
+        flow_text.append("             ▼\n", style="dim")
+        
+        for i, step in enumerate(steps):
+            # Determine step type
+            agent_key = step.get('agent', '')
+            step_name = step.get('name', '')
+            
+            # Check for special step types
+            has_route = 'route' in step
+            has_parallel = 'parallel' in step
+            has_loop = 'loop' in step
+            has_repeat = 'repeat' in step
+            
+            if has_route:
+                # Route step
+                flow_text.append("       ╔════════════════════════════════════╗\n", style="yellow")
+                line = f" ROUTE: {step_name or 'routing'}"
+                flow_text.append(f"       ║{pad_line(line)}║\n", style="yellow")
+                
+                routes = step['route']
+                for route_name, route_agents in routes.items():
+                    agents_str = ", ".join(route_agents) if isinstance(route_agents, list) else str(route_agents)
+                    line = f"   -> {route_name}: {agents_str}"
+                    flow_text.append(f"       ║{pad_line(line)}║\n", style="yellow")
+                
+                flow_text.append("       ╚════════════════════════════════════╝\n", style="yellow")
+                
+            elif has_parallel:
+                # Parallel step
+                flow_text.append("       ╔════════════════════════════════════╗\n", style="green")
+                line = f" PARALLEL: {step_name or 'parallel'}"
+                flow_text.append(f"       ║{pad_line(line)}║\n", style="green")
+                
+                for p_step in step['parallel']:
+                    p_agent = p_step.get('agent', '?')
+                    line = f"   |-- {p_agent}"
+                    flow_text.append(f"       ║{pad_line(line)}║\n", style="green")
+                
+                flow_text.append("       ╚════════════════════════════════════╝\n", style="green")
+                
+            else:
+                # Regular agent step
+                agent_info = agents.get(agent_key, {})
+                agent_name = agent_info.get('name', agent_key)
+                
+                flow_text.append("       ╔════════════════════════════════════╗\n", style="cyan")
+                line = f" Step {i+1}: {agent_name}"
+                flow_text.append(f"       ║{pad_line(line)}║\n", style="cyan")
+                
+                # Show modifiers
+                if has_loop:
+                    loop_over = step['loop'].get('over', '?')
+                    line = f"   [loop over: {loop_over}]"
+                    flow_text.append(f"       ║{pad_line(line)}║\n", style="dim magenta")
+                
+                if has_repeat:
+                    until = step['repeat'].get('until', '?')
+                    max_iter = step['repeat'].get('max_iterations', '?')
+                    line = f"   [repeat until: {until} max:{max_iter}]"
+                    flow_text.append(f"       ║{pad_line(line)}║\n", style="dim magenta")
+                
+                flow_text.append("       ╚════════════════════════════════════╝\n", style="cyan")
+            
+            # Arrow to next
+            if i < len(steps) - 1:
+                flow_text.append("             │\n", style="dim")
+                flow_text.append("             ▼\n", style="dim")
+        
+        flow_text.append("             │\n", style="dim")
+        flow_text.append("             ▼\n", style="dim")
+        flow_text.append("       └── END ────┘\n", style="red")
+        
+        console.print(Panel(flow_text, border_style="magenta", box=box.DOUBLE_EDGE,
+                           title="[bold white]Execution Flow[/bold white]"))
+    
+    def _display_workflow_agent_details(self, console, config: Dict):
+        """Display detailed agent information for workflow format."""
+        from rich.table import Table
+        from rich import box
+        
+        table = Table(
+            title="[bold cyan]📋 Agent Details[/bold cyan]",
+            box=box.ROUNDED,
+            show_header=True,
+            header_style="bold magenta",
+            border_style="blue",
+            padding=(0, 1),
+            expand=True
+        )
+        
+        table.add_column("#", style="dim", width=3, justify="center")
+        table.add_column("Agent Key", style="bold yellow", min_width=15)
+        table.add_column("Name", style="cyan", min_width=15)
+        table.add_column("Role", style="white", min_width=20)
+        table.add_column("Goal", style="green", min_width=25, overflow="fold")
+        
+        for i, (agent_key, details) in enumerate(config['agents'].items(), 1):
+            name = details.get('name', agent_key)
+            role = details.get('role', '-')
+            goal = details.get('goal', '-')
+            if len(goal) > 40:
+                goal = goal[:37] + "..."
+            
+            table.add_row(
+                str(i),
+                agent_key,
+                name,
+                role,
+                goal
+            )
+        
+        console.print(table)
+    
+    def display_workflow_start(self, workflow_name: str, agents: list) -> None:
+        """
+        Display workflow start message.
+        
+        Args:
+            workflow_name: Name of the workflow being started
+            agents: List of agent names in the workflow
+        """
+        console = self._get_console()
+        if console:
             try:
-                result = func(*args, **kwargs)
-                self.display_step(1, func_name, "completed")
-                return result
-            except Exception:
-                self.display_step(1, func_name, "failed")
-                raise
-        
-        return wrapper
+                from rich.panel import Panel
+                from rich import box
+                
+                agents_str = ", ".join(agents) if agents else "No agents"
+                content = f"🚀 Starting: {workflow_name}\n👥 Agents: {agents_str}"
+                console.print(Panel(content, title="[bold cyan]Workflow Started[/bold cyan]", 
+                                   border_style="cyan", box=box.ROUNDED))
+            except ImportError:
+                print(f"Starting workflow: {workflow_name} with agents: {agents}")
     
-    def execute(self, workflow_name: str = None, **kwargs) -> Any:
+    def display_workflow_end(self, success: bool = True) -> None:
         """
-        Execute flow display setup.
+        Display workflow end message.
         
         Args:
-            workflow_name: Name of the workflow
+            success: Whether the workflow completed successfully
+        """
+        console = self._get_console()
+        if console:
+            try:
+                from rich.panel import Panel
+                from rich import box
+                
+                if success:
+                    content = "✅ Workflow completed successfully"
+                    style = "green"
+                else:
+                    content = "❌ Workflow failed"
+                    style = "red"
+                
+                console.print(Panel(content, title=f"[bold {style}]Workflow Ended[/bold {style}]", 
+                                   border_style=style, box=box.ROUNDED))
+            except ImportError:
+                status = "successfully" if success else "with errors"
+                print(f"Workflow ended {status}")
+    
+    def execute(self, yaml_file: str = None, **kwargs) -> bool:
+        """
+        Execute flow display - shows diagram without running workflow.
+        
+        Args:
+            yaml_file: Path to the YAML file
             
         Returns:
-            FlowDisplay instance or None
+            True if displayed successfully
         """
-        if workflow_name:
-            self.display_workflow_start(workflow_name)
-        
-        return self.create_flow_display(workflow_name or "Workflow")
+        if yaml_file:
+            return self.display_flow_diagram(yaml_file)
+        return False

src/praisonai/praisonai/cli/features/n8n.py

@@ -0,0 +1,673 @@
+"""
+n8n Integration Handler for PraisonAI CLI.
+
+Converts PraisonAI agents.yaml workflows to n8n workflow JSON format
+and opens them in the n8n UI.
+
+Usage:
+    praisonai agents.yaml --n8n
+    praisonai agents.yaml --n8n --n8n-url http://localhost:5678
+"""
+
+import json
+import yaml
+import webbrowser
+import hashlib
+import os
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+try:
+    import requests
+    REQUESTS_AVAILABLE = True
+except ImportError:
+    REQUESTS_AVAILABLE = False
+
+from .base import FlagHandler
+
+
+class N8nHandler(FlagHandler):
+    """
+    Handler for n8n workflow export and visualization.
+    
+    Converts PraisonAI YAML workflows to n8n-compatible JSON format
+    and opens them in the n8n UI for visual editing.
+    """
+    
+    def __init__(self, verbose: bool = False, n8n_url: str = "http://localhost:5678",
+                 use_execute_command: bool = False, api_url: str = "http://127.0.0.1:8005"):
+        """
+        Initialize the n8n handler.
+        
+        Args:
+            verbose: Enable verbose output
+            n8n_url: Base URL of the n8n instance
+            use_execute_command: Use Execute Command nodes (runs praisonai directly)
+                                 instead of HTTP Request nodes
+            api_url: PraisonAI API URL that n8n will call (for tunnel/cloud deployments)
+        """
+        super().__init__(verbose=verbose)
+        self.n8n_url = n8n_url
+        self.praisonai_api_url = api_url
+        self.use_execute_command = use_execute_command
+    
+    @property
+    def feature_name(self) -> str:
+        return "n8n"
+    
+    @property
+    def flag_name(self) -> str:
+        return "n8n"
+    
+    @property
+    def flag_help(self) -> str:
+        return "Export workflow to n8n and open in browser"
+    
+    def execute(self, yaml_path: str, n8n_url: Optional[str] = None, 
+                open_browser: bool = True, **kwargs) -> Dict[str, Any]:
+        """
+        Execute the n8n export workflow.
+        
+        Args:
+            yaml_path: Path to the agents.yaml file
+            n8n_url: Optional custom n8n URL
+            open_browser: Whether to open the workflow in browser
+            
+        Returns:
+            Dictionary with workflow JSON and URL
+        """
+        if n8n_url:
+            self.n8n_url = n8n_url
+        
+        # Convert YAML to n8n workflow JSON
+        workflow_json = self.convert_yaml_to_n8n(yaml_path)
+        
+        # Save workflow JSON to file
+        output_path = self._save_workflow_json(workflow_json, yaml_path)
+        
+        self.print_status("✅ Workflow converted successfully!", "success")
+        self.print_status(f"📄 JSON saved to: {output_path}", "info")
+        
+        # Try to create workflow via n8n API
+        api_key = os.environ.get('N8N_API_KEY')
+        workflow_id = None
+        
+        if api_key and REQUESTS_AVAILABLE:
+            workflow_id = self._create_workflow_via_api(workflow_json, api_key)
+        
+        webhook_url = None
+        if workflow_id:
+            # Successfully created via API - open directly
+            url = f"{self.n8n_url}/workflow/{workflow_id}"
+            self.print_status("🚀 Workflow created in n8n!", "success")
+            
+            # Activate the workflow so webhook is available
+            if self._activate_workflow(workflow_id, api_key):
+                self.print_status("✅ Workflow activated!", "success")
+                
+                # Get webhook path from the workflow
+                trigger_node = next((n for n in workflow_json["nodes"] 
+                                    if n.get("type") == "n8n-nodes-base.webhook"), None)
+                if trigger_node:
+                    webhook_path = trigger_node["parameters"].get("path", "praisonai")
+                    webhook_url = f"{self.n8n_url}/webhook/{webhook_path}"
+                    self.print_status("", "info")
+                    self.print_status("🔗 Webhook URL (to trigger workflow):", "info")
+                    self.print_status(f"   POST {webhook_url}", "info")
+            else:
+                self.print_status("⚠️  Could not activate workflow (activate manually in n8n)", "warning")
+            
+            if open_browser:
+                self.open_in_browser(url)
+                self.print_status(f"🌐 Opening: {url}", "info")
+        else:
+            # Fallback to manual import instructions
+            url = self.generate_n8n_url(workflow_json, self.n8n_url)
+            
+            if not api_key:
+                self.print_status("", "info")
+                self.print_status("💡 Tip: Set N8N_API_KEY env var for auto-import", "info")
+                self.print_status("   Generate API key in n8n: Settings → API", "info")
+            
+            self.print_status("", "info")
+            self.print_status("📋 To import into n8n:", "info")
+            self.print_status("   1. Open n8n in your browser", "info")
+            self.print_status("   2. Click the three dots menu (⋮) in the top right", "info")
+            self.print_status("   3. Select 'Import from File'", "info")
+            self.print_status(f"   4. Choose: {output_path}", "info")
+            
+            if open_browser:
+                self.open_in_browser(url)
+                self.print_status(f"🌐 Opening n8n: {url}", "info")
+        
+        return {
+            "workflow": workflow_json,
+            "url": url,
+            "output_path": output_path,
+            "workflow_id": workflow_id,
+            "webhook_url": webhook_url
+        }
+    
+    def _create_workflow_via_api(self, workflow_json: Dict[str, Any], 
+                                  api_key: str) -> Optional[str]:
+        """
+        Create workflow in n8n via REST API.
+        
+        Args:
+            workflow_json: The n8n workflow JSON
+            api_key: n8n API key
+            
+        Returns:
+            Workflow ID if successful, None otherwise
+        """
+        if not REQUESTS_AVAILABLE:
+            return None
+        
+        try:
+            # Only include fields allowed by n8n API schema
+            # See: n8n/packages/cli/src/public-api/v1/handlers/workflows/spec/schemas/workflow.yml
+            workflow_data = {
+                "name": workflow_json.get("name", "PraisonAI Workflow"),
+                "nodes": workflow_json.get("nodes", []),
+                "connections": workflow_json.get("connections", {}),
+                "settings": workflow_json.get("settings", {"executionOrder": "v1"}),
+            }
+            
+            # Optional fields
+            if "staticData" in workflow_json:
+                workflow_data["staticData"] = workflow_json["staticData"]
+            
+            response = requests.post(
+                f"{self.n8n_url}/api/v1/workflows",
+                headers={
+                    "X-N8N-API-KEY": api_key,
+                    "Content-Type": "application/json"
+                },
+                json=workflow_data,
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                result = response.json()
+                return result.get('id')
+            else:
+                self.log(f"API error: {response.status_code} - {response.text}", "warning")
+                return None
+                
+        except Exception as e:
+            self.log(f"Failed to create workflow via API: {e}", "warning")
+            return None
+    
+    def _activate_workflow(self, workflow_id: str, api_key: str) -> bool:
+        """
+        Activate a workflow via n8n API.
+        
+        Args:
+            workflow_id: The workflow ID to activate
+            api_key: n8n API key
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        if not REQUESTS_AVAILABLE:
+            return False
+        
+        try:
+            response = requests.post(
+                f"{self.n8n_url}/api/v1/workflows/{workflow_id}/activate",
+                headers={
+                    "X-N8N-API-KEY": api_key,
+                    "Content-Type": "application/json"
+                },
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                return True
+            else:
+                self.log(f"Activation error: {response.status_code} - {response.text}", "warning")
+                return False
+                
+        except Exception as e:
+            self.log(f"Failed to activate workflow: {e}", "warning")
+            return False
+    
+    def convert_yaml_to_n8n(self, yaml_path: str, use_webhook: bool = True) -> Dict[str, Any]:
+        """
+        Convert a PraisonAI YAML workflow to n8n JSON format.
+        
+        The n8n workflow will have:
+        - A webhook trigger to receive requests
+        - One HTTP Request node per agent (calls /agents/{agent_name})
+        - Each agent node passes its output to the next agent
+        
+        Args:
+            yaml_path: Path to the agents.yaml file
+            use_webhook: Use webhook trigger for programmatic execution (default: True)
+            
+        Returns:
+            n8n workflow JSON as dictionary
+        """
+        # Load YAML file
+        with open(yaml_path, 'r') as f:
+            yaml_content = yaml.safe_load(f)
+        
+        # Extract workflow metadata
+        workflow_name = yaml_content.get('name', 'PraisonAI Workflow')
+        description = yaml_content.get('description', '')
+        
+        # Generate a unique webhook path from workflow name
+        webhook_path = workflow_name.lower().replace(' ', '-').replace('/', '-')[:50]
+        
+        # Get agents and steps
+        agents = yaml_content.get('agents', yaml_content.get('roles', {}))
+        steps = yaml_content.get('steps', [])
+        
+        # If no steps defined, create steps from agents
+        if not steps and agents:
+            steps = self._create_steps_from_agents(agents)
+        
+        # Build n8n nodes and connections
+        nodes = []
+        connections = {}
+        
+        # Add trigger node (webhook for programmatic execution, manual otherwise)
+        trigger_node = self._create_trigger_node(use_webhook=use_webhook, webhook_path=webhook_path)
+        nodes.append(trigger_node)
+        
+        # Track previous node for connections
+        prev_node_name = trigger_node["name"]
+        x_position = 450
+        
+        # Create one HTTP node per agent step
+        for i, step in enumerate(steps):
+            if isinstance(step, dict):
+                agent_id = step.get('agent', '')
+                action = step.get('action', step.get('description', ''))
+                agent_config = agents.get(agent_id, {})
+                
+                # Create HTTP node that calls the specific agent endpoint
+                agent_node = self._create_per_agent_node(
+                    agent_id=agent_id,
+                    agent_config=agent_config,
+                    action=action,
+                    position=[x_position, 300],
+                    index=i,
+                    is_first=(i == 0)
+                )
+                nodes.append(agent_node)
+                
+                # Connect to previous node
+                if prev_node_name not in connections:
+                    connections[prev_node_name] = {"main": [[]]}
+                connections[prev_node_name]["main"][0].append({
+                    "node": agent_node["name"],
+                    "type": "main",
+                    "index": 0
+                })
+                
+                prev_node_name = agent_node["name"]
+                x_position += 250
+        
+        # Build the complete workflow
+        # Generate a unique ID based on workflow name
+        workflow_id = hashlib.md5(workflow_name.encode()).hexdigest()[:8]
+        
+        workflow = {
+            "id": workflow_id,
+            "name": workflow_name,
+            "nodes": nodes,
+            "connections": connections,
+            "active": False,
+            "settings": {
+                "executionOrder": "v1"
+            },
+            "versionId": "1",
+            "pinData": {},
+            "meta": {
+                "instanceId": "praisonai-export",
+                "templateCredsSetupCompleted": True
+            },
+            "tags": []
+        }
+        
+        if description:
+            workflow["meta"]["description"] = description
+        
+        return workflow
+    
+    def _create_steps_from_agents(self, agents: Dict[str, Any]) -> List[Dict]:
+        """Create steps from agents when no steps are defined."""
+        steps = []
+        for agent_id, agent_config in agents.items():
+            if isinstance(agent_config, dict):
+                # Check for tasks nested in agent
+                tasks = agent_config.get('tasks', {})
+                if tasks:
+                    for task_id, task_config in tasks.items():
+                        steps.append({
+                            'agent': agent_id,
+                            'action': task_config.get('description', task_config.get('action', f'Execute {task_id}'))
+                        })
+                else:
+                    # Create a default step for the agent
+                    steps.append({
+                        'agent': agent_id,
+                        'action': agent_config.get('instructions', agent_config.get('goal', f'Execute {agent_id}'))
+                    })
+        return steps
+    
+    def _create_trigger_node(self, use_webhook: bool = False, 
+                              webhook_path: str = "praisonai") -> Dict[str, Any]:
+        """Create a trigger node (webhook or manual).
+        
+        Args:
+            use_webhook: If True, creates a webhook trigger for programmatic execution
+            webhook_path: Path for the webhook URL (only used if use_webhook=True)
+        """
+        if use_webhook:
+            # Generate a unique webhook ID
+            webhook_id = hashlib.md5(webhook_path.encode()).hexdigest()[:16]
+            return {
+                "id": "trigger",
+                "name": "Webhook",
+                "type": "n8n-nodes-base.webhook",
+                "typeVersion": 2,
+                "position": [250, 300],
+                "webhookId": webhook_id,
+                "parameters": {
+                    "path": webhook_path,
+                    "httpMethod": "POST",
+                    "responseMode": "lastNode",
+                    "options": {}
+                }
+            }
+        return {
+            "id": "trigger",
+            "name": "Manual Trigger",
+            "type": "n8n-nodes-base.manualTrigger",
+            "typeVersion": 1,
+            "position": [250, 300],
+            "parameters": {}
+        }
+    
+    def _create_per_agent_node(self, agent_id: str, agent_config: Dict,
+                                action: str, position: List[int],
+                                index: int, is_first: bool = False) -> Dict[str, Any]:
+        """
+        Create an HTTP Request node that calls a specific agent endpoint.
+        
+        Args:
+            agent_id: Agent identifier (used in URL path)
+            agent_config: Agent configuration from YAML
+            action: The action/task description for this agent
+            position: Node position [x, y]
+            index: Node index
+            is_first: Whether this is the first agent (uses webhook input)
+            
+        Returns:
+            n8n HTTP Request node configuration
+        """
+        agent_name = agent_config.get('name', agent_id.title())
+        # Convert agent_id to URL-safe format (lowercase, underscores)
+        agent_url_id = agent_id.lower().replace(' ', '_')
+        
+        # Build the query - first agent uses webhook input, others use previous response
+        # Escape single quotes and double braces (n8n expression syntax)
+        escaped_action = action.replace("'", "\\'").replace("{{", "").replace("}}", "")
+        if is_first:
+            # First agent: use query from webhook body
+            query_expr = "$json.body?.query || $json.query || '" + escaped_action + "'"
+        else:
+            # Subsequent agents: use previous agent's response + original action context
+            query_expr = "$json.response || '" + escaped_action + "'"
+        
+        return {
+            "id": f"agent_{index}",
+            "name": agent_name,
+            "type": "n8n-nodes-base.httpRequest",
+            "typeVersion": 4.2,
+            "position": position,
+            "parameters": {
+                "method": "POST",
+                "url": f"{self.praisonai_api_url}/agents/{agent_url_id}",
+                "sendBody": True,
+                "specifyBody": "json",
+                "jsonBody": f"={{{{ JSON.stringify({{ query: {query_expr} }}) }}}}",
+                "options": {
+                    "timeout": 300000  # 5 minute timeout per agent
+                }
+            },
+            "notes": f"Agent: {agent_name}\nTask: {action[:100]}"
+        }
+    
+    def _create_praisonai_workflow_node(self, workflow_name: str,
+                                         agent_names: List[str],
+                                         position: List[int]) -> Dict[str, Any]:
+        """
+        Create a single HTTP Request node that triggers the entire PraisonAI workflow.
+        
+        The PraisonAI API will run all agents sequentially when called.
+        
+        Args:
+            workflow_name: Name of the workflow
+            agent_names: List of agent names (for documentation)
+            position: Node position [x, y]
+            
+        Returns:
+            n8n HTTP Request node configuration
+        """
+        # The query will be passed from the webhook trigger
+        # Using n8n expression to get the body from the webhook
+        return {
+            "id": "praisonai_workflow",
+            "name": f"PraisonAI: {workflow_name}",
+            "type": "n8n-nodes-base.httpRequest",
+            "typeVersion": 4.2,
+            "position": position,
+            "parameters": {
+                "method": "POST",
+                "url": f"{self.praisonai_api_url}/agents",
+                "sendBody": True,
+                "specifyBody": "json",
+                # Pass the query from webhook body, or use a default
+                "jsonBody": "={{ JSON.stringify({ query: $json.body?.query || $json.query || 'Start workflow' }) }}",
+                "options": {
+                    "timeout": 600000  # 10 minute timeout for full workflow
+                }
+            },
+            "notes": f"Runs agents: {', '.join(agent_names)}"
+        }
+    
+    def _create_agent_node(self, agent_id: str, agent_config: Dict,
+                            action: str, position: List[int], 
+                            index: int) -> Dict[str, Any]:
+        """Create a node for an agent - either Execute Command or HTTP Request."""
+        if self.use_execute_command:
+            return self._create_execute_command_node(
+                agent_id, agent_config, action, position, index
+            )
+        else:
+            return self._create_http_request_node(
+                agent_id, agent_config, action, position, index
+            )
+    
+    def _create_execute_command_node(self, agent_id: str, agent_config: Dict,
+                                      action: str, position: List[int],
+                                      index: int) -> Dict[str, Any]:
+        """Create an Execute Command node that runs praisonai directly."""
+        agent_name = agent_config.get('name', agent_id.title())
+        
+        # Escape quotes in the action for shell command
+        escaped_action = action.replace('"', '\\"').replace("'", "\\'")
+        
+        # Build the praisonai command
+        # Uses the input from previous node if available
+        command = f'praisonai "{escaped_action}"'
+        
+        return {
+            "id": f"agent_{index}",
+            "name": agent_name,
+            "type": "n8n-nodes-base.executeCommand",
+            "typeVersion": 1,
+            "position": position,
+            "parameters": {
+                "command": command,
+                "executeOnce": True
+            }
+        }
+    
+    def _create_http_request_node(self, agent_id: str, agent_config: Dict,
+                                   action: str, position: List[int], 
+                                   index: int) -> Dict[str, Any]:
+        """Create an HTTP Request node for an agent."""
+        agent_name = agent_config.get('name', agent_id.title())
+        
+        # Build the request body
+        request_body = {
+            "query": action,
+            "agent": agent_id
+        }
+        
+        return {
+            "id": f"agent_{index}",
+            "name": agent_name,
+            "type": "n8n-nodes-base.httpRequest",
+            "typeVersion": 4.2,
+            "position": position,
+            "parameters": {
+                "method": "POST",
+                "url": f"{self.praisonai_api_url}/agents",
+                "sendBody": True,
+                "specifyBody": "json",
+                "jsonBody": json.dumps(request_body),
+                "options": {
+                    "timeout": 300000  # 5 minute timeout for LLM calls
+                }
+            }
+        }
+    
+    def _create_parallel_nodes(self, parallel_steps: List[Dict], 
+                                x_position: int,
+                                agents: Dict[str, Any]) -> tuple:
+        """Create nodes for parallel execution."""
+        nodes = []
+        connections = {}
+        
+        for i, step in enumerate(parallel_steps):
+            agent_id = step.get('agent', '')
+            action = step.get('action', step.get('description', ''))
+            agent_config = agents.get(agent_id, {})
+            
+            node = self._create_agent_node(
+                agent_id=agent_id,
+                agent_config=agent_config,
+                action=action,
+                position=[x_position + (i * 200), 300 + (i * 100)],
+                index=100 + i  # Offset index for parallel nodes
+            )
+            nodes.append(node)
+        
+        return nodes, connections
+    
+    def _create_route_node(self, step: Dict, x_position: int, 
+                           index: int) -> Dict[str, Any]:
+        """Create an IF node for routing decisions."""
+        route_config = step.get('route', {})
+        conditions = list(route_config.keys())
+        
+        return {
+            "id": f"route_{index}",
+            "name": f"Route Decision {index}",
+            "type": "n8n-nodes-base.if",
+            "typeVersion": 2,
+            "position": [x_position, 300],
+            "parameters": {
+                "conditions": {
+                    "options": {
+                        "caseSensitive": True,
+                        "leftValue": "",
+                        "typeValidation": "strict"
+                    },
+                    "conditions": [
+                        {
+                            "id": f"condition_{i}",
+                            "leftValue": "={{ $json.result }}",
+                            "rightValue": condition,
+                            "operator": {
+                                "type": "string",
+                                "operation": "contains"
+                            }
+                        }
+                        for i, condition in enumerate(conditions) if condition != 'default'
+                    ]
+                }
+            }
+        }
+    
+    def generate_n8n_url(self, workflow_json: Dict[str, Any], 
+                         base_url: str) -> str:
+        """
+        Generate a URL to open n8n workflow editor.
+        
+        Note: n8n doesn't support URL hash-based import. Users need to:
+        1. Open n8n
+        2. Use "Import from File" to load the saved JSON
+        
+        Args:
+            workflow_json: The n8n workflow JSON (unused, kept for API compatibility)
+            base_url: Base URL of the n8n instance
+            
+        Returns:
+            URL to open n8n workflow editor
+        """
+        # n8n doesn't support URL-based workflow import via hash
+        # Return the new workflow URL - user will need to import manually
+        return f"{base_url}/workflow/new"
+    
+    def open_in_browser(self, url: str) -> None:
+        """
+        Open a URL in the default web browser.
+        
+        Args:
+            url: URL to open
+        """
+        try:
+            webbrowser.open(url)
+        except Exception as e:
+            self.print_status(f"Could not open browser: {e}", "warning")
+            self.print_status(f"Please open this URL manually: {url}", "info")
+    
+    def _save_workflow_json(self, workflow_json: Dict[str, Any], 
+                            yaml_path: str) -> str:
+        """
+        Save the workflow JSON to a file.
+        
+        Args:
+            workflow_json: The n8n workflow JSON
+            yaml_path: Original YAML file path
+            
+        Returns:
+            Path to the saved JSON file
+        """
+        # Create output path based on input YAML
+        yaml_file = Path(yaml_path)
+        output_path = yaml_file.parent / f"{yaml_file.stem}_n8n.json"
+        
+        with open(output_path, 'w') as f:
+            json.dump(workflow_json, f, indent=2)
+        
+        return str(output_path)
+    
+    def get_workflow_json_for_clipboard(self, yaml_path: str) -> str:
+        """
+        Get the workflow JSON as a string for clipboard copy.
+        
+        Args:
+            yaml_path: Path to the agents.yaml file
+            
+        Returns:
+            JSON string ready for clipboard
+        """
+        workflow_json = self.convert_yaml_to_n8n(yaml_path)
+        return json.dumps(workflow_json, indent=2)

src/praisonai/praisonai/cli/features/workflow.py

@@ -367,6 +367,14 @@ Example:
         self.print_status(f"Validating: {file_path}", "info")
         
         try:
+            # Load raw YAML to check for non-canonical names
+            import yaml
+            with open(file_path, 'r') as f:
+                raw_data = yaml.safe_load(f)
+            
+            # Check for non-canonical names and suggest canonical ones
+            suggestions = self._get_canonical_suggestions(raw_data)
+            
             workflow = parser.parse_file(file_path)
             
             # Print validation results
@@ -386,12 +394,82 @@ Example:
             
             rprint(table)
             self.print_status("✓ Workflow is valid!", "success")
+            
+            # Show suggestions for canonical names
+            if suggestions:
+                rprint()
+                rprint("[yellow]💡 Suggestions for canonical field names:[/yellow]")
+                for suggestion in suggestions:
+                    rprint(f"   [dim]•[/dim] {suggestion}")
+                rprint()
+                rprint("[dim]Note: Both old and new names work, but canonical names are recommended.[/dim]")
+            
             return True
             
         except Exception as e:
             self.print_status(f"✗ Validation failed: {e}", "error")
             return False
     
+    def _get_canonical_suggestions(self, data: Dict) -> List[str]:
+        """
+        Check for non-canonical field names and return suggestions.
+        
+        Canonical names (A-I-G-S mnemonic):
+        - Agents (not roles)
+        - Instructions (not backstory)
+        - Goal (same)
+        - Steps (not tasks)
+        
+        Also:
+        - name (not topic)
+        - action (not description)
+        
+        Args:
+            data: Raw YAML data
+            
+        Returns:
+            List of suggestion strings
+        """
+        suggestions = []
+        
+        if not data:
+            return suggestions
+        
+        # Check top-level keys
+        if 'roles' in data:
+            suggestions.append("Use 'agents' instead of 'roles'")
+        
+        if 'topic' in data and 'name' not in data:
+            suggestions.append("Use 'name' instead of 'topic'")
+        
+        # Check agent fields
+        agents_data = data.get('agents', data.get('roles', {}))
+        for agent_id, agent_config in agents_data.items():
+            if isinstance(agent_config, dict):
+                if 'backstory' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'instructions' instead of 'backstory'")
+                
+                # Check nested tasks
+                if 'tasks' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'steps' at top level instead of nested 'tasks'")
+        
+        # Check step fields
+        steps_data = data.get('steps', [])
+        for i, step in enumerate(steps_data):
+            if isinstance(step, dict):
+                if 'description' in step and 'action' not in step:
+                    step_name = step.get('name', f'step {i+1}')
+                    suggestions.append(f"Step '{step_name}': Use 'action' instead of 'description'")
+                
+                # Check parallel steps
+                if 'parallel' in step:
+                    for j, parallel_step in enumerate(step['parallel']):
+                        if isinstance(parallel_step, dict):
+                            if 'description' in parallel_step and 'action' not in parallel_step:
+                                suggestions.append(f"Parallel step {j+1}: Use 'action' instead of 'description'")
+        
+        return suggestions
+    
     def action_list(self, args: List[str], **kwargs) -> List[str]:
         """
         List available workflows in .praison/workflows/ directory.
@@ -567,8 +645,8 @@ Example:
             
             return result_path
             
-        except ImportError as e:
-            self.print_status(f"Auto-generation requires instructor: pip install instructor", "error")
+        except ImportError:
+            self.print_status("Auto-generation requires instructor: pip install instructor", "error")
             return None
         except Exception as e:
             self.print_status(f"Generation failed: {e}", "error")

src/praisonai/praisonai/cli/main.py

@@ -210,6 +210,10 @@ class PraisonAI:
         version_string = f"PraisonAI version {__version__}"
 
         self.framework = args.framework or self.framework
+        
+        # Update config_list model if --model flag is provided
+        if getattr(args, 'model', None):
+            self.config_list[0]['model'] = args.model
 
         # Check for piped input from stdin
         stdin_input = self.read_stdin_if_available()
@@ -495,6 +499,32 @@ class PraisonAI:
                 print(result)
                 return result
         else:
+            # n8n Integration - Export workflow to n8n and open in browser
+            if getattr(args, 'n8n', False):
+                from .features.n8n import N8nHandler
+                n8n_handler = N8nHandler(
+                    verbose=getattr(args, 'verbose', False),
+                    n8n_url=getattr(args, 'n8n_url', 'http://localhost:5678'),
+                    api_url=getattr(args, 'api_url', 'http://127.0.0.1:8005')
+                )
+                result = n8n_handler.execute(self.agent_file)
+                return result
+            
+            # Flow Display - Show flow diagram WITHOUT executing (--flow-display flag)
+            if getattr(args, 'flow_display', False):
+                from .features.flow_display import FlowDisplayHandler
+                flow_handler = FlowDisplayHandler(verbose=getattr(args, 'verbose', False))
+                flow_handler.display_flow_diagram(self.agent_file)
+                return  # Exit without executing
+            
+            # Always show flow diagram before execution (default behavior)
+            try:
+                from .features.flow_display import FlowDisplayHandler
+                flow_handler = FlowDisplayHandler(verbose=getattr(args, 'verbose', False))
+                flow_handler.display_flow_diagram(self.agent_file, show_footer=False)
+            except Exception:
+                pass  # Continue even if flow display fails
+            
             agents_generator = AgentsGenerator(
                 self.agent_file,
                 self.framework,
@@ -549,7 +579,7 @@ class PraisonAI:
             return default_args
         
         # Define special commands
-        special_commands = ['chat', 'code', 'call', 'realtime', 'train', 'ui', 'context', 'research', 'memory', 'rules', 'workflow', 'hooks', 'knowledge', 'session', 'tools', 'todo', 'docs', 'mcp', 'commit']
+        special_commands = ['chat', 'code', 'call', 'realtime', 'train', 'ui', 'context', 'research', 'memory', 'rules', 'workflow', 'hooks', 'knowledge', 'session', 'tools', 'todo', 'docs', 'mcp', 'commit', 'serve']
         
         parser = argparse.ArgumentParser(prog="praisonai", description="praisonAI command-line interface")
         parser.add_argument("--framework", choices=["crewai", "autogen", "praisonai"], help="Specify the framework")
@@ -650,6 +680,16 @@ class PraisonAI:
         # Flow Display - visual workflow
         parser.add_argument("--flow-display", action="store_true", help="Enable visual workflow tracking")
         
+        # n8n Integration - export workflow to n8n
+        parser.add_argument("--n8n", action="store_true", help="Export workflow to n8n and open in browser")
+        parser.add_argument("--n8n-url", type=str, default="http://localhost:5678", help="n8n instance URL (default: http://localhost:5678)")
+        parser.add_argument("--api-url", type=str, default="http://127.0.0.1:8005", help="PraisonAI API URL for n8n to call (default: http://127.0.0.1:8005)")
+        
+        # Serve - start API server for agents
+        parser.add_argument("--serve", action="store_true", help="Start API server for agents (use with agents.yaml)")
+        parser.add_argument("--port", type=int, default=8005, help="Server port (default: 8005)")
+        parser.add_argument("--host", type=str, default="127.0.0.1", help="Server host (default: 127.0.0.1)")
+        
         # If we're in a test environment, parse with empty args to avoid pytest interference
         if in_test_env:
             args, unknown_args = parser.parse_known_args([])
@@ -677,6 +717,13 @@ class PraisonAI:
             args.realtime = True
         if args.command == 'call':
             args.call = True
+        if args.command == 'serve':
+            args.serve = True
+
+        # Handle serve command - start API server for agents
+        if args.command == 'serve' or args.serve:
+            self._handle_serve_command(args, unknown_args)
+            sys.exit(0)
 
         # Handle both command and flag versions for call
         if args.command == 'call' or args.call:
@@ -1632,6 +1679,10 @@ class PraisonAI:
                     if arg == '--output' and i + 1 < len(action_args):
                         output_file = action_args[i + 1]
                 self._create_workflow_from_template(template_name, output_file)
+            
+            elif action == 'auto':
+                # Auto-generate workflow from topic
+                self._auto_generate_workflow(action_args)
                 
             elif action == 'help' or action == '--help':
                 print("[bold]Workflow Commands:[/bold]")
@@ -1642,6 +1693,7 @@ class PraisonAI:
                 print("  praisonai workflow create <name>         - Create a new workflow")
                 print("  praisonai workflow validate <file.yaml>  - Validate a YAML workflow")
                 print("  praisonai workflow template <name>       - Create from template")
+                print('  praisonai workflow auto "topic"          - Auto-generate workflow')
                 print("\n[bold]Templates:[/bold]")
                 print("  simple, routing, parallel, loop, evaluator-optimizer")
                 print("\n[bold]Options (uses global flags):[/bold]")
@@ -1763,6 +1815,7 @@ class PraisonAI:
             from rich import print
             from rich.table import Table
             from rich.console import Console
+            import yaml
             
             console = Console()
             
@@ -1772,6 +1825,13 @@ class PraisonAI:
             
             print(f"[cyan]Validating: {yaml_file}[/cyan]")
             
+            # Load raw YAML to check for non-canonical names
+            with open(yaml_file, 'r') as f:
+                raw_data = yaml.safe_load(f)
+            
+            # Check for non-canonical names and suggest canonical ones
+            suggestions = self._get_canonical_suggestions(raw_data)
+            
             parser = YAMLWorkflowParser()
             workflow = parser.parse_file(yaml_file)
             
@@ -1790,8 +1850,77 @@ class PraisonAI:
             console.print(table)
             print("[green]✓ Workflow is valid![/green]")
             
+            # Show suggestions for canonical names
+            if suggestions:
+                print()
+                print("[yellow]💡 Suggestions for canonical field names:[/yellow]")
+                for suggestion in suggestions:
+                    print(f"   [dim]•[/dim] {suggestion}")
+                print()
+                print("[dim]Note: Both old and new names work, but canonical names are recommended.[/dim]")
+            
         except Exception as e:
             print(f"[red]✗ Validation failed: {e}[/red]")
+    
+    def _get_canonical_suggestions(self, data: dict) -> list:
+        """
+        Check for non-canonical field names and return suggestions.
+        
+        Canonical names (A-I-G-S mnemonic):
+        - Agents (not roles)
+        - Instructions (not backstory)
+        - Goal (same)
+        - Steps (not tasks)
+        
+        Also:
+        - name (not topic)
+        - action (not description)
+        
+        Args:
+            data: Raw YAML data
+            
+        Returns:
+            List of suggestion strings
+        """
+        suggestions = []
+        
+        if not data:
+            return suggestions
+        
+        # Check top-level keys
+        if 'roles' in data:
+            suggestions.append("Use 'agents' instead of 'roles'")
+        
+        if 'topic' in data and 'name' not in data:
+            suggestions.append("Use 'name' instead of 'topic'")
+        
+        # Check agent fields
+        agents_data = data.get('agents', data.get('roles', {}))
+        for agent_id, agent_config in agents_data.items():
+            if isinstance(agent_config, dict):
+                if 'backstory' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'instructions' instead of 'backstory'")
+                
+                # Check nested tasks
+                if 'tasks' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'steps' at top level instead of nested 'tasks'")
+        
+        # Check step fields
+        steps_data = data.get('steps', [])
+        for i, step in enumerate(steps_data):
+            if isinstance(step, dict):
+                if 'description' in step and 'action' not in step:
+                    step_name = step.get('name', f'step {i+1}')
+                    suggestions.append(f"Step '{step_name}': Use 'action' instead of 'description'")
+                
+                # Check parallel steps
+                if 'parallel' in step:
+                    for j, parallel_step in enumerate(step['parallel']):
+                        if isinstance(parallel_step, dict):
+                            if 'description' in parallel_step and 'action' not in parallel_step:
+                                suggestions.append(f"Parallel step {j+1}: Use 'action' instead of 'description'")
+        
+        return suggestions
 
     def _create_workflow_from_template(self, template_name: str = None, output_file: str = None):
         """
@@ -1839,6 +1968,76 @@ class PraisonAI:
         print(f"[green]✓ Created workflow: {output_file}[/green]")
         print(f"[cyan]Run with: praisonai workflow run {output_file}[/cyan]")
 
+    def _auto_generate_workflow(self, action_args: list):
+        """
+        Auto-generate a workflow from a topic description.
+        
+        Args:
+            action_args: ["topic description", --pattern, <pattern>, --output, <file.yaml>]
+        """
+        from rich import print
+        
+        # Parse arguments
+        topic = None
+        pattern = "sequential"
+        output_file = None
+        
+        i = 0
+        while i < len(action_args):
+            if action_args[i] == "--pattern" and i + 1 < len(action_args):
+                pattern = action_args[i + 1]
+                i += 2
+            elif action_args[i] == "--output" and i + 1 < len(action_args):
+                output_file = action_args[i + 1]
+                i += 2
+            elif not action_args[i].startswith("--") and topic is None:
+                topic = action_args[i]
+                i += 1
+            else:
+                i += 1
+        
+        if not topic:
+            print('[red]Usage: praisonai workflow auto "topic" --pattern <pattern>[/red]')
+            print("[cyan]Patterns: sequential, routing, parallel[/cyan]")
+            return
+        
+        # Validate pattern
+        valid_patterns = ["sequential", "routing", "parallel", "loop"]
+        if pattern not in valid_patterns:
+            print(f"[red]Unknown pattern: {pattern}[/red]")
+            print(f"[cyan]Valid patterns: {', '.join(valid_patterns)}[/cyan]")
+            return
+        
+        # Default output file
+        if not output_file:
+            safe_name = "".join(c if c.isalnum() else "_" for c in topic[:30]).lower()
+            output_file = f"{safe_name}_workflow.yaml"
+        
+        # Check if file exists
+        if os.path.exists(output_file):
+            print(f"[red]ERROR: File already exists: {output_file}[/red]")
+            return
+        
+        print(f"[cyan]Generating {pattern} workflow for: {topic}[/cyan]")
+        
+        try:
+            from praisonai.auto import WorkflowAutoGenerator
+            
+            generator = WorkflowAutoGenerator(
+                topic=topic,
+                workflow_file=output_file
+            )
+            
+            result_path = generator.generate(pattern=pattern)
+            
+            print(f"[green]✓ Created workflow: {result_path}[/green]")
+            print(f"[cyan]Run with: praisonai workflow run {output_file}[/cyan]")
+            
+        except ImportError:
+            print("[red]Auto-generation requires instructor: pip install instructor[/red]")
+        except Exception as e:
+            print(f"[red]Generation failed: {e}[/red]")
+
     def handle_hooks_command(self, action: str):
         """
         Handle hooks subcommand actions.
@@ -2859,6 +3058,219 @@ Now, {final_instruction.lower()}:"""
             print("pip install praisonaiagents # For PraisonAIAgents\n")  
             sys.exit(1)
 
+    def _handle_serve_command(self, args, unknown_args):
+        """
+        Handle the serve command - start API server for agents.
+        
+        Supports:
+        - Sequential workflows with agents and steps
+        - Workflow patterns: route, parallel, loop, repeat
+        - All process types: sequential, workflow, hierarchical
+        
+        Usage:
+            praisonai serve agents.yaml
+            praisonai serve agents.yaml --port 8005 --host 0.0.0.0
+            praisonai agents.yaml --serve
+        """
+        import yaml
+        from praisonaiagents import Agent, PraisonAIAgents
+        
+        # Determine the YAML file path
+        yaml_file = None
+        
+        # Check if command is 'serve' and there's a file in unknown_args
+        if args.command == 'serve' and unknown_args:
+            yaml_file = unknown_args[0]
+        # Check if command itself is a yaml file (praisonai agents.yaml --serve)
+        elif args.command and args.command.endswith('.yaml'):
+            yaml_file = args.command
+        # Default to agents.yaml
+        else:
+            yaml_file = 'agents.yaml'
+        
+        # Check if file exists
+        if not os.path.exists(yaml_file):
+            print(f"[red]ERROR: File not found: {yaml_file}[/red]")
+            print("\nUsage:")
+            print("  praisonai serve agents.yaml")
+            print("  praisonai serve agents.yaml --port 8005")
+            print("  praisonai agents.yaml --serve")
+            sys.exit(1)
+        
+        print(f"📄 Loading workflow from: {yaml_file}")
+        
+        # Load YAML file
+        with open(yaml_file, 'r') as f:
+            config = yaml.safe_load(f)
+        
+        # Extract agents
+        agents_config = config.get('agents', config.get('roles', {}))
+        agents_dict = {}  # Map agent_id to Agent instance
+        agents_list = []
+        
+        for agent_id, agent_config in agents_config.items():
+            if isinstance(agent_config, dict):
+                agent = Agent(
+                    name=agent_config.get('name', agent_id.title()),
+                    role=agent_config.get('role', ''),
+                    goal=agent_config.get('goal', ''),
+                    backstory=agent_config.get('backstory', ''),
+                    instructions=agent_config.get('instructions', ''),
+                    llm=agent_config.get('llm', 'gpt-4o-mini'),
+                    verbose=False
+                )
+                agents_dict[agent_id] = agent
+                agents_list.append(agent)
+                print(f"  ✓ Loaded agent: {agent.name}")
+        
+        if not agents_list:
+            print("[red]ERROR: No agents found in YAML file[/red]")
+            sys.exit(1)
+        
+        # Extract tasks from steps (if defined)
+        steps = config.get('steps', [])
+        tasks_list = []
+        
+        # Detect advanced workflow patterns
+        has_route = any(isinstance(s, dict) and 'route' in s for s in steps)
+        has_parallel = any(isinstance(s, dict) and 'parallel' in s for s in steps)
+        has_loop = any(isinstance(s, dict) and 'loop' in s for s in steps)
+        has_repeat = any(isinstance(s, dict) and 'repeat' in s for s in steps)
+        
+        if has_route or has_parallel or has_loop or has_repeat:
+            patterns = []
+            if has_route: patterns.append("route")
+            if has_parallel: patterns.append("parallel")
+            if has_loop: patterns.append("loop")
+            if has_repeat: patterns.append("repeat")
+            print(f"\n🔀 Detected workflow patterns: {', '.join(patterns)}")
+        
+        if steps:
+            from praisonaiagents import Task
+            print(f"\n📋 Loading workflow steps...")
+            
+            # First pass: create all tasks
+            task_name_map = {}  # Map step names to Task objects for context/next_tasks
+            for i, step in enumerate(steps):
+                if isinstance(step, dict):
+                    # Handle advanced patterns
+                    if 'route' in step:
+                        print(f"  ✓ Loaded routing step: {step.get('name', f'route_{i+1}')}")
+                        continue  # Route steps are handled by workflow process
+                    if 'parallel' in step:
+                        parallel_tasks = step.get('parallel', [])
+                        print(f"  ✓ Loaded parallel step: {len(parallel_tasks)} concurrent tasks")
+                        for j, pt in enumerate(parallel_tasks):
+                            if isinstance(pt, dict):
+                                agent_id = pt.get('agent', '')
+                                action = pt.get('action', pt.get('description', ''))
+                                if agent_id in agents_dict:
+                                    task = Task(
+                                        name=f"parallel_{i}_{j}",
+                                        description=action,
+                                        agent=agents_dict[agent_id],
+                                        expected_output=pt.get('expected_output', 'Completed task output'),
+                                        async_execution=True,  # Parallel tasks run async
+                                    )
+                                    tasks_list.append(task)
+                                    task_name_map[f"parallel_{i}_{j}"] = task
+                        continue
+                    if 'loop' in step:
+                        loop_config = step.get('loop', {})
+                        print(f"  ✓ Loaded loop step: over '{loop_config.get('over', 'items')}'")
+                        continue  # Loop steps are handled by workflow process
+                    if 'repeat' in step:
+                        repeat_config = step.get('repeat', {})
+                        print(f"  ✓ Loaded repeat step: until '{repeat_config.get('until', 'done')}'")
+                        continue  # Repeat steps are handled by workflow process
+                    
+                    # Standard step
+                    agent_id = step.get('agent', '')
+                    action = step.get('action', step.get('description', ''))
+                    task_name = step.get('name', f"step_{i+1}")
+                    
+                    if agent_id in agents_dict:
+                        task = Task(
+                            name=task_name,
+                            description=action,
+                            agent=agents_dict[agent_id],
+                            expected_output=step.get('expected_output', 'Completed task output'),
+                            task_type=step.get('task_type', 'task'),
+                            is_start=step.get('is_start', i == 0),
+                            async_execution=step.get('async_execution', False),
+                            output_file=step.get('output_file'),
+                        )
+                        tasks_list.append(task)
+                        task_name_map[task_name] = task
+                        print(f"  ✓ Loaded step {i+1}: {agent_id} → {action[:50]}...")
+            
+            # Second pass: set up next_tasks and context relationships
+            for i, step in enumerate(steps):
+                if isinstance(step, dict) and 'agent' in step:
+                    task_name = step.get('name', f"step_{i+1}")
+                    if task_name in task_name_map:
+                        task = task_name_map[task_name]
+                        
+                        # Set next_tasks if specified
+                        next_tasks = step.get('next_tasks', [])
+                        if next_tasks:
+                            task.next_tasks = next_tasks
+                        
+                        # Set context if specified
+                        context_refs = step.get('context', [])
+                        if context_refs:
+                            task.context = [task_name_map[ref] for ref in context_refs if ref in task_name_map]
+                        
+                        # Set condition for workflow branching
+                        condition = step.get('condition', {})
+                        if condition:
+                            task.condition = condition
+        
+        port = args.port
+        host = args.host
+        
+        # Extract process type from workflow config (default: sequential)
+        workflow_config = config.get('workflow', {})
+        process_type = workflow_config.get('process', 'sequential')
+        verbose = workflow_config.get('verbose', False)
+        
+        # Also check top-level process key
+        if 'process' in config:
+            process_type = config['process']
+        
+        print(f"\n🚀 Starting PraisonAI API server...")
+        print(f"   Host: {host}")
+        print(f"   Port: {port}")
+        print(f"   Agents: {len(agents_list)}")
+        if tasks_list:
+            print(f"   Tasks: {len(tasks_list)}")
+        print(f"   Process: {process_type}")
+        
+        # Create and launch - with tasks if defined
+        if tasks_list:
+            praison = PraisonAIAgents(
+                agents=agents_list, 
+                tasks=tasks_list,
+                process=process_type,
+                verbose=1 if verbose else 0
+            )
+        else:
+            praison = PraisonAIAgents(
+                agents=agents_list,
+                process=process_type,
+                verbose=1 if verbose else 0
+            )
+        praison.launch(port=port, host=host)
+        
+        # Keep the main thread alive to prevent exit
+        print("\n✅ Server running. Press Ctrl+C to stop.")
+        try:
+            import time
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            print("\n👋 Server stopped.")
+
     def create_chainlit_chat_interface(self):
         """
         Create a Chainlit interface for the chat application.

src/praisonai/praisonai/deploy.py

@@ -57,7 +57,7 @@ class CloudDeployer:
             file.write("FROM python:3.11-slim\n")
             file.write("WORKDIR /app\n")
             file.write("COPY . .\n")
-            file.write("RUN pip install flask praisonai==2.3.26 gunicorn markdown\n")
+            file.write("RUN pip install flask praisonai==2.3.38 gunicorn markdown\n")
             file.write("EXPOSE 8080\n")
             file.write('CMD ["gunicorn", "-b", "0.0.0.0:8080", "api:app"]\n')
             

src/praisonai/praisonai/version.py

@@ -1 +1 @@
-__version__ = "2.3.26"
+__version__ = "2.3.38"

src/praisonai/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "rich>=13.7",
     "markdown>=3.5",
     "pyparsing>=3.0.0",
-    "praisonaiagents>=0.1.4",
+    "praisonaiagents>=0.1.16",
     "python-dotenv>=0.19.0",
     "instructor>=1.3.3",
     "PyYAML>=6.0",

src/praisonai/tests/test_n8n_integration.py

@@ -0,0 +1,246 @@
+"""
+Test-Driven Development tests for n8n integration.
+
+Tests for converting PraisonAI agents.yaml to n8n workflow JSON format.
+"""
+
+import pytest
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+class TestN8nConverter:
+    """Tests for YAML to n8n JSON conversion."""
+    
+    @pytest.fixture
+    def sample_agents_yaml(self):
+        """Sample agents.yaml content for testing."""
+        return """
+name: Test Workflow
+description: A test workflow for n8n integration
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: Research and gather information
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write content
+    instructions: Write based on research
+
+steps:
+  - agent: researcher
+    action: "Research the topic"
+  
+  - agent: writer
+    action: "Write content based on research"
+"""
+
+    @pytest.fixture
+    def sample_yaml_file(self, sample_agents_yaml):
+        """Create a temporary YAML file for testing."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+            f.write(sample_agents_yaml)
+            f.flush()
+            yield f.name
+        os.unlink(f.name)
+
+    def test_n8n_handler_import(self):
+        """Test that N8nHandler can be imported."""
+        from praisonai.cli.features.n8n import N8nHandler
+        assert N8nHandler is not None
+
+    def test_n8n_handler_initialization(self):
+        """Test N8nHandler initialization."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler(verbose=True)
+        assert handler.feature_name == "n8n"
+        assert handler.verbose is True
+
+    def test_convert_yaml_to_n8n_returns_dict(self, sample_yaml_file):
+        """Test that convert_yaml_to_n8n returns a dictionary."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        assert isinstance(result, dict)
+
+    def test_n8n_workflow_has_required_keys(self, sample_yaml_file):
+        """Test that n8n workflow JSON has required keys."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        assert "name" in result
+        assert "nodes" in result
+        assert "connections" in result
+
+    def test_n8n_workflow_has_trigger_node(self, sample_yaml_file):
+        """Test that n8n workflow has a trigger node (webhook or manual)."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        nodes = result["nodes"]
+        # Check for webhook or manual trigger nodes
+        trigger_nodes = [n for n in nodes if "trigger" in n.get("type", "").lower() 
+                        or "webhook" in n.get("type", "").lower()
+                        or "trigger" in n.get("name", "").lower()
+                        or "webhook" in n.get("name", "").lower()]
+        assert len(trigger_nodes) >= 1
+
+    def test_n8n_workflow_has_per_agent_nodes(self, sample_yaml_file):
+        """Test that n8n workflow has HTTP Request nodes for each agent."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        nodes = result["nodes"]
+        # Should have HTTP Request nodes for each agent
+        http_nodes = [n for n in nodes if "httpRequest" in n.get("type", "")]
+        assert len(http_nodes) >= 2  # At least 2 agents
+        
+        # Each node should call a specific agent endpoint
+        for node in http_nodes:
+            assert "/agents/" in node["parameters"]["url"]
+
+    def test_n8n_workflow_nodes_are_connected(self, sample_yaml_file):
+        """Test that nodes are properly connected."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        connections = result["connections"]
+        assert len(connections) > 0
+
+    def test_n8n_workflow_name_from_yaml(self, sample_yaml_file):
+        """Test that workflow name is taken from YAML."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        assert result["name"] == "Test Workflow"
+
+    def test_generate_n8n_url(self, sample_yaml_file):
+        """Test URL generation for n8n."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        workflow_json = handler.convert_yaml_to_n8n(sample_yaml_file)
+        url = handler.generate_n8n_url(workflow_json, "http://localhost:5678")
+        
+        assert url.startswith("http://localhost:5678")
+        assert "workflow" in url.lower()
+
+    def test_node_positions_are_sequential(self, sample_yaml_file):
+        """Test that node positions are laid out sequentially."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        result = handler.convert_yaml_to_n8n(sample_yaml_file)
+        
+        nodes = result["nodes"]
+        positions = [n.get("position", [0, 0]) for n in nodes]
+        
+        # X positions should increase for sequential workflow
+        x_positions = [p[0] for p in positions]
+        assert x_positions == sorted(x_positions), "Nodes should be positioned left to right"
+
+
+class TestN8nCLIIntegration:
+    """Tests for CLI integration of n8n feature."""
+    
+    def test_n8n_flag_in_argparser(self):
+        """Test that --n8n flag is recognized by argparser."""
+        import argparse
+        # This will be tested after we add the flag to main.py
+        pass
+
+    def test_execute_method_exists(self):
+        """Test that execute method exists."""
+        from praisonai.cli.features.n8n import N8nHandler
+        handler = N8nHandler()
+        assert hasattr(handler, 'execute')
+        assert callable(handler.execute)
+
+
+class TestN8nWorkflowPatterns:
+    """Tests for different workflow patterns."""
+    
+    @pytest.fixture
+    def parallel_workflow_yaml(self):
+        """YAML with parallel steps."""
+        return """
+name: Parallel Workflow
+
+agents:
+  agent1:
+    name: Agent1
+    role: Role1
+    goal: Goal1
+  agent2:
+    name: Agent2
+    role: Role2
+    goal: Goal2
+
+steps:
+  - parallel:
+      - agent: agent1
+        action: "Do task 1"
+      - agent: agent2
+        action: "Do task 2"
+"""
+
+    @pytest.fixture
+    def route_workflow_yaml(self):
+        """YAML with route/decision steps."""
+        return """
+name: Route Workflow
+
+agents:
+  classifier:
+    name: Classifier
+    role: Classifier
+    goal: Classify input
+  handler_a:
+    name: HandlerA
+    role: Handler
+    goal: Handle type A
+  handler_b:
+    name: HandlerB
+    role: Handler
+    goal: Handle type B
+
+steps:
+  - agent: classifier
+    action: "Classify the input"
+  
+  - route:
+      type_a: [handler_a]
+      type_b: [handler_b]
+"""
+
+    def test_parallel_workflow_creates_split_node(self, parallel_workflow_yaml):
+        """Test that parallel steps create appropriate n8n structure."""
+        import tempfile
+        import os
+        from praisonai.cli.features.n8n import N8nHandler
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+            f.write(parallel_workflow_yaml)
+            f.flush()
+            
+            handler = N8nHandler()
+            result = handler.convert_yaml_to_n8n(f.name)
+            
+            # Should have nodes for parallel execution
+            assert len(result["nodes"]) >= 2
+            
+        os.unlink(f.name)
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/praisonai/tests/test_phase2_refactor.py

@@ -1,15 +1,21 @@
 #!/usr/bin/env python3
-"""Test script to verify Phase 2 refactoring maintains backward compatibility"""
+"""Test script to verify Phase 2 refactoring maintains backward compatibility
+
+NOTE: These tests make real API calls and require valid API keys.
+They are marked with @pytest.mark.real to be excluded from CI.
+"""
 
 import asyncio
 import sys
 import os
+import pytest
 
 # Add the correct path for imports
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src/praisonai-agents'))
 
 from praisonaiagents.llm import LLM
 
+@pytest.mark.real
 def test_sync_methods():
     """Test synchronous methods still work correctly"""
     print("Testing synchronous methods...")
@@ -52,6 +58,7 @@ def test_sync_methods():
     
     print("✅ Synchronous methods working correctly\n")
 
+@pytest.mark.real
 async def test_async_methods():
     """Test asynchronous methods still work correctly"""
     print("Testing asynchronous methods...")
@@ -94,6 +101,7 @@ async def test_async_methods():
     
     print("✅ Asynchronous methods working correctly\n")
 
+@pytest.mark.real
 def test_edge_cases():
     """Test edge cases and special scenarios"""
     print("Testing edge cases...")