CAMEL, or agents talking in roles

CAMEL, or agents talking in roles

CAMEL grew out of a research question rather than a production need, and its construction shows it. The original thesis ran: two language models, one playing the requester and the other the worker, will solve a task better than one model handed the instruction directly.

It sounds like a trick and turned out to be the direction the whole field took. Splitting roles between whoever formulates the next steps and whoever performs them reduces the model's tendency to skip stages and produces a record of the reasoning you can read.

Today the project is more than that one concept. It is a library for building multi agent systems, a toolkit for generating training data, and a base for running simulations. That breadth is its strength and equally the reason it gets misjudged.

Three things it suits

Separating them at the start pays off, since material about the project usually blends them, and the decision to use it depends on which one you have in mind.

The first is building agents that perform tasks, meaning what other libraries of this class do. Here the project is one of many choices with no particular advantage.

The second is generating synthetic data. Two agents conversing in roles produce a record suitable as training or test material. That is the use where the project genuinely leads the competition, since it was built for exactly this.

The third is simulation. Dozens of agents with assigned roles, goals, and the ability to communicate let you study what happens inside a group. That is a research use, rarely reaching a product, while remaining interesting for modelling behaviour.

If you are looking for a library to build an agent handling customer tickets, the second and third are irrelevant to you, and for the first it pays to compare it against tools aimed squarely at production.

A single agent

pip install "camel-ai[all]"

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

agent = ChatAgent(
    system_message=BaseMessage.make_assistant_message(
        role_name="Analyst",
        content="You analyse sales data. You answer with numbers and conclusions.",
    ),
)

response = agent.step("Which quarter had the highest margin and why?")
print(response.msg.content)

The notion of a role is present from the first line, and that sets the library apart. An agent is not simply a model with instructions but a character with a named function, which matters once you place several such characters together.

Models from various vendors and locally run ones are supported, as are tools attached through a widely adopted protocol, so integration with existing systems needs no custom connectors.

Conversation in roles

This is the mechanism everything started from.

from camel.societies import RolePlaying

session = RolePlaying(
    assistant_role_name="Python developer",
    user_role_name="Data analyst",
    task_prompt="Build a sales report broken down by region.",
)

message = session.init_chat()
for _ in range(15):
    assistant_reply, user_reply = session.step(message)
    if assistant_reply.terminated or user_reply.terminated:
        break
    message = assistant_reply.msg

The agent in the requester role formulates successive instructions, the agent in the worker role carries them out, and the conversation runs until the task is solved or the turn limit is reached. Nobody plans this in advance: the task's breakdown into steps emerges as it goes.

The advantage is real on open ended tasks where you do not know in advance how many steps they take. So is the drawback: on a task with a known order this mechanism adds uncertainty and cost while returning nothing.

The turn limit is a safeguard here rather than a formality. Two agents can fall into an exchange of pleasantries or loop on clarification, and each turn is two model calls, so the bill grows at a pace invisible until you count it.

It also pays to know where the real cost of such a conversation comes from. Every turn carries the whole history so far, so the fifteenth utterance costs many times more than the first despite looking the same. Across twenty turns the cost of a single task can pass the point where the whole idea stops making economic sense, and that is exactly the moment to check whether the task genuinely needs a conversation.

The practical hint follows directly. Before running role play across a thousand cases, run it on ten and sum the tokens consumed. That one number multiplied by the planned scale says more than any estimate made up front.

A workforce of agents

A newer module lets you assemble a team where a task is divided and distributed among workers with different specialisms.

from camel.societies.workforce import Workforce

workforce = Workforce("Analytics team")
workforce.add_single_agent_worker("Data analyst", worker=analyst)
workforce.add_single_agent_worker("Report editor", worker=editor)

result = workforce.process_task(task)

A coordinator breaks the task into parts, assigns them, and assembles results, returning to the breakdown on failure. That is closer to what a production library is expected to do than a free conversation between two agents.

Judge it carefully, though. A coordinator arrangement is expensive, since planning and assembling results are model calls beyond the work itself. On a task describable as three steps in sequence, a simpler flow comes out better on every measure.

The gain appears only once parts of the task are independent of each other and can run in parallel. Response time then drops to the slowest part rather than growing to the sum of all of them, and the planning cost spreads across something that actually paid off. With interdependent parts the coordinator becomes a bottleneck and adds latency with nothing in return.

Synthetic data, the genuine advantage

Here the project does something the competition either skips or does incidentally.

A conversation between two agents in roles is a ready dialogue record split into messages, steps, and an outcome. Run across a thousand task variants it yields a set suitable as material for fine tuning a smaller model or as a set of test cases.

The use that works best looks like this. You have an expensive model handling a task and want a cheaper model of comparable effectiveness at that one job. You generate a few thousand conversations, filter them for correctness, and fine tune a smaller model on them.

Three caveats deserve stating honestly. First: data generated by a model carries its errors and biases, so filtering and correctness checking are part of the process rather than an extra. Second: model terms of use sometimes restrict training competing models on their output, so read them before starting. Third: a set generated from one task template lacks variety, and variety decides fine tuning quality more than example count does.

How to build a good data set

Since this is the project's main advantage, the whole process deserves describing, because generating the conversations is the easiest part of it.

Start by defining what the target model must do. Not "handle tickets" but specifically: assign a ticket to one of eight categories, extract the order number, and propose a reply in one of three variants. The narrower the task, the better fine tuning a smaller model works.

Then attend to input variety, since that decides quality. A thousand conversations generated from one task template is worth less than two hundred conversations from two hundred different real cases. The best source of variety is your own historical data, used as conversation starting points.

The third step is filtering, and a fair portion of the set usually falls away here. Automated checks catch answers in the wrong format, incomplete ones, or ones contradicting the input. A manual review across a hundred examples reveals errors no rule catches and is worth the hour it takes.

The fourth is splitting into a training set and an evaluation set, with the latter built from real cases rather than generated ones. Judging a model on data from the same process that taught it produces an inflated and useless number.

The fifth is comparison. A fine tuned model wins when, at comparable effectiveness, it costs noticeably less or answers noticeably faster. If the cost difference is a dozen or so percent, the whole effort usually does not pay off and staying with a larger model and a better prompt is wiser.

That last route deserves considering earlier, because a better prompt can be worked out mechanically too. DSPy optimises the instruction and the choice of examples placed into the request, guided by a quality measure you define yourself. The set gathered for fine tuning serves this unchanged, and the result arrives in hours rather than days, so the sensible order is prompt optimisation first and fine tuning only once it falls short.

Multi agent simulations

The third use deserves a few sentences, since it gets confused with building production systems, and that is entirely different work.

A simulation means running many agents with assigned roles, goals, and the ability to exchange messages, then observing what emerges. There is no correct answer here and no success metric in the ordinary sense, since the group's behaviour is itself the object of study.

The uses are mainly research: checking how a role split affects solution quality, how information spreads through a group, when looping appears, and what happens when one agent receives contradictory instructions. That is valuable when designing your own multi agent system, since it reveals limits you will hit later anyway.

Keep two things in mind, though. The first is cost: a simulation with twenty agents across a hundred turns is two thousand model calls, so a spending cap set in advance is mandatory here. The second is drawing conclusions carefully. Language model behaviour in a simulation says something about models and not necessarily about people, and confusing those two is the most common interpretive error in this area.

CAMEL against the alternatives

The decision is simpler here than usual, since the projects aim at different things. For a system serving real users, reach for one of the production oriented entries, since they offer better observability, checkpoints, and support.

For producing training data, studying group behaviour among agents, or experimenting with role splits, this library provides tools the others simply lack.

Common mistakes

The first is using role playing for a task with a known order of steps. The mechanism then adds cost and uncertainty while returning nothing.

The second is no turn limit and no cost cap. Each turn is two model calls, so a looping conversation runs up a bill faster than intuition suggests.

The third is treating model generated data as finished. Filtering and correctness checking are part of the process, since a model reproduces its own errors.

The fourth is generating a set from one task template. Variety decides fine tuning quality more than example count does.

The fifth is skipping the model's terms of use before generating training data. Some vendors restrict training competing models on their output.

The sixth is picking this library for a production system purely because it read well. Production values checkpoints, observability, and predictability, and the emphasis here lies elsewhere.

FAQ

How does CAMEL differ from CrewAI?

In purpose. CrewAI targets processes with clearly assigned roles and tasks, built with production in mind. CAMEL grew out of research into how agents converse and leans harder into data generation and simulation. For typical automation the first is simpler, for research the second gives more.

What does it genuinely suit?

Three things: producing synthetic data from agent conversations, studying group behaviour among agents, and building agents that perform tasks. It leads on the first two and is one of many choices on the third.

Is agent generated data usable for training?

After filtering and correctness checking, yes, and that is a proven route to a cheaper model of comparable effectiveness at one job. Without that stage the set reproduces the errors of the model that produced it.

Does it work with models beyond one vendor?

Yes, various vendors are supported along with locally run models, through Ollama for instance. Tools attach through a widely adopted protocol too, so integrating with existing systems needs no custom connectors.

Is it suitable for production?

For simple uses yes, while libraries designed squarely for production offer better observability, checkpoints, and run predictability. If repeatability and easy diagnosis matter to you, start with those.

Documentation sits on the project site, and the code in the GitHub repository.