Downloads · 30 days
0
0% of all-time downloads
zoe102/owl-agent
owl-agent is a machine learning model from zoe102. Use it for the machine learning task on the model card, and read the license before you ship it in a product.
<h1 align="center" 🦉 OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation </h1
Downloads · 30 days
0
0% of all-time downloads
All-time downloads
1
Public
Repo size
3.3 MB
Likes
0
Public
Click a slice to open those files.
.jpg2.7 MB · 60%
From the Hugging Face model README
中文阅读 | Community | Installation | Examples | Paper | Citation | Contributing | CAMEL-AI
</h4> <div align="center" style="background-color: #f0f7ff; padding: 10px; border-radius: 5px; margin: 15px 0;"> <h3 style="color: #1e88e5; margin: 0;"> 🏆 OWL achieves <span style="color: #d81b60; font-weight: bold; font-size: 1.2em;">58.18</span> average score on GAIA benchmark and ranks <span style="color: #d81b60; font-weight: bold; font-size: 1.2em;">🏅️ #1</span> among open-source frameworks! 🏆 </h3> </div> <div align="center">🦉 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.
<!-- OWL achieves **58.18** average score on [GAIA](https://huggingface.co/spaces/gaia-benchmark/leaderboard) benchmark and ranks 🏅️ #1 among open-source frameworks. -->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.
</div>
https://github.com/user-attachments/assets/2a2a825d-39ea-45c5-9ba1-f9d58efbc372
OWL supports multiple installation methods to fit your workflow preferences. Choose the option that works best for you.
# 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
# We support using Python 3.10, 3.11, 3.12
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 .
# Exit the virtual environment when done
deactivate
# 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
# 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
# Exit the conda environment when done
conda deactivate
OWL requires various API keys to interact with different services. The owl/.env_template file contains placeholders for all necessary API keys along with links to the services where you can register for them.
.env File (Recommended)Copy and Rename the Template:
cd owl
cp .env_template .env
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 (
run_mini.py), you only need to configure the LLM API key (e.g.,OPENAI_API_KEY).
Alternatively, you can set environment variables directly in your terminal:
macOS/Linux (Bash/Zsh):
export OPENAI_API_KEY="your-openai-api-key-here"
Windows (Command Prompt):
set OPENAI_API_KEY="your-openai-api-key-here"
Windows (PowerShell):
$env:OPENAI_API_KEY = "your-openai-api-key-here"
Note: Environment variables set directly in the terminal will only persist for the current session.
# Clone the repository
git clone https://github.com/camel-ai/owl.git
cd owl
# Configure environment variables
cp owl/.env_template owl/.env
# Edit the .env file and fill in your API keys
# Option 1: Using docker-compose directly
cd .container
docker-compose up -d
# Run OWL inside the container
docker-compose exec owl bash -c "xvfb-python run.py"
# Option 2: Build and run using the provided scripts
cd .container
chmod +x build_docker.sh
./build_docker.sh
# Run OWL inside the container
./run_in_docker.sh "your question"
For more detailed Docker usage instructions, including cross-platform support, optimized configurations, and troubleshooting, please refer to DOCKER_README.md.
After installation and setting up your environment variables, you can start using OWL right away:
python owl/run.py
Tool Calling: OWL requires models with robust tool calling capabilities to interact with various toolkits. Models must be able to understand tool descriptions, generate appropriate tool calls, and process tool outputs.
Multimodal Understanding: For tasks involving web interaction, image analysis, or video processing, models with multimodal capabilities are required to interpret visual content and context.
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 Qwen model
python owl/run_qwen_zh.py
# Run with Deepseek model
python owl/run_deepseek_zh.py
# Run with other OpenAI-compatible models
python owl/run_openai_compatiable_model.py
# Run with Ollama
python owl/run_ollama.py
For a simpler version that only requires an LLM API key, you can try our minimal example:
python owl/run_mini.py
You can run OWL agent with your own task by modifying the run.py script:
# Define your own task
question = "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`)
question = "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.
Here are some tasks you can try with OWL:
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 = [
*WebToolkit(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,
*ExcelToolkit().get_tools(),
*DocumentProcessingToolkit(model=models["document"]).get_tools(),
*FileWriteToolkit(output_dir="./").get_tools(),
]
Key toolkits include:
Additional specialized toolkits: ArxivToolkit, GitHubToolkit, GoogleMapsToolkit, MathToolkit, NetworkXToolkit, NotionToolkit, RedditToolkit, WeatherToolkit, and more. For a complete list, see the CAMEL toolkits documentation.
To customize available tools:
# 1. Import toolkits
from camel.toolkits import WebToolkit, SearchToolkit, CodeExecutionToolkit
# 2. Configure tools list
tools = [
*WebToolkit(headless=True).get_tools(),
SearchToolkit().search_wiki,
*CodeExecutionToolkit(sandbox="subprocess").get_tools(),
]
# 3. Pass to assistant agent
assistant_agent_kwargs = {"model": models["assistant"], "tools": tools}
Selecting only necessary toolkits optimizes performance and reduces resource usage.
OWL includes an intuitive web-based user interface that makes it easier to interact with the system.
# Start the Chinese version
python run_app_zh.py
# Start the English version
python run_app.py
The web interface is built using Gradio and runs locally on your machine. No data is sent to external servers beyond what's required for the model API calls you configure.
To reproduce OWL's GAIA benchmark score of 58.18:
Switch to the gaia58.18 branch:
git checkout gaia58.18
Run the evaluation script:
python run_gaia_roleplaying.py
This will execute the same configuration that achieved our top-ranking performance on the GAIA benchmark.
We're continuously working to improve OWL. Here's what's on our roadmap:
The source code is licensed under Apache 2.0.
If you find this repo useful, please cite:
@misc{owl2025,
title = {OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation},
author = {{CAMEL-AI.org}},
howpublished = {\url{https://github.com/camel-ai/owl}},
note = {Accessed: 2025-03-07},
year = {2025}
}
We welcome contributions from the community! Here's how you can help:
Current Issues Open for Contribution:
To take on an issue, simply leave a comment stating your interest.
Join us (Discord or WeChat) in pushing the boundaries of finding the scaling laws of agents.
Join us for further discussions!

Q: Why don't I see Chrome running locally after starting the example script?
A: If OWL determines that a task can be completed using non-browser tools (such as search or code execution), the browser will not be launched. The browser window will only appear when OWL determines that browser-based interaction is necessary.
Q: Which Python version should I use?
A: OWL supports Python 3.10, 3.11, and 3.12.
Q: How can I contribute to the project?
A: See our Contributing section for details on how to get involved. We welcome contributions of all kinds, from code improvements to documentation updates.
OWL is built on top of the CAMEL Framework, here's how you can explore the CAMEL source code and understand how it works with OWL:
# Clone the CAMEL repository
git clone https://github.com/camel-ai/camel.git
cd camel