CAMEL AI Framework

Deep-dive source code analysis — v0.2.91a4 · 502 Python modules · 155K LOC

Framework Overview

CAMEL (Communicative Agents for "Mind" Exploration of Large Language Model Society) is one of the earliest and most comprehensive multi-agent frameworks. Originating from the "AI Society" research paper (2023), it has evolved into a full-stack agent framework covering:

• Single-agent chat with tool use, memory, and streaming
• Multi-agent role-playing and collaborative societies
• Hierarchical workforce orchestration (Workforce)
• 80+ toolkits spanning search, browser, code exec, cloud services, messaging, etc.
• 40+ LLM provider backends
• RAG pipelines, embeddings, retrievers
• RL-style environments for agent evaluation
• Sandboxed code execution runtimes (Docker, Daytona, HTTP)

The framework is Apache-2.0 licensed, requires Python 3.10+, and is structured as a single monorepo package camel-ai.

By the Numbers

System Architecture

The architecture follows a layered design: Models at the bottom, Agents in the middle, Societies at the top. Toolkits, Memory, and Runtimes are cross-cutting concerns that agents compose.

Agent Hierarchy

Agent Types

ChatAgent — The Core

ChatAgent is the beating heart of CAMEL at 6444 lines. It handles the complete agent lifecycle:

Step Execution Flow

Key Design Decisions in ChatAgent

ChatAgent Constructor Signature (Key Params)

class ChatAgent(BaseAgent):
    def __init__(
        self,
        system_message: Optional[Union[BaseMessage, str]] = None,
        model: Optional[Union[BaseModelBackend, ModelManager, ...]] = None,
        memory: Optional[AgentMemory] = None,
        message_window_size: Optional[int] = None,
        summarize_threshold: Optional[int] = 50,  # % of token limit
        token_limit: Optional[int] = None,
        output_language: Optional[str] = None,
        tools: Optional[List[Union[FunctionTool, Callable]]] = None,
        external_tools: Optional[List[...]] = None,
        response_terminators: Optional[List[ResponseTerminator]] = None,
        max_iteration: Optional[int] = None,
        tool_execution_timeout: Optional[float] = 10,
        mask_tool_output: bool = False,
        prune_tool_calls_from_memory: bool = False,
        retry_attempts: int = 3,
        retry_delay: float = 1.0,
        step_timeout: Optional[float] = 10,
        stream_accumulate: Optional[bool] = None,
        summary_window_ratio: float = 0.6,
    )

Societies & Orchestration

RolePlaying

The original CAMEL pattern: two agents (assistant + user) converse in character to solve a task. A CriticAgent or Human can be added to the loop.

class RolePlaying:
    def __init__(
        self,
        assistant_role_name: str,
        user_role_name: str,
        critic_role_name: str = "critic",
        task_prompt: str = "",
        with_task_specify: bool = True,
        with_task_planner: bool = False,
        with_critic_in_the_loop: bool = False,
        task_type: TaskType = TaskType.AI_SOCIETY,
        ...
    )

Workforce — Hierarchical Multi-Agent

A 6239-line orchestrator for distributed task execution. Workers form a tree structure with a coordinator at the root.

Workforce manages task assignment, decomposition, and worker lifecycle. Key features:

• Task channel: Workers listen to a shared TaskChannel
• Dynamic creation: New workers can be spawned mid-run
• Failure handling: Configurable recovery strategies (retry, decompose, reassign)
• Pipeline mode: Sequential task chaining with PipelineTaskBuilder
• Quality evaluation: Built-in output quality scoring
• Metrics: WorkforceMetrics tracks task stats

Memory System

Memory Block Types

LongtermAgentMemory — Hybrid

Combines both blocks. On retrieve():

def retrieve(self) -> List[ContextRecord]:
    chat_history = self.chat_history_block.retrieve()
    vector_db = self.vector_db_block.retrieve(
        self._current_topic, self.retrieve_limit,
    )
    # Insert relevant history BETWEEN system msg and recent msgs
    return chat_history[:1] + vector_db + chat_history[1:]

Context Creation Strategy

ScoreBasedContextCreator orders records chronologically and uses token counting with caching:

• Caches actual token counts from LLM response usage
• For new messages, estimates via ~2 chars/token heuristic
• Returns all records that fit within token_limit

Messages & Prompts

BaseMessage

A @dataclass that serves as the universal message type. Not a Pydantic model — it's a plain dataclass for performance.

@dataclass
class BaseMessage:
    role_name: str
    role_type: RoleType          # USER | ASSISTANT | SYSTEM | CRITIC | EMBODIMENT
    meta_dict: Optional[Dict]
    content: str
    video_bytes: Optional[bytes]
    image_list: Optional[List[Union[Image.Image, str]]]
    image_detail: Literal["auto", "low", "high"]
    parsed: Optional[Union[BaseModel, dict]]
    reasoning_content: Optional[str]

Key conversion methods:

• to_openai_system/user/assistant_message() — OpenAI API format
• to_sharegpt() / from_sharegpt() — ShareGPT format
• extract_text_and_code_prompts() — Parse out code blocks
• Supports multimodal: images (PIL or URL), video bytes

FunctionCallingMessage

Extends BaseMessage for tool calls with func_name, args, and result fields.

