Camel-AI / Owl: 🦉 Owl: Optimized job job for general multi-agent assistance in real-world task automation

• (2025.03.12): Added searchptoolkit, integrated volcano english platform, and enhances azurei and opuai models with financing call and tool call.
• (2025.03.11): We add mcptoolkit, filewardetoolkit, and terminaltoolkit to develop Owl Agents with MCP writing capabilities, and file writing execution.
• (2025.03.09): We add a web-based user interface that is easier to interact with the system.
• (2025.03.07): We opened the condition of the Owl project.
• (2025.03.03): Owl gets # 1 position of open source frameworks in Gaia Benchmark with a score of 58.18.

• Real-time information on information: Leverage Wikipedia, Google search, and other online sources for up-to-date information.
• Multimodal processing: Support for Internet management or local videos, images, and audio data.
• Browser Automation: Using PlayWright Framework for simulating browser interactions, including scrolling, clicking, input input, download, navigation, and more.
• Document to parsing: Take content from word, excel, pdf, and powerpoint files, reinstate this text or markdod format.
• Killing the code: Write and enforce the python code using the translator.
• Built-in toolkits: Access to a comprehensive set of built toolkits including:
  • Model Context Protocol (MCP): A universal layer of protocol standardizing with AI model interactions with different tools and data sources
  • Core toolkits: Arxivtoolkit, audioanalysistoolkit, codeexecutiontoolkit, dalletoolkit, datacommonstoolkit, exceltoolkit, githubtoolkit, googlemapstoolkit, googlescholartoolkit, googlescholartoolkit, mathtoolkit, networkxtoolkit, net.com Openapitolkit, reddittoolkit, seatthtoolkit, semanticscholartoolkit, Symanttoolkit, VideosAnalysisKoiolkit, weatertoolkit, browntoolkit, broadgoolkit, and more for specialized work

Owl supports several methods of installation to suit your workflow preferences. Choose the option 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 --use-pep517

# 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

# Exit the conda environment when done
conda deactivate

Owl requires different API keys to interact with different services. the owl/.env_template The file contains placeholders for all required API keys along with the services links where you can register for them.

1. Copy and Change Turglate:

   cd owl
   cp .env_template .env

2. Configure your API keys: Open the .env File to your desired text editor and enter your API keys to corresponding fields.

   money: For a small example (run_mini.py), you just have to configure the LLM API key (eg, OPENAI_API_KEY).

Alternatively, you can put variables around your terminal directly:

money: Environmental variables directly to the terminal will continue only 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

# activate the virtual environment
cd .. && source .venv/bin/activate && cd owl

playwright install-deps 

#run example demo script
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 instructions to use Docker, including cross-platform support, configurations are optimized, and resolve, please see Docker_readme.md.

MCP power experienced by running our example showing information and processing of many agents:

# Set up MCP servers (one-time setup)
npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude
npx @wonderwhy-er/desktop-commander setup

# Run the MCP example
python owl/run_mcp.py

This example shows how Owl agents can be bright together with file systems, web automation, and gain information on MCP protocol. Search owl/run_mcp.py for perfect implementation.

After installing and setting up your variables around, you can start using Owl away:

• Tool call: Owl requires models with Calling Calls Calling Calls to Talk to Different Toolkits. Models need to understand tool descriptions, generate appropriate tool calls, and processing tool games.

• Multimodal understanding: For tasks involving web interaction, image analyzing, or video processing, models with multimodal capabilities required to translate visual content and context.

For information about configuring AI models, please see our Camel models.

money: For optimal performance, we strongly recommend using OpenI models (GPT-4 or later versions). Our experiments show that other models may result in a greater performance of complex functions and benchmarks, especially the required claim to be multi-modal understanding and tool use.

Owl supports different backends of LLM, although capabilities may vary depending on model model 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 Azure OpenAI
python owl/run_azure_openai.py

# Run with Ollama
python owl/run_ollama.py

