# https://github.com/camel-ai/owl Project Manual

Generated at: 2026-06-17 05:28:23 UTC

## Table of Contents

- [Installation & Quick Start Guide](#page-1)
- [OWL Architecture & Core Framework](#page-2)
- [Model Integrations, MCP & Toolkit Configuration](#page-3)
- [Web Interface, Community Use Cases & Contribution](#page-4)

<a id='page-1'></a>

## Installation & Quick Start Guide

### Related Pages

Related topics: [OWL Architecture & Core Framework](#page-2), [Model Integrations, MCP & Toolkit Configuration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/camel-ai/owl/blob/main/README.md)
- [requirements.txt](https://github.com/camel-ai/owl/blob/main/requirements.txt)
- [pyproject.toml](https://github.com/camel-ai/owl/blob/main/pyproject.toml)
- [owl/.env_template](https://github.com/camel-ai/owl/blob/main/owl/.env_template)
- [examples/run.py](https://github.com/camel-ai/owl/blob/main/examples/run.py)
- [.container/Dockerfile](https://github.com/camel-ai/owl/blob/main/.container/Dockerfile)
- [community_usecase/qwen3_mcp/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md)
</details>

# Installation & Quick Start Guide

This page documents how to install OWL, configure its environment, and run a first task. OWL is a multi-agent collaboration framework built on top of the CAMEL-AI framework, designed to push the boundaries of task automation through dynamic agent interactions [Source: [README.md:1-30]()].

## 1. Prerequisites and System Requirements

OWL targets modern Python and Node.js toolchains:

- **Python 3.10, 3.11, or 3.12** is required. Newer Python versions are not yet supported by the bundled CAMEL fork [Source: [README.md:50-70]()].
- **pip** for Python package installation [Source: [README.md:50-70]()]().
- **Node.js + npm** when you plan to use MCP servers such as Playwright or Notion [Source: [community_usecase/qwen3_mcp/README.md:30-60]()]().
- **Git** to clone the repository [Source: [README.md:50-70]()]().

> **Note for GAIA Benchmark Users**: When running the GAIA benchmark evaluation, use the `gaia58.18` branch, which includes a customized CAMEL framework under `owl/camel` with enhanced toolkits tuned for benchmark stability [Source: [README.md:50-70]()]().

## 2. Installation Paths

OWL supports three installation paths. Choose based on your use case.

### 2.1 Local Python Installation (Recommended for Development)

```bash
# 1. Clone the repository
git clone https://github.com/camel-ai/owl
cd owl

# 2. Install Python dependencies
pip install -r requirements.txt
```

Source: [README.md:50-70]() and [requirements.txt:1-30]().

The default `requirements.txt` installs the runtime libraries OWL needs to load toolkits, call model APIs, and orchestrate agents. After installation, verify Python can import the framework:

```bash
python -c "import owl; print('OWL installed successfully')"
```

### 2.2 Containerized Installation (Docker)

A reproducible container build is provided in `.container/Dockerfile`. The container bundles Python, system libraries, and OWL's dependencies so you can run the framework without polluting your host environment [Source: [.container/Dockerfile:1-40]()]().

```bash
docker build -f .container/Dockerfile -t owl:latest .
docker run --rm -it -v $(pwd):/app owl:latest
```

### 2.3 Project Metadata (pyproject.toml)

`pyproject.toml` declares the package version, supported Python range, and tooling configuration. It is the authoritative source for the supported interpreter range and entry points; refer to it whenever you integrate OWL into a larger Python project [Source: [pyproject.toml:1-40]()]().

## 3. Environment Configuration

OWL relies on environment variables to connect to model providers and external services. A template is provided in `owl/.env_template`; copy it to `.env` and fill in only the variables required for your chosen model [Source: [owl/.env_template:1-30]()]().

### Common Configuration Variables

| Variable | Required? | Purpose |
|----------|-----------|---------|
| `OPENAI_API_KEY` | Required when using OpenAI models | Auth for OpenAI / GPT-4 endpoints |
| `QWEN_API_KEY` | Required when using Qwen models | Auth for Alibaba DashScope (Qwen-Plus, Qwen3) |
| `DEEPSEEK_API_KEY` | Optional | Auth for DeepSeek model endpoints |
| Model base URL overrides | Optional | Point to local servers (e.g., Ollama) |
| MCP server config path | Optional | Path to a JSON file describing MCP servers |

> **Community note (Issue #150)**: Several users have reported confusion about which `.env` variables are mandatory. The rule of thumb is: only the API key for the model you actively call is mandatory. All other entries can be left blank.

Source: [community_usecase/qwen3_mcp/README.md:50-90]() and [owl/.env_template:1-30]().

### Connecting to a Local Model (e.g., Ollama)

A frequent question is how to point OWL at a locally hosted model such as Ollama. Configure the relevant base URL and model name in your `.env` (or pass them via the Web UI) so that OWL uses your local server instead of a hosted endpoint [Source: [README.md:50-100]()]().

> **Community note (Issue #2)**: Step-by-step Ollama tutorials are a frequent request. Because OWL delegates model calls to the CAMEL model factory, any provider compatible with the OpenAI-style chat-completions interface can be plugged in by setting the appropriate base URL and API key (any placeholder string usually works for local servers).

## 4. Quick Start: Running Your First Task

OWL exposes three entry points: example scripts, a Gradio Web UI, and CLI entry points.

### 4.1 Run a Python Example

The minimal end-to-end smoke test is `examples/run.py`. It loads a task prompt, constructs an agent society, and prints the final answer [Source: [examples/run.py:1-60]()]():

```bash
python examples/run.py "Search the latest news about multi-agent systems and summarize the top three results."
```

### 4.2 Launch the Web UI

The repository ships localized Gradio web apps. Pick the variant that matches your language [Source: [README.md:90-130]()]():

```bash
python owl/webapp.py      # English
python owl/webapp_zh.py   # Chinese
python owl/webapp_jp.py   # Japanese
```

The Gradio UI lets you select the model provider, manage environment variables interactively, and view the task history — all locally, with no data sent to external servers beyond the model API calls you configure [Source: [README.md:90-130]()]().

> **Community note (Issue #437)**: The `run_mcp` workflow is not yet wired into the Gradio UI. If you need MCP-enabled runs from the GUI, use the CLI scripts such as `run_mcp.py` or the community example `run_mcp_qwen3.py` until GUI integration is completed.

### 4.3 Run a Task with MCP Toolkits

To enable browser or external-tool integration, configure an MCP server file (e.g., `mcp_sse_config.json`) and run:

```bash
python run_mcp_qwen3.py "Your task description"
```

If no task is provided, a default task will be used [Source: [community_usecase/qwen3_mcp/README.md:80-120]()]().

## 5. Security and Best Practices

- **Never commit API keys.** A historical incident (Issue #553) reported a hard-coded key in `video_analysis_toolkit.py` on the `gaia69` branch. Always keep secrets in `.env` and ensure `.env` is in your `.gitignore`.
- **Pin the branch you evaluate.** Use `main` for the latest general-purpose toolkits, or `gaia58.18` / `gaia69` branches when reproducing GAIA benchmark numbers [Source: [README.md:130-160]()]().
- **Start with the Web UI.** It is the fastest way to validate your environment variables and model connectivity before running heavier multi-agent workloads.

## 6. Troubleshooting Common Issues

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| `ModuleNotFoundError: camel` | Python version mismatch | Use Python 3.10–3.12 and reinstall requirements |
| `401 Unauthorized` from model API | Missing or invalid key | Re-check the key in `.env` matches the provider |
| `playwright` MCP server fails to start | Node.js not installed | Install Node.js ≥ 18 and rerun `npx @playwright/mcp@latest` |
| GUI cannot start `run_mcp` | MCP integration not in UI | Use the CLI scripts directly until GUI support lands |
| Local model (Ollama) not answering | Wrong base URL or model name | Set the provider's base URL and model name in `.env` or the Web UI |

## See Also

- [OWL Overview & Architecture](architecture-overview.md)
- [Built-in Toolkits Reference](toolkits-reference.md)
- [MCP Integration Guide](mcp-integration.md)
- [Contributing Guide](contributing.md)

---

<a id='page-2'></a>

## OWL Architecture & Core Framework

### Related Pages

Related topics: [Installation & Quick Start Guide](#page-1), [Model Integrations, MCP & Toolkit Configuration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/camel-ai/owl/blob/main/README.md)
- [community_usecase/OWL Interview Preparation Assistant/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/OWL%20Interview%20Preparation%20Assistant/README.md)
- [community_usecase/qwen3_mcp/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md)
- [community_usecase/Whatsapp-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Whatsapp-MCP/README.md)
- [community_usecase/Notion-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Notion-MCP/README.md)
- [community_usecase/Puppeteer MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Puppeteer%20MCP/README.md)
- [community_usecase/a_share_investment_agent_camel/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/README.md)
- [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bear.py](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/src/agents/researcher_bear.py)
- [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bull.py](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/src/agents/researcher_bull.py)
- [community_usecase/stock-analysis/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/stock-analysis/README.md)
</details>

# OWL Architecture & Core Framework

## Overview and Purpose

**OWL (Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation)** is a multi-agent collaboration framework built on top of the [CAMEL-AI Framework](https://github.com/camel-ai/camel). Its stated vision is to "revolutionize how AI agents collaborate to solve real-world tasks" through dynamic agent interactions [Source: [README.md:1-40](https://github.com/camel-ai/owl/blob/main/README.md)].

OWL ranks **#1 among open-source frameworks** on the GAIA benchmark with an average score of **69.09**, a result that frames the project's positioning as a research-grade but production-ready stack [Source: [README.md:1-40](https://github.com/camel-ai/owl/blob/main/README.md)]. The codebase was open-sourced on 2025-03-07, and the project continues to ship updates through the `main` branch (general improvements) and the `gaia69` branch (GAIA-specific performance) [Source: [README.md:1-40](https://github.com/camel-ai/owl/blob/main/README.md)].

The framework targets end-to-end task automation spanning browsing, document parsing, multimodal analysis, and code execution, exposing them as composable **toolkits** to LLM-powered agents [Source: [README.md:1-80](https://github.com/camel-ai/owl/blob/main/README.md)].

## System Architecture

OWL's runtime is organized around four layers: a **CAMEL-AI agent layer** that orchestrates role-playing and chat-driven collaboration, a **Toolkit Layer** that wraps external capabilities behind a uniform tool interface, an **MCP (Model Context Protocol) Layer** for plugging in remote/local MCP servers, and a **Presentation Layer** that exposes both CLI scripts and Gradio-based web UIs [Source: [README.md:1-120](https://github.com/camel-ai/owl/blob/main/README.md)].

```mermaid
flowchart TB
    subgraph Presentation["Presentation Layer"]
        UI[Gradio Web Apps<br/>webapp.py / webapp_zh.py / webapp_jp.py]
        CLI[CLI Examples<br/>examples/run_*.py]
    end

    subgraph AgentLayer["CAMEL-AI Agent Layer"]
        A1[User / Assistant Agents]
        A2[Role-Playing Society]
    end

    subgraph ToolLayer["Toolkit Layer"]
        T1[BrowserToolkit]
        T2[VideoAnalysisToolkit]
        T3[AudioAnalysisToolkit]
        T4[ImageAnalysisToolkit]
        T5[CodeExecutionToolkit]
        T6[SearchToolkit]
        T7[DocumentToolkit]
    end

    subgraph MCPLayer["MCP Layer"]
        M1[MCPToolkit / mcp_servers_config.json]
        M2[Playwright MCP]
        M3[Notion MCP]
        M4[WhatsApp MCP]
        M5[Puppeteer MCP]
    end

    UI --> A2
    CLI --> A2
    A2 --> A1
    A1 --> T1 & T2 & T3 & T4 & T5 & T6 & T7
    A1 -.optional.-> M1
    M1 --> M2 & M3 & M4 & M5
```

The toolkit surface is intentionally flat: each toolkit exposes a `get_tools()` method (or attribute) that the user concatenates into a `tools` list passed into a CAMEL agent society. A typical configuration block looks like:

```python
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,
]
```
Source: [README.md:80-130](https://github.com/camel-ai/owl/blob/main/README.md)

For MCP integrations, the configuration is loaded from a JSON file and an async connection is established:

```python
from pathlib import Path
from mcp_toolkit import MCPToolkit

config_path = Path(__file__).parent / "mcp_servers_config.json"
mcp_toolkit = MCPToolkit(config_path=str(config_path))
await mcp_toolkit.connect()
```
Source: [community_usecase/Whatsapp-MCP/README.md:1-40](https://github.com/camel-ai/owl/blob/main/community_usecase/Whatsapp-MCP/README.md)

### Community notes on architecture choices

- **Headless vs. visible browser** — Issue #150 requests a dedicated configuration toggle for browser startup. The framework currently accepts `headless=False` in the toolkit constructor [Source: [README.md:80-130](https://github.com/camel-ai/owl/blob/main/README.md)].
- **GUI ↔ MCP integration** — Issue #437 reports that the `run-mcp` command is not wired into the Gradio UI, and that some toolkits (e.g., the file writer) don't run asynchronously with the MCP variant.
- **Secret hygiene** — Issue #553 flagged a hard-coded API key in `video_analysis_toolkit.py` on the `gaia69` branch, underscoring that branch-level copies of toolkits must be audited independently.

## Core Capabilities

OWL ships with a curated set of built-in toolkits that cover the dominant modalities of real-world tasks [Source: [README.md:40-90](https://github.com/camel-ai/owl/blob/main/README.md)]:

| Capability | Toolkit(s) | Notes |
|---|---|---|
| Online search | `SearchToolkit` | Wikipedia, Google, DuckDuckGo, Baidu, Bocha |
| Browser automation | `BrowserToolkit` | Playwright-based scrolling, clicking, input, download |
| Multimodal | `VideoAnalysisToolkit`, `AudioAnalysisToolkit`, `ImageAnalysisToolkit` | Requires a multimodal model; Audio requires OpenAI key |
| Document parsing | `DocumentToolkit` | Word, Excel, PDF, PowerPoint → text/Markdown |
| Code execution | `CodeExecutionToolkit` | Sandbox via `subprocess` |
| MCP bridge | `MCPToolkit` | Reads `mcp_servers_config.json`; supports Playwright, Notion, WhatsApp, Puppeteer |

Source: [README.md:40-130](https://github.com/camel-ai/owl/blob/main/README.md); [community_usecase/qwen3_mcp/README.md:1-60](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md); [community_usecase/Notion-MCP/README.md:1-50](https://github.com/camel-ai/owl/blob/main/community_usecase/Notion-MCP/README.md)

> **Important**: Effective toolkit use requires models with strong tool-calling ability. Multimodal toolkits additionally require a multimodal-capable model [Source: [README.md:100-130](https://github.com/camel-ai/owl/blob/main/README.md)].

## Reference Applications and Community Use Cases

The repository ships a `community_usecase/` directory that demonstrates how OWL's primitives compose into vertical applications.

- **Interview Preparation Assistant** — A multi-agent pipeline that performs company research, generates tailored interview questions, and produces day-by-day prep plans, exposing both a web UI and CLI entrypoints [Source: [community_usecase/OWL Interview Preparation Assistant/README.md:1-80](https://github.com/camel-ai/owl/blob/main/community_usecase/OWL%20Interview%20Preparation%20Assistant/README.md)].
- **Qwen3 + MCP** — Demonstrates OWL with the Qwen-Plus model and MCP servers (EdgeOne Pages, Playwright), with markdown logging and async cleanup [Source: [community_usecase/qwen3_mcp/README.md:1-60](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md)].
- **WhatsApp MCP** — Bridges WhatsApp Web (via a Go-based local store + Python MCP server) into OWL agents for message and media handling [Source: [community_usecase/Whatsapp-MCP/README.md:1-60](https://github.com/camel-ai/owl/blob/main/community_usecase/Whatsapp-MCP/README.md)].
- **Notion MCP** — Connects a Notion workspace through the official `@notionhq/notion-mcp-server` package [Source: [community_usecase/Notion-MCP/README.md:1-50](https://github.com/camel-ai/owl/blob/main/community_usecase/Notion-MCP/README.md)].
- **A-Share Investment Agent** — A 10-agent pipeline (bull researcher, bear researcher, risk manager, portfolio manager, …) producing trade decisions; the bull/bear researcher modules return structured `ResearchReport` objects with `stance`, `key_points`, `confidence`, and per-axis summaries [Source: [community_usecase/a_share_investment_agent_camel/README.md:1-60](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/README.md); [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bear.py](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/src/agents/researcher_bear.py); [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bull.py](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/src/agents/researcher_bull.py)].
- **Puppeteer MCP & Stock Analysis** — Further examples of MCP-driven browsing and quantitative stock workflows [Source: [community_usecase/Puppeteer MCP/README.md:1-60](https://github.com/camel-ai/owl/blob/main/community_usecase/Puppeteer%20MCP/README.md); [community_usecase/stock-analysis/README.md:1-40](https://github.com/camel-ai/owl/blob/main/community_usecase/stock-analysis/README.md)].

## Web UI and Frontend Surfaces

Three localized Gradio applications are shipped in the `owl/` package:

```bash
python owl/webapp_zh.py   # Chinese
python owl/webapp.py      # English
python owl/webapp_jp.py   # Japanese
```
Source: [README.md:1-40](https://github.com/camel-ai/owl/blob/main/README.md)

Features advertised by the web UI include model selection (OpenAI, Qwen, DeepSeek, …), in-UI environment variable management, an interactive chat surface, and task history. All processing happens locally apart from the model API calls the user configures [Source: [README.md:1-40](https://github.com/camel-ai/owl/blob/main/README.md)].

## Deployment and Configuration Notes

- **Node.js prerequisite for MCP** — Required before any MCP-based example; install via the official installer, `apt`, or Homebrew [Source: [README.md:80-130](https://github.com/camel-ai/owl/blob/main/README.md)].
- **Playwright MCP** — Installed via `npm install -g @executeautomation/playwright-mcp-server` followed by `npx playwright install-deps` [Source: [README.md:80-130](https://github.com/camel-ai/owl/blob/main/README.md)].
- **Local Ollama** — Issue #2 (9 comments) is the most upvoted question on the repo and asks specifically how to point OWL at a local Ollama instance; this is currently answered via community guidance rather than first-party docs.
- **Contributing** — Issue #1 asks for beginner-friendly tasks. The `community_usecase/` directory is the most natural entry point for new contributors, since each sub-project is self-contained.

## See Also

- [README.md](https://github.com/camel-ai/owl/blob/main/README.md) — Project overview, news, installation, and citation
- [Examples directory](https://github.com/camel-ai/owl/tree/main/owl) — CLI examples and MCP demos
- [Paper (arXiv 2505.23885)](https://arxiv.org/abs/2505.23885) — Underlying research
- [CAMEL-AI Framework](https://github.com/camel-ai/camel) — Base agent framework

---

<a id='page-3'></a>

## Model Integrations, MCP & Toolkit Configuration

### Related Pages

Related topics: [Installation & Quick Start Guide](#page-1), [OWL Architecture & Core Framework](#page-2), [Web Interface, Community Use Cases & Contribution](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/camel-ai/owl/blob/main/README.md)
- [owl/utils/enhanced_role_playing.py](https://github.com/camel-ai/owl/blob/main/owl/utils/enhanced_role_playing.py)
- [community_usecase/qwen3_mcp/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md)
- [community_usecase/Notion-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Notion-MCP/README.md)
- [community_usecase/Whatsapp-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Whatsapp-MCP/README.md)
- [community_usecase/Puppeteer MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Puppeteer%20MCP/README.md)
</details>

# Model Integrations, MCP & Toolkit Configuration

## Overview

OWL (Optimized Workforce Learning) is built on top of the CAMEL-AI multi-agent framework and exposes a flexible integration surface for large language models, the Model Context Protocol (MCP), and a broad set of domain-specific toolkits. Configuration decisions are made primarily through environment variables (typically loaded from a `.env` file), JSON-based MCP server manifests, and Python-level `tools` lists in the example scripts under `examples/`. The README summarises this breadth: toolkits span ArxivToolkit, AudioAnalysisToolkit, CodeExecutionToolkit, DalleToolkit, DataCommonsToolkit, ExcelToolkit, GitHubToolkit, GoogleMapsToolkit, GoogleScholarToolkit, ImageAnalysisToolkit, MathToolkit, NetworkXToolkit, NotionToolkit, OpenAPIToolkit, RedditToolkit, SearchToolkit, SemanticScholarToolkit, SymPyToolkit, VideoAnalysisToolkit, WeatherToolkit, BrowserToolkit, and an MCP adapter (`README.md:18-22`). Community feedback (e.g. issue #150) repeatedly asks which configuration keys are mandatory and how logging can be simplified, which motivates a clear mental model of these three layers.

## Model Integrations

Model selection in OWL is driven by which model client is constructed inside each `run_*.py` example. The root README enumerates a Web UI selector for OpenAI, Qwen, and DeepSeek models (`README.md:97-105`), and community examples extend this to Claude, Gemini, Groq, Qwen3-Plus, and local backends such as Ollama. For example, the Qwen3 MCP community example instantiates a `Qwen3-Plus` model for both user and assistant roles and configures a `round_limit` parameter that caps the agent conversation depth (`community_usecase/qwen3_mcp/README.md:30-32`). The system prompt scaffold used by every role-playing session lives in `owl/utils/enhanced_role_playing.py` and embeds operating instructions — for example, telling the assistant to think step-by-step like a human, prefer concise search queries that find sources rather than direct answers, and fall back to writing and executing code for Excel-style tasks (`owl/utils/enhanced_role_playing.py:1-30`).

For local model serving, issue #2 ("怎么连接本地ollma") is a recurring question: users must point the model client at a local OpenAI-compatible endpoint (typically `http://localhost:11434/v1`) and supply the appropriate model name string in the `construct_society` call. Because the same prompt scaffold is reused across providers, switching from a hosted model to a local one is a configuration change rather than a code change.

A persistent security reminder comes from issue #553, which reported a hard-coded API key in `video_analysis_toolkit.py` on GAIA branches. Any key referenced from environment variables should never be checked in; OWL relies on `.env` files and the Web UI's environment-variable manager (`README.md:103-105`) to keep secrets out of source.

## Model Context Protocol (MCP)

MCP is OWL's universal protocol layer for tool and data-source integration. The architecture is a thin Python client (`MCPToolkit`) that reads a JSON manifest and spawns one or more MCP servers as child processes, exposing their tools as async callables. The community WhatsApp MCP example shows the canonical wiring (`community_usecase/Whatsapp-MCP/README.md:20-32`):

```python
from pathlib import Path
from mcp_toolkit import MCPToolkit

config_path = Path(__file__).parent / "mcp_servers_config.json"
mcp_toolkit = MCPToolkit(config_path=str(config_path))
await mcp_toolkit.connect()
```

The manifest format is the same across the ecosystem. For Playwright-driven browsing, the qwen3 example uses:

```json
"playwright": {
  "command": "npx",
  "args": ["@playwright/mcp@latest"]
}
```
Source: [community_usecase/qwen3_mcp/README.md:12-18]()

Notion follows the same shape via `@notionhq/notion-mcp-server` (`community_usecase/Notion-MCP/README.md:18-22`), while the Puppeteer and WhatsApp variants swap in their own server entries. The root README also documents two delivery modes: a local-stdio example at `examples/run_mcp.py` and an SSE example at `examples/run_mcp_sse.py` for remote services (`README.md:53-56`).

Issue #437 highlights a real limitation: the Web UI does not yet expose an MCP launcher, and some toolkits (notably the file writer) do not run cleanly in async mode with MCP servers. As a workaround, MCP is normally driven from a CLI script rather than the Gradio UI.

## Toolkit Configuration

Toolkits are composed per-task by combining objects from CAMEL's toolkit namespace. The README shows the canonical pattern (`README.md:67-74`):

```python
tools = [
    *BrowserToolkit(headless=False).get_tools(),
    *VideoAnalysisToolkit(model=models["video"]).get_tools(),
    *AudioAnalysisToolkit().get_tools(),
    *CodeExecutionToolkit(sandbox="subprocess").get_tools(),
    *ImageAnalysisToolkit(model=models["image"]).get_tools(),
    SearchToolkit().search_duckduckgo,
]
```

Three configuration axes matter most:

1. **Headless browser toggle** — issue #150 requests an explicit flag so users can always see the agent driving a browser. The `headless=False` argument already exposes this, and OWL deliberately leaves browser launch decisions to the model by default.
2. **Sandbox mode for code execution** — `CodeExecutionToolkit(sandbox="subprocess")` isolates generated Python; switching to `"internal"` is faster but less safe.
3. **Per-toolkit model binding** — multimodal toolkits (`VideoAnalysisToolkit`, `ImageAnalysisToolkit`) require a model entry in the `models` dict that has vision capability.

```mermaid
flowchart LR
    A[User Prompt] --> B[construct_society]
    B --> C{Model Client}
    C -->|Hosted API| D[OpenAI / Qwen / Claude]
    C -->|Local| E[Ollama / vLLM]
    B --> F[Toolkit List]
    F --> G[BrowserToolkit]
    F --> H[CodeExecutionToolkit]
    F --> I[MCPToolkit]
    I --> J[playwright]
    I --> K[notion]
    I --> L[whatsapp]
    B --> M[run_society]
    M --> N[Answer + Logs]
```

The `models` dictionary and `tools` list are then passed into `construct_society`, which together with `run_society` forms the agent loop documented across every community example. Logs are produced as Markdown files under `conversation_logs/` (Qwen3 MCP variant) and as Gradio chat history in the Web UI, addressing the log-noise concern from issue #150 by giving users two readable views of the same trace.

## See Also

- [examples/run_mcp.py](https://github.com/camel-ai/owl/blob/main/examples/run_mcp.py) — local stdio MCP example
- [examples/run_mcp_sse.py](https://github.com/camel-ai/owl/blob/main/examples/run_mcp_sse.py) — remote SSE MCP example
- [OWL Web UI documentation](https://github.com/camel-ai/owl#starting-the-web-ui) — Gradio launcher details
- [Model Context Protocol specification](https://modelcontextprotocol.io/introduction) — protocol reference
- Community use cases: `community_usecase/qwen3_mcp/`, `community_usecase/Notion-MCP/`, `community_usecase/Whatsapp-MCP/`, `community_usecase/Puppeteer MCP/`

---

<a id='page-4'></a>

## Web Interface, Community Use Cases & Contribution

### Related Pages

Related topics: [Installation & Quick Start Guide](#page-1), [Model Integrations, MCP & Toolkit Configuration](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/camel-ai/owl/blob/main/README.md)
- [owl/webapp.py](https://github.com/camel-ai/owl/blob/main/owl/webapp.py)
- [owl/webapp_zh.py](https://github.com/camel-ai/owl/blob/main/owl/webapp_zh.py)
- [owl/webapp_jp.py](https://github.com/camel-ai/owl/blob/main/owl/webapp_jp.py)
- [owl/webapp_backup.py](https://github.com/camel-ai/owl/blob/main/owl/webapp_backup.py)
- [owl/utils/enhanced_role_playing.py](https://github.com/camel-ai/owl/blob/main/owl/utils/enhanced_role_playing.py)
- [community_usecase/COMMUNITY_CALL_FOR_USE_CASES.md](https://github.com/camel-ai/owl/blob/main/community_usecase/COMMUNITY_CALL_FOR_USE_CASES.md)
- [community_usecase/qwen3_mcp/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/qwen3_mcp/README.md)
- [community_usecase/Notion-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Notion-MCP/README.md)
- [community_usecase/Whatsapp-MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Whatsapp-MCP/README.md)
- [community_usecase/Puppeteer MCP/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/Puppeteer%20MCP/README.md)
- [community_usecase/OWL Interview Preparation Assistant/README.md](https://github.com/camel-ai/owl/blob/main/community_usecase/OWL%20Interview%20Preparation%20Assistant/README.md)
- [community_usecase/PHI_Sanitization_Summarization_and_Article_Writing/readme.md](https://github.com/camel-ai/owl/blob/main/community_usecase/PHI_Sanitization_Summarization_and_Article_Writing/readme.md)
- [community_usecase/a_share_investment_agent_camel/src/models.py](https://github.com/camel-ai/owl/blob/main/community_usecase/a_share_investment_agent_camel/src/models.py)
</details>

# Web Interface, Community Use Cases & Contribution

## Overview

OWL (Optimized Workforce Learning) is a multi-agent collaboration framework built on top of the CAMEL-AI Framework, designed to push the boundaries of automated task solving. Beyond the core agent runtime, the project ships a Gradio-based **Web Interface** for end users and a curated `community_usecase/` directory that hosts integrations, vertical agents, and tutorials contributed by the community. This page documents the three launchers of the Web UI, the structure of community contributions, and the supported paths for new contributors — directly addressing several of the most-asked questions in the issue tracker (configuration clarity, browser control, local model support, and MCP integration). Source: [README.md:1-200]()

## 1. Web Interface (Gradio Launchers)

OWL ships three parallel Gradio applications so users can run the UI in their preferred language. The English, Chinese, and Japanese variants share the same feature surface but localize all UI strings. Source: [README.md:1-200]()

### 1.1 Launching the UI

The three launchers are invoked identically — only the file name changes. Source: [README.md:1-200]()

| Command | Locale | Source |
| --- | --- | --- |
| `python owl/webapp.py` | English | [owl/webapp.py]() |
| `python owl/webapp_zh.py` | Simplified Chinese | [owl/webapp_zh.py]() |
| `python owl/webapp_jp.py` | Japanese | [owl/webapp_jp.py]() |
| `python owl/webapp_backup.py` | Legacy backup (fallback) | [owl/webapp_backup.py]() |

### 1.2 Features Exposed in the Web UI

According to the project README, the Gradio surface provides: Source: [README.md:1-200]()

- **Model selection** — switch between OpenAI, Qwen, DeepSeek, and other providers.
- **Environment variable management** — configure API keys and other settings directly in the UI, removing the need to edit `.env` by hand.
- **Interactive chat** — submit tasks to the OWL agent society and stream responses.
- **Task history** — review prior runs and their results.

A known limitation, surfaced in community discussion (issue #437), is that **the `run-mcp` command is not yet integrated in the GUI**, and ad-hoc integration attempts have shown asynchronous incompatibilities between the MCP toolkit and certain toolkits (e.g., the file writer toolkit). Users wanting MCP today must run the Python entry points directly rather than rely on the Web UI. Source: [README.md:1-200]()

### 1.3 Browser Control & Log Verbosity (Issue #150)

The README and issue #150 clarify two recurring configuration questions:

- The decision to launch a browser is made **autonomously by the model**, not by a configuration flag. Users who want to force-enable the browser should rely on the `BrowserToolkit` and the underlying `enhanced_role_playing` orchestration. Source: [owl/utils/enhanced_role_playing.py:1-50]()
- Logs are intentionally verbose because the OWL society produces many intermediate steps (search, browse, code execution, etc.). The `conversation_logs/` directory in the Qwen3-MCP example captures full per-step markdown logs for later review. Source: [community_usecase/qwen3_mcp/README.md:1-100]()

```mermaid
flowchart LR
    A[User opens webapp.py] --> B[Select model + enter API key]
    B --> C[Submit task prompt]
    C --> D[enhanced_role_playing constructs society]
    D --> E[Assistant agent invokes toolkits]
    E --> F[Verbose logs + chat history]
    F --> G[Result streamed back to Gradio]
```

## 2. Community Use Cases

The `community_usecase/` directory is the official landing pad for community contributions. The `COMMUNITY_CALL_FOR_USE_CASES.md` file defines the expectations, and a growing list of sub-projects demonstrates the breadth of what OWL enables. Source: [community_usecase/COMMUNITY_CALL_FOR_USE_CASES.md]() Source: [README.md:1-200]()

### 2.1 MCP Server Integrations

| Sub-project | What it adds | Source |
| --- | --- | --- |
| **qwen3_mcp** | Qwen3-Plus model + Playwright MCP + EdgeOne Pages MCP, with auto-generated markdown conversation logs. | [community_usecase/qwen3_mcp/README.md]() |
| **Notion-MCP** | Wraps the official `@notionhq/notion-mcp-server` so OWL agents can read/write Notion pages. | [community_usecase/Notion-MCP/README.md]() |
| **Whatsapp-MCP** | Uses a Go WhatsApp bridge + Python MCP server for searching, reading, and sending WhatsApp messages. | [community_usecase/Whatsapp-MCP/README.md]() |
| **Puppeteer MCP** | Streamlit-based demo that drives a Puppeteer MCP server for browser automation. | [community_usecase/Puppeteer%20MCP/README.md]() |

### 2.2 Vertical / Domain Agents

- **OWL Interview Preparation Assistant** — a multi-agent pipeline with three functions: `research_company`, `generate_interview_questions`, and `create_interview_prep_plan`, exposed both through a Gradio UI and a CLI. Source: [community_usecase/OWL Interview Preparation Assistant/README.md]()
- **PHI Sanitization, Summarization and Article Writing** — a Streamlit app for healthcare-style data de-identification, summarization, and article drafting. Source: [community_usecase/PHI_Sanitization_Summarization_and_Article_Writing/readme.md]()
- **a_share_investment_agent_camel** — an A-share investment research pipeline with bull (`researcher_bull.py`) and bear (`researcher_bear.py`) researchers that emit structured `ResearchReport` Pydantic models containing `stance`, `key_points`, `confidence`, and per-dimension summaries. Source: [community_usecase/a_share_investment_agent_camel/src/models.py]() Source: [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bull.py]() Source: [community_usecase/a_share_investment_agent_camel/src/agents/researcher_bear.py]()

## 3. Contributing to the Project

Issue #1 in the repository is the canonical "how do I contribute?" thread. The README and `COMMUNITY_CALL_FOR_USE_CASES.md` outline three well-defined paths so newcomers can start small. Source: [README.md:1-200]()

1. **Beginner-friendly tasks** — pick an open issue labeled `good first issue`, run the Gradio UI locally, and triage bugs. The `webapp_backup.py` file is a safe target for cleanup patches because it is the legacy fallback. Source: [owl/webapp_backup.py]()
2. **Community use case** — add a self-contained sub-directory under `community_usecase/` following the conventions in `COMMUNITY_CALL_FOR_USE_CASES.md`. Each submission should ship its own `README.md`, `requirements.txt`, and (where applicable) MCP config. Source: [community_usecase/COMMUNITY_CALL_FOR_USE_CASES.md]()
3. **Core framework work** — improvements to the role-playing loop in `owl/utils/enhanced_role_playing.py` (e.g., refining the assistant system prompt, adding new toolkit integrations, or fixing async issues such as the MCP+file-writer incompatibility raised in issue #437). Source: [owl/utils/enhanced_role_playing.py:1-50]()

### 3.1 Security Reminder (Issue #553)

A high-priority community report (#553) flagged a hard-coded API key in `video_analysis_toolkit.py` on the `gaia69` and `gaia69_vllm` branches. Contributors must scan their patches for embedded secrets before opening a pull request, and reviewers should rotate any key that has already been exposed. Source: [README.md:1-200]()

### 3.2 Local Model Support (Issue #2)

Although OWL does not ship a first-party tutorial, the Web UI's model selector accepts any OpenAI-compatible endpoint. To connect a **local Ollama** instance, point the base URL to `http://localhost:11434/v1` and supply a dummy API key in the Gradio "Environment Variable Management" panel. This is the same pattern used in the Qwen3-MCP example, where `QWEN_API_KEY` is set via `.env` and consumed by `run_mcp_qwen3.py`. Source: [community_usecase/qwen3_mcp/README.md:1-100]() Source: [README.md:1-200]()

## See Also

- Getting Started & Installation — main README installation prerequisites and GAIA benchmark notes.
- Toolkits Overview — built-in toolkits referenced by `enhanced_role_playing.py`.
- GAIA Benchmark & Experiments — reproducing the 69.09 GAIA score via `run_gaia_workforce_claude.py` on the `gaia69` branch.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: camel-ai/owl

Summary: Found 18 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Runtime risk - Runtime risk requires verification.

## 1. Runtime risk - Runtime risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/615

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/613

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/608

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/610

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/611

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/612

## 7. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/camel-ai/owl

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/596

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/camel-ai/owl

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/camel-ai/owl

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/camel-ai/owl

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/595

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/600

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/603

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/602

## 16. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/camel-ai/owl/issues/609

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/camel-ai/owl

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/camel-ai/owl

<!-- canonical_name: camel-ai/owl; human_manual_source: deepwiki_human_wiki -->