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 文件夹里有现成可运行的脚本,其中还包括一个最简示例。
用它是必须要 OpenAI 的 API 密钥吗?是的——OWL 需要用到它所交互的各服务的 API 密钥,首先是你的大模型服务商的密钥。最简示例只需配置这一个密钥就能运行。
随便什么大模型都行吗,还是说模型的选择很重要?很重要。OWL 需要工具调用能力强的模型,处理网页、图片或视频任务时还需要多模态模型。作者强烈建议使用 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 和 Google Scholar、Reddit、Notion、天气、Excel、SymPy 数学运算、代码执行、DALL-E 图像生成,还有浏览器、搜索、视频、音频和图像分析等工具包。编辑脚本里的 tools 列表即可启用它们。
What are similar projects?hive, qwen-code, semantic-kernel, turnstone, adk-python, penguin-harness, Agent-S, Agentlas-OS
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