OverAI is an AI Agents Framework with Self Reflection. OverAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.

These details have not been verified by PyPI

Project description

OverAI Logo

Total Downloads License

OverAI Agents

OverAI Agents is a production-ready Multi-AI Agents framework with self-reflection, designed to create AI Agents to automate and solve problems ranging from simple tasks to complex challenges. By integrating OverAI Agents, AG2 (Formerly AutoGen), and CrewAI into a low-code solution, it streamlines the building and management of multi-agent LLM systems, emphasising simplicity, customisation, and effective human-agent collaboration.

Quick Paths:

🚀 New here? → Quick Start

📦 Installing? → Installation

💻 Python SDK? → Python Examples

🎯 CLI user? → CLI Reference

🔧 Need config? → Configuration

🤝 Contributing? → Development

📑 Table of Contents

⚡ Performance

OverAI Agents is the fastest AI agent framework for agent instantiation.

Framework	Avg Time (μs)	Relative
OverAI	3.77	1.00x (fastest)
OpenAI Agents SDK	5.26	1.39x
Agno	5.64	1.49x
OverAI (LiteLLM)	7.56	2.00x
PydanticAI	226.94	60.16x
LangGraph	4,558.71	1,209x
CrewAI	15,607.92	4,138x

Run benchmarks yourself

cd overai-agents
python benchmarks/simple_benchmark.py

🚀 Quick Start

Get started with OverAI in under 1 minute:

# Install
pip install overai

# Set API key
export OPENAI_API_KEY=your_key_here

# Create a simple agent
python -c "from overai import Agent; Agent(instructions='You are a helpful AI assistant').start('Write a haiku about AI')"

📦 Installation

Python SDK

Lightweight package dedicated for coding:

pip install overai

For the full framework with CLI support:

pip install overai-cli

JavaScript SDK

npm install overai

Environment Variables

Variable	Required	Description
`OPENAI_API_KEY`	Yes*	OpenAI API key
`ANTHROPIC_API_KEY`	No	Anthropic Claude API key
`GOOGLE_API_KEY`	No	Google Gemini API key
`GROQ_API_KEY`	No	Groq API key
`OPENAI_BASE_URL`	No	Custom API endpoint (for Ollama, Groq, etc.)

*At least one LLM provider API key is required.

# Set your API key
export OPENAI_API_KEY=your_key_here

# For Ollama (local models)
export OPENAI_BASE_URL=http://localhost:11434/v1

# For Groq
export OPENAI_API_KEY=your_groq_key
export OPENAI_BASE_URL=https://api.groq.com/openai/v1

💻 Usage

CLI / No-Code Interface

🎯 Auto Mode
🔬 Deep Research
📋 Planning Mode
💾 Memory Management
🔄 Workflow Execution

JavaScript Code Examples

💻 JavaScript Usage

✨ Key Features

🤖 Core Agents

Feature	Code	Docs
Single Agent	Example
Multi Agents	Example
Auto Agents	Example
Self Reflection AI Agents	Example
Reasoning AI Agents	Example
Multi Modal AI Agents	Example

🔄 Workflows

Feature	Code	Docs
Simple Workflow	Example
Workflow with Agents	Example
Agentic Routing (`route()`)	Example
Parallel Execution (`parallel()`)	Example
Loop over List/CSV (`loop()`)	Example
Evaluator-Optimizer (`repeat()`)	Example
Conditional Steps	Example
Workflow Branching	Example
Workflow Early Stop	Example
Workflow Checkpoints	Example

💻 Code & Development

Feature	Code	Docs
Code Interpreter Agents	Example
AI Code Editing Tools	Example
External Agents (All)	Example
Claude Code CLI	Example
Gemini CLI	Example
Codex CLI	Example
Cursor CLI	Example

🧠 Memory & Knowledge

Feature	Code	Docs
Memory (Short & Long Term)	Example
File-Based Memory	Example
Claude Memory Tool	Example
Add Custom Knowledge	Example
RAG Agents	Example
Chat with PDF Agents	Example
Data Readers (PDF, DOCX, etc.)	CLI
Vector Store Selection	CLI
Retrieval Strategies	CLI
Rerankers	CLI
Index Types (Vector/Keyword/Hybrid)	CLI
Query Engines (Sub-Question, etc.)	CLI

🔬 Research & Intelligence

Feature	Code	Docs
Deep Research Agents	Example
Query Rewriter Agent	Example
Native Web Search	Example
Built-in Search Tools	Example
Unified Web Search	Example
Web Fetch (Anthropic)	Example

📋 Planning & Execution

Feature	Code	Docs
Planning Mode	Example
Planning Tools	Example
Planning Reasoning	Example
Prompt Chaining	Example
Evaluator Optimiser	Example
Orchestrator Workers	Example

👥 Specialized Agents

Feature	Code	Docs
Data Analyst Agent	Example
Finance Agent	Example
Shopping Agent	Example
Recommendation Agent	Example
Wikipedia Agent	Example
Programming Agent	Example
Math Agents	Example
Markdown Agent	Example
Prompt Expander Agent	Example

🎨 Media & Multimodal

Feature	Code	Docs
Image Generation Agent	Example
Image to Text Agent	Example
Video Agent	Example
Camera Integration	Example

🔌 Protocols & Integration

Feature	Code	Docs
MCP Transports	Example
WebSocket MCP	Example
MCP Security	Example
MCP Resumability	Example
MCP Config Management	Example
LangChain Integrated Agents	Example

🛡️ Safety & Control

Feature	Code	Docs
Guardrails	Example
Human Approval	Example
Rules & Instructions	Example

⚙️ Advanced Features

Feature	Code	Docs
Async & Parallel Processing	Example
Parallelisation	Example
Repetitive Agents	Example
Agent Handoffs	Example
Stateful Agents	Example
Autonomous Workflow	Example
Structured Output Agents	Example
Model Router	Example
Prompt Caching	Example
Fast Context	Example

🛠️ Tools & Configuration

Feature	Code	Docs
100+ Custom Tools	Example
YAML Configuration	Example
100+ LLM Support	Example
Callback Agents	Example
Hooks	Example
Middleware System	Example
Configurable Model	Example
Rate Limiter	Example
Injected Tool State	Example
Shadow Git Checkpoints	Example
Background Tasks	Example
Policy Engine	Example
Thinking Budgets	Example
Output Styles	Example
Context Compaction	Example

📊 Monitoring & Management

Feature	Code	Docs
Sessions Management	Example
Auto-Save Sessions	Example
History in Context	Example
Telemetry	Example
Project Docs (.praison/docs/)	Example
AI Commit Messages	Example
@Mentions in Prompts	Example

🖥️ CLI Features

Feature	Code	Docs
Slash Commands	Example
Autonomy Modes	Example
Cost Tracking	Example
Repository Map	Example
Interactive TUI	Example
Git Integration	Example
Sandbox Execution	Example
CLI Compare	Example
Profile/Benchmark	Example
Auto Mode	Example
Init	Example
File Input	Example
Final Agent	Example
Max Tokens	Example

🧪 Evaluation

Feature	Code	Docs
Accuracy Evaluation	Example
Performance Evaluation	Example
Reliability Evaluation	Example
Criteria Evaluation	Example

🎯 Agent Skills

Feature	Code	Docs
Skills Management	Example
Custom Skills	Example

⏰ 24/7 Scheduling

Feature	Code	Docs
Agent Scheduler	Example

🌐 Supported Providers

OverAI supports 100+ LLM providers through seamless integration:

Provider	Example
OpenAI	Example
Anthropic	Example
Google Gemini	Example
Ollama	Example
Groq	Example
DeepSeek	Example
xAI Grok	Example
Mistral	Example
Cohere	Example
Perplexity	Example
Fireworks	Example
Together AI	Example
OpenRouter	Example
HuggingFace	Example
Azure OpenAI	Example
AWS Bedrock	Example
Google Vertex	Example
Databricks	Example
Cloudflare	Example
AI21	Example
Replicate	Example
SageMaker	Example
Moonshot	Example
vLLM	Example

📘 Using Python Code

Light weight package dedicated for coding:

pip install overai
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx

1. Single Agent

Create app.py file and add the code below:

from overai import Agent
agent = Agent(instructions="Your are a helpful AI assistant")
agent.start("Write a movie script about a robot in Mars")

Run:

python app.py

2. Multi Agents

Create app.py file and add the code below:

from overai import Agent, OverAIAgents

research_agent = Agent(instructions="Research about AI")
summarise_agent = Agent(instructions="Summarise research agent's findings")
agents = OverAIAgents(agents=[research_agent, summarise_agent])
agents.start()

Run:

python app.py

3. Agent with Planning Mode

Enable planning for any agent - the agent creates a plan, then executes step by step:

from overai import Agent

def search_web(query: str) -> str:
    return f"Search results for: {query}"

agent = Agent(
    name="AI Assistant",
    instructions="Research and write about topics",
    planning=True,              # Enable planning mode
    planning_tools=[search_web], # Tools for planning research
    planning_reasoning=True      # Chain-of-thought reasoning
)

