CAMEL: a Python framework for studying how groups of AI agents cooperate

The problem CAMEL targets: agents that talk to each other, not one agent with tools

Most agent libraries in Python are built around a single assistant that calls functions. CAMEL starts from a different unit of analysis. The README describes it as "an open-source community dedicated to finding the scaling laws of agents," and the framework is organized around groups: agents with roles, tasks, prompts, models and simulated environments that exchange messages over multiple turns. The intended user is a researcher or an engineer running experiments on cooperative behavior, not someone shipping a support bot.

The repository states the design principles explicitly. Evolvability means agents improve through generated data and environment interaction, driven by reinforcement learning with verifiable rewards or supervised learning. Scalability is stated as support for systems with millions of agents. Statefulness means agents keep memory across multi-step interactions. Code-as-Prompt means the codebase itself is treated as a prompt surface: the README says every line of code and comment serves as a prompt, so readability is a functional requirement rather than a style preference. That last principle explains why the project ships an unusually large examples/ tree instead of a single quickstart.

How CAMEL is put together: societies, datagen, and a broad example tree

The package layout in the repository shows three clusters. Under camel/ there is a datagen directory with modules such as cot_datagen.py, self_improving_cot.py, and subpackages self_instruct and source2synth. There is a societies directory containing role_playing.py, which the README links as the entry point for task automation. Around those sit directories for memories, environments, interpreters, loaders, extractors, embeddings, evaluation and benchmarks, each with a matching folder under examples/.

That structure tells you what the framework actually is: a collection of building blocks for constructing agent conversations and turning them into data. The role-playing pattern is the core mechanism. Two or more agents are given roles and a task, and the framework drives the exchange between them. Data generation reuses the same machinery, which is why the datagen modules and the societies modules live side by side rather than in separate projects.

The dependency list in pyproject.toml is a useful signal about scope. Core dependencies include openai, httpx, pydantic, mcp, tiktoken, jsonschema and google-search-results. Retrieval support is not in the core install: numpy, qdrant-client and pymilvus sit behind a rag extra. So a plain install gives you the conversation and data machinery, and vector-backed memory requires opting in.

Installing camel-ai and running a first role-playing exchange

The distribution name on PyPI is camel-ai, not camel. That matters because the import package is camel, and the Makefile confirms the split: PROJECT_NAME is set to camel while the project name in pyproject.toml is camel-ai. The Makefile's install target runs a plain pip install of the project, and install-editable adds --no-build-isolation --editable for development work.

The package requires Python >=3.10,<3.15, so check your interpreter before anything else.

python -m pip install camel-ai
python -c "import camel; print(camel.__file__)"

The second command should print the path of the installed package. If it fails, you are likely on a Python version outside the supported range or you installed the wrong distribution name.

Model credentials come from environment variables. The repository ships .env.example, which lists provider blocks for OpenAI, Anthropic, Groq, Cohere, Hugging Face, Azure OpenAI, Mistral, MiniMax, Reka, Zhipu AI and Qwen, among others. Each block is commented out with a placeholder value. Uncomment the one you need and fill it in.

cp .env.example .env
# then edit .env and set, for example:
# OPENAI_API_KEY="..."

The file's own header shows the loading pattern: call load_dotenv() from the python-dotenv package at the top of your script so the keys are present before the framework reads them.

from dotenv import load_dotenv
load_dotenv()

For an actual first run, the README points at the examples tree rather than an inline snippet, and specifically links camel/societies/role_playing.py for task automation. That is the honest starting point: browse examples/agents/ and examples/ai_society/ for a script close to your use case, then adapt it. The README does not document a single canonical hello-world command, so expect to read a few example files before your first successful run.

Where CAMEL gets in the way: alpha versioning and a thin core

The release history is the first constraint. The most recent release listed is v0.2.91a5, pushed on 2026-07-13, and the two before it are v0.2.91a4 and v0.2.91a3. Every one of those is an alpha. The version string in pyproject.toml reads 0.2.91a7, which is ahead of the newest tagged release, so the working tree and the published artifact are not the same thing. For research code that is normal. For anything you intend to pin and upgrade on a schedule, it means treating minor bumps as potentially breaking.

The second constraint is scope. CAMEL is not a deployment framework. There is no server, no scheduler and no persistence layer in the core dependency list. Statefulness is a property of agents in memory during a run, not a database you can query afterwards. If your requirement is durable conversation history across process restarts, you are building that yourself on top of the framework's memory abstractions.

The third is documentation shape. The README links a documentation site, a paper, a cookbook list and a large examples tree, but the README itself does not document rollback, migration between alpha versions, or a deprecation policy. If you need a compatibility guarantee before you start, the project does not provide one. That is a real reason to choose something else for a product with an external API surface.

CAMEL compared with a single-agent orchestration library

The closest alternative in practice is a general-purpose single-agent framework, where one model is given a set of tools and a loop. The difference is architectural, not cosmetic. In a single-agent design, the interesting state is the tool-call history of one actor. In CAMEL, the interesting state is the message history between actors with distinct roles, and the framework's job is to drive that exchange and capture it.

That distinction changes what you can measure. If your question is "can this model complete this task with these tools," a single-agent loop is a shorter path. If your question is "what happens when two agents with conflicting instructions negotiate," or "can I generate a training set of multi-turn dialogues from a seed corpus," CAMEL's societies and datagen modules are aimed at exactly that, and the README lists data generation, task automation and world simulation as the three things you build with it.

The cost of the CAMEL approach is that you now have more moving parts to configure: roles, prompts, models per agent, and termination conditions for the exchange. The README does not spell out how the loop terminates, so plan to read the role_playing module before you rely on it.

Licence and the cost of keeping up with an alpha

CAMEL is licensed under Apache-2.0, stated both in the repository metadata and in pyproject.toml. That is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. The repository also carries a licenses/ directory, which is worth reading if you redistribute the package or bundle it into a larger product, since third-party components may sit under different terms. Nothing here is legal advice; if you are shipping commercially, have counsel read the licences directory rather than the top-level identifier alone.

The upgrade cost is the more practical concern. Dependencies are pinned with upper bounds in several places: pydantic is capped at <=2.12.0, tiktoken at <=0.12, websockets below 15.1, and mcp within the 1.x line. Those caps protect you from upstream breakage but also mean a fresh install months later may not resolve if a transitive dependency moves. The pyproject.toml sets upgrade = false under [tool.uv], which signals the maintainers do not want automatic dependency upgrades. If you use uv.lock, commit it, because that file is the only place the resolved set is recorded.

Editorial conclusion

Adopt CAMEL if your work is research on agent interaction, synthetic data generation, or role-playing simulations, and you are comfortable reading examples/ rather than a stable API reference. Do not adopt it as the coordination layer of a production system that needs a frozen interface: the current line is an alpha (v0.2.91a5, pushed 2026-07-13) and the README points to examples and cookbooks rather than a versioned contract. Before committing, verify three things yourself: that your Python version falls inside the >=3.10,<3.15 range in pyproject.toml, that the extras you need (rag, dev, docs) resolve against the pinned pydantic and openai ranges, and that the model provider you intend to use has an entry in .env.example, because the framework reads provider keys from environment variables rather than a config file.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes