CAMEL-AI: Building Multi-Agent Systems with Communicative AI Agents

Introduction

CAMEL-AI (Communicative Agents for "Mind" Exploration of Large Language Model Society) is an open-source framework designed for building multi-agent systems where AI agents communicate, collaborate, and solve complex tasks together. Originally introduced in a research paper by a team from King Abdullah University of Science and Technology (KAUST), CAMEL has grown into a mature Python framework that enables developers to orchestrate sophisticated agent-to-agent interactions.

The core idea behind CAMEL is simple but powerful: instead of relying on a single LLM prompt to handle everything, you assign distinct roles to multiple agents and let them communicate with each other through structured conversations. One agent might act as a Python programmer, another as a project manager, and a third as a code reviewer. Each agent operates within its role, contributing specialized knowledge and perspective to achieve a shared goal.

This approach mirrors how human teams work. Complex problems are rarely solved by a single person. They require collaboration between specialists who bring different skills and viewpoints. CAMEL-AI provides the infrastructure to replicate this pattern with LLM-powered agents.

In this tutorial, you will learn how to install and configure CAMEL-AI, build role-playing agent pairs, create task-oriented workflows, integrate external tools, use Retrieval-Augmented Generation (RAG) with agents, and design multi-agent societies. By the end, you will have the practical knowledge to build production-ready multi-agent systems.

Installation and Setup

Installing CAMEL-AI

CAMEL-AI is distributed as a Python package. The base installation gives you the core framework, and you can add optional dependencies for specific features.

# Base installation
pip install camel-ai

Installation with all features (recommended for this tutorial)
pip install "camel-ai[all]"

Or install specific extras as needed
pip install "camel-ai[tools]"       # External tool integrations
pip install "camel-ai[rag]"         # RAG support
pip install "camel-ai[huggingface]" # HuggingFace model support

Setting Up API Keys

CAMEL-AI supports multiple LLM backends. The most common setup uses OpenAI, but you can also use Anthropic Claude, open-source models, or other providers.

import os

Option 1: Set environment variables directly
os.environ["OPENAIAPIKEY"] = "your-openai-api-key"

Option 2: Use a .env file (recommended for projects)
Create a .env file with:
OPENAIAPIKEY=your-openai-api-key
ANTHROPICAPIKEY=your-anthropic-api-key

Then load it in your script
from dotenv import loaddotenv

loaddotenv()

Verifying the Installation

Run this quick check to confirm everything is working:

from camel.agents import ChatAgent
from camel.messages import BaseMessage
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType

Create a simple agent
agent = ChatAgent(
    systemmessage="You are a helpful assistant.",

)

Send a test message
response = agent.step("Hello! Can you confirm CAMEL-AI is working?")
print(response.msgs[0].content)

from camel.agents import ChatAgent
from camel.messages import BaseMessage

Define the agent's role through its system message
systemmsg = """You are a senior Python developer with 15 years of experience.
You write clean, well-documented code following PEP 8 standards.
You always include type hints and docstrings in your code.
When explaining code, you break down complex concepts into simple terms."""

Create the agent
pythondev = ChatAgent(

    systemmessage=systemmsg,

)

Interact with the agent
usermsg = "Write a function that implements binary search on a sorted list."
response = pythondev.step(usermsg)
print(response.msgs[0].content)

Role-Playing Conversations

The role-playing mechanism is what makes CAMEL unique. It sets up a structured conversation between two agents: an AI User (who asks questions and provides feedback) and an AI Assistant (who performs the task). Both agents stay in character throughout the conversation.

from camel.societies import RolePlaying
from camel.types import TaskType

Define the role-playing session
roleplaysession = RolePlaying(
    assistantrolename="Python Programmer",
    userrolename="Data Scientist",
    taskprompt="Develop a data pipeline that reads CSV files, "

                "cleans the data by handling missing values and outliers, "
                "and outputs a summary statistics report.",
    withtaskspecify=True,  # Let CAMEL refine the task description

)

Print the refined task and system messages
print(f"AI Assistant System Message:\n{roleplaysession.assistantsysmsg}\n")

print(f"AI User System Message:\n{roleplaysession.usersysmsg}\n")


