There is a question that sounds almost childish until you try to answer it: what happens to agent behavior when you multiply agents the way you multiply model parameters? CAMEL is an open-source community dedicated to finding the scaling laws of agents, and its Python framework is the instrument for that experiment. The README describes a project built by a community of researchers who simulate agent populations at remarkable scale — up to a million agents in companion work — to study their behaviors, capabilities, and risks. What you get after pip install camel-ai is deceptively simple: ChatAgent wraps your model of choice, a handful of lines create a conversation, and from that seed grow three documented use cases — data generation, task automation, and world simulation. The design principle is called Code-as-Prompt: the code your agents run is itself part of the prompt, blurring the boundary between programming and instructing.

The source tree mirrors that research agenda. The agents package is anchored by one enormous file, nearly six thousand lines, that carries the entire conversational core; specialized siblings for critique, MCP tool servers, repository understanding, and knowledge graphs sit beside it. The societies package holds the multi-agent patterns, from the original two-agent role-playing loop to a Workforce so large it has its own subpackage with task channels, worker types, metrics, and callbacks. The models directory carries one file per provider — OpenAI, Anthropic, Gemini, DeepSeek, Groq, Ollama, vLLM, SGLang, LiteLLM, Together, xAI, Qwen, ZhipuAI and dozens more — behind a factory and a manager. Around these live messages, tasks, memories, prompts, retrievers, verifiers, environments, and a datagen package that distills agent dialogues into chain-of-thought training data. As always in this series, what follows is an educational tour of published source code.

CAMEL at a glance: the ModelFactory instantiates provider adapters that back ChatAgent; typed messages and prompt templates shape its context while memories record it and toolkits extend it; RolePlaying pairs two agents, the Workforce employs many through a priority task channel, and the data generation machinery harvests the dialogues.

Reading the overview from left to right:

• Everything is grounded in ChatAgent, the foundational conversational agent that every higher pattern builds on.
• Conversations flow as typed messages, with a sibling class for function calls.
• Prompt templates carry the research-backed phrasing that shaped the original role-playing experiments.
• The ModelFactory instantiates one adapter per provider from a catalog that starts with OpenAI.
• RolePlaying pairs an AI user with an AI assistant in the society that made the project famous.
• The Workforce hires agents as workers and coordinates them through a priority task channel.
• Browser control headlines ninety-three toolkit entries the agent can call.
• Data generation harvests the resulting dialogues into chain-of-thought training data.

Why You Need This

The first reason is that CAMEL is the home of role-playing, the technique that started a research movement. The 2023 paper behind this repository showed that two LLMs given opposing roles — an eager task-solver and a mischievous user who keeps inventing new requirements — will happily converse for dozens of turns, and the transcript is a treasure: synthetic dialogue data for instruction tuning, produced without human labeling. The RolePlaying society encodes that experiment as reusable machinery at eight hundred lines: it constructs the two ChatAgents from role descriptions drawn from the prompt template library, drives their turn-taking through a task-specified helper, and exposes a critic variant in the CriticAgent so multiple candidate answers can be scored instead of blindly accepted. Loop termination is its own abstraction in the terminator base, the kind of care you only see when researchers have run these loops thousands of times and know every way they can run away.

The second reason is the Workforce, which is the most complete open-source take on hierarchical agent teams. Its main module runs five and a half thousand lines implementing a tree of workers: a coordinator node decomposes an incoming task and assigns pieces to children, children can themselves be Workforces, and results flow back up through callbacks while a workflow memory manager records what happened for later reflection. The plumbing between workers is the TaskChannel, a priority queue with explicit states where tasks — objects carrying content, parent links, subtask lists, and failure counts — are posted, claimed, sent back for rework, and archived. A worker is either a SingleAgentWorker owning one ChatAgent that loops on its assignment, or a RolePlayingWorker that spins up a full two-agent session per task, so the framework’s founding pattern literally becomes one worker type among others.