Prompt System

TextPrompt extends str with template keyword extraction and partial formatting:

@wrap_prompt_functions
class TextPrompt(str):
    @property
    def key_words(self) -> Set[str]:
        # Extracts {placeholder} patterns from the string
        return get_prompt_template_key_words(self)

    def format(self, *args, **kwargs) -> 'TextPrompt':
        # Allows partial formatting — unfilled keys stay as {key}
        default_kwargs = {key: '{' + f'{key}' + '}' for key in self.key_words}
        default_kwargs.update(kwargs)
        return TextPrompt(super().format(*args, **default_kwargs))

CodePrompt extends TextPrompt with code_type and an execute() method that runs through an interpreter.

Tool System

FunctionTool

The core abstraction — wraps any callable into an OpenAI-compatible tool:

class FunctionTool:
    def __init__(
        self,
        func: Callable,
        openai_tool_schema: Optional[Dict] = None,
        synthesize_schema: bool = False,    # Auto-generate schema via LLM
        synthesize_output: bool = False,     # Mock execution via LLM
        ...
    )

Key features:

• Auto schema generation: Parses function signature + docstring → OpenAI JSON schema
• Schema synthesis: If validation fails, can use an LLM to generate a compliant schema
• Output synthesis: Mock tool execution by having an LLM predict the output
• Pydantic coercion: Auto-converts JSON dict args to Pydantic models when the function signature expects them
• Async support: async_call() for async functions; sync calls with async detection and warnings
• @tool decorator: Converts any function to a FunctionTool

BaseToolkit

class BaseToolkit(metaclass=AgentOpsMeta):
    timeout: Optional[float] = Constants.TIMEOUT_THRESHOLD

    def get_tools(self) -> List[FunctionTool]:  # Abstract
        ...

    def run_mcp_server(self, mode):  # MCP protocol support
        self.mcp.run(mode)

All toolkit methods auto-wrapped with with_timeout unless they have a timeout parameter or are marked @manual_timeout.

RegisteredAgentToolkit Mixin

Toolkits that need a reference to their owning ChatAgent can inherit this. The agent auto-registers itself via toolkits_to_register_agent.

Toolkit Ecosystem (80+)

Model Layer

ModelFactory

Creates backend instances from (ModelPlatformType, ModelType) tuples:

class ModelFactory:
    _MODEL_PLATFORM_TO_CLASS_MAP = {
        ModelPlatformType.OPENAI: OpenAIModel,
        ModelPlatformType.ANTHROPIC: AnthropicModel,
        ModelPlatformType.GEMINI: GeminiModel,
        ModelPlatformType.DEEPSEEK: DeepSeekModel,
        ModelPlatformType.OLLAMA: OllamaModel,
        ModelPlatformType.VLLM: VLLMModel,
        ModelPlatformType.SGLANG: SGLangModel,
        ModelPlatformType.LITELLM: LiteLLMModel,
        # ... 40+ more
    }

    @classmethod
    def create(cls, model_platform, model_type, **kwargs) -> BaseModelBackend

ModelManager

Manages multiple model backends with scheduling strategies:

• round_robin — rotate through models
• Custom strategies possible

ModelBackendMeta (Metaclass)

Automatically wraps run() and arun() to:

1. preprocess_messages() — Remove <think> tags, format parallel tool calls
2. Call original _run()
3. postprocess_response() — Extract <think> content into reasoning_content

Environments

CAMEL provides RL-style environments for agent evaluation:

class StepResult(BaseModel):
    observation: Observation
    reward: float
    rewards_dict: Dict[str, float]
    done: bool
    info: Dict[str, Any]

Standard RL interface with reset() and step() methods. Used for benchmarking and evaluating agent performance on structured tasks.

Runtimes

Sandboxed execution environments for tool code:

class BaseRuntime(ABC):
    def add(self, funcs: Union[FunctionTool, List[FunctionTool]]) -> BaseRuntime
    def reset(self) -> Any
    def cleanup(self) -> None
    def get_tools(self) -> List[FunctionTool]

Runtimes can be used as context managers (with runtime:) for automatic cleanup.

Prompt Template Analysis

AI Society Prompts

The original CAMEL research prompts define a structured dialogue protocol:

===== RULES OF ASSISTANT =====
Never forget you are a {assistant_role} and I am a {user_role}.
Never flip roles! Never instruct me!
We share a common interest in collaborating to successfully complete a task.
You must help me to complete the task.
Here is the task: {task}. Never forget our task!
...
Always end <YOUR_SOLUTION> with: Next request.

===== RULES OF USER =====
Never forget you are a {user_role} and I am a {assistant_role}.
Never flip roles! You will always instruct me.
...
Instruction: <YOUR_INSTRUCTION>
Input: <YOUR_INPUT>
...
When the task is completed, you must only reply with
a single word <CAMEL_TASK_DONE>.

Embodiment Prompt

You are the physical embodiment of the {role} who is working on
solving a task: {task}.
You can do things in the physical world including browsing the Internet,
reading documents, drawing images, creating videos, executing code and so on.
...
Here is your action space but it is not limited:
{action_space}

Prompt Design Patterns

Design Patterns

Patterns Used in CAMEL

Framework Comparison

Strengths & Weaknesses

Verdict