Run the conversation
print("="  60)

print("Starting Role-Playing Session")
print("="  60)

chatturnlimit = 10

n = 0

inputmsg = roleplaysession.initchat()


while n < chatturnlimit:

    n += 1
    assistantresponse, userresponse = roleplaysession.step(inputmsg)

    # Print the assistant's response
    print(f"\n[Turn {n} - Assistant]:")
    if assistantresponse.msgs:

        print(assistantresponse.msgs[0].content)

    # Print the user's response
    print(f"\n[Turn {n} - User]:")
    if userresponse.msgs:

        print(userresponse.msgs[0].content)

    # Check for termination
    if assistantresponse.terminated or userresponse.terminated:
        print("\nConversation ended.")
        break

    # The user response becomes the next input
    if userresponse.msgs:

        inputmsg = userresponse.msg

    else:
        break

print(f"\nTotal turns: {n}")

from camel.societies import RolePlaying
from camel.types import TaskType

Create a task-oriented session
tasksession = RolePlaying(
    assistantrolename="Software Architect",
    userrolename="Product Manager",
    taskprompt="Design a microservices architecture for an e-commerce platform "

                "that handles user authentication, product catalog, shopping cart, "
                "order processing, and payment integration. The system should "
                "support 10,000 concurrent users.",
    withtaskspecify=True,

    tasktype=TaskType.DEFAULT,
)

Run with a specific number of turns
inputmsg = tasksession.initchat()


for turn in range(6):
    assistantresponse, userresponse = tasksession.step(inputmsg)


    if assistantresponse.msgs:
        print(f"\n{'='50}")

        print(f"ARCHITECT (Turn {turn + 1}):")
        print(assistantresponse.msgs[0].content[:500])  # Truncated for display


    if userresponse.terminated or assistantresponse.terminated:

        break

    if userresponse.msgs:
        inputmsg = userresponse.msg
    else:
        break

from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType

Using OpenAI GPT-4o
openaimodel = ModelFactory.create(

    modelplatform=ModelPlatformType.OPENAI,
    modeltype=ModelType.GPT4O,
    modelconfigdict={"temperature": 0.7, "maxtokens": 4096},

)

agentgpt = ChatAgent(
    systemmessage="You are an AI research assistant.",

    model=openaimodel,
)

Using Anthropic Claude
anthropicmodel = ModelFactory.create(

    modelplatform=ModelPlatformType.ANTHROPIC,
    modeltype=ModelType.CLAUDE35SONNET,
    modelconfigdict={"temperature": 0.7, "maxtokens": 4096},

)

agentclaude = ChatAgent(
    systemmessage="You are an AI research assistant.",

    model=anthropicmodel,
)

Using open-source models via Ollama
ollamamodel = ModelFactory.create(

    modelplatform=ModelPlatformType.OLLAMA,
    modeltype="llama3.1:8b",

    modelconfigdict={"temperature": 0.7},

    url="http://localhost:11434/v1",
)

agentlocal = ChatAgent(
    systemmessage="You are an AI research assistant.",

    model=ollamamodel,
)

from camel.agents import ChatAgent
from camel.societies.workforce import Workforce
from camel.tasks import Task

Define specialized agents
researcher = ChatAgent(
    systemmessage="""You are a research analyst specializing in technology trends.

    You gather information, analyze data, and provide evidence-based insights.
    You cite sources and distinguish between facts and opinions.""",
)

writer = ChatAgent(
    systemmessage="""You are a technical writer who creates clear, engaging content.
    You take complex technical information and make it accessible to a general audience.
    You structure content logically with clear headings and transitions.""",
)

reviewer = ChatAgent(
    systemmessage="""You are a content reviewer and editor.

    You check for accuracy, clarity, consistency, and completeness.
    You provide specific, actionable feedback for improvement.""",
)

Create a workforce with these agents
workforce = Workforce(
    description="Content Creation Team",
    workers=[
        (researcher, "Research Analyst"),
        (writer, "Technical Writer"),
        (reviewer, "Content Reviewer"),
    ],
)