result = agent.start("Research AI trends in 2025 and write a summary")

What happens:

📋 Agent creates a multi-step plan
🚀 Executes each step sequentially
📊 Shows progress with context passing
✅ Returns final result

4. Deep Research Agent

Automated research with real-time streaming, web search, and citations using OpenAI or Gemini Deep Research APIs.

from overai import DeepResearchAgent

# OpenAI Deep Research
agent = DeepResearchAgent(
    model="o4-mini-deep-research",  # or "o3-deep-research"
    verbose=True
)

result = agent.research("What are the latest AI trends in 2025?")
print(result.report)
print(f"Citations: {len(result.citations)}")

# Gemini Deep Research
from overai import DeepResearchAgent

agent = DeepResearchAgent(
    model="deep-research-pro",  # Auto-detected as Gemini
    verbose=True
)

result = agent.research("Research quantum computing advances")
print(result.report)

Features:

🔍 Multi-provider support (OpenAI, Gemini, LiteLLM)
📡 Real-time streaming with reasoning summaries
📚 Structured citations with URLs
🛠️ Built-in tools: web search, code interpreter, MCP, file search
🔄 Automatic provider detection from model name

5. Query Rewriter Agent

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

from overai import QueryRewriterAgent, RewriteStrategy

agent = QueryRewriterAgent(model="gpt-4o-mini")

# Basic - expands abbreviations, adds context
result = agent.rewrite("AI trends")
print(result.primary_query)  # "What are the current trends in Artificial Intelligence?"

# HyDE - generates hypothetical document for semantic matching
result = agent.rewrite("What is quantum computing?", strategy=RewriteStrategy.HYDE)

# Step-back - generates broader context question
result = agent.rewrite("GPT-4 vs Claude 3?", strategy=RewriteStrategy.STEP_BACK)

# Sub-queries - decomposes complex questions
result = agent.rewrite("RAG setup and best embedding models?", strategy=RewriteStrategy.SUB_QUERIES)

# Contextual - resolves references using chat history
result = agent.rewrite("What about cost?", chat_history=[...])

Strategies:

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

6. Agent Memory (Zero Dependencies)

Enable persistent memory for agents - works out of the box without any extra packages.

from overai import Agent
from overai.memory import FileMemory

# Enable memory with a single parameter
agent = Agent(
    name="Personal Assistant",
    instructions="You are a helpful assistant that remembers user preferences.",
    memory=True,  # Enables file-based memory (no extra deps!)
    user_id="user123"  # Isolate memory per user
)

# Memory is automatically injected into conversations
result = agent.start("My name is John and I prefer Python")
# Agent will remember this for future conversations

Memory Types:

Short-term: Rolling buffer of recent context (auto-expires)
Long-term: Persistent important facts (sorted by importance)
Entity: People, places, organizations with attributes
Episodic: Date-based interaction history

Advanced Features:

from overai.memory import FileMemory

memory = FileMemory(user_id="user123")

# Session Save/Resume
memory.save_session("project_session", conversation_history=[...])
memory.resume_session("project_session")

# Context Compression
memory.compress(llm_func=lambda p: agent.chat(p), max_items=10)

# Checkpointing
memory.create_checkpoint("before_refactor", include_files=["main.py"])
memory.restore_checkpoint("before_refactor", restore_files=True)

# Slash Commands
memory.handle_command("/memory show")
memory.handle_command("/memory save my_session")

Storage Options:

Option	Dependencies	Description
`memory=True`	None	File-based JSON storage (default)
`memory="file"`	None	Explicit file-based storage
`memory="sqlite"`	Built-in	SQLite with indexing
`memory="chromadb"`	chromadb	Vector/semantic search

7. Rules & Instructions

OverAI auto-discovers instruction files from your project root and git root:

File	Description	Priority
`PRAISON.md`	OverAI native instructions	High
`PRAISON.local.md`	Local overrides (gitignored)	Higher
`CLAUDE.md`	Claude Code memory file	High
`CLAUDE.local.md`	Local overrides (gitignored)	Higher
`AGENTS.md`	OpenAI Codex CLI instructions	High
`GEMINI.md`	Gemini CLI memory file	High
`.cursorrules`	Cursor IDE rules	High
`.windsurfrules`	Windsurf IDE rules	High
`.claude/rules/*.md`	Claude Code modular rules	Medium
`.windsurf/rules/*.md`	Windsurf modular rules	Medium
`.cursor/rules/*.mdc`	Cursor modular rules	Medium
`.praison/rules/*.md`	Workspace rules	Medium
`~/.praison/rules/*.md`	Global rules	Low

from overai import Agent

# Agent auto-discovers CLAUDE.md, AGENTS.md, GEMINI.md, etc.
agent = Agent(name="Assistant", instructions="You are helpful.")
# Rules are injected into system prompt automatically

@Import Syntax:

# CLAUDE.md
See @README for project overview
See @docs/architecture.md for system design
@~/.praison/my-preferences.md

Rule File Format (with YAML frontmatter):

---
description: Python coding guidelines
globs: ["**/*.py"]
activation: always  # always, glob, manual, ai_decision
---

# Guidelines
- Use type hints
- Follow PEP 8

8. Auto-Generated Memories

from overai.memory import FileMemory, AutoMemory

memory = FileMemory(user_id="user123")
auto = AutoMemory(memory, enabled=True)

# Automatically extracts and stores memories from conversations
memories = auto.process_interaction(
    "My name is John and I prefer Python for backend work"
)
# Extracts: name="John", preference="Python for backend"

9. Agentic Workflows

Create powerful multi-agent workflows with the Workflow class:

from overai import Agent, Workflow

# Create agents
researcher = Agent(
    name="Researcher",
    role="Research Analyst",
    goal="Research topics thoroughly",
    instructions="Provide concise, factual information."
)

writer = Agent(
    name="Writer",
    role="Content Writer", 
    goal="Write engaging content",
    instructions="Write clear, engaging content based on research."
)

# Create workflow with agents as steps
workflow = Workflow(steps=[researcher, writer])

# Run workflow - agents process sequentially
result = workflow.start("What are the benefits of AI agents?")
print(result["output"])

Key Features:

Agent-first - Pass Agent objects directly as workflow steps
Pattern helpers - Use route(), parallel(), loop(), repeat()
Planning mode - Enable with planning=True
Callbacks - Monitor with on_step_complete, on_workflow_complete
Async execution - Use workflow.astart() for async

Workflow Patterns (route, parallel, loop, repeat)

from overai import Agent, Workflow
from overai.workflows import route, parallel, loop, repeat

# 1. ROUTING - Classifier agent routes to specialized agents
classifier = Agent(name="Classifier", instructions="Respond with 'technical' or 'creative'")
tech_agent = Agent(name="TechExpert", role="Technical Expert")
creative_agent = Agent(name="Creative", role="Creative Writer")

workflow = Workflow(steps=[
    classifier,
    route({
        "technical": [tech_agent],
        "creative": [creative_agent]
    })
])

# 2. PARALLEL - Multiple agents work concurrently
market_agent = Agent(name="Market", role="Market Researcher")
competitor_agent = Agent(name="Competitor", role="Competitor Analyst")
aggregator = Agent(name="Aggregator", role="Synthesizer")

workflow = Workflow(steps=[
    parallel([market_agent, competitor_agent]),
    aggregator
])

# 3. LOOP - Agent processes each item
processor = Agent(name="Processor", role="Item Processor")
summarizer = Agent(name="Summarizer", role="Summarizer")

workflow = Workflow(
    steps=[loop(processor, over="items"), summarizer],
    variables={"items": ["AI", "ML", "NLP"]}
)

# 4. REPEAT - Evaluator-Optimizer pattern
generator = Agent(name="Generator", role="Content Generator")
evaluator = Agent(name="Evaluator", instructions="Say 'APPROVED' if good")

workflow = Workflow(steps=[
    generator,
    repeat(evaluator, until=lambda ctx: "approved" in ctx.previous_result.lower(), max_iterations=3)
])

# 5. CALLBACKS
workflow = Workflow(
    steps=[researcher, writer],
    on_step_complete=lambda name, r: print(f"✅ {name} done")
)

# 6. WITH PLANNING & REASONING
workflow = Workflow(
    steps=[researcher, writer],
    planning=True,
    reasoning=True
)

# 7. ASYNC EXECUTION
result = asyncio.run(workflow.astart("input"))

# 8. STATUS TRACKING
workflow.status  # "not_started" | "running" | "completed"
workflow.step_statuses  # {"step1": "completed", "step2": "skipped"}

YAML Workflow Template

# .praison/workflows/research.yaml
name: Research Workflow
description: Research and write content with all patterns

agents:
  researcher:
    role: Research Expert
    goal: Find accurate information
    tools: [tavily_search, web_scraper]
  writer:
    role: Content Writer
    goal: Write engaging content
  editor:
    role: Editor
    goal: Polish content