For a more simple version that requires a LLM API key, you can try our little example:

You can run to the Owl Agent on your own assignment by changing 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, just give the passage to the file 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 then automatically prompts document-related tools to process the file and get the answer.

Here are some tasks you can try on the owl:

• “Find the latest stock price for Apple Inc.”
• “Check cement on new tweet about climate change”
• “Help me debug this Python code: (Your code here)”
• “Summarize the main points from this research paper: (Paper URL)”
• “Create a Data Visualization for this DataSet: (DataSet Road)”

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

Test our comprehensive example of MCP in owl/run_mcp.py To see these action capabilities!

essential: Effective use of toolkits require models with strong ability to call tool. For multimodal toolkits (web, image, video), models should also have multiple multimodal understanding abilities.

Owl supports different toolkits to be customized by repeating the tools List 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,
    *ExcelToolkit().get_tools(),
    *DocumentProcessingToolkit(model=models("document")).get_tools(),
    *FileWriteToolkit(output_dir="./").get_tools(),
)

The key toolkits include:

• BrowserHolkit: Browser automation for web interaction and navigation
• Video analysis: Video processing and analyzing content
• Imsenyanalysiskoolkit: Image analysis and interpretation

• Audioanalysiskoolkit: Audio processing (OpenI API required)
• Codeexecutiolkit: Python Code Dead and Check
• Searchtoolkit: Web Searches (Google, Duckduckgo, Wikipedia)
• Documentprocesingtolkit: Document parsing (PDF, Docx, etc)

Additional Specialized Toolkits: Arxivtoolkit, Githubtoolkit, Googlemapstoolkit, Mathtoolkit, Networkxtoolkit, Notiontoolkit, Reddittoolkit, WeatherToolkit, and more. For a complete list, see the The camel’s camel documentation.

To match the available tools:

# 1. Import toolkits
from camel.toolkits import BrowserToolkit, SearchToolkit, CodeExecutionToolkit

# 2. Configure tools list
tools = (
    *BrowserToolkit(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}

Choosing only necessary toolkits optimizes performance and reduction in resource use.

The owl includes an intuitive web-based user interface that is easier to interact with the system.

# Start the Chinese version
python run_app_zh.py

# Start the English version
python run_app.py

• Easy model selection: Choose between different models (Openi, Qwen, Deepsheek, etc.)
• Management of Kapilluran: Configure your API keys and other settings directly from UI
• Interactive Chat Interface: Talk to Owl Agents by an interface-friendly interface
• BACKGROUND: Look at the history and consequences of your interviews

Web interface is built with grado and runs on local machine. No external servers are sent above required for the Model API calling you to be configured.

To change Gaia Benchmark Percentage 58.18:

1. Transfer to gaia58.18 Branch:

2. Run the script of the checking:

   python run_gaia_roleplaying.py

This will implement the same configuration that reach our rank ranked on The Gaia Benchmark.

We keep working to improve the owl. Here’s what’s on our roadmap:

The source code is licensed under Apache 2.0.

If you find this repo useful, please indicate:

@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 help:

1. Read our Contribution Instructions
2. CHECKS Open issues or make new
3. Submit the binding requests to your progress

The current issues open for contribution:

To go to an issue, simply to leave a comment expressing your interest.

Involve us (contention or Wechat) to push boundaries to find the rules of scaling agents.

Join us for more discussions!

Q: Why don’t I see chrome running locally after the start of Example Script?

A: If the Owl is determined to be a task can be completed using non-browser tools (such as searching or execution code), the browser will not be launched. The browser window only appears if owls determine that the browser interaction requires.

Q: Which version of Python 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 causes Section for details on how to participate. We welcome contributions to all kinds, from repair code to documentation updates.

Owl is built on top of Camel Outline, here’s how you explore Camel Code code source how it works in the owl:

# Clone the CAMEL repository
git clone https://github.com/camel-ai/camel.git
cd camel