Define and process a task
task = Task(
    content="Create a comprehensive analysis of how large language models "
            "are being used in healthcare, covering current applications, "
            "challenges, and future opportunities.",
    id="healthcare-llm-analysis",
)

Process the task through the workforce
result = workforce.processtask(task)
print(result.content)

from camel.agents import ChatAgent
from camel.toolkits import (
    SearchToolkit,
    MathToolkit,
    CodeExecutionToolkit,
)

Create tool instances
searchtools = SearchToolkit().gettools()
mathtools = MathToolkit().gettools()

Create an agent with tools
researchagent = ChatAgent(

    systemmessage="""You are a research assistant with access to search and
    mathematical tools. Use the search tool to find current information and
    the math tool for calculations. Always verify your findings with
    multiple approaches when possible.""",
    tools=[searchtools, mathtools],

)

The agent can now use tools during conversations
response = researchagent.step(

    "What is the current market cap of the top 3 AI companies? "
    "Calculate their combined market cap and average."
)
print(response.msgs[0].content)

from camel.toolkits import FunctionTool

def querydatabase(query: str) -> str:
    """Execute a SQL query against the analytics database.

    Args:
        query: The SQL query string to execute.

    Returns:
        A string containing the query results formatted as a table.
    """
    # In production, this would connect to a real database
    # Here we simulate a response
    import json
    mockresults = {

        "columns": ["product", "revenue", "unitssold"],
        "rows": [
            ["Widget A", 150000, 3000],
            ["Widget B", 220000, 4400],
            ["Widget C", 85000, 1700],
        ]
    }
    return json.dumps(mockresults, indent=2)



def sendnotification(channel: str, message: str) -> str:
    """Send a notification message to a specified channel.

    Args:
        channel: The notification channel (e.g., 'email', 'slack', 'teams').
        message: The notification message content.

    Returns:
        A confirmation string indicating the notification was sent.
    """
    return f"Notification sent to {channel}: {message}"


Wrap functions as CAMEL tools
dbtool = FunctionTool(querydatabase)
notifytool = FunctionTool(sendnotification)

Create an agent with custom tools
analyticsagent = ChatAgent(

    systemmessage="""You are a business analytics assistant.
    Use the database tool to query sales data and the notification
    tool to alert stakeholders about important findings.""",
    tools=[dbtool, notifytool],
)

response = analyticsagent.step(

    "Query the database for product revenue data and send a "
    "summary notification to the slack channel."
)
print(response.msgs[0].content)

from camel.agents import ChatAgent
from camel.retrievers import AutoRetriever
from camel.types import StorageType

Set up the auto retriever with local vector storage
autoretriever = AutoRetriever(
    vectorstoragelocalpath="./localdata",
    storagetype=StorageType.QDRANT,

)

Ingest documents (supports PDF, TXT, DOCX, and more)
autoretriever.runvectorretriever(
    contentinputpaths=[
        "path/to/technicaldocumentation.pdf",

        "path/to/apireference.txt",
        "path/to/architectureguide.md",

    ],
    returndetailedinfo=False,

)

Create a RAG-enabled agent
ragagent = ChatAgent(
    systemmessage="""You are a technical support agent with access to

    the company's documentation. Always ground your answers in the
    retrieved documents. If the documentation does not contain relevant
    information, clearly state that.""",
)

Query with retrieval
retrievedinfo = autoretriever.runvectorretriever(

    query="How do I configure the authentication middleware?",
    returndetailedinfo=True,

)

Feed retrieved context to the agent
context = "\n".join([str(r) for r in retrievedinfo])
response = ragagent.step(

    f"Based on the following documentation:\n{context}\n\n"
    f"Question: How do I configure the authentication middleware?"
)
print(response.msgs[0].content)

from camel.toolkits import FunctionTool
from camel.retrievers import AutoRetriever
from camel.types import StorageType

Create a retrieval function as a tool
retriever = AutoRetriever(
    vectorstoragelocalpath="./knowledgebase",

    storagetype=StorageType.QDRANT,
)

def searchknowledgebase(query: str) -> str:
    """Search the company knowledge base for relevant information.

    Args:
        query: The search query describing what information you need.

    Returns:
        Retrieved text passages relevant to the query.
    """
    results = retriever.runvectorretriever(
        query=query,
        returndetailedinfo=True,
    )
    return "\n\n".join([str(r) for r in results])