steps:
  # Sequential
  - agent: researcher
    action: Research {{topic}}
    output_variable: research_data

  # Routing
  - name: classifier
    action: Classify content type
    route:
      technical: [tech_handler]
      creative: [creative_handler]
      default: [general_handler]

  # Parallel
  - name: parallel_research
    parallel:
      - agent: researcher
        action: Research market
      - agent: researcher
        action: Research competitors

  # Loop
  - agent: writer
    action: Write about {{item}}
    loop_over: topics
    loop_var: item

  # Repeat (evaluator-optimizer)
  - agent: editor
    action: Review and improve
    repeat:
      until: "quality > 8"
      max_iterations: 3

  # Output to file
  - agent: writer
    action: Write final report
    output_file: output/{{topic}}_report.md

variables:
  topic: AI trends
  topics: [ML, NLP, Vision]

workflow:
  planning: true
  planning_llm: gpt-4o
  memory_config:
    provider: chroma
    persist: true

Loading YAML Workflows

from overai.workflows import YAMLWorkflowParser, WorkflowManager

# Option 1: Parse YAML string
parser = YAMLWorkflowParser()
workflow = parser.parse_string(yaml_content)
result = workflow.start("Research AI trends")

# Option 2: Load from file with WorkflowManager
manager = WorkflowManager()
workflow = manager.load_yaml("research_workflow.yaml")
result = workflow.start("Research AI trends")

# Option 3: Execute YAML directly
result = manager.execute_yaml(
    "research_workflow.yaml",
    input_data="Research AI trends",
    variables={"topic": "Machine Learning"}
)

Complete workflow.yaml Reference

# workflow.yaml - Full feature reference
name: Complete Workflow
description: Demonstrates all workflow.yaml features
framework: overai  # overai, 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

10. Hooks

Intercept and modify agent behavior at various lifecycle points:

from overai.hooks import (
    HookRegistry, HookRunner, HookEvent, HookResult,
    BeforeToolInput
)

# Create a hook registry
registry = HookRegistry()

# Log all tool calls
@registry.on(HookEvent.BEFORE_TOOL)
def log_tools(event_data: BeforeToolInput) -> HookResult:
    print(f"Tool: {event_data.tool_name}")
    return HookResult.allow()

# Block dangerous operations
@registry.on(HookEvent.BEFORE_TOOL)
def security_check(event_data: BeforeToolInput) -> HookResult:
    if "delete" in event_data.tool_name.lower():
        return HookResult.deny("Delete operations blocked")
    return HookResult.allow()

# Execute hooks
runner = HookRunner(registry)

CLI Commands:

overai hooks list                    # List registered hooks
overai hooks test before_tool        # Test hooks for an event
overai hooks run "echo test"         # Run a command hook
overai hooks validate hooks.json     # Validate configuration

11. Shadow Git Checkpoints

File-level undo/restore using shadow git:

from overai.checkpoints import CheckpointService

service = CheckpointService(workspace_dir="./my_project")
await service.initialize()

# Save checkpoint before changes
result = await service.save("Before refactoring")

# Make changes...

# Restore if needed
await service.restore(result.checkpoint.id)

# View diff
diff = await service.diff()

CLI Commands:

overai checkpoint save "Before changes"  # Save checkpoint
overai checkpoint list                   # List checkpoints
overai checkpoint diff                   # Show changes
overai checkpoint restore abc123         # Restore to checkpoint

Links:

12. Background Tasks

Run agent tasks asynchronously without blocking:

import asyncio
from overai.background import BackgroundRunner, BackgroundConfig

async def main():
    config = BackgroundConfig(max_concurrent_tasks=3)
    runner = BackgroundRunner(config=config)
    
    async def my_task(name: str) -> str:
        await asyncio.sleep(2)
        return f"Task {name} completed"
    
    task = await runner.submit(my_task, args=("example",), name="my_task")
    await task.wait(timeout=10.0)
    print(task.result)

asyncio.run(main())

CLI Commands:

overai background list          # List running tasks
overai background status <id>   # Check task status
overai background cancel <id>   # Cancel a task
overai background clear         # Clear completed tasks

Links:

13. Policy Engine

Control what agents can and cannot do with policy-based execution:

from overai.policy import (
    PolicyEngine, Policy, PolicyRule, PolicyAction
)

engine = PolicyEngine()

policy = Policy(
    name="no_delete",
    rules=[
        PolicyRule(
            action=PolicyAction.DENY,
            resource="tool:delete_*",
            reason="Delete operations blocked"
        )
    ]
)
engine.add_policy(policy)

result = engine.check("tool:delete_file", {})
print(f"Allowed: {result.allowed}")

CLI Commands:

overai policy list                  # List policies
overai policy check "tool:name"     # Check if allowed
overai policy init                  # Create template

Links:

14. Thinking Budgets

Configure token budgets for extended thinking:

from overai.thinking import ThinkingBudget, ThinkingTracker

# Use predefined levels
budget = ThinkingBudget.high()  # 16,000 tokens

# Track usage
tracker = ThinkingTracker()
session = tracker.start_session(budget_tokens=16000)
tracker.end_session(session, tokens_used=12000)

summary = tracker.get_summary()
print(f"Utilization: {summary['average_utilization']:.1%}")

CLI Commands:

overai thinking status      # Show current budget
overai thinking set high    # Set budget level
overai thinking stats       # Show usage statistics

Links:

15. Output Styles

Configure how agents format their responses:

from overai.output import OutputStyle, OutputFormatter

# Use preset styles
style = OutputStyle.concise()
formatter = OutputFormatter(style)

# Format output
text = "# Hello\n\nThis is **bold** text."
plain = formatter.format(text)
print(plain)

CLI Commands:

overai output status        # Show current style
overai output set concise   # Set output style

Links:

16. Context Compaction

Automatically manage context window size:

from overai.compaction import (
    ContextCompactor, CompactionStrategy
)

compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.SLIDING,
    preserve_recent=3
)

messages = [...]  # Your conversation history
compacted, result = compactor.compact(messages)

print(f"Compression: {result.compression_ratio:.1%}")

CLI Commands:

overai compaction status        # Show settings
overai compaction set sliding   # Set strategy
overai compaction stats         # Show statistics

Links:

17. Field Names Reference (A-I-G-S)

OverAI 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:

Agents - Who does the work
Instructions - How they behave
Goal - What they achieve
Steps - What they do

# 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 overai workflow validate <file.yaml> to see suggestions for canonical names.

18. 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 (overai, crewai, autogen)
Process types (sequential, hierarchical, workflow)

You can use advanced workflow patterns directly in agents.yaml by setting process: workflow:

# agents.yaml with workflow patterns
framework: overai
process: workflow  # Enables workflow mode
topic: "Research AI trends"

workflow:
  planning: true
  reasoning: true
  verbose: true

variables:
  topic: AI trends

agents:  # Canonical: use 'agents' instead of 'roles'
  classifier:
    role: Request Classifier
    instructions: "Classify requests into categories"  # Canonical: use 'instructions' instead of 'backstory'
    goal: Classify requests
    
  researcher:
    role: Research Analyst
    instructions: "Expert researcher"  # Canonical: use 'instructions' instead of 'backstory'
    goal: Research topics
    tools:
      - tavily_search

steps:
  # Sequential step
  - agent: classifier
    action: "Classify: {{topic}}"
    
  # Route pattern - decision-based branching
  - name: routing
    route:
      technical: [tech_expert]
      default: [researcher]
      
  # Parallel pattern - concurrent execution
  - name: parallel_research
    parallel:
      - agent: researcher
        action: "Research market trends"
      - agent: researcher
        action: "Research competitors"
        
  # Loop pattern - iterate over items
  - agent: researcher
    action: "Analyze {{item}}"
    loop:
      over: topics
      
  # Repeat pattern - evaluator-optimizer
  - agent: aggregator
    action: "Synthesize findings"
    repeat:
      until: "comprehensive"
      max_iterations: 3

Run with the same simple command:

overai agents.yaml

19. MCP (Model Context Protocol)

OverAI supports MCP Protocol Revision 2025-11-25 with multiple transports.

MCP Client (Consume MCP Servers)

from overai 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"}
    )
)

# 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)

Expose your Python functions as MCP tools for Claude Desktop, Cursor, and other MCP clients:

from overai.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

20. A2A (Agent2Agent Protocol)

OverAI supports the A2A Protocol for agent-to-agent communication, enabling your agents to be discovered and collaborate with other AI agents.

A2A Server (Expose Agent as A2A Server)

from overai 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 | Examples: examples/python/a2a

🎯 CLI / No-Code Interface

OverAI provides a powerful CLI for no-code automation and quick prototyping.

CLI Quick Reference

Category	Commands
Execution	`overai`, `--auto`, `--interactive`, `--chat`
Research	`research`, `--query-rewrite`, `--deep-research`
Planning	`--planning`, `--planning-tools`, `--planning-reasoning`
Workflows	`workflow run`, `workflow list`, `workflow auto`
Memory	`memory show`, `memory add`, `memory search`, `memory clear`
Knowledge	`knowledge add`, `knowledge query`, `knowledge list`
Sessions	`session list`, `session resume`, `session delete`
Tools	`tools list`, `tools info`, `tools search`
MCP	`mcp list`, `mcp create`, `mcp enable`
Development	`commit`, `docs`, `checkpoint`, `hooks`
Scheduling	`schedule start`, `schedule list`, `schedule stop`

