{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\".github/images/logo_dark.png\" />\n    <source media=\"(prefers-color-scheme: light)\" srcset=\".github/images/logo_light.png\" />\n    <img alt=\"PraisonAI Logo\" src=\".github/images/logo_light.png\" width=\"250\" />\n  </picture>\n</p>\n\n<!-- mcp-name: io.github.MervinPraison/praisonai -->\n\n<p align=\"center\">\n<a href=\"https://github.com/MervinPraison/PraisonAI\"><img src=\"https://static.pepy.tech/badge/PraisonAI\" alt=\"Total Downloads\" /></a>\n<a href=\"https://github.com/MervinPraison/PraisonAI\"><img src=\"https://img.shields.io/github/v/release/MervinPraison/PraisonAI\" alt=\"Latest Stable Version\" /></a>\n<a href=\"https://github.com/MervinPraison/PraisonAI\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License\" /></a>\n<a href=\"https://registry.modelcontextprotocol.io/servers/io.github.MervinPraison/praisonai\"><img src=\"https://img.shields.io/badge/MCP-Registry-blue\" alt=\"MCP Registry\" /></a>\n</p>\n\n<div align=\"center\">\n\n# PraisonAI 🦞\n\n<a href=\"https://trendshift.io/repositories/9130\" target=\"_blank\"><img src=\"https://trendshift.io/api/badge/repositories/9130\" alt=\"MervinPraison%2FPraisonAI | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"/></a>\n\n</div>\n\nPraisonAI 🦞 — **Hire a 24/7 AI Workforce.** Stop writing boilerplate and start shipping autonomous, self-improving agents that research, plan, and execute tasks across your apps. From one agent to an entire organization, deployed in 5 lines of code.\n\n```bash\ncurl -fsSL https://praison.ai/install.sh | bash\n```\n\n<div align=\"center\">\n  <br>\n  <a href=\"https://x.com/elonmusk/status/1893870468249141688\" target=\"_blank\">\n    <img src=\"https://img.shields.io/badge/Highlighted_by_Elon_Musk-000000?style=for-the-badge&logo=x&logoColor=white\" alt=\"Highlighted by Elon Musk\" />\n  </a>\n  <br>\n  <br>\n  <a href=\"https://github.com/MervinPraison/PraisonAI/releases/latest\">\n    <img src=\"https://img.shields.io/badge/Download_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white\" alt=\"Download for macOS\" />\n  </a>\n  &nbsp;&nbsp;\n  <a href=\"https://github.com/MervinPraison/PraisonAI/releases/latest\">\n    <img src=\"https://img.shields.io/badge/Download_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white\" alt=\"Download for Windows\" />\n  </a>\n  &nbsp;&nbsp;\n  <a href=\"https://github.com/MervinPraison/PraisonAI/releases/latest\">\n    <img src=\"https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black\" alt=\"Download for Linux\" />\n  </a>\n  <br>\n</div>\n\n<p align=\"center\">\n  <img src=\".github/images/dashboard.png\" alt=\"PraisonAI Dashboard\" width=\"800\" />\n</p>\n\n```\n ██████╗ ██████╗  █████╗ ██╗███████╗ ██████╗ ███╗   ██╗     █████╗ ██╗\n ██╔══██╗██╔══██╗██╔══██╗██║██╔════╝██╔═══██╗████╗  ██║    ██╔══██╗██║\n ██████╔╝██████╔╝███████║██║███████╗██║   ██║██╔██╗ ██║    ███████║██║\n ██╔═══╝ ██╔══██╗██╔══██║██║╚════██║██║   ██║██║╚██╗██║    ██╔══██║██║\n ██║     ██║  ██║██║  ██║██║███████║╚██████╔╝██║ ╚████║    ██║  ██║██║\n ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝    ╚═╝  ╚═╝╚═╝\n\n pip install praisonai\n```\n\n<div align=\"center\">\n  <a href=\"https://docs.praison.ai\">\n    <p align=\"center\">\n      <img src=\"https://img.shields.io/badge/📚_Documentation-Visit_docs.praison.ai-blue?style=for-the-badge&logo=bookstack&logoColor=white\" alt=\"Documentation\" />\n    </p>\n  </a>\n</div>\n\n---\n\n## 🎯 Use Cases\n\nAI agents solving real-world problems across industries:\n\n| Use Case | Description |\n|----------|-------------|\n| 🔍 **Research & Analysis** | Conduct deep research, gather information, and generate insights from multiple sources automatically |\n| 💻 **Code Generation** | Write, debug, and refactor code with AI agents that understand your codebase and requirements |\n| ✍️ **Content Creation** | Generate blog posts, documentation, marketing copy, and technical writing with multi-agent teams |\n| 📊 **Data Pipelines** | Extract, transform, and analyze data from APIs, databases, and web sources automatically |\n| 🤖 **Customer Support** | Deploy 24/7 support bots on Telegram, Discord, Slack with memory and knowledge-backed responses |\n| ⚙️ **Workflow Automation** | Automate multi-step business processes with agents that hand off tasks, verify results, and self-correct |\n\n---\n\n## 🚀 Meet your first Agent (Under 1 Minute)\n\n1. Install the lightweight core SDK:\n```bash\npip install praisonaiagents\nexport OPENAI_API_KEY=\"your-api-key\"\n```\n\n2. Run your first autonomous agent:\n```python\nfrom praisonaiagents import Agent\n\n# Give your agent a goal, and watch it work.\nagent = Agent(instructions=\"You are a senior data analyst.\")\nagent.start(\"Analyze the top 3 tech trends of 2026 and format as a markdown table.\")\n```\n\n---\n\n## 🧬 The Five-Layer Agent Stack\n\nMost frameworks hand you one or two layers and leave the rest as homework. PraisonAI covers **all five** — plus the outer layer that decides *where* your agent actually runs.\n\nEach layer wraps the one inside it. When an agent misbehaves, the layer tells you where to look.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ ⬡ MANAGED AGENTS — Where does it actually run?                  │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ 5 · GRAPH — Who runs when, and who checks whom?             │ │\n│ │ ┌─────────────────────────────────────────────────────────┐ │ │\n│ │ │ 4 · LOOP — When do we stop?                             │ │ │\n│ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │\n│ │ │ │ 3 · HARNESS — Can it act, and be checked?           │ │ │ │\n│ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ │\n│ │ │ │ │ 2 · CONTEXT — Is the right thing in the window? │ │ │ │ │\n│ │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ │ │\n│ │ │ │ │ │ 1 · PROMPT — Did I say it clearly?          │ │ │ │ │ │\n│ │ │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ │\n│ │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │\n│ │ │ └─────────────────────────────────────────────────────┘ │ │ │\n│ │ └─────────────────────────────────────────────────────────┘ │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n| Layer | The question it answers | PraisonAI |\n|:--|:--|:--|\n| **1 · Prompt** | Did I say it clearly? | `instructions=`, `role`/`goal`/`backstory`, `output=`, `templates=` |\n| **2 · Context** | Is the right thing in the window? | `memory=`, `knowledge=`, `context=`, handoff `ContextPolicy` |\n| **3 · Harness** | Can it act, and be checked? | `tools=`, `MCP()`, `guardrails=`, `approval=`, `hooks=`, `sandbox=` |\n| **4 · Loop** | When do we stop? | `execution=ExecutionConfig(...)`, `reflection=`, `autonomy=`, doom-loop detection |\n| **5 · Graph** | Who runs when, and who checks whom? | `AgentFlow`, `route()`, `parallel()`, `loop()`, `repeat()` |\n| **⬡ Managed** | *Where does it actually run?* | `tools_run_on=\"docker\"` — one shared sandbox for the tools, or `run_on=\"anthropic\"` for the whole agent |\n\n### Layer 1 · Prompt — *Did I say it clearly?*\n\nRole, instructions, examples, output format.\n\n```python\nfrom praisonaiagents import Agent\n\nagent = Agent(\n    role=\"Senior Data Analyst\",\n    goal=\"Turn raw numbers into decisions\",\n    output=\"verbose\",              # markdown-formatted output\n)\nagent.start(\"Summarise Q3 revenue trends\")\n```\n\n### Layer 2 · Context — *Is the right thing in the window?*\n\nWrite, select, compress, isolate — the four context operations, one parameter each.\n\n```python\nfrom praisonaiagents import Agent\n\nagent = Agent(\n    instructions=\"You are a support engineer.\",\n    memory={\"user_id\": \"u-42\"},    # write    — persists across runs (needs a user_id)\n    knowledge=[\"docs/\"],           # select   — retrieves only what's relevant\n    context=\"summarize\",           # compress — auto-compacts before the limit\n)\n```\n\n> **Isolate** is `handoffs=[specialist]` — a sub-agent inherits the last few messages and the intersection of your tools, not your whole transcript. [📖 Handoffs](https://docs.praison.ai/docs/concepts/handoffs)\n\n### Layer 3 · Harness — *Can it act, and be checked?*\n\n*Agent = Model + Harness.* Tool dispatch, plus the guides that steer before acting and the sensors that observe after.\n\n```python\nfrom praisonaiagents import Agent, MCP, tool\n\n@tool\ndef deploy(env: str) -> str:\n    \"\"\"Deploy the current build to an environment.\"\"\"\n    return f\"Deployed to {env}\"\n\nagent = Agent(\n    name=\"ReleaseEngineer\",\n    instructions=\"You are a release engineer.\",\n    tools=[deploy, MCP(\"npx -y @modelcontextprotocol/server-filesystem /tmp\")],\n    approval=True,                 # guide — human gate before risky tools run\n)\nagent.start(\"Deploy to staging, then list the files you can read\")\n```\n\n### Layer 4 · Loop — *When do we stop?*\n\nHard iteration caps, budget ceilings, no-progress detection and completion checks — every brake is explicit.\n\n```python\nfrom praisonaiagents import Agent, ExecutionConfig\n\nagent = Agent(\n    instructions=\"Fix the failing tests.\",\n    execution=ExecutionConfig(max_iter=30, max_budget=0.50, on_budget_exceeded=\"stop\"),\n    autonomy=True,                 # required to drive the loop with run_autonomous()\n)\nresult = agent.run_autonomous(\"Refactor the auth module\", max_iterations=5)\n\nprint(result.completion_reason)\n# goal | no_tool_calls | max_iterations | timeout | doom_loop | needs_help | error\n# (with on_budget_exceeded=\"stop\", hitting the cap raises BudgetExceededError,\n#  surfaced here as completion_reason=\"error\")\n```\n\n> **Doom-loop detection is on by default.** Repeated identical tool calls and A→B→A→B oscillation get caught — while a poller whose output keeps changing does not. [📖 Doom Loop Detection](https://docs.praison.ai/docs/features/doom-loop-detection)\n\n### Layer 5 · Graph — *Who runs when, and who checks whom?*\n\nTopology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.\n\n```python\nfrom praisonaiagents import AgentFlow\nfrom praisonaiagents.workflows import route, parallel, repeat\n\nflow = AgentFlow(steps=[\n    classifier,\n    route({\"bug\": [bug_agent], \"feature\": [feature_agent], \"default\": [triage]}),\n    parallel([reviewer, tester]),                      # fan out, join automatically\n    repeat(editor, until=lambda ctx: \"approved\" in ctx.previous_result.lower(),\n           max_iterations=3),                          # evaluator–optimizer\n])\nflow.run(\"Ticket #123: login fails on Safari\")\n```\n\n> The same graph is expressible in YAML with no Python at all. [📖 AgentFlow](https://docs.praison.ai/docs/concepts/agentflow)\n\n### ⬡ Outside the stack: Managed Agents — *Where does it actually run?*\n\nThe harness is commoditising; **where** the agent executes is the next multiplier. Rather than burning your laptop's CPU, hand an agent a short-lived cloud sandbox — repo, tools and tests run there.\n\n```bash\npip install praisonai\n```\n\nThe simplest way in is `tools_run_on=` — one whole team or workflow shares **one** sandbox, so a file written by step 1 is there for step 2. Thinking stays on your machine:\n\n```python\nfrom praisonaiagents import Agent, AgentFlow\n\nwriter = Agent(name=\"Writer\", instructions=\"You write files.\")\nreader = Agent(name=\"Reader\", instructions=\"You read files.\")\n\nflow = AgentFlow(tools_run_on=\"docker\", steps=[writer, reader])  # or e2b | modal | daytona | flyio\nflow.run(\"Write 'hello' to /workspace/note.txt, then read it back\")\n```\n\nSame thing with no Python at all:\n\n```yaml\nname: remote-demo\ntools_run_on: docker      # every step shares one sandbox\nagents:\n  writer: {role: Writer, goal: Write files}\n  reader: {role: Reader, goal: Read files}\nsteps:\n  - agent: writer\n    action: \"Write 'hello' to /workspace/note.txt\"\n  - agent: reader\n    action: \"Read /workspace/note.txt\"\n```\n\nFor a single agent, two words cover it — and they answer different questions:\n\n```python\nfrom praisonaiagents import Agent\n\n# A. Only the TOOLS move. Thinking stays on your machine.\nagent = Agent(name=\"builder\", instructions=\"You build things.\",\n              tools_run_on=\"docker\")   # docker | e2b | modal | daytona | flyio\n                                       # tenki | sandlock | ssh | novita | subprocess\n\n# B. The WHOLE agent moves — model calls, loop and tools\nagent = Agent(name=\"teacher\", instructions=\"You teach.\", run_on=\"anthropic\")  # hosted\nagent = Agent(name=\"builder\", instructions=\"You build.\", run_on=\"docker\")     # self-hosted\nagent.start(\"Write a Python script that prints the first 10 primes, then run it\")\n```\n\nAsk any object where it runs, and it will tell you:\n\n```python\n>>> Agent(name=\"builder\", instructions=\"x\", tools_run_on=\"docker\")\nAgent(name='builder', thinks_on='this machine', tools_run_on='a Docker container')\n\n>>> agent.where_does_it_run()\nThinking (the AI model calls) happens on this machine.\nTools run on a Docker container.\nYour own tools (check_db) still run on this machine -- only shell, file and\ncode tools move. They read and write this machine's files.\n```\n\nNaming a place that cannot do the job is a typo, not a preference, so it says so:\n\n```python\n>>> Agent(name=\"x\", instructions=\"i\", run_on=\"e2b\")\nTypeError: Agent(run_on='e2b') is not valid: run_on= places the whole agent\n-- model calls, loop and tools -- on a managed runtime, and 'e2b' runs\ncommands but cannot host an agent loop.\n  To run only the tools there:  Agent(tools_run_on='e2b')\n```\n\nTo run one block of code somewhere else, name the place on that call:\n\n```python\nagent.execute_code_sync(\"print(6 * 7)\", run_in=\"sandlock\")   # kernel-enforced\n```\n\nSee what is running and reclaim strays:\n\n```bash\npraisonai managed ps          # list running sandboxes\npraisonai managed stop --all  # reclaim them\n```\n\nSandboxes shut themselves down when idle (`auto_shutdown`, `idle_timeout_s`), and a post-setup snapshot is reused so the next run skips the image pull and dependency install. Commit a `.praisonai/environment.yaml` and the environment travels with the repo.\n\n> 📖 [20 runnable examples](examples/python/managed-agents/) · manage sessions with `praisonai managed sessions list <agent-id>` or `praisonai managed sessions resume <session-id> \"<prompt>\"`\n\n<sub>Stack framing adapted from [The Five-Layer Agent Stack](https://mer.vin/2026/07/five-layer-agent-stack-match-bug-to-right-layer/) and [Agent Harnesses vs Orbs](https://mer.vin/2026/08/agent-harnesses-vs-orbs-why-remote-sandboxes-beat-local-agent-loops/).</sub>\n\n---\n\n## 🌌 The PraisonAI Ecosystem\n\nStart simple with the core SDK, or expand to full visual builders and dashboards when you're ready.\n\n*   **Core SDK (`praisonaiagents`)**: For pure Python development. `pip install praisonaiagents`\n*   💻 **PraisonAI CLI (`praisonai`)**: For terminal-based developers. `pip install praisonai`\n*   🦞 **Claw Dashboard**: Connect agents directly to Telegram, Slack, or Discord. `pip install \"praisonai[claw]\"`\n*   🔗 **Flow Visual Builder**: Drag-and-drop workflow creation. `pip install \"praisonai[flow]\"`\n*   🤖 **PraisonAI UI**: Clean chat interface. `pip install \"praisonai[ui]\"`\n\n### JavaScript SDK\n\n```bash\nnpm install praisonai\n```\n\n## 🧠 Supported Providers & Features\n\nPowered by 100+ LLMs (OpenAI, Anthropic, Gemini & local models).\n\n<p align=\"center\">\n<img src=\"https://img.shields.io/badge/OpenAI-412991?style=flat&logo=openai&logoColor=white\" alt=\"OpenAI\" />\n<img src=\"https://img.shields.io/badge/Anthropic-191919?style=flat&logo=anthropic&logoColor=white\" alt=\"Anthropic\" />\n<img src=\"https://img.shields.io/badge/Google_Gemini-4285F4?style=flat&logo=google&logoColor=white\" alt=\"Google Gemini\" />\n<img src=\"https://img.shields.io/badge/DeepSeek-566AB2?style=flat\" alt=\"DeepSeek\" />\n<img src=\"https://img.shields.io/badge/Azure-0078D4?style=flat&logo=microsoftazure&logoColor=white\" alt=\"Azure\" />\n<img src=\"https://img.shields.io/badge/Ollama-000000?style=flat\" alt=\"Ollama\" />\n<img src=\"https://img.shields.io/badge/Groq-F05237?style=flat\" alt=\"Groq\" />\n<img src=\"https://img.shields.io/badge/Mistral-FF7000?style=flat\" alt=\"Mistral\" />\n<img src=\"https://img.shields.io/badge/Cerebras-F05A28?style=flat\" alt=\"Cerebras\" />\n<img src=\"https://img.shields.io/badge/Cohere-39594D?style=flat\" alt=\"Cohere\" />\n<img src=\"https://img.shields.io/badge/OpenRouter-6467F2?style=flat\" alt=\"OpenRouter\" />\n<img src=\"https://img.shields.io/badge/Perplexity-20808D?style=flat\" alt=\"Perplexity\" />\n<img src=\"https://img.shields.io/badge/Fireworks-FF6B35?style=flat\" alt=\"Fireworks\" />\n<img src=\"https://img.shields.io/badge/AWS_Bedrock-FF9900?style=flat&logo=amazonaws&logoColor=white\" alt=\"AWS Bedrock\" />\n<img src=\"https://img.shields.io/badge/xAI_Grok-000000?style=flat\" alt=\"xAI Grok\" />\n<img src=\"https://img.shields.io/badge/Vertex_AI-4285F4?style=flat&logo=googlecloud&logoColor=white\" alt=\"Vertex AI\" />\n<img src=\"https://img.shields.io/badge/HuggingFace-FFD21E?style=flat&logo=huggingface&logoColor=black\" alt=\"HuggingFace\" />\n<img src=\"https://img.shields.io/badge/Together_AI-000000?style=flat\" alt=\"Together AI\" />\n<img src=\"https://img.shields.io/badge/Databricks-FF3621?style=flat&logo=databricks&logoColor=white\" alt=\"Databricks\" />\n<img src=\"https://img.shields.io/badge/Replicate-262626?style=flat\" alt=\"Replicate\" />\n<img src=\"https://img.shields.io/badge/Cloudflare-F38020?style=flat&logo=cloudflare&logoColor=white\" alt=\"Cloudflare\" />\n</p>\n\n<details>\n<summary><strong>View all 24 providers with examples</strong></summary>\n\n| Provider | Example |\n|----------|:-------:|\n| OpenAI | [Example](examples/python/providers/openai/openai_gpt4_example.py) |\n| Anthropic | [Example](examples/python/providers/anthropic/anthropic_claude_example.py) |\n| Google Gemini | [Example](examples/python/providers/google/google_gemini_example.py) |\n| Ollama | [Example](examples/python/providers/ollama/ollama-agents.py) |\n| Groq | [Example](examples/python/providers/groq/kimi_with_groq_example.py) |\n| DeepSeek | [Example](examples/python/providers/deepseek/deepseek_example.py) |\n| xAI Grok | [Example](examples/python/providers/xai/xai_grok_example.py) |\n| Mistral | [Example](examples/python/providers/mistral/mistral_example.py) |\n| Cohere | [Example](examples/python/providers/cohere/cohere_example.py) |\n| Perplexity | [Example](examples/python/providers/perplexity/perplexity_example.py) |\n| Fireworks | [Example](examples/python/providers/fireworks/fireworks_example.py) |\n| Together AI | [Example](examples/python/providers/together/together_ai_example.py) |\n| OpenRouter | [Example](examples/python/providers/openrouter/openrouter_example.py) |\n| HuggingFace | [Example](examples/python/providers/huggingface/huggingface_example.py) |\n| Azure OpenAI | [Example](examples/python/providers/azure/azure_openai_example.py) |\n| AWS Bedrock | [Example](examples/python/providers/aws/aws_bedrock_example.py) |\n| Google Vertex | [Example](examples/python/providers/vertex/vertex_example.py) |\n| Databricks | [Example](examples/python/providers/databricks/databricks_example.py) |\n| Cloudflare | [Example](examples/python/providers/cloudflare/cloudflare_example.py) |\n| AI21 | [Example](examples/python/providers/ai21/ai21_example.py) |\n| Replicate | [Example](examples/python/providers/replicate/replicate_example.py) |\n| SageMaker | [Example](examples/python/providers/sagemaker/sagemaker_example.py) |\n| Moonshot | [Example](examples/python/providers/moonshot/moonshot_example.py) |\n| vLLM | [Example](examples/python/providers/vllm/vllm_example.py) |\n\n</details>\n\n<div align=\"center\">\n  <a href=\"https://x.com/elonmusk/status/1893870468249141688\" target=\"_blank\">\n    <img src=\".github/images/elon_musk_praisonai.png\" alt=\"Highlighted by Elon Musk\" width=\"600\" />\n  </a>\n  <p><em>\"Grok 3 customer support\" — <a href=\"https://x.com/elonmusk/status/1893870468249141688\">Elon Musk quoting PraisonAI's tutorial</a></em></p>\n</div>\n<br>\n\n---\n\n## 🌟 Why PraisonAI?\n\n| | Feature | How |\n|--|---------|-----|\n| 🔌 | **MCP Protocol** — stdio, HTTP, WebSocket, SSE | `tools=MCP(\"npx ...\")` |\n| 🧠 | **Planning Mode** — plan → execute → reason | `planning=True` |\n| 🔍 | **Deep Research** — multi-step autonomous research | [Docs](https://docs.praison.ai/docs/agents/deep-research) |\n| 🤖 | **External Agents** — orchestrate Claude Code, Gemini CLI, Codex | [Docs](https://docs.praison.ai/docs/code/external-agents) |\n| 🔄 | **Agent Handoffs** — seamless conversation passing | `handoffs=[other_agent]` |\n| 🛡️ | **Guardrails** — input/output validation | [Docs](https://docs.praison.ai/docs/concepts/guardrails) |\n|  | **Web Search + Fetch** — native browsing | `web=True` |\n| 🪞 | **Self Reflection** — agent reviews its own output | [Docs](https://docs.praison.ai/docs/concepts/reflection) |\n| 🔀 | **Workflow Patterns** — route, parallel, loop, repeat | [Docs](https://docs.praison.ai/docs/concepts/agentflow) |\n| 🧠 | **Memory (zero deps)** — works out of the box | `memory=True` |\n\n<details>\n<summary><strong>View all 25 features</strong></summary>\n\n| | Feature | How |\n|--|---------|-----|\n| 💡 | **Prompt Caching** — reduce latency + cost | `caching=True` |\n| 💾 | **Sessions + Auto-Save** — persistent state across restarts | `auto_save=\"my-project\"` |\n| 💭 | **Thinking Budgets** — control reasoning depth | `agent.thinking_budget = 1024` |\n| 📚 | **RAG + Quality-Based RAG** — auto quality scoring retrieval | [Docs](https://docs.praison.ai/docs/concepts/rag) |\n| 📊 | **Model Router** — auto-routes to cheapest capable model | [Docs](https://docs.praison.ai/docs/features/model-router) |\n| 🧊 | **Shadow Git Checkpoints** — auto-rollback on failure | [Docs](https://docs.praison.ai/docs/features/checkpoints) |\n| 📡 | **A2A Protocol** — agent-to-agent interop | [Docs](https://docs.praison.ai/docs/features/a2a) |\n| 📏 | **Context Compaction** — never hit token limits | [Docs](https://docs.praison.ai/docs/features/context-compaction) |\n| 📡 | **Telemetry** — OpenTelemetry traces, spans, metrics | [Docs](https://docs.praison.ai/docs/features/telemetry) |\n| 📜 | **Policy Engine** — declarative agent behavior control | [Docs](https://docs.praison.ai/docs/features/policy-engine) |\n| 🔄 | **Background Tasks** — fire-and-forget agents | [Docs](https://docs.praison.ai/docs/features/background-tasks) |\n| 🔁 | **Doom Loop Detection** — auto-recovery from stuck agents | [Docs](https://docs.praison.ai/docs/features/doom-loop-detection) |\n| 🕸️ | **Graph Memory** — Neo4j-style relationship tracking | [Docs](https://docs.praison.ai/docs/features/graph-memory) |\n| 🏖️ | **Sandbox Execution** — isolated code execution | [Docs](https://docs.praison.ai/docs/features/sandbox) |\n| 🖥️ | **Bot Gateway** — multi-agent routing across channels | [Docs](https://docs.praison.ai/docs/features/bot-gateway) |\n\n</details>\n\n\n\n\n---\n\n## 📘 Using Python Code\n\n### 1. Single Agent\n\n```python\nfrom praisonaiagents import Agent\nagent = Agent(instructions=\"You are a helpful AI assistant\")\nagent.start(\"Write a movie script about a robot in Mars\")\n```\n\n### 2. Multi Agents\n\n```python\nfrom praisonaiagents import Agent, Agents\n\nresearch_agent = Agent(instructions=\"Research about AI\")\nsummarise_agent = Agent(instructions=\"Summarise research agent's findings\")\nagents = Agents(agents=[research_agent, summarise_agent])\nagents.start()\n```\n\n### 3. MCP (Model Context Protocol)\n\n```python\nfrom praisonaiagents import Agent, MCP\n\n# stdio - Local NPX/Python servers\nagent = Agent(tools=MCP(\"npx @modelcontextprotocol/server-memory\"))\n\n# Streamable HTTP - Production servers\nagent = Agent(tools=MCP(\"https://api.example.com/mcp\"))\n\n# WebSocket - Real-time bidirectional\nagent = Agent(tools=MCP(\"wss://api.example.com/mcp\", auth_token=\"token\"))\n\n# With environment variables\nagent = Agent(\n    tools=MCP(\n        command=\"npx\",\n        args=[\"-y\", \"@modelcontextprotocol/server-brave-search\"],\n        env={\"BRAVE_API_KEY\": \"your-key\"}\n    )\n)\n```\n\n> 📖 [Full MCP docs](https://docs.praison.ai/docs/mcp/transports) — stdio, HTTP, WebSocket, SSE transports\n\n### 4. Custom Tools\n\n```python\nfrom praisonaiagents import Agent, tool\n\n@tool\ndef search(query: str) -> str:\n    \"\"\"Search the web for information.\"\"\"\n    return f\"Results for: {query}\"\n\n@tool\ndef calculate(expression: str) -> float:\n    \"\"\"Safely evaluate a numeric arithmetic expression.\"\"\"\n    import ast\n    import operator\n    \n    # Define allowed operations\n    _OPS = {\n        ast.Add: operator.add,\n        ast.Sub: operator.sub,\n        ast.Mult: operator.mul,\n        ast.Div: operator.truediv,\n        ast.Pow: operator.pow,\n        ast.USub: operator.neg,\n        ast.UAdd: operator.pos,\n    }\n    \n    def _safe_eval(node):\n        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):\n            return node.value\n        elif isinstance(node, ast.BinOp) and type(node.op) in _OPS:\n            return _OPS[type(node.op)](_safe_eval(node.left), _safe_eval(node.right))\n        elif isinstance(node, ast.UnaryOp) and type(node.op) in _OPS:\n            return _OPS[type(node.op)](_safe_eval(node.operand))\n        else:\n            raise ValueError(\"Unsupported expression\")\n    \n    try:\n        return _safe_eval(ast.parse(expression, mode=\"eval\").body)\n    except (ValueError, SyntaxError, TypeError, ZeroDivisionError, OverflowError):\n        raise ValueError(\"Invalid arithmetic expression\")\n\nagent = Agent(\n    instructions=\"You are a helpful assistant\",\n    tools=[search, calculate]\n)\nagent.start(\"Search for AI news and calculate 15*4\")\n```\n\n> ⚠️ **Security Note:** Never use `eval()`, `exec()`, or `subprocess` in tool functions that process LLM-generated or user-supplied input. Always validate and sanitize inputs to prevent code injection attacks.\n> 📖 [Full tools docs](https://docs.praison.ai/docs/tools/tools) — BaseTool, tool packages, 100+ built-in tools\n\n### 5. Persistence (Databases)\n\n```python\nfrom praisonaiagents import Agent, db\n\nagent = Agent(\n    name=\"Assistant\",\n    memory={\n        \"db\": db(database_url=\"postgresql://localhost/mydb\"),\n        \"session_id\": \"my-session\",\n    },\n)\nagent.chat(\"Hello!\")  # Auto-persists messages, runs, traces\n```\n\n> 📖 [Full persistence docs](https://docs.praison.ai/docs/databases/overview) — PostgreSQL, MySQL, SQLite, MongoDB, Redis, and 20+ more\n\n### 6. PraisonAI Claw 🦞 (Dashboard UI)\n\nConnect your AI agents to **Telegram, Discord, Slack, WhatsApp** and more — all from a single command.\n\n```bash\npip install \"praisonai[claw]\"\npraisonai claw\n```\n\n#### Required Environment Variables\n\nCopy `.env.example` to `.env` and configure the following variables:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | Yes | OpenAI API key for all LLM calls |\n| `TAVILY_API_KEY` | Yes (Claw) | Tavily key for the built-in web-search tool. Get one free at https://app.tavily.com |\n\nOpen **http://localhost:8082** — the dashboard comes with 13 built-in pages: Chat, Agents, Memory, Knowledge, Channels, Guardrails, Cron, and more. Add messaging channels directly from the UI.\n\n> 📖 [Full Claw docs](https://docs.praison.ai/docs/concepts/claw) — platform tokens, CLI options, Docker, and YAML agent mode\n\n### 7. Langflow Integration 🔗 (Visual Flow Builder)\n\nBuild multi-agent workflows visually with **drag-and-drop** components in Langflow.\n\n```bash\npip install \"praisonai[flow]\"\npraisonai flow\n```\n\nOpen **http://localhost:7861** — use the **Agent** and **Agent Team** components to create sequential or parallel workflows. Connect Chat Input → Agent Team → Chat Output for instant multi-agent pipelines.\n\n> 📖 [Full Flow docs](https://docs.praison.ai/docs/concepts/agentflow) — visual agent building, component reference, and deployment\n\n### 8. PraisonAI UI 🤖 (Clean Chat)\n\nLightweight chat interface for your AI agents.\n\n```bash\npip install \"praisonai[ui]\"\npraisonai ui\n```\n\n---\n\n## 📄 Using YAML (No Code)\n\n### Example 1: Two Agents Working Together\n\nCreate `agents.yaml`:\n\n```yaml\nframework: praisonai\ntopic: \"Write a blog post about AI\"\n\nagents:\n  researcher:\n    role: Research Analyst\n    goal: Research AI trends and gather information\n    instructions: \"Find accurate information about AI trends\"\n    \n  writer:\n    role: Content Writer\n    goal: Write engaging blog posts\n    instructions: \"Write clear, engaging content based on research\"\n```\n\nRun with:\n```bash\npraisonai agents.yaml\n```\n\n> The agents automatically work together sequentially\n\n### Example 2: Agent with Custom Tool\n\nCreate two files in the same folder:\n\n**agents.yaml:**\n```yaml\nframework: praisonai\ntopic: \"Calculate the sum of 25 and 15\"\n\nagents:\n  calculator_agent:\n    role: Calculator\n    goal: Perform calculations\n    instructions: \"Use the add_numbers tool to help with calculations\"\n    tools:\n      - add_numbers\n```\n\n**tools.py:**\n```python\ndef add_numbers(a: float, b: float) -> float:\n    \"\"\"\n    Add two numbers together.\n    \n    Args:\n        a: First number\n        b: Second number\n    \n    Returns:\n        The sum of a and b\n    \"\"\"\n    return a + b\n```\n\nRun with:\n```bash\npraisonai agents.yaml\n```\n\n> 💡 **Tips:** \n> - Use the function name (e.g., `add_numbers`) in the tools list, not the file name\n> - Tools in `tools.py` are automatically discovered\n> - The function's docstring helps the AI understand how to use it\n\n---\n\n## 🎯 CLI Quick Reference\n\n| Category | Commands |\n|----------|----------|\n| **Execution** | `praisonai`, `--auto`, `--interactive`, `--chat` |\n| **Research** | `research`, `--query-rewrite`, `--deep-research` |\n| **Planning** | `--planning`, `--planning-tools`, `--planning-reasoning` |\n| **Workflows** | `workflow run`, `workflow list`, `workflow auto` |\n| **Memory** | `memory show`, `memory add`, `memory search`, `memory clear` |\n| **Knowledge** | `knowledge add`, `knowledge query`, `knowledge list` |\n| **Sessions** | `session list`, `session resume`, `session delete` |\n| **Tools** | `tools list`, `tools info`, `tools search` |\n| **MCP** | `mcp list`, `mcp create`, `mcp enable` |\n| **Development** | `commit`, `docs`, `checkpoint`, `hooks` |\n| **Scheduling** | `schedule start`, `schedule list`, `schedule stop` |\n\n> 📖 [Full CLI reference](https://docs.praison.ai/docs/cli/cli-reference)\n\n---\n\n## ✨ Key Features\n\n<details open>\n<summary><strong>🤖 Core Agents</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Single Agent | [Example](examples/python/agents/single-agent.py) | [📖](https://docs.praison.ai/docs/agents/single) |\n| Multi Agents | [Example](examples/python/general/mini_agents_example.py) | [📖](https://docs.praison.ai/docs/concepts/agents) |\n| Auto Agents | [Example](examples/python/general/auto_agents_example.py) | [📖](https://docs.praison.ai/docs/features/autoagents) |\n| Self Reflection AI Agents | [Example](examples/python/concepts/self-reflection-details.py) | [📖](https://docs.praison.ai/docs/concepts/reflection) |\n| Reasoning AI Agents | [Example](examples/python/concepts/reasoning-extraction.py) | [📖](https://docs.praison.ai/docs/features/reasoning) |\n| Multi Modal AI Agents | [Example](examples/python/general/multimodal.py) | [📖](https://docs.praison.ai/docs/features/multimodal) |\n\n</details>\n\n<details>\n<summary><strong>🔄 Workflows</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Simple Workflow | [Example](examples/python/workflows/simple_workflow.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n| Workflow with Agents | [Example](examples/python/workflows/workflow_with_agents.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n| Agentic Routing (`route()`) | [Example](examples/python/workflows/workflow_routing.py) | [📖](https://docs.praison.ai/docs/features/routing) |\n| Parallel Execution (`parallel()`) | [Example](examples/python/workflows/workflow_parallel.py) | [📖](https://docs.praison.ai/docs/features/parallelisation) |\n| Loop over List/CSV (`loop()`) | [Example](examples/python/workflows/workflow_loop_csv.py) | [📖](https://docs.praison.ai/docs/features/repetitive) |\n| Evaluator-Optimizer (`repeat()`) | [Example](examples/python/workflows/workflow_repeat.py) | [📖](https://docs.praison.ai/docs/concepts/evaluation) |\n| Conditional Steps | [Example](examples/python/workflows/workflow_conditional.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n| Workflow Branching | [Example](examples/python/workflows/workflow_branching.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n| Workflow Early Stop | [Example](examples/python/workflows/workflow_early_stop.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n| Workflow Checkpoints | [Example](examples/python/workflows/workflow_checkpoints.py) | [📖](https://docs.praison.ai/docs/concepts/agentflow) |\n\n</details>\n\n<details>\n<summary><strong>💻 Code & Development</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Code Interpreter Agents | [Example](examples/python/agents/code-agent.py) | [📖](https://docs.praison.ai/docs/features/codeagent) |\n| AI Code Editing Tools | [Example](examples/python/code/code_editing_example.py) | [📖](https://docs.praison.ai/docs/code/editing) |\n| External Agents (All) | [Example](examples/python/code/external_agents_example.py) | [📖](https://docs.praison.ai/docs/code/external-agents) |\n| Claude Code CLI | [Example](examples/python/code/claude_code_example.py) | [📖](https://docs.praison.ai/docs/code/claude-code) |\n| Gemini CLI | [Example](examples/python/code/gemini_cli_example.py) | [📖](https://docs.praison.ai/docs/code/gemini-cli) |\n| Codex CLI | [Example](examples/python/code/codex_cli_example.py) | [📖](https://docs.praison.ai/docs/code/codex-cli) |\n| Cursor CLI | [Example](examples/python/code/cursor_cli_example.py) | [📖](https://docs.praison.ai/docs/code/cursor-cli) |\n\n</details>\n\n<details>\n<summary><strong>🧠 Memory & Knowledge</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Memory (Short & Long Term) | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/docs/concepts/memory) |\n| File-Based Memory | [Example](examples/python/general/memory_example.py) | [📖](https://docs.praison.ai/docs/concepts/memory) |\n| Claude Memory Tool | [Example](examples/python/memory/claude_memory_example.py) | [📖](https://docs.praison.ai/docs/features/claude-memory-tool) |\n| Add Custom Knowledge | [Example](examples/python/concepts/knowledge-agents.py) | [📖](https://docs.praison.ai/docs/concepts/knowledge) |\n| RAG Agents | [Example](examples/python/concepts/rag-agents.py) | [📖](https://docs.praison.ai/docs/concepts/rag) |\n| Chat with PDF Agents | [Example](examples/python/concepts/chat-with-pdf.py) | [📖](https://docs.praison.ai/docs/features/chat-with-pdf) |\n| Data Readers (PDF, DOCX, etc.) | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/chunking-strategies) |\n| Vector Store Selection | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/knowledge-backends) |\n| Retrieval Strategies | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/retrieval-strategies) |\n| Rerankers | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/smart-retrieval) |\n| Index Types (Vector/Keyword/Hybrid) | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/incremental-indexing) |\n| Query Engines (Sub-Question, etc.) | [CLI](https://docs.praison.ai/docs/cli/knowledge) | [📖](https://docs.praison.ai/docs/features/retrieval) |\n\n</details>\n\n<details>\n<summary><strong>🔬 Research & Intelligence</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Deep Research Agents | [Example](examples/python/agents/research-agent.py) | [📖](https://docs.praison.ai/docs/agents/deep-research) |\n| Query Rewriter Agent | [Example](examples/python/agents/query-rewriter-agent.py) | [📖](https://docs.praison.ai/docs/agents/query-rewriter) |\n| Native Web Search | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/docs/agents/websearch) |\n| Built-in Search Tools | [Example](examples/python/agents/websearch-agent.py) | [📖](https://docs.praison.ai/docs/tools/tavily) |\n| Unified Web Search | [Example](examples/python/web_search_example.py) | [📖](https://docs.praison.ai/docs/tools/web-search) |\n| Web Fetch (Anthropic) | [Example](examples/python/agents/web-fetch-agent.py) | [📖](https://docs.praison.ai/docs/features/model-capabilities) |\n\n</details>\n\n<details>\n<summary><strong>📋 Planning & Execution</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Planning Mode | [Example](examples/python/agents/planning-agent.py) | [📖](https://docs.praison.ai/docs/concepts/planning) |\n| Planning Tools | [Example](examples/python/agents/planning-agent.py) | [📖](https://docs.praison.ai/docs/concepts/planning) |\n| Planning Reasoning | [Example](examples/python/agents/planning-agent.py) | [📖](https://docs.praison.ai/docs/concepts/planning) |\n| Prompt Chaining | [Example](examples/python/general/prompt_chaining.py) | [📖](https://docs.praison.ai/docs/features/promptchaining) |\n| Evaluator Optimiser | [Example](examples/python/general/evaluator-optimiser.py) | [📖](https://docs.praison.ai/docs/concepts/evaluation) |\n| Orchestrator Workers | [Example](examples/python/general/orchestrator-workers.py) | [📖](https://docs.praison.ai/docs/concepts/orchestration) |\n\n</details>\n\n<details>\n<summary><strong>👥 Specialized Agents</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Data Analyst Agent | [Example](examples/python/agents/data-analyst-agent.py) | [📖](https://docs.praison.ai/docs/agents/data-analyst) |\n| Finance Agent | [Example](examples/python/agents/finance-agent.py) | [📖](https://docs.praison.ai/docs/agents/finance) |\n| Shopping Agent | [Example](examples/python/agents/shopping-agent.py) | [📖](https://docs.praison.ai/docs/agents/shopping) |\n| Recommendation Agent | [Example](examples/python/agents/recommendation-agent.py) | [📖](https://docs.praison.ai/docs/agents/recommendation) |\n| Wikipedia Agent | [Example](examples/python/agents/wikipedia-agent.py) | [📖](https://docs.praison.ai/docs/agents/wikipedia) |\n| Programming Agent | [Example](examples/python/agents/programming-agent.py) | [📖](https://docs.praison.ai/docs/agents/programming) |\n| Math Agents | [Example](examples/python/agents/math-agent.py) | [📖](https://docs.praison.ai/docs/features/mathagent) |\n| Markdown Agent | [Example](examples/python/agents/markdown-agent.py) | [📖](https://docs.praison.ai/docs/agents/markdown) |\n| Prompt Expander Agent | [Example](examples/python/agents/prompt-expander-agent.py) | [📖](https://docs.praison.ai/docs/agents/prompt-expander) |\n\n</details>\n\n<details>\n<summary><strong>🎨 Media & Multimodal</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Image Generation Agent | [Example](examples/python/image/image-agent.py) | [📖](https://docs.praison.ai/docs/features/image-generation) |\n| Image to Text Agent | [Example](examples/python/agents/image-to-text-agent.py) | [📖](https://docs.praison.ai/docs/agents/image-to-text) |\n| Video Agent | [Example](examples/python/agents/video-agent.py) | [📖](https://docs.praison.ai/docs/agents/video) |\n| Camera Integration | [Example](examples/python/camera/) | [📖](https://docs.praison.ai/docs/features/camera-integration) |\n\n</details>\n\n<details>\n<summary><strong>🔌 Protocols & Integration</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| MCP Transports | [Example](examples/python/mcp/mcp-transports-overview.py) | [📖](https://docs.praison.ai/docs/mcp/transports) |\n| WebSocket MCP | [Example](examples/python/mcp/websocket-mcp.py) | [📖](https://docs.praison.ai/docs/mcp/sse-transport) |\n| MCP Security | [Example](examples/python/mcp/mcp-security.py) | [📖](https://docs.praison.ai/docs/mcp/transports) |\n| MCP Resumability | [Example](examples/python/mcp/mcp-resumability.py) | [📖](https://docs.praison.ai/docs/mcp/sse-transport) |\n| MCP Config Management | [Docs](https://docs.praison.ai/docs/cli/mcp) | [📖](https://docs.praison.ai/docs/cli/mcp) |\n| LangChain Integrated Agents | [Example](examples/python/general/langchain_example.py) | [📖](https://docs.praison.ai/docs/features/langchain) |\n\n</details>\n\n<details>\n<summary><strong>🛡️ Safety & Control</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Guardrails | [Example](examples/python/guardrails/comprehensive-guardrails-example.py) | [📖](https://docs.praison.ai/docs/concepts/guardrails) |\n| Human Approval | [Example](examples/python/general/human_approval_example.py) | [📖](https://docs.praison.ai/docs/concepts/approval) |\n| Rules & Instructions | [Docs](https://docs.praison.ai/docs/features/rules) | [📖](https://docs.praison.ai/docs/features/rules) |\n\n</details>\n\n<details>\n<summary><strong>⚙️ Advanced Features</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Async & Parallel Processing | [Example](examples/python/general/async_example.py) | [📖](https://docs.praison.ai/docs/features/async) |\n| Parallelisation | [Example](examples/python/general/parallelisation.py) | [📖](https://docs.praison.ai/docs/features/parallelisation) |\n| Repetitive Agents | [Example](examples/python/concepts/repetitive-agents.py) | [📖](https://docs.praison.ai/docs/features/repetitive) |\n| Agent Handoffs | [Example](examples/python/handoff/handoff_basic.py) | [📖](https://docs.praison.ai/docs/concepts/handoffs) |\n| Stateful Agents | [Example](examples/python/stateful/workflow-state-example.py) | [📖](https://docs.praison.ai/docs/features/stateful-agents) |\n| Autonomous Workflow | [Example](examples/python/general/autonomous-agent.py) | [📖](https://docs.praison.ai/docs/concepts/autonomy) |\n| Structured Output Agents | [Example](examples/python/general/structured_agents_example.py) | [📖](https://docs.praison.ai/docs/features/structured) |\n| Model Router | [Example](examples/python/agents/router-agent-cost-optimization.py) | [📖](https://docs.praison.ai/docs/features/model-router) |\n| Prompt Caching | [Example](examples/python/agents/prompt-caching-agent.py) | [📖](https://docs.praison.ai/docs/features/model-capabilities) |\n| Fast Context | [Example](examples/context/00_agent_fast_context_basic.py) | [📖](https://docs.praison.ai/docs/features/fast-context) |\n\n</details>\n\n<details>\n<summary><strong>🛠️ Tools & Configuration</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| 100+ Custom Tools | [Example](examples/python/general/tools_example.py) | [📖](https://docs.praison.ai/docs/tools/tools) |\n| YAML Configuration | [Example](examples/cookbooks/yaml/secondary_market_research_agents.yaml) | [📖](https://docs.praison.ai/docs/developers/agents-playbook) |\n| 100+ LLM Support | [Example](examples/python/providers/openai/openai_gpt4_example.py) | [📖](https://docs.praison.ai/docs/models) |\n| Callback Agents | [Example](examples/python/general/advanced-callback-systems.py) | [📖](https://docs.praison.ai/docs/concepts/hooks) |\n| Hooks | [Example](examples/python/hooks/hooks_example.py) | [📖](https://docs.praison.ai/docs/concepts/hooks) |\n| Middleware System | [Example](examples/middleware/basic_middleware.py) | [📖](https://docs.praison.ai/docs/features/middleware) |\n| Configurable Model | [Example](examples/middleware/configurable_model.py) | [📖](https://docs.praison.ai/docs/features/configurable-model) |\n| Rate Limiter | [Example](examples/middleware/rate_limiter.py) | [📖](https://docs.praison.ai/docs/features/rate-limiter) |\n| Injected Tool State | [Example](examples/middleware/injected_state.py) | [📖](https://docs.praison.ai/docs/features/injected-state) |\n| Shadow Git Checkpoints | [Example](examples/checkpoints/basic_checkpoint.py) | [📖](https://docs.praison.ai/docs/features/checkpoints) |\n| Background Tasks | [Example](examples/background/basic_background.py) | [📖](https://docs.praison.ai/docs/features/background-tasks) |\n| Policy Engine | [Example](examples/policy/basic_policy.py) | [📖](https://docs.praison.ai/docs/features/policy-engine) |\n| Thinking Budgets | [Example](examples/thinking/basic_thinking.py) | [📖](https://docs.praison.ai/docs/features/thinking-budgets) |\n| Output Styles | [Example](examples/output/basic_output.py) | [📖](https://docs.praison.ai/docs/features/output-styles) |\n| Context Compaction | [Example](examples/compaction/basic_compaction.py) | [📖](https://docs.praison.ai/docs/features/context-compaction) |\n\n</details>\n\n<details>\n<summary><strong>📊 Monitoring & Management</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Sessions Management | [Example](examples/python/sessions/comprehensive-session-management.py) | [📖](https://docs.praison.ai/docs/concepts/session-management) |\n| Auto-Save Sessions | [Docs](https://docs.praison.ai/docs/cli/session) | [📖](https://docs.praison.ai/docs/cli/session) |\n| History in Context | [Docs](https://docs.praison.ai/docs/cli/session) | [📖](https://docs.praison.ai/docs/cli/session) |\n| Telemetry | [Example](examples/python/telemetry/production-telemetry-example.py) | [📖](https://docs.praison.ai/docs/features/telemetry) |\n| Langfuse Tracing | [Docs](https://docs.praison.ai/docs/observability/langfuse) | [📖](https://docs.praison.ai/docs/observability/langfuse) |\n| Project Docs (.praison/docs/) | [Docs](https://docs.praison.ai/docs/cli/docs) | [📖](https://docs.praison.ai/docs/cli/docs) |\n| AI Commit Messages | [Docs](https://docs.praison.ai/docs/cli/commit) | [📖](https://docs.praison.ai/docs/cli/commit) |\n| @Mentions in Prompts | [Docs](https://docs.praison.ai/docs/cli/mentions) | [📖](https://docs.praison.ai/docs/cli/mentions) |\n\n</details>\n\n<details>\n<summary><strong>🖥️ CLI Features</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Slash Commands | [Example](examples/python/cli/slash_commands_example.py) | [📖](https://docs.praison.ai/docs/cli/slash-commands) |\n| Autonomy Modes | [Example](examples/python/cli/autonomy_modes_example.py) | [📖](https://docs.praison.ai/docs/cli/autonomy-modes) |\n| Cost Tracking | [Example](examples/python/cli/cost_tracking_example.py) | [📖](https://docs.praison.ai/docs/cli/cost-tracking) |\n| Repository Map | [Example](examples/python/cli/repo_map_example.py) | [📖](https://docs.praison.ai/docs/cli/repo-map) |\n| Interactive TUI | [Example](examples/python/cli/interactive_tui_example.py) | [📖](https://docs.praison.ai/docs/cli/interactive-tui) |\n| Git Integration | [Example](examples/python/cli/git_integration_example.py) | [📖](https://docs.praison.ai/docs/cli/git-integration) |\n| Sandbox Execution | [Example](examples/python/cli/sandbox_execution_example.py) | [📖](https://docs.praison.ai/docs/cli/sandbox-execution) |\n| CLI Compare | [Example](examples/compare/cli_compare_basic.py) | [📖](https://docs.praison.ai/docs/cli/compare) |\n| Profile/Benchmark | [Docs](https://docs.praison.ai/docs/cli/profile) | [📖](https://docs.praison.ai/docs/cli/profile) |\n| Auto Mode | [Docs](https://docs.praison.ai/docs/cli/auto) | [📖](https://docs.praison.ai/docs/cli/auto) |\n| Init | [Docs](https://docs.praison.ai/docs/cli/init) | [📖](https://docs.praison.ai/docs/cli/init) |\n| File Input | [Docs](https://docs.praison.ai/docs/cli/file-input) | [📖](https://docs.praison.ai/docs/cli/file-input) |\n| Final Agent | [Docs](https://docs.praison.ai/docs/cli/final-agent) | [📖](https://docs.praison.ai/docs/cli/final-agent) |\n| Max Tokens | [Docs](https://docs.praison.ai/docs/cli/max-tokens) | [📖](https://docs.praison.ai/docs/cli/max-tokens) |\n\n</details>\n\n<details>\n<summary><strong>🧪 Evaluation</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Accuracy Evaluation | [Example](examples/eval/accuracy_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |\n| Performance Evaluation | [Example](examples/eval/performance_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |\n| Reliability Evaluation | [Example](examples/eval/reliability_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |\n| Criteria Evaluation | [Example](examples/eval/criteria_example.py) | [📖](https://docs.praison.ai/docs/cli/eval) |\n\n</details>\n\n<details>\n<summary><strong>🎯 Agent Skills</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Skills Management | [Example](examples/skills/basic_skill_usage.py) | [📖](https://docs.praison.ai/docs/concepts/skills) |\n| Custom Skills | [Example](examples/skills/custom_skill_example.py) | [📖](https://docs.praison.ai/docs/concepts/skills) |\n\n</details>\n\n<details>\n<summary><strong>⏰ 24/7 Scheduling</strong></summary>\n\n| Feature | Code | Docs |\n|---------|:----:|:----:|\n| Agent Scheduler | [Example](examples/python/scheduled_agents/news_checker_live.py) | [📖](https://docs.praison.ai/docs/cli/scheduler) |\n\n</details>\n\n---\n\n## 💻 Using JavaScript Code\n\n```bash\nnpm install praisonai\nexport OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx\n```\n\n```javascript\nconst { Agent } = require('praisonai');\nconst agent = new Agent({ instructions: 'You are a helpful AI assistant' });\nagent.start('Write a movie script about a robot in Mars');\n```\n\n---\n\n## ⚡ Performance\n\nPraisonAI is built for speed, with agent instantiation in around 14μs. This reduces overhead, improves responsiveness, and helps multi-agent systems scale efficiently in real-world production workloads.\n\n| Performance Metric | PraisonAI |\n|--------------------|-----------|\n| Avg Instantiation Time | **14 μs** |\n\n---\n\n\n\n---\n\n## ⭐ Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=MervinPraison/PraisonAI&type=Date)](https://docs.praison.ai)\n\n---\n\n<p align=\"center\">\n  <img src=\".github/images/agentflow.gif\" alt=\"PraisonAI AgentFlow\" width=\"800\" />\n</p>\n\n<p align=\"center\">\n  <img src=\".github/images/latest_ai_news_and_crawl_each_url_to_find_info.gif\" alt=\"PraisonAI command execution\" width=\"800\" />\n</p>\n\n\\* `export TAVILY_API_KEY=xxxxx`\n\n## 🔍 Langfuse Tracing\n\n```bash\npip install \"praisonai[langfuse]\"\npraisonai langfuse\n```\n\n<p align=\"center\">\n  <img src=\".github/images/langfuse.png\" alt=\"PraisonAI Langfuse Tracing\" width=\"800\" />\n</p>\n\n---\n\n## 🎓 Video Tutorials\n\nLearn PraisonAI through our comprehensive video series:\n\n<details>\n<summary><strong>View all 22 video tutorials</strong></summary>\n\n| Topic | Video |\n|-------|--------|\n| AI Agents with Self Reflection | [![Self Reflection](https://img.youtube.com/vi/vLXobEN2Vc8/0.jpg)](https://www.youtube.com/watch?v=vLXobEN2Vc8) |\n| Reasoning Data Generating Agent | [![Reasoning Data](https://img.youtube.com/vi/fUT332Y2zA8/0.jpg)](https://www.youtube.com/watch?v=fUT332Y2zA8) |\n| AI Agents with Reasoning | [![Reasoning](https://img.youtube.com/vi/KNDVWGN3TpM/0.jpg)](https://www.youtube.com/watch?v=KNDVWGN3TpM) |\n| Multimodal AI Agents | [![Multimodal](https://img.youtube.com/vi/hjAWmUT1qqY/0.jpg)](https://www.youtube.com/watch?v=hjAWmUT1qqY) |\n| AI Agents Workflow | [![Workflow](https://img.youtube.com/vi/yWTH44QPl2A/0.jpg)](https://www.youtube.com/watch?v=yWTH44QPl2A) |\n| Async AI Agents | [![Async](https://img.youtube.com/vi/VhVQfgo00LE/0.jpg)](https://www.youtube.com/watch?v=VhVQfgo00LE) |\n| Mini AI Agents | [![Mini](https://img.youtube.com/vi/OkvYp5aAGSg/0.jpg)](https://www.youtube.com/watch?v=OkvYp5aAGSg) |\n| AI Agents with Memory | [![Memory](https://img.youtube.com/vi/1hVfVxvPnnQ/0.jpg)](https://www.youtube.com/watch?v=1hVfVxvPnnQ) |\n| Repetitive Agents | [![Repetitive](https://img.youtube.com/vi/dAYGxsjDOPg/0.jpg)](https://www.youtube.com/watch?v=dAYGxsjDOPg) |\n| Introduction | [![Introduction](https://img.youtube.com/vi/Fn1lQjC0GO0/0.jpg)](https://www.youtube.com/watch?v=Fn1lQjC0GO0) |\n| Tools Overview | [![Tools Overview](https://img.youtube.com/vi/XaQRgRpV7jo/0.jpg)](https://www.youtube.com/watch?v=XaQRgRpV7jo) |\n| Custom Tools | [![Custom Tools](https://img.youtube.com/vi/JSU2Rndh06c/0.jpg)](https://www.youtube.com/watch?v=JSU2Rndh06c) |\n| Firecrawl Integration | [![Firecrawl](https://img.youtube.com/vi/UoqUDcLcOYo/0.jpg)](https://www.youtube.com/watch?v=UoqUDcLcOYo) |\n| User Interface | [![UI](https://img.youtube.com/vi/tg-ZjNl3OCg/0.jpg)](https://www.youtube.com/watch?v=tg-ZjNl3OCg) |\n| Crawl4AI Integration | [![Crawl4AI](https://img.youtube.com/vi/KAvuVUh0XU8/0.jpg)](https://www.youtube.com/watch?v=KAvuVUh0XU8) |\n| Chat Interface | [![Chat](https://img.youtube.com/vi/sw3uDqn2h1Y/0.jpg)](https://www.youtube.com/watch?v=sw3uDqn2h1Y) |\n| Code Interface | [![Code](https://img.youtube.com/vi/_5jQayO-MQY/0.jpg)](https://www.youtube.com/watch?v=_5jQayO-MQY) |\n| Mem0 Integration | [![Mem0](https://img.youtube.com/vi/KIGSgRxf1cY/0.jpg)](https://www.youtube.com/watch?v=KIGSgRxf1cY) |\n| Training | [![Training](https://img.youtube.com/vi/aLawE8kwCrI/0.jpg)](https://www.youtube.com/watch?v=aLawE8kwCrI) |\n| Realtime Voice Interface | [![Realtime](https://img.youtube.com/vi/frRHfevTCSw/0.jpg)](https://www.youtube.com/watch?v=frRHfevTCSw) |\n| Call Interface | [![Call](https://img.youtube.com/vi/m1cwrUG2iAk/0.jpg)](https://www.youtube.com/watch?v=m1cwrUG2iAk) |\n| Reasoning Extract Agents | [![Reasoning Extract](https://img.youtube.com/vi/2PPamsADjJA/0.jpg)](https://www.youtube.com/watch?v=2PPamsADjJA) |\n\n</details>\n\n---\n\n## 👥 Contributing\n\nWe welcome contributions! Fork the repo, create a branch, and submit a PR → [Contributing Guide](https://github.com/MervinPraison/PraisonAI/blob/main/CONTRIBUTING.md).\n\n---\n\n## ❓ FAQ & Troubleshooting\n\n<details>\n<summary><strong>ModuleNotFoundError: No module named 'praisonaiagents'</strong></summary>\n\nInstall the package:\n```bash\npip install praisonaiagents\n```\n\n</details>\n\n<details>\n<summary><strong>API key not found / Authentication error</strong></summary>\n\nEnsure your API key is set:\n```bash\nexport OPENAI_API_KEY=your_key_here\n```\n\nFor other providers, see [Models docs](https://docs.praison.ai/docs/models).\n\n</details>\n\n<details>\n<summary><strong>How do I use a local model (Ollama)?</strong></summary>\n\n```bash\n# Start Ollama and pull a model\nollama serve\nollama pull llama3.2\n```\n\n```python\nfrom praisonaiagents import Agent\n\nagent = Agent(instructions=\"You are a helpful assistant\", llm=\"ollama/llama3.2\")\nagent.start(\"Why is the sky blue?\")\n```\n\nThe `ollama/` prefix is what selects Ollama's handling — tool-call repair,\ntool-result formatting and the streaming rules small local models need. Or set\nit by environment instead:\n\n```bash\nexport OPENAI_MODEL_NAME=ollama/llama3.2\n```\n\nSetting only `OPENAI_BASE_URL` is not enough: with no model named, the OpenAI\ndefault (`gpt-4o-mini`) is sent to Ollama, which answers\n`404 model 'gpt-4o-mini' not found`. Always name the model.\n\nPoint at a non-default host with `base_url=` or `OLLAMA_HOST`:\n\n```python\nagent = Agent(instructions=\"...\", llm=\"ollama/llama3.2\", base_url=\"http://192.168.1.10:11434\")\n```\n\nThe same shape works for other local runtimes — `lm_studio/`, `vllm/` and\n`hosted_vllm/` with their server's `base_url`.\n\nSee [Models docs](https://docs.praison.ai/docs/models) for more details.\n\n</details>\n\n<details>\n<summary><strong>How do I persist conversations to a database?</strong></summary>\n\nUse the `db` parameter:\n```python\nfrom praisonaiagents import Agent, db\n\nagent = Agent(\n    name=\"Assistant\",\n    memory={\n        \"db\": db(database_url=\"postgresql://localhost/mydb\"),\n        \"session_id\": \"my-session\",\n    },\n)\n```\n\nSee [Persistence docs](https://docs.praison.ai/docs/databases/overview) for supported databases.\n\n</details>\n\n<details>\n<summary><strong>How do I enable agent memory?</strong></summary>\n\n```python\nfrom praisonaiagents import Agent\n\nagent = Agent(\n    name=\"Assistant\",\n    # Enables file-based memory (no extra deps!)\n    memory={\"user_id\": \"user123\"},\n)\n```\n\nSee [Memory docs](https://docs.praison.ai/docs/concepts/memory) for more options.\n\n</details>\n\n<details>\n<summary><strong>How do I run multiple agents together?</strong></summary>\n\n```python\nfrom praisonaiagents import Agent, Agents\n\nagent1 = Agent(instructions=\"Research topics\")\nagent2 = Agent(instructions=\"Summarize findings\")\nagents = Agents(agents=[agent1, agent2])\nagents.start()\n```\n\nSee [Agents docs](https://docs.praison.ai/docs/concepts/agents) for more examples.\n\n</details>\n\n<details>\n<summary><strong>How do I use MCP tools?</strong></summary>\n\n```python\nfrom praisonaiagents import Agent, MCP\n\nagent = Agent(\n    tools=MCP(\"npx @modelcontextprotocol/server-memory\")\n)\n```\n\nSee [MCP docs](https://docs.praison.ai/docs/mcp/transports) for all transport options.\n\n</details>\n\n### Getting Help\n\n- 📚 [Full Documentation](https://docs.praison.ai)\n- 🐛 [Report Issues](https://github.com/MervinPraison/PraisonAI/issues)\n- 💬 [Discussions](https://github.com/MervinPraison/PraisonAI/discussions)\n\n---\n\n<div align=\"center\">\n  <p><strong>Made with ❤️ by the PraisonAI Team</strong></p>\n  <p>\n    <a href=\"https://docs.praison.ai\">📚 Documentation</a> •\n    <a href=\"https://github.com/MervinPraison/PraisonAI\">GitHub</a> •\n    <a href=\"https://youtube.com/@MervinPraison\">▶️ YouTube</a> •\n    <a href=\"https://x.com/MervinPraison\">𝕏 X</a> •\n    <a href=\"https://linkedin.com/in/mervinpraison\">💼 LinkedIn</a>\n  </p>\n</div>\n",
  "bytes": 57265,
  "sha": "746c44db7b5610f3210f995785e5b31e560d8b5a3e31b802503adee739a9ab90",
  "repo_slug": "mervinpraison/praisonai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mervinpraison_praisonai_5cd973f4/readme"
}