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
Что это такое?OWL (Optimized Workforce Learning) — это опенсорсный фреймворк для взаимодействия нескольких агентов, который автоматизирует реальные задачи. Он построен поверх фреймворка CAMEL-AI и занимает первое место среди опенсорсных фреймворков в бенчмарке GAIA со средним баллом 69,09.
Это онлайн-сервис, для которого нужна регистрация, или я устанавливаю и запускаю его сам?Вы запускаете его сами: это Python-фреймворк, который устанавливается локально и управляется через примеры скриптов или встроенный веб-интерфейс. Свою задачу вы задаёте, отредактировав скрипт run.py.
Как его запустить?Установите Python 3.10, 3.11 или 3.12, затем выберите один из четырёх способов установки: uv (рекомендуется), обычный venv с pip, conda или готовый Docker-образ. В папке examples лежат готовые скрипты, включая минимальный.
Для работы нужен API-ключ OpenAI?Да — OWL требует API-ключи для сервисов, с которыми взаимодействует, начиная с ключа вашего LLM-провайдера. Минимальный пример работает уже с одним только этим ключом.
Подойдёт любая LLM, или выбор модели имеет значение?Имеет. OWL нужны модели с сильными навыками вызова инструментов (tool calling), а для задач с вебом, изображениями или видео — мультимодальные. Авторы настоятельно рекомендуют GPT-4 или новее: более слабые модели заметно хуже справляются со сложными задачами.
Он построен на фреймворке CAMEL-AI — что это такое?CAMEL-AI — это базовый мультиагентный фреймворк, который обеспечивает среду выполнения агентов OWL и интеграции с моделями. Для бенчмарка GAIA есть даже отдельная ветка, в которой в каталоге owl/camel поставляется кастомизированная копия CAMEL для большей стабильности.
Что такое MCP и зачем при установке упоминается Node.js?MCP (Model Context Protocol) — это стандартный слой, который позволяет агентам OWL взаимодействовать с внешними инструментами и источниками данных. Прежде чем им пользоваться, нужно установить Node.js и сервис Playwright MCP.
Какие наборы инструментов входят в комплект?Список большой: Arxiv, GitHub, Google Maps и Scholar, Reddit, Notion, Weather, Excel, математика через SymPy, выполнение кода, генерация изображений в DALL-E, а также тулкиты для браузера, поиска, видео, аудио и анализа изображений. Включаются они правкой списка tools в вашем скрипте.
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