searchtool = FunctionTool(searchknowledgebase)


Agent with RAG as a tool
supportagent = ChatAgent(
    systemmessage="""You are a customer support agent. Use the knowledge

    base search tool to find accurate answers to customer questions.
    Always cite the specific document or section where you found
    the information.""",
    tools=[searchtool],
)

from camel.agents import ChatAgent
from camel.societies import RolePlaying
from camel.toolkits import FunctionTool
import json

Step 1: Define the code to review
codetoreview = '''
def processdata(data):

    result = []
    for i in range(len(data)):
        if data[i] != None:
            result.append(data[i]  2)
    return result

def fetchuser(id):
    import requests
    r = requests.get(f"http://api.example.com/users/{id}")
    return r.json()
'''

Step 2: Create specialized review agents
securityreviewer = ChatAgent(

    systemmessage="""You are a security-focused code reviewer.
    You identify potential security vulnerabilities including:
Injection attacks (SQL, command, etc.)
Insecure API usage
Missing input validation
Hardcoded credentials
Unsafe deserialization
    Provide specific line numbers and remediation advice.""",

)

stylereviewer = ChatAgent(

    systemmessage="""You are a code style and best practices reviewer.
    You check for:
PEP 8 compliance
Pythonic idioms
Type hints
Docstrings
Naming conventions
Code simplification opportunities
    Provide specific suggestions with corrected code.""",

)

performancereviewer = ChatAgent(

    systemmessage="""You are a performance-focused code reviewer.
    You identify:
Algorithmic inefficiencies
Unnecessary memory allocations
Opportunities for vectorization or batch processing
Database query optimization
Caching opportunities
    Provide benchmarking suggestions where applicable.""",

)

Step 3: Run each review
reviewprompt = f"Review the following Python code:\n\n

Managing Agent Memory and Context

CAMEL provides memory management utilities that help agents maintain context across long conversations:

Best Practices

1. Design Clear and Specific System Messages

The quality of your multi-agent system depends heavily on how well you define each agent's role. Vague system messages lead to agents that overlap in responsibility or produce generic outputs.

2. Set Appropriate Turn Limits

Multi-agent conversations can run indefinitely. Always set reasonable turn limits and implement termination conditions.

3. Handle Errors Gracefully

LLM calls can fail due to rate limits, network issues, or context length overflows. Build resilience into your agent systems.

4. Use Temperature Strategically

Different agents in your system may benefit from different temperature settings. Creative agents should use higher temperatures, while analytical agents should use lower ones.

5. Log and Monitor Agent Interactions

In production systems, always log agent interactions for debugging and quality assurance.

6. Cost Management

Multi-agent systems multiply API costs since each agent makes separate LLM calls. Monitor and control costs by choosing appropriate models for each agent's complexity level.

Common Patterns and Use Cases

Pattern 1: Expert Panel

Multiple domain experts discuss a problem from different angles.

Pattern 2: Iterative Refinement

An agent produces work, a critic reviews it, and the original agent refines based on feedback.

• Single agents with well-defined roles serve as the building blocks of your system.
• Role-playing sessions enable two agents to collaborate on tasks through natural conversation.
• Tool integration extends agent capabilities beyond pure text generation to interact with external systems, databases, and APIs.
• RAG integration grounds agent responses in your actual documentation and data.
• Multi-agent societies and workforce patterns** let you orchestrate teams of specialized agents for complex workflows.

As you build with CAMEL-AI, remember that the framework is actively developed and its API surface evolves. Always check the official documentation at https://docs.camel-ai.org and the GitHub repository at https://github.com/camel-ai/camel for the latest features and best practices.

The multi-agent paradigm represents an important shift in how we build AI systems. Rather than trying to make a single model do everything, we can compose specialized agents that communicate and collaborate, much like a well-organized human team. CAMEL-AI makes this pattern accessible, practical, and production-ready. Start with simple two-agent role-playing scenarios, validate that your system messages produce the behavior you need, and gradually increase complexity as your confidence grows.