owl README

The project's README from github.com/camel-ai/owl. As one markdown file: README.md.

🦉 OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation

[![Documentation][docs-image]][docs-url] [![Discord][discord-image]][discord-url] [![X][x-image]][x-url] [![Reddit][reddit-image]][reddit-url] [![Wechat][wechat-image]][wechat-url] [![Wechat][owl-image]][owl-url] [![Hugging Face][huggingface-image]][huggingface-url] [![Star][star-image]][star-url] [![Package License][package-license-image]][package-license-url] Citation

中文阅读 | Community | Installation | Examples | Paper | Citation | Contributing | CAMEL-AI |

🏆 OWL achieves 69.09 average score on GAIA benchmark and ranks 🏅️ #1 among open-source frameworks! 🏆

🦉 OWL is a cutting-edge framework for multi-agent collaboration that pushes the boundaries of task automation, built on top of the CAMEL-AI Framework.

Our vision is to revolutionize how AI agents collaborate to solve real-world tasks. By leveraging dynamic agent interactions, OWL enables more natural, efficient, and robust task automation across diverse domains.

If you find this repo useful, please consider citing our work (citation).


📋 Table of Contents

🔥 News

🧩 NEW: COMMUNITY AGENT CHALLENGES! 🧩

Showcase your creativity by designing unique challenges for AI agents!
Join our community and see your innovative ideas tackled by cutting-edge AI.

View & Submit Challenges

🎬 Demo Video

https://github.com/user-attachments/assets/2a2a825d-39ea-45c5-9ba1-f9d58efbc372

https://private-user-images.githubusercontent.com/55657767/420212194-e813fc05-136a-485f-8df3-f10d9b4e63ec.mp4

This video demonstrates how to install OWL locally and showcases its capabilities as a cutting-edge framework for multi-agent collaboration: https://www.youtube.com/watch?v=8XlqVyAZOr8

✨️ Core Features

🛠️ Installation

Prerequisites

Install Python

Before installing OWL, ensure you have Python installed (version 3.10, 3.11, or 3.12 is supported):

Note for GAIA Benchmark Users: When running the GAIA benchmark evaluation, please use the gaia58.18 branch which includes a customized version of the CAMEL framework in the owl/camel directory. This version contains enhanced toolkits with improved stability specifically optimized for the GAIA benchmark compared to the standard CAMEL installation.

# Check if Python is installed
python --version

# If not installed, download and install from https://www.python.org/downloads/
# For macOS users with Homebrew:
brew install [email protected]

# For Ubuntu/Debian:
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip

Installation Options

OWL supports multiple installation methods to fit your workflow preferences.

# Clone github repo
git clone https://github.com/camel-ai/owl.git

# Change directory into project directory
cd owl

# Install uv if you don't have it already
pip install uv

# Create a virtual environment and install dependencies
uv venv .venv --python=3.10

# Activate the virtual environment
# For macOS/Linux
source .venv/bin/activate
# For Windows
.venv\Scripts\activate

# Install CAMEL with all dependencies
uv pip install -e .

Option 2: Using venv and pip

# Clone github repo
git clone https://github.com/camel-ai/owl.git

# Change directory into project directory
cd owl

# Create a virtual environment
# For Python 3.10 (also works with 3.11, 3.12)
python3.10 -m venv .venv

# Activate the virtual environment
# For macOS/Linux
source .venv/bin/activate
# For Windows
.venv\Scripts\activate

# Install from requirements.txt
pip install -r requirements.txt --use-pep517

Option 3: Using conda

# Clone github repo
git clone https://github.com/camel-ai/owl.git

# Change directory into project directory
cd owl

# Create a conda environment
conda create -n owl python=3.10

# Activate the conda environment
conda activate owl

# Option 1: Install as a package (recommended)
pip install -e .

# Option 2: Install from requirements.txt
pip install -r requirements.txt --use-pep517

Option 4: Using Docker

# This option downloads a ready-to-use image from Docker Hub
# Fastest and recommended for most users
docker compose up -d

# Run OWL inside the container
docker compose exec owl bash
cd .. && source .venv/bin/activate
playwright install-deps
xvfb-python examples/run.py

Building Image Locally

# For users who need to customize the Docker image or cannot access Docker Hub:
# 1. Open docker-compose.yml
# 2. Comment out the "image: mugglejinx/owl:latest" line
# 3. Uncomment the "build:" section and its nested properties
# 4. Then run:
docker compose up -d --build

# Run OWL inside the container
docker compose exec owl bash
cd .. && source .venv/bin/activate
playwright install-deps
xvfb-python examples/run.py

Using Convenience Scripts

# Navigate to container directory
cd .container

# Make the script executable and build the Docker image
chmod +x build_docker.sh
./build_docker.sh

# Run OWL with your question
./run_in_docker.sh "your question"

Setup Environment Variables

OWL requires various API keys to interact with different services.

Setting Environment Variables Directly

You can set environment variables directly in your terminal:

Note: Environment variables set directly in the terminal will only persist for the current session.

Alternative: Using a .env File

If you prefer using a .env file instead, you can:

  1. Copy and Rename the Template:

    # For macOS/Linux
cd owl
cp .env_template .env

# For Windows
cd owl
copy .env_template .env

    Alternatively, you can manually create a new file named .env in the owl directory and copy the contents from .env_template.

  2. Configure Your API Keys: Open the .env file in your preferred text editor and insert your API keys in the corresponding fields.

Note: For the minimal example (examples/run_mini.py), you only need to configure the LLM API key (e.g., OPENAI_API_KEY).

MCP Desktop Commander Setup

If using MCP Desktop Commander within Docker, run:

npx -y @wonderwhy-er/desktop-commander setup --force-file-protocol

