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

docs: Update get_started section (#2630)

Sarthak Bhardwajd8706c12aefc
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 1b06f3dc0..5e69eecb5 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -24,45 +24,75 @@ jobs:
with:
python-version: "3.10"
+ # Determine the commit to diff against so we only process changed docs
+ - name: Determine BASE_SHA for diff
+ id: diff
+ run: |
+ if git rev-parse --verify -q HEAD^1 >/dev/null; then
+ echo "BASE_SHA=$(git rev-parse HEAD^1)" >> $GITHUB_OUTPUT
+ else
+ echo "BASE_SHA=${{ github.event.before }}" >> $GITHUB_OUTPUT
+ fi
+
- name: Install Pandoc
run: sudo apt-get install -y pandoc
- name: Convert Cookbooks and Update Mintlify Config
run: |
source .venv/bin/activate
- echo "Manual workflow - processing all cookbooks files"
-
+ BASE_SHA="${{ steps.diff.outputs.BASE_SHA }}"
+ echo "Incremental mode - processing changed cookbooks files since $BASE_SHA"
+
python docs/mintlify/convert_notebook2mdx.py \
--input docs/cookbooks \
--output docs/mintlify \
--update-docs-json docs/mintlify/docs.json \
--docs-path-prefix "" \
+ --incremental --use-git --base-branch "$BASE_SHA" \
--verbose
- name: Convert Get Started docs
run: |
source .venv/bin/activate
- echo "Manual workflow - processing all get_started files"
+ BASE_SHA="${{ steps.diff.outputs.BASE_SHA }}"
+ echo "Incremental mode - processing changed get_started files since $BASE_SHA"
python docs/mintlify/convert_notebook2mdx.py \
--input docs/get_started \
--output docs/mintlify \
--update-docs-json docs/mintlify/docs.json \
--docs-path-prefix "" \
+ --incremental --use-git --base-branch "$BASE_SHA" \
--verbose
- name: Convert Key Modules docs
run: |
source .venv/bin/activate
-
- echo "Manual workflow - processing all key_modules files"
+ BASE_SHA="${{ steps.diff.outputs.BASE_SHA }}"
+ echo "Incremental mode - processing changed key_modules files since $BASE_SHA"
+
python docs/mintlify/convert_notebook2mdx.py \
--input docs/key_modules \
--output docs/mintlify \
--update-docs-json docs/mintlify/docs.json \
--docs-path-prefix "" \
+ --incremental --use-git --base-branch "$BASE_SHA" \
+ --verbose
+
+ - name: Sync modified MDX files back to source docs
+ run: |
+ source .venv/bin/activate
+ BASE_SHA="${{ steps.diff.outputs.BASE_SHA }}"
+ echo "Reverse sync - processing changed MDX files since $BASE_SHA"
+
+ python docs/mintlify/convert_notebook2mdx.py \
+ --input docs/mintlify \
+ --output docs/mintlify \
+ --update-docs-json docs/mintlify/docs.json \
+ --docs-path-prefix "" \
+ --incremental --use-git --base-branch "$BASE_SHA" \
--verbose
-
+
- name: Generate API Documentation
run: |
source .venv/bin/activate
@@ -82,6 +112,7 @@ jobs:
git config --global user.email "[email protected]"
git add docs/mintlify/ docs/mintlify/get_started/ docs/mintlify/key_modules/ docs/mintlify/reference/ docs/mintlify/docs.json
+ git add docs/
if git diff --staged --quiet; then
echo "No changes to commit"
diff --git a/docs/mintlify/convert_notebook2mdx.py b/docs/mintlify/convert_notebook2mdx.py
index 37a2db22e..195bb4a6d 100644
--- a/docs/mintlify/convert_notebook2mdx.py
+++ b/docs/mintlify/convert_notebook2mdx.py
@@ -378,6 +378,11 @@ def convert_ipynb_to_mdx(
"""Convert Jupyter Notebook to MDX format."""
print(f"Converting IPYNB file: {ipynb_file}")
+ if nbformat is None:
+ raise RuntimeError(
+ "nbformat/nbconvert is not installed. Cannot process .ipynb files."
+ )
+
# Read Jupyter Notebook
with open(ipynb_file, 'r', encoding='utf-8') as f:
notebook = nbformat.read(f, as_version=4)
@@ -646,7 +651,7 @@ def process_directory(
for root, _dirs, files in os.walk(directory):
root_path = Path(root)
for file in files:
- if file.endswith(('.ipynb', '.md')):
+ if file.endswith(('.ipynb', '.md', '.mdx')):
files_to_process.append(root_path / file)
# Process the determined files
@@ -688,6 +693,54 @@ def process_directory(
converted_files.append((file_path, output_file))
total_md += 1
print(f" Converted MD: {file_path.name} -> {output_file}")
+ elif file_path.suffix == '.mdx':
+ # If an explicit output directory is provided and differs from the current
+ # file location, copy the mdx file to the expected output location to keep
+ # folder structures in sync. Otherwise, just reference the existing file.
+ if (
+ current_output_dir
+ and file_path.parent != current_output_dir
+ ):
+ dest_path = current_output_dir / file_path.name
+ try:
+ import shutil
+
+ shutil.copy2(file_path, dest_path)
+ output_file = dest_path
+ except Exception as copy_err:
+ print(
+ f"Error copying MDX file {file_path} -> {dest_path}: {copy_err}"
+ )
+ output_file = file_path # Fallback to original path
+ else:
+ output_file = file_path
+
+ converted_files.append((file_path, output_file))
+ print(f" Detected modified MDX: {file_path.name}")
+
+ # Reverse sync: copy the modified MDX back to the corresponding
+ # source docs directory (docs/...) as a .md file so changes made
+ # in Mintlify output become the new canonical docs source.
+ try:
+ if 'mintlify' in file_path.parts:
+ mintlify_idx = list(file_path.parts).index('mintlify')
+ rel_parts = file_path.parts[mintlify_idx + 1 :]
+
+ dest_md_path = (
+ Path('docs')
+ .joinpath(*rel_parts)
+ .with_suffix('.md')
+ )
+ dest_md_path.parent.mkdir(parents=True, exist_ok=True)
+
+ import shutil
+
+ shutil.copy2(file_path, dest_md_path)
+ print(f" ↳ Synced MDX back to {dest_md_path}")
+ except Exception as sync_err:
+ print(
+ f"Warning: failed to sync MDX back to docs folder: {sync_err}"
+ )
except Exception as e:
print(f"Error converting {file_path}: {e}")
@@ -924,7 +977,7 @@ def merge_navigation_groups(existing_nav, new_nav):
def get_changed_files(directory, since_hours=24, file_extensions=None):
"""Get recently modified files in the directory"""
if file_extensions is None:
- file_extensions = ['.ipynb', '.md']
+ file_extensions = ['.ipynb', '.md', '.mdx']
changed_files = []
directory = Path(directory)
@@ -951,7 +1004,7 @@ def get_git_changed_files(
):
"""Get files changed in git compared to base branch"""
if file_extensions is None:
- file_extensions = ['.ipynb', '.md']
+ file_extensions = ['.ipynb', '.md', '.mdx']
try:
# Find the git repository root
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index 3698bc449..3b17d96b8 100644
--- a/docs/mintlify/docs.json
+++ b/docs/mintlify/docs.json
@@ -46,6 +46,7 @@
{
"group": "Get Started",
"pages": [
+ "get_started/introduction",
"get_started/installation",
"get_started/setup"
]
diff --git a/docs/mintlify/get_started/installation.mdx b/docs/mintlify/get_started/installation.mdx
index fb1239fec..34bce638b 100644
--- a/docs/mintlify/get_started/installation.mdx
+++ b/docs/mintlify/get_started/installation.mdx
@@ -1,205 +1,289 @@
---
-title: "Installation"
+title: Installation
+description: Get started with CAMEL-AI - Install, configure, and build your first multi-agent system
+icon: wrench
---
-🐫 **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
+## 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/mintlify/get_started/introduction.mdx b/docs/mintlify/get_started/introduction.mdx
new file mode 100644
index 000000000..a7ce2ed33
--- /dev/null
+++ b/docs/mintlify/get_started/introduction.mdx
@@ -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/mintlify/get_started/setup.mdx b/docs/mintlify/get_started/setup.mdx
index e3a912320..23c79d79b 100644
--- a/docs/mintlify/get_started/setup.mdx
+++ b/docs/mintlify/get_started/setup.mdx
@@ -1,67 +1,55 @@
---
title: "Setup"
+icon: gear
+description: "Configure API credentials and select a model provider"
---
-# 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)
-
+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)