Skip to content

armgit / camel

Public Imported from GitHub
0

đŸ« CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

Auto-update documentation after merge

camel-docs-bot75ebaa838852
diff --git a/docs/get_started/installation.md b/docs/get_started/installation.md
index 80c1cf594..34bce638b 100644
--- a/docs/get_started/installation.md
+++ b/docs/get_started/installation.md
@@ -1,201 +1,289 @@
-đŸ« **Welcome to CAMEL!** đŸ«
-
-## Installation
-
-### 1. From PyPI
-
-To install the base CAMEL library:
-```bash
-pip install camel-ai
-```
-
-> **Note**: Some features may not work without their required dependencies. Install `camel-ai[all]` to ensure all dependencies are available, or install specific extras based on the features you need.
-
-```bash
-pip install 'camel-ai[all]' # Replace with options below
-```
-
-Available extras:
-- `all`: Includes all features below
-- `model_platforms`: OpenAI, Google, Mistral, Anthropic Claude, Cohere etc.
-- `huggingface`: Transformers, Diffusers, Accelerate, Datasets, PyTorch etc.
-- `rag`: Sentence Transformers, Qdrant, Milvus, TiDB, BM25,OceanBase, Weaviate etc.
-- `storage`: Neo4j, Redis, Azure Blob, Google Cloud Storage, AWS S3 etc.
-- `web_tools`: DuckDuckGo, Wikipedia, WolframAlpha, Google Maps, Weather API etc.
-- `document_tools`: PDF, Word, OpenAPI, BeautifulSoup, Unstructured etc.
-- `media_tools`: Image Processing, Audio Processing, YouTube Download, FFmpeg etc.
-- `communication_tools`: Slack, Discord, Telegram, GitHub, Reddit, Notion etc.
-- `data_tools`: Pandas, TextBlob, DataCommons, OpenBB, Stripe etc.
-- `research_tools`: arXiv, Google Scholar etc.
-- `dev_tools`: Docker, Jupyter, Tree-sitter, Code Interpreter etc.
-
-Multiple extras can be combined using commas:
-```bash
-pip install 'camel-ai[rag,web_tools,document_tools]' # Example: RAG system with web search and document processing
-```
-
-### 2. From Docker
-
-Detailed guidance can be find [here](https://github.com/camel-ai/camel/blob/master/.container/README.md)
-
-
-By default, the agent uses the `ModelType.DEFAULT` model from the `ModelPlatformType.DEFAULT`. You can configure the default model platform and model type using environment variables. If these are not set, the agent will fall back to the default settings:
-
-```bash
-ModelPlatformType.DEFAULT = "openai"
-ModelType.DEFAULT = "gpt-4o-mini"
-```
-
-### 3. From Source with uv
+---
+title: Installation
+description: Get started with CAMEL-AI - Install, configure, and build your first multi-agent system
+icon: wrench
+---
+
+## Tutorial
+<Note>
+ **Python Version Requirements**
+
+ CAMEL-AI requires `Python >=3.10 and <=3.12`. Here's how to check your version:
+ ```bash
+ python3 --version
+ ```
+
+ If you need to update Python, visit [python.org/downloads](https://python.org/downloads)
+</Note>
+
+CAMEL-AI supports multiple installation methods to suit different development workflows. Choose the method that best fits your needs.
+
+<Steps>
+ <Step title="Install CAMEL-AI đŸȘ">
+ - **Basic Installation:**
+
+ Install the core CAMEL library:
+
+ ```shell
+ pip install camel-ai
+ ```
+
+ - **Full Installation (Recommended):**
+
+ Install CAMEL with all features and dependencies:
+
+ ```shell
+ pip install 'camel-ai[all]'
+ ```
+
+ <Note>
+ Some features may not work without their required dependencies. Install `camel-ai[all]` to ensure all dependencies are available, or install specific extras based on the features you need.
+ </Note>
+
+ - **Custom Installation:**
+
+ Available extras for specific use cases:
+ - `all`: Includes all features below
+ - `model_platforms`: OpenAI, Google, Mistral, Anthropic Claude, Cohere etc.
+ - `huggingface`: Transformers, Diffusers, Accelerate, Datasets, PyTorch etc.
+ - `rag`: Sentence Transformers, Qdrant, Milvus, TiDB, BM25, OceanBase, Weaviate etc.
+ - `storage`: Neo4j, Redis, Azure Blob, Google Cloud Storage, AWS S3 etc.
+ - `web_tools`: DuckDuckGo, Wikipedia, WolframAlpha, Google Maps, Weather API etc.
+ - `document_tools`: PDF, Word, OpenAPI, BeautifulSoup, Unstructured etc.
+ - `media_tools`: Image Processing, Audio Processing, YouTube Download, FFmpeg etc.
+ - `communication_tools`: Slack, Discord, Telegram, GitHub, Reddit, Notion etc.
+ - `data_tools`: Pandas, TextBlob, DataCommons, OpenBB, Stripe etc.
+ - `research_tools`: arXiv, Google Scholar etc.
+ - `dev_tools`: Docker, Jupyter, Tree-sitter, Code Interpreter etc.
+
+ Multiple extras can be combined:
+ ```shell
+ pip install 'camel-ai[rag,web_tools,document_tools]' # Example: RAG system with web search and document processing
+ ```
+
+ - To verify that `camel-ai` is installed, run:
+ ```shell
+ pip show camel-ai
+ ```
+
+ <Check>Installation successful! You're ready to create your first multi-agent system! 🎉</Check>
+ </Step>
+</Steps>
+
+# Creating a CAMEL-AI Project
+
+We recommend starting with a simple role-playing scenario to understand CAMEL's multi-agent capabilities. Here's how to get started:
+
+<Steps>
+ <Step title="Set Up Your Project Structure">
+ - Create a new project directory:
+ ```shell
+ mkdir my_camel_project
+ cd my_camel_project
+ ```
+ </Step>
+
+ <Step title="Configure Your Environment">
+ - Create a `.env` file with your API keys:
+ ```bash
+ OPENAI_API_KEY=<your_openai_api_key>
+ OPENAI_API_BASE_URL=<your_openai_base_url> # Optional: for proxy services
+ ANTHROPIC_API_KEY=<your_anthropic_api_key>
+ GOOGLE_API_KEY=<your_google_api_key>
+ ```
+
+ - Create a `requirements.txt` file:
+ ```txt
+ camel-ai[all]
+ python-dotenv
+ ```
+ </Step>
+
+ <Step title="Install Dependencies and Run">
+ - Install project dependencies:
+ ```bash
+ pip install -r requirements.txt
+ ```
+
+ - Set up your environment variables by loading the `.env` file:
+ ```python
+ from dotenv import load_dotenv
+ load_dotenv()
+ ```
+
+ - Run your first multi-agent example:
+ ```bash
+ python examples/role_playing.py
+ ```
+
+
+<Tip>
+Want to see multi-agent collaboration at scale?
+Try running the <a href="https://github.com/camel-ai/camel/tree/master/examples/workforce" target="_blank">workforce example</a>:
+
+<code>python examples/workforce/multiple_single_agents.py</code>
+</Tip>
+ </Step>
+</Steps>
+
+## Alternative Installation Methods
+
+<Note type="info">
+CAMEL-AI offers multiple installation approaches for different development needs:
+
+### From Docker
+- Containerized deployment with pre-configured environment
+- Detailed guidance available at [CAMEL Docker Guide](https://github.com/camel-ai/camel/blob/master/.container/README.md)
+
+### From Source with UV
+- Development installation with full source access
+- Supports Python 3.10, 3.11, 3.12
+- Includes development tools and testing capabilities
```bash
-# Clone github repo
+# Clone the repository
git clone https://github.com/camel-ai/camel.git
-
-# Change directory into project directory
cd camel
-# Install uv if you don't have it already
+# Install UV package manager
pip install uv
-# Create a virtual environment and install dependencies
-# We support using Python 3.10, 3.11, 3.12
+# Create virtual environment
uv venv .venv --python=3.10
-# Activate the virtual environment
-# For macOS/Linux
+# Activate environment (macOS/Linux)
source .venv/bin/activate
-# For Windows
-.venv\Scripts\activate
+# For Windows: .venv\Scripts\activate
# Install CAMEL with all dependencies
uv pip install -e ".[all, dev, docs]"
-
-# For developers: Install pre-commit hooks and mypy
-uv pip install pre-commit mypy
-pre-commit install
-
-# Exit the virtual environment when done
-deactivate
-```
-
-### 4. Running Tests
-
-To run tests, make sure you have activated the virtual environment first:
-
-```bash
-# Activate the virtual environment
-# For macOS/Linux
-source .venv/bin/activate
-# For Windows
-.venv\Scripts\activate
-
-# Run tests
-pytest --fast-test-mode test/
-
-# Run specific tests
-pytest -v apps/
-pytest -v examples/
-
-# Exit the virtual environment when done
-deactivate
-```
-
-### 5. Setting Default Model Platform and Model Type (Optional)
-
-You can customize the default model platform and model type by setting the following environment variables:
-```bash
-export DEFAULT_MODEL_PLATFORM_TYPE=<your preferred platform> # e.g., openai, anthropic, etc.
-export DEFAULT_MODEL_TYPE=<your preferred model> # e.g., gpt-3.5-turbo, gpt-4o-mini, etc.
```
-### 6. Setting Your Model API Key (Using OpenAI as an Example)
-
-**For Bash shell (Linux, macOS, Git Bash on Windows):**
+<Card title="Explore Development Setup" icon="code" href="https://github.com/camel-ai/camel">
+ Learn about contributing to CAMEL-AI and development best practices
+</Card>
+</Note>
+
+## Configuration Options
+
+<Steps>
+ <Step title="Set Default Model Configuration">
+ Configure default model platform and type using environment variables:
+ ```bash
+ export DEFAULT_MODEL_PLATFORM_TYPE=openai # e.g., openai, anthropic, etc.
+ export DEFAULT_MODEL_TYPE=gpt-4o-mini # e.g., gpt-3.5-turbo, gpt-4o-mini, etc.
+ ```
+
+ By default, CAMEL uses:
+ ```bash
+ ModelPlatformType.DEFAULT = "openai"
+ ModelType.DEFAULT = "gpt-4o-mini"
+ ```
+ </Step>
+
+ <Step title="Set Up API Keys">
+ **For Bash shell (Linux, macOS, Git Bash on Windows):**
+ ```bash
+ export OPENAI_API_KEY=<insert your OpenAI API key>
+ export OPENAI_API_BASE_URL=<insert your OpenAI API BASE URL> # Optional
+ ```
+
+ **For Windows Command Prompt:**
+ ```cmd
+ set OPENAI_API_KEY=<insert your OpenAI API key>
+ set OPENAI_API_BASE_URL=<insert your OpenAI API BASE URL>
+ ```
+
+ **For Windows PowerShell:**
+ ```powershell
+ $env:OPENAI_API_KEY="<insert your OpenAI API key>"
+ $env:OPENAI_API_BASE_URL="<insert your OpenAI API BASE URL>"
+ ```
+
+ **Using .env File (Recommended):**
+ ```bash
+ OPENAI_API_KEY=<fill your API KEY here>
+ ANTHROPIC_API_KEY=<fill your Anthropic API KEY here>
+ GOOGLE_API_KEY=<fill your Google API KEY here>
+ ```
+
+ Load in Python:
+ ```python
+ from dotenv import load_dotenv
+ load_dotenv() # Use load_dotenv(override=True) to overwrite existing variables
+ ```
+ </Step>
+</Steps>
+
+## Running Examples
+
+After setting up your API keys, explore CAMEL's capabilities:
```bash
-# Export your OpenAI API key
-export OPENAI_API_KEY=<insert your OpenAI API key>
-OPENAI_API_BASE_URL=<inert your OpenAI API BASE URL> #(Should you utilize an OpenAI proxy service, kindly specify this)
-```
+# Two agents role-playing and collaborating
+python examples/ai_society/role_playing.py
-**For Windows Command Prompt:**
+# Agent utilizing code execution tools
+python examples/toolkits/code_execution_toolkit.py
-```cmd
-REM export your OpenAI API key
-set OPENAI_API_KEY=<insert your OpenAI API key>
-set OPENAI_API_BASE_URL=<inert your OpenAI API BASE URL> #(Should you utilize an OpenAI proxy service, kindly specify this)
-```
+# Generating knowledge graphs with agents
+python examples/knowledge_graph/knowledge_graph_agent_example.py
-**For Windows PowerShell:**
+# Multiple agents collaborating on complex tasks
+python examples/workforce/multiple_single_agents.py
-```powershell
-# Export your OpenAI API key
-$env:OPENAI_API_KEY="<insert your OpenAI API key>"
-$env:OPENAI_API_BASE_URL="<inert your OpenAI API BASE URL>" #(Should you utilize an OpenAI proxy service, kindly specify this)
+# Creative image generation with agents
+python examples/vision/image_crafting.py
```
-Replace `<insert your OpenAI API key>` with your actual OpenAI API key in each case.
-
+## Testing Your Installation
-Please note that the environment variable is session-specific. If you open a new terminal window or tab, you will need to set the API key again in that new session.
-
-**For `.env` File:**
-
-To simplify the process of managing API Keys, you can use store information in a `.env` file and load them into your application dynamically.
-
-1. Modify .env file in the root directory of CAMEL and fill the following lines:
+Run the test suite to ensure everything is working:
```bash
-OPENAI_API_KEY=<fill your API KEY here>
-```
-
-Replace `<fill your API KEY here>` with your actual API key.
-
-2. Load the .env file in your Python script: Use the load_dotenv() function from the dotenv module to load the variables from the .env file into the environment. Here's an example:
-
-```python
-from dotenv import load_dotenv
-import os
-
-# Load environment variables from the .env file
-load_dotenv()
-```
-For more details about the key names in project and how to apply key,
-you can refer to [here](./setup.md).
+# Activate virtual environment first
+source .venv/bin/activate # macOS/Linux
+# .venv\Scripts\activate # Windows
-> [!TIP]
-> By default, the load_dotenv() function does not overwrite existing environment variables that are already set in your system. It only populates variables that are missing.
-If you need to overwrite existing environment variables with the values from your `.env` file, use the `override=True` parameter:
-> ```python
-> load_dotenv(override=True)
-> ```
-
-After setting the OpenAI API key, you can run the `role_playing.py` script. Find tasks for various assistant-user roles [here](https://drive.google.com/file/d/194PPaSTBR07m-PzjS-Ty6KlPLdFIPQDd/view?usp=share_link).
+# Run all tests
+pytest --fast-test-mode test/
-```bash
-# You can change the role pair and initial prompt in role_playing.py
-python examples/ai_society/role_playing.py
+# Run specific test categories
+pytest -v apps/
+pytest -v examples/
```
-Also feel free to run any scripts below that interest you:
-
-```bash
-# You can change the role pair and initial prompt in these python files
-
-# Examples of two agents role-playing
-python examples/ai_society/role_playing.py
-
-# The agent answers questions by utilizing code execution tools.
-python examples/toolkits/code_execution_toolkit.py
-
-# Generating a knowledge graph with an agent
-python examples/knowledge_graph/knowledge_graph_agent_example.py
-
-# Multiple agents collaborating to decompose and solve tasks
-python examples/workforce/multiple_single_agents.py
-
-# Use agent to generate creative image
-python examples/vision/image_crafting.py
-```
-For additional feature examples, see the [`examples`](https://github.com/camel-ai/camel/tree/master/examples) directory.
+## Next Steps
+
+<CardGroup cols={2}>
+ <Card
+ title="Build Your First Agent"
+ icon="users"
+ href="/basic_concepts/create_your_first_agent"
+ >
+ Follow our quickstart guide to create role-playing agents and see CAMEL in action.
+ </Card>
+ <Card
+ title="Explore Advanced Features & Cookbooks"
+ icon="bookmark"
+ href="/cookbooks/"
+ >
+ Discover RAG systems, tool integration, and complex multi-agent cookbooks.
+ </Card>
+ <Card
+ title="Join the Community"
+ icon="comments"
+ href="discord.camel-ai.org"
+ >
+ Connect with other developers, contribute, and share your CAMEL experiences.
+ </Card>
+ <Card
+ title="API Documentation"
+ icon="book"
+ href="/reference"
+ >
+ Dive deep into CAMEL's API and advanced configuration options.
+ </Card>
+</CardGroup>
+
+For additional feature examples and use cases, explore the [`examples`](https://github.com/camel-ai/camel/tree/master/examples) directory in the CAMEL repository.
diff --git a/docs/get_started/introduction.md b/docs/get_started/introduction.md
new file mode 100644
index 000000000..a7ce2ed33
--- /dev/null
+++ b/docs/get_started/introduction.md
@@ -0,0 +1,65 @@
+---
+title: "Introduction"
+icon: rocket
+description: |
+ CAMEL-AI is an open-source community for finding the scaling laws of agents for data generation, world simulation, and task automation.
+---
+
+## What is CAMEL-AI?
+
+**CAMEL‑AI is an open‑source, modular framework for building intelligent multi‑agent systems.** It provides the primitives to:
+
+- Create **Agents** that reason, plan, and act
+- Compose **Societies** of agents with defined roles
+- Integrate **Interpreters** for code execution and analysis
+- Manage **Memory** for long‑horizon context and learning
+- Orchestrate **Retrieval‑Augmented Generation (RAG)** pipelines
+- Generate **Synthetic Data** at scale with self‑instruct and verifier loops
+- Simulate **Worlds** and agent interactions in environments like social networks
+
+## Core Components
+
+- **Agents**: Atomic reasoning units driven by LLMs, capable of tool calls and decision‑making
+- **Societies**: Coordinator layers that assign roles, delegate tasks, and manage collaboration
+- **Interpreters**: Execution backends (Python, shell, browsers) for live code evaluation and automation
+- **Memory & Storage**: Persistent context layers for chat history, tool outputs, and learned knowledge
+- **RAG Pipelines**: Combine chunking, retrieval, and generation for grounded, accurate responses
+- **Synthetic Data Engines**: Self‑instruct, Chain‑of‑Thought, and Source2Synth pipelines with verifiers
+- **World Simulation**: Platforms like Oasis for large‑scale multi‑agent social simulations
+- **Task Automation**: Benchmarks like CRAB for real‑world multi‑step software workflows
+
+## Ecosystem Highlights
+
+<CardGroup cols={2}>
+ <Card title="OASIS" icon="globe" href="https://oasis.camel-ai.org">
+ Large‑scale social simulation environment: model Reddit, Twitter, and user interactions
+ </Card>
+
+ <Card title="CRAB Benchmark" icon="crab" href="https://crab.camel-ai.org">
+ Cross‑environment agent automation tasks across Ubuntu and Android platforms
+ </Card>
+
+ <Card title="Project Loong" icon="dragon" href="/cookbooks/loong/">
+ Verifier‑driven synthetic data generation for domain‑specific QA at scale
+ </Card>
+
+ <Card title="Agentic RAG Bots" icon="comments" href="/cookbooks/applications/customer_service_Discord_bot_with_agentic_RAG">
+ Real‑world retrieval agents for Discord, support, and knowledge applications
+ </Card>
+</CardGroup>
+
+## Ready to Get Started?
+
+<CardGroup cols={3}>
+ <Card title="Quickstart" icon="bolt" href="/cookbooks/basic_concepts/create_your_first_agent">
+ Spin up your first agent in under 5 minutes
+ </Card>
+
+ <Card title="Installation" icon="wrench" href="/get_started/installation">
+ pip install camel-ai[all] – all toolkits and interpreters included
+ </Card>
+
+ <Card title="Explore Cookbooks" icon="book-open" href="/cookbooks/">
+ Hands‑on examples: data gen, RAG, simulations, and more
+ </Card>
+</CardGroup>
diff --git a/docs/get_started/setup.md b/docs/get_started/setup.md
index 62b7b574b..23c79d79b 100644
--- a/docs/get_started/setup.md
+++ b/docs/get_started/setup.md
@@ -1,63 +1,55 @@
-# API Setup
-Our agents can be deployed with either OpenAI API or your local models.
-
-## [Option 1] Using OpenAI API
-Accessing the OpenAI API requires the API key, which you could get from [here](https://platform.openai.com/account/api-keys). We here provide instructions for different OS.
-
-### Unix-like System (Linux / MacOS)
-```bash
-echo 'export OPENAI_API_KEY="your_api_key"' >> ~/.zshrc
-
-# # If you are using other proxy services like Azure [TODO]
-# echo 'export OPENAI_API_BASE_URL="your_base_url"' >> ~/.zshrc # (Optional)
-
-# Let the change take place
-source ~/.zshrc
-```
-
-Replace `~/.zshrc` with `~/.bashrc` if you are using bash.
-
-### Windows
-If you are using Command Prompt:
-```bash
-set OPENAI_API_KEY="your_api_key"
-
-# If you are using other proxy services
-# set OPENAI_API_BASE_URL="your_base_url" # (Optional)
-```
-Or if you are using PowerShell:
-```powershell
-$env:OPENAI_API_KEY="your_api_key"
-
-# If you are using other proxy services
-$env:OPENAI_API_BASE_URL="your_base_url" # (Optional)
-```
-These commands on Windows will set the environment variable for the duration of that particular Command Prompt or PowerShell session only. You may use `setx` or change the system properties dialog for the change to take place in all the new sessions.
-
-### General method
-
-Create a file named `.env` in your project directory, with the following setting.
-
-```bash
-OPENAI_API_KEY=<your-openai-api-key>
-```
-
-Then, load the environment variables in your python script:
-
-```python
-from dotenv import load_dotenv
-import os
-
-load_dotenv()
-
-OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
-```
-
-
-## [Option 2] Using other APIs
-
-If you are using other APIs that are not provided by OpenAI, you can refer to [Models/Using Models by API calling](../key_modules/models.md#using-models-by-api-calling)
-
-## [Option 3] Using Local Models
-If you are using local models, you can refer to [Models/Using Local Models](../key_modules/models.md#using-on-device-open-source-models)
-
+---
+title: "Setup"
+icon: gear
+description: "Configure API credentials and select a model provider"
+---
+
+CAMEL-AI supports multiple model backends. Choose one below and configure your environment variables.
+
+## 1. OpenAI API
+
+Obtain your `OPENAI_API_KEY` from [OpenAI Dashboard](https://platform.openai.com/account/api-keys).
+
+<Steps>
+ <Step title="Unix (macOS/Linux)">
+ ```bash
+ echo 'export OPENAI_API_KEY="<YOUR_KEY>"' >> ~/.zshrc
+ source ~/.zshrc
+ ```
+ _Replace `~/.zshrc` with `~/.bashrc` if using bash._
+ </Step>
+ <Step title="Windows (Permanent)">
+ ```powershell
+ setx OPENAI_API_KEY "<YOUR_KEY>" /M
+ ```
+ _You may need to restart your terminal for changes to apply._
+ </Step>
+ <Step title=".env File (Project-specific)">
+ Create a `.env` file in your project root:
+ ```dotenv
+ OPENAI_API_KEY=<YOUR_KEY>
+ ```
+ Load in Python:
+ ```python
+ from dotenv import load_dotenv
+ load_dotenv()
+ import os
+ print(os.getenv("OPENAI_API_KEY"))
+ ```
+ </Step>
+</Steps>
+
+<Note>
+ To configure an `API_BASE_URL` (e.g., Azure), also set:
+ ```bash
+ export OPENAI_API_BASE_URL="<YOUR_BASE_URL>"
+ ```
+</Note>
+
+## 2. Other Hosted APIs
+
+For non-OpenAI providers, see [Using Models by API Calling](../key_modules/models).
+
+## 3. Local Models
+
+To run fully on-device with open-source models, refer to [Local Models Guide](../key_modules/models)