đ« CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
Auto-update documentation after merge
camel-docs-bot75ebaa838852
diff --git a/docs/get_started/installation.md b/docs/get_started/installation.mdindex 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 repositorygit clone https://github.com/camel-ai/camel.git--# Change directory into project directorycd camel-# Install uv if you don't have it already+# Install UV package managerpip install uv-# Create a virtual environment and install dependencies-# We support using Python 3.10, 3.11, 3.12+# Create virtual environmentuv 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 dependenciesuv 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.mdnew file mode 100644index 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.mdindex 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)