Auto Mode

pip install overai
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx
overai --auto create a movie script about Robots in Mars

Interactive Mode CLI:

# Start interactive terminal mode (inspired by Gemini CLI, Codex CLI, Claude Code)
overai --interactive
overai -i

# Features:
# - Streaming responses (no boxes)
# - Built-in tools: read_file, write_file, list_files, execute_command, internet_search
# - Slash commands: /help, /exit, /tools, /clear

# Chat mode - single prompt with interactive style (for testing/scripting)
# Use --chat (or --chat-mode for backward compatibility)
overai "list files in current folder" --chat
overai "search the web for AI news" --chat
overai "read README.md" --chat

Chat UI (Web Interface):

# Start web-based Chainlit chat interface (requires overai[chat])
pip install "overai[chat]"
overai chat
# Opens browser at http://localhost:8084

Query Rewriting (works with any command):

# Rewrite query for better results (uses QueryRewriterAgent)
overai "AI trends" --query-rewrite

# Rewrite with search tools (agent decides when to search)
overai "latest developments" --query-rewrite --rewrite-tools "internet_search"

# Works with any prompt
overai "explain quantum computing" --query-rewrite -v

Deep Research CLI:

# Default: OpenAI (o4-mini-deep-research)
overai research "What are the latest AI trends in 2025?"

# Use Gemini
overai research --model deep-research-pro "Your research query"

# Rewrite query before research
overai research --query-rewrite "AI trends"

# Rewrite with search tools
overai research --query-rewrite --rewrite-tools "internet_search" "AI trends"

# Use custom tools from file (gathers context before deep research)
overai research --tools tools.py "Your research query"
overai research -t my_tools.py "Your research query"

# Use built-in tools by name (comma-separated)
overai research --tools "internet_search,wiki_search" "Your query"
overai research -t "yfinance,calculator_tools" "Stock analysis query"

# Save output to file (output/research/{query}.md)
overai research --save "Your research query"
overai research -s "Your research query"

# Combine options
overai research --query-rewrite --tools tools.py --save "Your research query"

# Verbose mode (show debug logs)
overai research -v "Your research query"

Planning Mode CLI:

# Enable planning mode - agent creates a plan before execution
overai "Research AI trends and write a summary" --planning

# Planning with tools for research
overai "Analyze market trends" --planning --planning-tools tools.py

# Planning with chain-of-thought reasoning
overai "Complex analysis task" --planning --planning-reasoning

# Auto-approve plans without confirmation
overai "Task" --planning --auto-approve-plan

Tool Approval CLI:

# Auto-approve ALL tool executions (use with caution!)
overai "run ls command" --trust

# Auto-approve tools up to a risk level (prompt for higher)
# Levels: low, medium, high, critical
overai "write to file" --approve-level high  # Prompts for critical tools only
overai "task" --approve-level medium         # Prompts for high and critical

# Default behavior (no flags): prompts for all dangerous tools
overai "run shell command"  # Will prompt for approval

Memory CLI:

# Enable memory for agent (persists across sessions)
overai "My name is John" --memory

# Memory with user isolation
overai "Remember my preferences" --memory --user-id user123

# Memory management commands
overai memory show                      # Show memory statistics
overai memory add "User prefers Python" # Add to long-term memory
overai memory search "Python"           # Search memories
overai memory clear                     # Clear short-term memory
overai memory clear all                 # Clear all memory
overai memory save my_session           # Save session
overai memory resume my_session         # Resume session
overai memory sessions                  # List saved sessions
overai memory checkpoint                # Create checkpoint
overai memory restore <checkpoint_id>   # Restore checkpoint
overai memory checkpoints               # List checkpoints
overai memory help                      # Show all commands

Rules CLI:

# List all loaded rules (from PRAISON.md, CLAUDE.md, etc.)
overai rules list

# Show specific rule details
overai rules show <rule_name>

# Create a new rule
overai rules create my_rule "Always use type hints"

# Delete a rule
overai rules delete my_rule

# Show rules statistics
overai rules stats

# Include manual rules with prompts
overai "Task" --include-rules security,testing

Workflow CLI:

# List available workflows
overai workflow list

# Execute a workflow with tools and save output
overai workflow run "Research Blog" --tools tavily --save

# Execute with variables
overai workflow run deploy --workflow-var environment=staging --workflow-var branch=main

# Execute with planning mode (AI creates sub-steps for each workflow step)
overai workflow run "Research Blog" --planning --verbose

# Execute with reasoning mode (chain-of-thought)
overai workflow run "Analysis" --reasoning --verbose

# Execute with memory enabled
overai workflow run "Research" --memory

# Show workflow details
overai workflow show deploy

# Create a new workflow template
overai workflow create my_workflow

# Inline workflow (no template file needed)
overai "What is AI?" --workflow "Research,Summarize" --save

# Inline workflow with step actions
overai "GPT-5" --workflow "Research:Search for info,Write:Write blog" --tools tavily

# Workflow CLI help
overai workflow help

YAML Workflow Files:

# Run a YAML workflow file
overai workflow run research.yaml

# Run with variables
overai workflow run research.yaml --var topic="AI trends"

# Validate a YAML workflow
overai workflow validate research.yaml

# Create from template (simple, routing, parallel, loop, evaluator-optimizer)
overai workflow template routing --output my_workflow.yaml

Auto-Generate Workflows:

# Auto-generate a sequential workflow from topic
overai workflow auto "Research AI trends"

# Generate parallel workflow (multiple agents work concurrently)
overai workflow auto "Research AI trends" --pattern parallel

# Generate routing workflow (classifier routes to specialists)
overai workflow auto "Build a chatbot" --pattern routing

# Generate orchestrator-workers workflow (central orchestrator delegates)
overai workflow auto "Comprehensive market analysis" --pattern orchestrator-workers

# Generate evaluator-optimizer workflow (iterative refinement)
overai workflow auto "Write and refine article" --pattern evaluator-optimizer

# Specify output file
overai workflow auto "Build a chatbot" --pattern routing