For more detailed Docker usage instructions, including cross-platform support, optimized configurations, and troubleshooting, please refer to DOCKER_README.md.

🚀 Quick Start

Basic Usage

After installation and setting up your environment variables, you can start using OWL right away:

python examples/run.py

Running with Different Models

Model Requirements

Supported Models

For information on configuring AI models, please refer to our CAMEL models documentation.

Note: For optimal performance, we strongly recommend using OpenAI models (GPT-4 or later versions). Our experiments show that other models may result in significantly lower performance on complex tasks and benchmarks, especially those requiring advanced multi-modal understanding and tool use.

OWL supports various LLM backends, though capabilities may vary depending on the model's tool calling and multimodal abilities. You can use the following scripts to run with different models:

# Run with Claude model
python examples/run_claude.py

# Run with Qwen model
python examples/run_qwen_zh.py

# Run with Deepseek model
python examples/run_deepseek_zh.py

# Run with other OpenAI-compatible models
python examples/run_openai_compatible_model.py

# Run with Gemini model
python examples/run_gemini.py

# Run with Azure OpenAI
python examples/run_azure_openai.py

# Run with Ollama
python examples/run_ollama.py

For a simpler version that only requires an LLM API key, you can try our minimal example:

python examples/run_mini.py

You can run OWL agent with your own task by modifying the examples/run.py script:

# Define your own task
task = "Task description here."

society = construct_society(question)
answer, chat_history, token_count = run_society(society)

print(f"\033[94mAnswer: {answer}\033[0m")

For uploading files, simply provide the file path along with your question:

# Task with a local file (e.g., file path: `tmp/example.docx`)
task = "What is in the given DOCX file? Here is the file path: tmp/example.docx"

society = construct_society(question)
answer, chat_history, token_count = run_society(society)
print(f"\033[94mAnswer: {answer}\033[0m")

OWL will then automatically invoke document-related tools to process the file and extract the answer.

Example Tasks

Here are some tasks you can try with OWL:

🧰 Toolkits and Capabilities

Model Context Protocol (MCP)

OWL's MCP integration provides a standardized way for AI models to interact with various tools and data sources:

Before using MCP, you need to install Node.js first.

Install Node.js

Windows

Download the official installer: Node.js.

Check "Add to PATH" option during installation.

Linux

sudo apt update
sudo apt install nodejs npm -y

Mac

brew install node

Install Playwright MCP Service

npm install -g @executeautomation/playwright-mcp-server
npx playwright install-deps

Try our comprehensive MCP examples:

Available Toolkits

Important: Effective use of toolkits requires models with strong tool calling capabilities. For multimodal toolkits (Web, Image, Video), models must also have multimodal understanding abilities.

OWL supports various toolkits that can be customized by modifying the tools list in your script:

# Configure toolkits
tools = [
    *BrowserToolkit(headless=False).get_tools(),  # Browser automation
    *VideoAnalysisToolkit(model=models["video"]).get_tools(),
    *AudioAnalysisToolkit().get_tools(),  # Requires OpenAI Key
    *CodeExecutionToolkit(sandbox="subprocess").get_tools(),
    *ImageAnalysisToolkit(model=models["image"]).get_tools(),
    SearchToolkit().search_duckduckgo,
    SearchToolkit().search_google,  # Comment out if unavailable
    SearchToolkit().search_wiki,
    SearchToolkit().search_bocha,
    SearchToolkit().search_baidu,
    *ExcelToolkit().g

owl (camel-ai/owl)

Searching Database…

20.2K ·GitHub
Owl
What is this?OWL (Optimized Workforce Learning) is an open-source framework for multi-agent collaboration that automates real-world tasks. Built on top of the CAMEL-AI framework, it ranks #1 among open-source frameworks on the GAIA benchmark with a 69.09 average score.
Is this a hosted service I sign up for, or something I install and run myself?Something you run yourself: it's a Python framework you install locally and drive through example scripts or its built-in web UI. You point it at your own task by editing the run.py script.
How do I get it running?Install Python 3.10, 3.11 or 3.12, then pick one of four install routes: uv (recommended), a plain venv with pip, conda, or a pre-built Docker image. The examples folder ships ready-to-run scripts, including a minimal one.
Do I need an OpenAI API key to use it?Yes - OWL requires API keys for the services it interacts with, starting with your LLM provider's key. The minimal example runs with just that one key configured.
Will any LLM work, or does the model choice matter?It matters. OWL needs models with strong tool-calling skills, and multimodal ones for web, image or video tasks. The authors strongly recommend GPT-4 or newer, since weaker models score significantly lower on complex tasks.
It's built on the CAMEL-AI framework - what is that?CAMEL-AI is the underlying multi-agent framework that provides OWL's agent runtime and model integrations. There's even a special branch for the GAIA benchmark that ships a customized copy of CAMEL in the owl/camel directory for better stability.
What is MCP, and why does setup mention installing Node.js?MCP (Model Context Protocol) is a standard layer that lets OWL's agents interact with external tools and data sources. Before using it, you need to install Node.js and the Playwright MCP service.
Which toolkits come built in?A long list: Arxiv, GitHub, Google Maps and Scholar, Reddit, Notion, Weather, Excel, SymPy math, code execution, DALL-E image generation, plus browser, search, and video, audio and image analysis toolkits. You enable them by editing the tools list in your script.
What are similar projects?hive, qwen-code, semantic-kernel, turnstone, adk-python, Agent-S, Agentlas-OS, CUAWright
Which topics is it in?task-automation, multi-agent-systems, webui, playwright, agent-framework, search, browser-automation, multimodal, artificial-intelligence, agentic-ai, gemini, multi-agent
Creator
camel-ai
Size
40.1 MB
Stars
20.2K
Updated
CommitOct 12
Age
1y
Commits · 90 Days