The third reason is the breadth of the model and capability layers, which makes CAMEL a practical hub rather than a laboratory toy. The models directory carries sixty entries, one backend per provider, all implementing a common abstract interface so the factory needs only a ModelType token and the manager can route across backends honoring token budgets and priorities — a sensible hedge when a single agent run may consume millions of tokens. The toolkits package holds ninety-three entries: browser automation, terminal access, code execution, GitHub, Gmail, Google Calendar, Excel, search engines, arXiv, and MCP bridges to external tool servers through the MCPAgent. And because the founding goal is studying agents at scale, the framework ships its own experimental apparatus: verifiers that execute generated Python and check it, environments for single-step and multi-step interaction, and the chain-of-thought generator alongside self-instruct and source2synth flows in the datagen package.

The detail view: ChatAgent and its specialized siblings at the top, messages and tasks feeding them, the memory layer with blocks, records, and the score-based context creator, the model layer with factory, manager, and provider backends, the society machinery with workers and the task channel, and the capability layer of toolkits, retrievers, verifiers, and data generation.

Walking the detail diagram, the agent layer explains how one class carries so much. ChatAgent is the flagship at five and a half thousand lines, and its size is honest: it owns the model call, the tool-call protocol, structured output, streaming, memory hooks, and step accounting for every downstream pattern. Its conversation currency is the BaseMessage, a role-and-content wrapper with conversion helpers for every provider’s wire format, extended by FunctionCallingMessage for tool name, arguments, and result. Memory is a layered system: AgentMemory composes a chat-history block and a vector-database block, both producing scored records that the context creator packs into a prompt under a strict token budget — oldest messages drop off not by position but by score. A research flavor sits alongside: Memanto experiments with human-like recall structures.

The model and society tiers complete the picture. Every backend, from the OpenAI adapter with its stream and tool handling to the Ollama adapter for fully local runs, implements the BaseModelBackend interface, and the factory is a clean two-hundred-line map from enum token to class. On the society side, RolePlaying and the Workforce share the same currency of Task objects, which is why tasks, the channel, and both worker types form a coherent graph rather than two unrelated subsystems. The capability layer shows the same discipline: the vector retriever does semantic search, the auto retriever wraps it in an end-to-end ingest-and-query flow, the Python verifier executes and grades generated code at nearly five hundred lines, and browser control tops a thousand lines of Playwright integration.

From Install to Your First Society

The whole path fits in an afternoon. Install with pip install camel-ai, or pip install "camel-ai[all]" when you want the optional toolkit dependencies. Set one API key — or point at a local Ollama server and use none at all — then create ChatAgent with a system message and a model string, and call step with your question; the reply arrives as a typed message you can immediately act on. The next rung is RolePlaying: give it an assistant role, a user role, and a task prompt, call init_chat, and loop step pairs that return the user’s escalating instructions and the assistant’s answers until the terminator fires. The top rung is Workforce: construct it with worker nodes describing each agent’s competence, hand it one Task, and watch the coordinator split it, workers claim pieces from the channel, and failed tasks bounce back with incremented failure counts until the tree delivers a final answer. Each rung is a dozen or so lines, because the complexity budget was spent inside the framework, not at its edge.

Honest limits: CAMEL is a research framework first, and that cuts both ways. The abstraction surface — societies, terminators, context creators, worker types — is heavier than a simple chat client needs, and the API moves fast enough that code copied from older tutorials can break between minor versions. The README’s most ambitious claims, such as million-agent world simulation, live partly in the companion oasis repository rather than this one, so read this codebase as the framework core, not the whole research program. Error messages when a model key or toolkit dependency is missing can be terse, and the sheer number of provider backends means the less popular ones receive thinner test coverage than OpenAI and Anthropic. None of that dims the core value: for role-playing data generation, hierarchical workforces, or reproducible multi-agent experiments, this is the codebase the literature keeps coming back to.

Enjoyed this post? Never miss out on future posts by following us