# Specify output file
overai 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, orchestrator-workers, evaluator-optimizer)
`--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
`--reasoning`	Enable reasoning mode
`--memory`	Enable memory
`--verbose`	Enable verbose output
`--save`	Save output to file

Hooks CLI:

# List configured hooks
overai hooks list

# Show hooks statistics
overai hooks stats

# Create hooks.json template
overai hooks init

Claude Memory Tool CLI:

# Enable Claude Memory Tool (Anthropic models only)
overai "Research and remember findings" --claude-memory --llm anthropic/claude-sonnet-4-20250514

Guardrail CLI:

# Validate output with LLM guardrail
overai "Write code" --guardrail "Ensure code is secure and follows best practices"

# Combine with other flags
overai "Generate SQL query" --guardrail "No DROP or DELETE statements" --save

Metrics CLI:

# Display token usage and cost metrics
overai "Analyze this data" --metrics

# Combine with other features
overai "Complex task" --metrics --planning

Scheduler CLI:

overai schedule start <name> "task" --interval hourly
overai schedule list
overai schedule logs <name> [--follow]
overai schedule stop <name>
overai schedule restart <name>
overai schedule delete <name>
overai schedule describe <name>
overai schedule save <name> [file.yaml]
overai schedule "task" --interval hourly  # foreground mode
overai schedule agents.yaml  # foreground mode

Image Processing CLI:

# Process images with vision-based tasks
overai "Describe this image" --image path/to/image.png

# Analyze image content
overai "What objects are in this photo?" --image photo.jpg --llm openai/gpt-4o

Telemetry CLI:

# Enable usage monitoring and analytics
overai "Task" --telemetry

# Combine with metrics for full observability
overai "Complex analysis" --telemetry --metrics

MCP (Model Context Protocol) CLI:

# Use MCP server tools
overai "Search files" --mcp "npx -y @modelcontextprotocol/server-filesystem ."

# MCP with environment variables
overai "Search web" --mcp "npx -y @modelcontextprotocol/server-brave-search" --mcp-env "BRAVE_API_KEY=your_key"

# Multiple MCP options
overai "Task" --mcp "npx server" --mcp-env "KEY1=value1,KEY2=value2"

Fast Context CLI:

# Search codebase for relevant context
overai "Find authentication code" --fast-context ./src

# Add code context to any task
overai "Explain this function" --fast-context /path/to/project

Knowledge CLI:

# Add documents to knowledge base
overai knowledge add document.pdf
overai knowledge add ./docs/

# Search knowledge base
overai knowledge search "API authentication"

# List indexed documents
overai knowledge list

# Clear knowledge base
overai knowledge clear

# Show knowledge base info
overai knowledge info

# Show all commands
overai knowledge help

Session CLI:

# List all saved sessions
overai session list

# Show session details
overai session show my-project

# Resume a session (load into memory)
overai session resume my-project

# Delete a session
overai session delete my-project

# Auto-save session after each run
overai "Analyze this code" --auto-save my-project

# Load history from last N sessions into context
overai "Continue our discussion" --history 5

Session Management (Python):

from overai import Agent

# Auto-save session after each run
agent = Agent(
    name="Assistant",
    memory=True,
    auto_save="my-project"
)

# Load history from last 5 sessions
agent = Agent(
    name="Assistant",
    memory=True,
    history_in_context=5
)

Workflow Checkpoints:

from overai.memory.workflows import WorkflowManager

manager = WorkflowManager()

# Save checkpoint after each step
result = manager.execute("deploy", checkpoint="deploy-v1")

# Resume from checkpoint
result = manager.execute("deploy", resume="deploy-v1")

# List/delete checkpoints
manager.list_checkpoints()
manager.delete_checkpoint("deploy-v1")

Tools CLI:

overai tools list
overai tools info internet_search
overai tools search "web"
overai tools doctor
overai tools resolve shell_tool
overai tools discover
overai tools show-sources
overai tools show-sources --template ai-video-editor

Command	Example	Docs
`tools list`	example	docs
`tools resolve`	example	docs
`tools discover`	example	docs
`tools show-sources`	example	docs

Handoff CLI:

# Enable agent-to-agent task delegation
overai "Research and write article" --handoff "researcher,writer,editor"

# Complex multi-agent workflow
overai "Analyze data and create report" --handoff "analyst,visualizer,writer"

Auto Memory CLI:

# Enable automatic memory extraction
overai "Learn about user preferences" --auto-memory

# Combine with user isolation
overai "Remember my settings" --auto-memory --user-id user123

Todo CLI:

# Generate todo list from task
overai "Plan the project" --todo

# Add a todo item
overai todo add "Implement feature X"

# List all todos
overai todo list

# Complete a todo
overai todo complete 1

# Delete a todo
overai todo delete 1

# Clear all todos
overai todo clear

# Show all commands
overai todo help

Router CLI:

# Auto-select best model based on task complexity
overai "Simple question" --router

# Specify preferred provider
overai "Complex analysis" --router --router-provider anthropic

# Router automatically selects:
# - Simple tasks → gpt-4o-mini, claude-3-haiku
# - Complex tasks → gpt-4-turbo, claude-3-opus

# Create workflow with model routing template
overai workflow create --template model-routing --output my_workflow.yaml

Custom models can be configured in agents.yaml. See Model Router Docs for details.

Flow Display CLI:

# Enable visual workflow tracking
overai agents.yaml --flow-display

# Combine with other features
overai "Multi-step task" --planning --flow-display

Docs CLI:

# List all project docs
overai docs list

# Create a new doc
overai docs create project-overview "This project is a Python web app..."

# Show a specific doc
overai docs show project-overview

# Delete a doc
overai docs delete old-doc

# Show all commands
overai docs help

MCP Config CLI:

# List all MCP configurations
overai mcp list

# Create a new MCP config
overai mcp create filesystem npx -y @modelcontextprotocol/server-filesystem .

# Show a specific config
overai mcp show filesystem

# Enable/disable a config
overai mcp enable filesystem
overai mcp disable filesystem

# Delete a config
overai mcp delete filesystem

# Show all commands
overai mcp help

AI Commit CLI:

# Full auto mode: stage all, security check, commit, and push
overai commit -a

# Interactive mode (requires git add first)
overai commit

# Interactive with auto-push
overai commit --push

# Skip security check (not recommended)
overai commit -a --no-verify

Features:

🤖 AI-generated conventional commit messages
🔒 Built-in security scanning (API keys, passwords, secrets, sensitive files)
📦 Auto-staging with -a flag
🚀 Auto-push in full auto mode
✏️ Edit message before commit in interactive mode

Security Detection:

API keys, secrets, tokens (AWS, GitHub, GitLab, Slack)
Passwords and private keys
Sensitive files (.env, id_rsa, .pem, .key, etc.)

Serve CLI (API Server):

# Start API server for agents defined in YAML
overai serve agents.yaml

# With custom port and host
overai serve agents.yaml --port 8005 --host 0.0.0.0

# Alternative flag style
overai 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:

# Export workflow to n8n and open in browser
overai agents.yaml --n8n

# With custom n8n URL
overai agents.yaml --n8n --n8n-url http://localhost:5678

# Set N8N_API_KEY for auto-import
export N8N_API_KEY="your-api-key"
overai agents.yaml --n8n

External Agents CLI:

Use external AI coding CLI tools (Claude Code, Gemini CLI, Codex CLI, Cursor CLI) as agent tools:

# Use Claude Code for coding tasks
overai "Refactor the auth module" --external-agent claude

# Use Gemini CLI for code analysis
overai "Analyze codebase architecture" --external-agent gemini

# Use OpenAI Codex CLI
overai "Fix all bugs in src/" --external-agent codex

# Use Cursor CLI
overai "Add comprehensive tests" --external-agent cursor

Python API:

from overai.integrations import (
    ClaudeCodeIntegration,
    GeminiCLIIntegration,
    CodexCLIIntegration,
    CursorCLIIntegration
)

# Create integration
claude = ClaudeCodeIntegration(workspace="/project")

# Execute a coding task
result = await claude.execute("Refactor the auth module")

# Use as agent tool
from overai import Agent
tool = claude.as_tool()
agent = Agent(tools=[tool])

Environment Variables:

export ANTHROPIC_API_KEY=your-key  # Claude Code
export GEMINI_API_KEY=your-key     # Gemini CLI
export OPENAI_API_KEY=your-key     # Codex CLI
export CURSOR_API_KEY=your-key     # Cursor CLI

See External Agents Documentation for more details.

@Mentions in Prompts:

# Include file content in prompt
overai "@file:src/main.py explain this code"

# Include project doc
overai "@doc:project-overview help me add a feature"

# Search the web
overai "@web:python best practices give me tips"

# Fetch URL content
overai "@url:https://docs.python.org summarize this"

# Combine multiple mentions
overai "@file:main.py @doc:coding-standards review this code"

Prompt Expansion

Expand short prompts into detailed, actionable prompts:

CLI Usage

# Expand a short prompt into detailed prompt
overai "write a movie script in 3 lines" --expand-prompt

# With verbose output
overai "blog about AI" --expand-prompt -v

# With tools for context gathering
overai "latest AI trends" --expand-prompt --expand-tools tools.py

# Combine with query rewrite
overai "AI news" --query-rewrite --expand-prompt

Programmatic Usage

from overai import PromptExpanderAgent, ExpandStrategy

# Basic usage
agent = PromptExpanderAgent()
result = agent.expand("write a movie script in 3 lines")
print(result.expanded_prompt)

# With specific strategy
result = agent.expand("blog about AI", strategy=ExpandStrategy.DETAILED)

# Available strategies: BASIC, DETAILED, STRUCTURED, CREATIVE, AUTO

Key Difference:

--query-rewrite: Optimizes queries for search/retrieval (RAG)
--expand-prompt: Expands prompts for detailed task execution

Web Search, Web Fetch & Prompt Caching

CLI Usage

# Web Search - Get real-time information
overai "What are the latest AI news today?" --web-search --llm openai/gpt-4o-search-preview

# Web Fetch - Retrieve and analyze URL content (Anthropic only)
overai "Summarize " --web-fetch --llm anthropic/claude-sonnet-4-20250514

# Prompt Caching - Reduce costs for repeated prompts
overai "Analyze this document..." --prompt-caching --llm anthropic/claude-sonnet-4-20250514

Programmatic Usage

from overai import Agent

# Web Search
agent = Agent(
    instructions="You are a research assistant",
    llm="openai/gpt-4o-search-preview",
    web_search=True
)

# 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

CLI Features

Feature	Docs
🔄 Query Rewrite - RAG optimization
🔬 Deep Research - Automated research
📋 Planning - Step-by-step execution
💾 Memory - Persistent agent memory
📜 Rules - Auto-discovered instructions
🔄 Workflow - Multi-step workflows
🪝 Hooks - Event-driven actions
🧠 Claude Memory - Anthropic memory tool
🛡️ Guardrail - Output validation
📊 Metrics - Token usage tracking
🖼️ Image - Vision processing
📡 Telemetry - Usage monitoring
🔌 MCP - Model Context Protocol
⚡ Fast Context - Codebase search
📚 Knowledge - RAG management
💬 Session - Conversation management
🔧 Tools - Tool discovery
🤝 Handoff - Agent delegation
🧠 Auto Memory - Memory extraction
📋 Todo - Task management
🎯 Router - Smart model selection
📈 Flow Display - Visual workflow
✨ Prompt Expansion - Detailed prompts
🌐 Web Search - Real-time search
📥 Web Fetch - URL content retrieval
💾 Prompt Caching - Cost reduction
📦 Template Catalog - Browse & discover templates

Template Catalog CLI

Command	Description
`overai templates browse`	Open template catalog in browser
`overai templates browse --print`	Print catalog URL only
`overai templates validate`	Validate template YAML files
`overai templates validate --source <dir>`	Validate specific directory
`overai templates validate --strict`	Strict validation mode
`overai templates validate --json`	JSON output format
`overai templates catalog build`	Build catalog locally
`overai templates catalog build --out <dir>`	Build to specific directory
`overai templates catalog sync`	Sync template sources
`overai templates catalog sync --source <name>`	Sync specific source

Examples: examples/catalog/ | Docs: Code | CLI

💻 Using JavaScript Code

npm install overai
export OPENAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxx

const { Agent } = require('overai');
const agent = new Agent({ instructions: 'You are a helpful AI assistant' });
agent.start('Write a movie script about a robot in Mars');

OverAI CLI Demo

⭐ Star History

📊 Process Types & Patterns

AI Agents Flow

graph LR
    %% Define the main flow
    Start([▶ Start]) --> Agent1
    Agent1 --> Process[⚙ Process]
    Process --> Agent2
    Agent2 --> Output([✓ Output])
    Process -.-> Agent1
    
    %% Define subgraphs for agents and their tasks
    subgraph Agent1[ ]
        Task1[📋 Task]
        AgentIcon1[🤖 AI Agent]
        Tools1[🔧 Tools]
        
        Task1 --- AgentIcon1
        AgentIcon1 --- Tools1
    end
    
    subgraph Agent2[ ]
        Task2[📋 Task]
        AgentIcon2[🤖 AI Agent]
        Tools2[🔧 Tools]
        
        Task2 --- AgentIcon2
        AgentIcon2 --- Tools2
    end

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef tools fill:#2E8B57,stroke:#7C90A0,color:#fff
    classDef transparent fill:none,stroke:none

    class Start,Output,Task1,Task2 input
    class Process,AgentIcon1,AgentIcon2 process
    class Tools1,Tools2 tools
    class Agent1,Agent2 transparent

AI Agents with Tools

Create AI agents that can use tools to interact with external systems and perform actions.

flowchart TB
    subgraph Tools
        direction TB
        T3[Internet Search]
        T1[Code Execution]
        T2[Formatting]
    end

    Input[Input] ---> Agents
    subgraph Agents
        direction LR
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent 3]
    end
    Agents ---> Output[Output]

    T3 --> A1
    T1 --> A2
    T2 --> A3

    style Tools fill:#189AB4,color:#fff
    style Agents fill:#8B0000,color:#fff
    style Input fill:#8B0000,color:#fff
    style Output fill:#8B0000,color:#fff

AI Agents with Memory

Create AI agents with memory capabilities for maintaining context and information across tasks.

flowchart TB
    subgraph Memory
        direction TB
        STM[Short Term]
        LTM[Long Term]
    end

    subgraph Store
        direction TB
        DB[(Vector DB)]
    end

    Input[Input] ---> Agents
    subgraph Agents
        direction LR
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent 3]
    end
    Agents ---> Output[Output]

    Memory <--> Store
    Store <--> A1
    Store <--> A2
    Store <--> A3

    style Memory fill:#189AB4,color:#fff
    style Store fill:#2E8B57,color:#fff
    style Agents fill:#8B0000,color:#fff
    style Input fill:#8B0000,color:#fff
    style Output fill:#8B0000,color:#fff

AI Agents with Different Processes

Sequential Process

The simplest form of task execution where tasks are performed one after another.

graph LR
    Input[Input] --> A1
    subgraph Agents
        direction LR
        A1[Agent 1] --> A2[Agent 2] --> A3[Agent 3]
    end
    A3 --> Output[Output]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef transparent fill:none,stroke:none

    class Input,Output input
    class A1,A2,A3 process
    class Agents transparent

Hierarchical Process

Uses a manager agent to coordinate task execution and agent assignments.

graph TB
    Input[Input] --> Manager
    
    subgraph Agents
        Manager[Manager Agent]
        
        subgraph Workers
            direction LR
            W1[Worker 1]
            W2[Worker 2]
            W3[Worker 3]
        end
        
        Manager --> W1
        Manager --> W2
        Manager --> W3
    end
    
    W1 --> Manager
    W2 --> Manager
    W3 --> Manager
    Manager --> Output[Output]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef transparent fill:none,stroke:none

    class Input,Output input
    class Manager,W1,W2,W3 process
    class Agents,Workers transparent

Workflow Process

Advanced process type supporting complex task relationships and conditional execution.

graph LR
    Input[Input] --> Start
    
    subgraph Workflow
        direction LR
        Start[Start] --> C1{Condition}
        C1 --> |Yes| A1[Agent 1]
        C1 --> |No| A2[Agent 2]
        A1 --> Join
        A2 --> Join
        Join --> A3[Agent 3]
    end
    
    A3 --> Output[Output]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#2E8B57,stroke:#7C90A0,color:#fff
    classDef transparent fill:none,stroke:none

    class Input,Output input
    class Start,A1,A2,A3,Join process
    class C1 decision
    class Workflow transparent

Agentic Routing Workflow

Create AI agents that can dynamically route tasks to specialized LLM instances.

flowchart LR
    In[In] --> Router[LLM Call Router]
    Router --> LLM1[LLM Call 1]
    Router --> LLM2[LLM Call 2]
    Router --> LLM3[LLM Call 3]
    LLM1 --> Out[Out]
    LLM2 --> Out
    LLM3 --> Out
    
    style In fill:#8B0000,color:#fff
    style Router fill:#2E8B57,color:#fff
    style LLM1 fill:#2E8B57,color:#fff
    style LLM2 fill:#2E8B57,color:#fff
    style LLM3 fill:#2E8B57,color:#fff
    style Out fill:#8B0000,color:#fff

Agentic Orchestrator Worker

Create AI agents that orchestrate and distribute tasks among specialized workers.

flowchart LR
    In[In] --> Router[LLM Call Router]
    Router --> LLM1[LLM Call 1]
    Router --> LLM2[LLM Call 2]
    Router --> LLM3[LLM Call 3]
    LLM1 --> Synthesizer[Synthesizer]
    LLM2 --> Synthesizer
    LLM3 --> Synthesizer
    Synthesizer --> Out[Out]
    
    style In fill:#8B0000,color:#fff
    style Router fill:#2E8B57,color:#fff
    style LLM1 fill:#2E8B57,color:#fff
    style LLM2 fill:#2E8B57,color:#fff
    style LLM3 fill:#2E8B57,color:#fff
    style Synthesizer fill:#2E8B57,color:#fff
    style Out fill:#8B0000,color:#fff

Agentic Autonomous Workflow

Create AI agents that can autonomously monitor, act, and adapt based on environment feedback.

flowchart LR
    Human[Human] <--> LLM[LLM Call]
    LLM -->|ACTION| Environment[Environment]
    Environment -->|FEEDBACK| LLM
    LLM --> Stop[Stop]
    
    style Human fill:#8B0000,color:#fff
    style LLM fill:#2E8B57,color:#fff
    style Environment fill:#8B0000,color:#fff
    style Stop fill:#333,color:#fff

Agentic Parallelization

Create AI agents that can execute tasks in parallel for improved performance.

flowchart LR
    In[In] --> LLM2[LLM Call 2]
    In --> LLM1[LLM Call 1]
    In --> LLM3[LLM Call 3]
    LLM1 --> Aggregator[Aggregator]
    LLM2 --> Aggregator
    LLM3 --> Aggregator
    Aggregator --> Out[Out]
    
    style In fill:#8B0000,color:#fff
    style LLM1 fill:#2E8B57,color:#fff
    style LLM2 fill:#2E8B57,color:#fff
    style LLM3 fill:#2E8B57,color:#fff
    style Aggregator fill:#fff,color:#000
    style Out fill:#8B0000,color:#fff

Agentic Prompt Chaining

Create AI agents with sequential prompt chaining for complex workflows.

flowchart LR
    In[In] --> LLM1[LLM Call 1] --> Gate{Gate}
    Gate -->|Pass| LLM2[LLM Call 2] -->|Output 2| LLM3[LLM Call 3] --> Out[Out]
    Gate -->|Fail| Exit[Exit]
    
    style In fill:#8B0000,color:#fff
    style LLM1 fill:#2E8B57,color:#fff
    style LLM2 fill:#2E8B57,color:#fff
    style LLM3 fill:#2E8B57,color:#fff
    style Out fill:#8B0000,color:#fff
    style Exit fill:#8B0000,color:#fff

Agentic Evaluator Optimizer

Create AI agents that can generate and optimize solutions through iterative feedback.

flowchart LR
    In[In] --> Generator[LLM Call Generator] 
    Generator -->|SOLUTION| Evaluator[LLM Call Evaluator] -->|ACCEPTED| Out[Out]
    Evaluator -->|REJECTED + FEEDBACK| Generator
    
    style In fill:#8B0000,color:#fff
    style Generator fill:#2E8B57,color:#fff
    style Evaluator fill:#2E8B57,color:#fff
    style Out fill:#8B0000,color:#fff

Repetitive Agents

Create AI agents that can efficiently handle repetitive tasks through automated loops.

flowchart LR
    In[Input] --> LoopAgent[("Looping Agent")]
    LoopAgent --> Task[Task]
    Task --> |Next iteration| LoopAgent
    Task --> |Done| Out[Output]
    
    style In fill:#8B0000,color:#fff
    style LoopAgent fill:#2E8B57,color:#fff,shape:circle
    style Task fill:#2E8B57,color:#fff
    style Out fill:#8B0000,color:#fff

🔧 Configuration & Integration

Ollama Integration

export OPENAI_BASE_URL=http://localhost:11434/v1

Groq Integration

Replace xxxx with Groq API KEY:

export OPENAI_API_KEY=xxxxxxxxxxx
export OPENAI_BASE_URL=https://api.groq.com/openai/v1

100+ Models Support

OverAI supports 100+ LLM models from various providers. Visit our models documentation for the complete list.

📋 Agents Playbook

Simple Playbook Example

Create agents.yaml file and add the code below:

framework: overai
topic: Artificial Intelligence
agents:  # Canonical: use 'agents' instead of 'roles'
  screenwriter:
    instructions: "Skilled in crafting scripts with engaging dialogue about {topic}."  # Canonical: use 'instructions' instead of 'backstory'
    goal: Create scripts from concepts.
    role: Screenwriter
    tasks:
      scriptwriting_task:
        description: "Develop scripts with compelling characters and dialogue about {topic}."
        expected_output: "Complete script ready for production."

To run the playbook:

overai agents.yaml

🛠️ Custom Tools / Create Plugins

OverAI supports multiple ways to create and integrate custom tools (plugins) into your agents.

Using `@tool` Decorator

from overai import Agent, tool

@tool
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

@tool
def calculate(expression: str) -> float:
    """Evaluate a math expression."""
    return eval(expression)

agent = Agent(
    instructions="You are a helpful assistant",
    tools=[search, calculate]
)
agent.start("Search for AI news and calculate 15*4")

Using `BaseTool` Class

from overai import Agent, BaseTool

class WeatherTool(BaseTool):
    name = "weather"
    description = "Get current weather for a location"
    
    def run(self, location: str) -> str:
        return f"Weather in {location}: 72°F, Sunny"

agent = Agent(
    instructions="You are a weather assistant",
    tools=[WeatherTool()]
)
agent.start("What's the weather in Paris?")

Creating a Tool Package (pip installable)

# pyproject.toml
[project]
name = "my-overai-tools"
version = "1.0.0"
dependencies = ["overai"]

[project.entry-points."overai.tools"]
my_tool = "my_package:MyTool"

# my_package/__init__.py
from overai import BaseTool

class MyTool(BaseTool):
    name = "my_tool"
    description = "My custom tool"
    
    def run(self, param: str) -> str:
        return f"Result: {param}"

After pip install, tools are auto-discovered:

agent = Agent(tools=["my_tool"])  # Works automatically!

🧠 Memory & Context

OverAI provides zero-dependency persistent memory for agents. For detailed examples, see section 6. Agent Memory in the Python Code Examples.

📚 Knowledge & Retrieval (RAG)

OverAI provides a complete knowledge stack for building RAG applications with multiple vector stores, retrieval strategies, rerankers, and query modes.

Knowledge CLI Commands

Command	Description
`overai knowledge add <file\|dir\|url>`	Add documents to knowledge base
`overai knowledge query <question>`	Query knowledge base with RAG
`overai knowledge list`	List indexed documents
`overai knowledge clear`	Clear knowledge base
`overai knowledge stats`	Show knowledge base statistics

Knowledge CLI Options

Option	Values	Description
`--vector-store`	`memory`, `chroma`, `pinecone`, `qdrant`, `weaviate`	Vector store backend
`--retrieval`	`basic`, `fusion`, `recursive`, `auto_merge`	Retrieval strategy
`--reranker`	`simple`, `llm`, `cross_encoder`, `cohere`	Reranking method
`--index-type`	`vector`, `keyword`, `hybrid`	Index type
`--query-mode`	`default`, `sub_question`, `summarize`	Query mode

Knowledge CLI Examples

# Add documents
overai knowledge add ./docs/
overai knowledge add https://example.com/page.html
overai knowledge add "*.pdf"

# Query with advanced options
overai knowledge query "How to authenticate?" --retrieval fusion --reranker llm

# Full advanced query
overai knowledge query "authentication flow" \
  --vector-store chroma \
  --retrieval fusion \
  --reranker llm \
  --index-type hybrid \
  --query-mode sub_question

Knowledge SDK Usage

from overai import Agent, Knowledge

# Simple usage with Agent
agent = Agent(
    name="Research Assistant",
    knowledge=["docs/manual.pdf", "data/faq.txt"],
    knowledge_config={
        "vector_store": {"provider": "chroma"}
    }
)
response = agent.chat("How do I authenticate?")

# Direct Knowledge usage
knowledge = Knowledge()
knowledge.add("document.pdf")
results = knowledge.search("authentication", limit=5)

Knowledge Stack Features Table

Feature	Description	SDK Docs	CLI Docs
Data Readers	Load PDF, Markdown, Text, HTML, URLs	SDK	CLI
Vector Stores	ChromaDB, Pinecone, Qdrant, Weaviate, In-Memory	SDK	CLI
Retrieval Strategies	Basic, Fusion (RRF), Recursive, Auto-Merge	SDK	CLI
Rerankers	Simple, LLM, Cross-Encoder, Cohere	SDK	CLI
Index Types	Vector, Keyword (BM25), Hybrid	SDK	CLI
Query Engines	Default, Sub-Question, Summarize	SDK	CLI

🔬 Advanced Features

Research & Intelligence

🔬 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

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 for web search, news, content extraction

Planning & Workflows

📋 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

Specialised Agents

🖼️ 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
🔀 Model Router - Smart model selection based on task complexity

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

A2A & A2UI Protocols

🔗 A2A Protocol - Agent-to-Agent communication for inter-agent collaboration
🖼️ A2UI Protocol - Agent-to-User Interface for generating rich UIs from agents
📋 UI Templates - ChatTemplate, ListTemplate, FormTemplate, DashboardTemplate
🔧 Surface Builder - Fluent API for building declarative UIs

Safety & Control

🤝 Agent Handoffs - Transfer context between specialised agents
🛡️ Guardrails - Input/output validation and safety checks
✅ Human Approval - Require human confirmation for critical actions
🔐 Tool Approval CLI - --trust (auto-approve all) and --approve-level (risk-based approval)
💬 Sessions Management - Isolated conversation contexts
🔄 Stateful Agents - Maintain state across interactions

Developer Tools

⚡ 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

Other Features

🔄 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

💾 Persistence (Databases)

Enable automatic conversation persistence with 2 lines of code:

from overai import Agent, db

agent = Agent(
    name="Assistant",
    db=db(database_url="postgresql://localhost/mydb"),  # db(...) shortcut
    session_id="my-session"  # Optional: defaults to per-hour ID (YYYYMMDDHH)
)
agent.chat("Hello!")  # Auto-persists messages, runs, traces

Persistence CLI Commands

Command	Description
`overai persistence doctor`	Validate DB connectivity
`overai persistence run`	Run agent with persistence
`overai persistence resume`	Resume existing session
`overai persistence export`	Export session to JSONL
`overai persistence import`	Import session from JSONL
`overai persistence migrate`	Apply schema migrations
`overai persistence status`	Show schema status

Knowledge CLI Commands {#knowledge-cli}

Command	Description
`overai knowledge add <source>`	Add file, directory, URL, or glob pattern
`overai knowledge query "<question>"`	Query knowledge base with RAG
`overai knowledge list`	List indexed documents
`overai knowledge clear`	Clear knowledge base
`overai knowledge stats`	Show knowledge base statistics

Knowledge Query Flags:

Flag	Values	Default
`--vector-store`	`memory`, `chroma`, `pinecone`, `qdrant`, `weaviate`	`chroma`
`--retrieval-strategy`	`basic`, `fusion`, `recursive`, `auto_merge`	`basic`
`--reranker`	`none`, `simple`, `llm`, `cross_encoder`, `cohere`	`none`
`--index-type`	`vector`, `keyword`, `hybrid`	`vector`
`--query-mode`	`default`, `sub_question`, `summarize`	`default`
`--workspace`	Path to workspace directory	Current dir
`--session`	Session ID for persistence	-

Examples:

# Add documents
overai knowledge add document.pdf
overai knowledge add ./docs/
overai knowledge add "*.md"

# Query with options
overai knowledge query "How to authenticate?" \
  --vector-store chroma \
  --retrieval-strategy fusion \
  --reranker simple \
  --query-mode sub_question

Databases Table

Database	Store Type	Install	Example	Docs
PostgreSQL	Conversation	`pip install "overai[tools]"`	simple_db_agent.py	docs
MySQL	Conversation	`pip install "overai[tools]"`	-	docs
SQLite	Conversation	`pip install "overai[tools]"`	-	docs
SingleStore	Conversation	`pip install "overai[tools]"`	-	docs
Supabase	Conversation	`pip install "overai[tools]"`	-	docs
SurrealDB	Conversation	`pip install "overai[tools]"`	-	docs
Qdrant	Knowledge	`pip install "overai[tools]"`	knowledge_qdrant.py	docs
ChromaDB	Knowledge	`pip install "overai[tools]"`	-	docs
Pinecone	Knowledge	`pip install pinecone`	pinecone_wow.py	docs
Weaviate	Knowledge	`pip install weaviate-client`	weaviate_wow.py	docs
LanceDB	Knowledge	`pip install lancedb`	lancedb_real_wow.py	docs
Milvus	Knowledge	`pip install "overai[tools]"`	-	docs
PGVector	Knowledge	`pip install psycopg2-binary`	pgvector_real_wow.py	docs
Redis Vector	Knowledge	`pip install "overai[tools]"`	-	docs
Cassandra	Knowledge	`pip install "overai[tools]"`	-	docs
ClickHouse	Knowledge	`pip install "overai[tools]"`	-	docs
Redis	State	`pip install "overai[tools]"`	state_redis.py	docs
MongoDB	State	`pip install "overai[tools]"`	-	docs
DynamoDB	State	`pip install "overai[tools]"`	-	docs
Firestore	State	`pip install "overai[tools]"`	-	docs
Upstash	State	`pip install "overai[tools]"`	-	docs
Memory	State	`pip install "overai[tools]"`	-	docs

🔧 Tools Table

Install all tools with: pip install "overai[tools]"

Tool	Category	Import	Docs
Tavily	Web Search	`from overai_tools import TavilyTool`	docs
DuckDuckGo	Web Search	`from overai_tools import DuckDuckGoTool`	docs
Exa	Web Search	`from overai_tools import ExaTool`	docs
Serper	Web Search	`from overai_tools import SerperTool`	docs
Jina	Web Reader	`from overai_tools import JinaTool`	docs
Firecrawl	Web Scraping	`from overai_tools import FirecrawlTool`	docs
Crawl4AI	Web Scraping	`from overai_tools import Crawl4AITool`	docs
Wikipedia	Knowledge	`from overai_tools import WikipediaTool`	docs
ArXiv	Research	`from overai_tools import ArxivTool`	docs
HackerNews	News	`from overai_tools import HackerNewsTool`	docs
YouTube	Media	`from overai_tools import YouTubeTool`	docs
Weather	Data	`from overai_tools import WeatherTool`	docs
PostgreSQL	Database	`from overai_tools import PostgresTool`	docs
MySQL	Database	`from overai_tools import MySQLTool`	docs
SQLite	Database	`from overai_tools import SQLiteTool`	docs
MongoDB	Database	`from overai_tools import MongoDBTool`	docs
Redis	Database	`from overai_tools import RedisTool`	docs
Qdrant	Vector DB	`from overai_tools import QdrantTool`	docs
GitHub	DevOps	`from overai_tools import GitHubTool`	docs
Slack	Communication	`from overai_tools import SlackTool`	docs
Discord	Communication	`from overai_tools import DiscordTool`	docs
Telegram	Communication	`from overai_tools import TelegramTool`	docs
Email	Communication	`from overai_tools import EmailTool`	docs
Notion	Productivity	`from overai_tools import NotionTool`	docs
File	File System	`from overai_tools import FileTool`	docs
Shell	System	`from overai_tools import ShellTool`	docs
Python	Code	`from overai_tools import PythonTool`	docs
JSON	Data	`from overai_tools import JSONTool`	docs
CSV	Data	`from overai_tools import CSVTool`	docs
Calculator	Math	`from overai_tools import CalculatorTool`	docs

See full tools documentation for all 100+ available tools.

👥 Contributing

We welcome contributions from the community! Here's how you can contribute:

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

🔧 Development

Using uv

# 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

# From project root - bumps version and releases in one command
python src/overai/scripts/bump_and_release.py 2.2.99

# With overai dependency
python src/overai/scripts/bump_and_release.py 2.2.99 --agents 0.0.169

# Then publish
cd src/overai && uv publish

❓ FAQ & Troubleshooting

ModuleNotFoundError: No module named 'overai'

Install the package:

pip install overai

API key not found / Authentication error

Ensure your API key is set:

export OPENAI_API_KEY=your_key_here

For other providers, see Environment Variables.

How do I use a local model (Ollama)?

# Start Ollama server first
ollama serve

# Set environment variable
export OPENAI_BASE_URL=http://localhost:11434/v1

See Ollama Integration for more details.

How do I persist conversations to a database?

Use the db parameter:

from overai import Agent, db

agent = Agent(
    name="Assistant",
    db=db(database_url="postgresql://localhost/mydb"),
    session_id="my-session"
)

See Persistence (Databases) for supported databases.

How do I enable agent memory?

from overai import Agent

agent = Agent(
    name="Assistant",
    memory=True,  # Enables file-based memory (no extra deps!)
    user_id="user123"
)

See Agent Memory for more options.

How do I run multiple agents together?

from overai import Agent, OverAIAgents

agent1 = Agent(instructions="Research topics")
agent2 = Agent(instructions="Summarize findings")
agents = OverAIAgents(agents=[agent1, agent2])
agents.start()

See Multi Agents for more examples.

How do I use MCP tools?

from overai import Agent, MCP

agent = Agent(
    tools=MCP("npx @modelcontextprotocol/server-memory")
)

See MCP Protocol for all transport options.

Getting Help

Made with ❤️ by the OverAI Team

• • Issues

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

3.1.6

Jan 11, 2026

This version

3.1.5

Jan 11, 2026

3.1.4

Jan 11, 2026

3.1.3

Jan 11, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

overai_cli-3.1.5.tar.gz (994.7 kB view details)

Uploaded Jan 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

overai_cli-3.1.5-py3-none-any.whl (1.2 MB view details)

Uploaded Jan 11, 2026 Python 3

File details

Details for the file overai_cli-3.1.5.tar.gz.

File metadata

Download URL: overai_cli-3.1.5.tar.gz
Upload date: Jan 11, 2026
Size: 994.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for overai_cli-3.1.5.tar.gz
Algorithm	Hash digest
SHA256	`b774a5abc15b0643f986503712204d0a65032f42ca2dab3f8eff2dc21491d945`
MD5	`e6068eb3f228328afa7795b6ee23ab3a`
BLAKE2b-256	`66137dd2a72cf22a28369ab9749bbbb0c81eebb021cabe71ed326da85e0f1d0d`

See more details on using hashes here.

File details

Details for the file overai_cli-3.1.5-py3-none-any.whl.

File metadata

Download URL: overai_cli-3.1.5-py3-none-any.whl
Upload date: Jan 11, 2026
Size: 1.2 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for overai_cli-3.1.5-py3-none-any.whl
Algorithm	Hash digest
SHA256	`9f7bb4fd948efd76c0a037f49097b2c413dd806c7e1e725f4037e9ba69cdf8f2`
MD5	`b281812c5e52d3ec3f69b934e62dd851`
BLAKE2b-256	`86f71a778375976d7b740f6b42c3de20219b46520957c8c55f6ba5ac15be0117`

See more details on using hashes here.

overai-cli 3.1.5

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

OverAI Agents

📑 Table of Contents

Getting Started

Core Concepts

Python SDK

JavaScript SDK

CLI Reference

Configuration

Advanced Features

Architecture

Data & Persistence

Learning & Community

⚡ Performance

🚀 Quick Start

📦 Installation

Python SDK

JavaScript SDK

Environment Variables

💻 Usage

Python Code Examples

CLI / No-Code Interface

JavaScript Code Examples

✨ Key Features

🌐 Supported Providers

📘 Using Python Code

1. Single Agent

2. Multi Agents

3. Agent with Planning Mode

4. Deep Research Agent

5. Query Rewriter Agent

6. Agent Memory (Zero Dependencies)

7. Rules & Instructions

8. Auto-Generated Memories

9. Agentic Workflows

Workflow Patterns (route, parallel, loop, repeat)

YAML Workflow Template

Loading YAML Workflows

Complete workflow.yaml Reference

10. Hooks

11. Shadow Git Checkpoints

12. Background Tasks

13. Policy Engine

14. Thinking Budgets

15. Output Styles

16. Context Compaction

17. Field Names Reference (A-I-G-S)

18. Extended agents.yaml with Workflow Patterns

19. MCP (Model Context Protocol)

MCP Client (Consume MCP Servers)

MCP Server (Expose Tools as MCP Server)

MCP Features

20. A2A (Agent2Agent Protocol)

A2A Server (Expose Agent as A2A Server)

A2A Features

🎯 CLI / No-Code Interface

CLI Quick Reference

Auto Mode

Interactive Mode CLI:

Chat UI (Web Interface):

Query Rewriting (works with any command):

Deep Research CLI:

Planning Mode CLI:

Tool Approval CLI:

Memory CLI:

Rules CLI:

Workflow CLI:

YAML Workflow Files:

Auto-Generate Workflows:

Hooks CLI:

Claude Memory Tool CLI:

Guardrail CLI:

Metrics CLI:

Scheduler CLI:

Using `@tool` Decorator

Using `BaseTool` Class