MMOOZZGG.com

How to build an AI agent

CrewAI multi agent team: roles, tasks and a worked example

8 min read7 sources

A CrewAI multi agent team works like a small staff: each agent has its own role, goal and task, and the framework passes the result of one agent to the next. CrewAI is open under the MIT license, and its first release came in December 2023. Below is an example team of a researcher, an analyst and an editor who prepare a report, with the steps from the documentation.

On this page · 4 sections

A developer is needed

Roles and tasks

A framework is the skeleton of a program: ready rules and code into which a developer writes their own logic. CrewAI builds a team (crew) from agents and hands out tasks to them.

An agent has three required fields: “role” (for example “market analyst”), “goal” (what it works toward) and “backstory” (its experience and manner of work). From these the model understands how to behave.

The other fields are optional: “llm” (which model works for the agent), “tools”, “max_iter” (how many attempts the agent has before its final answer, 20 by default) and “allow_delegation” (whether the agent may pass work to another, off by default).

One more useful agent field is “reasoning”. If you turn it on, the agent first makes a plan before a task and only then acts. The field is off by default.

A task describes the work, not the worker. Its required fields are “description” (what to do) and “expected_output” (what the finished result looks like). The more specific the second field, the easier it is to check the work.

A task has fields for control: “context” (which tasks’ results to build on), “human_input” (show the result to a person before the next step), “guardrail” (a function that checks the result; if the check fails, up to 3 retries by default) and “output_file” (where to save the result).

A role without a task does nothing, and a task without a checkable result gives a text that nobody can accept. So start with the “expected_output” field: which document you need at the end and who will accept it.

An example team

Let’s build a team of three agents: a researcher collects information on a topic, an analyst draws conclusions and an editor writes a report. Setup and build follow the CrewAI documentation:

1. Check your Python version with python3 --version: you need Python 3.10 or newer and below 3.14.

2. Install the uv package manager, which CrewAI uses. On macOS and Linux: curl -LsSf https://astral.sh/uv/install.sh | sh.

3. Install CrewAI itself: uv tool install crewai. To check, run uv tool list; crewai must be in the list.

4. Create a project: crewai create crew report. A folder appears with a crew.jsonc file (team settings and task order), an agents folder (one file per agent), an .env file (keys and variables), and the knowledge (knowledge files) and tools (your own tools) folders.

5. In the agents folder, create three files: researcher.jsonc, analyst.jsonc and editor.jsonc. In each, fill in “role”, “goal” and “backstory”. For example, the editor’s goal: “write a two-page report for the CEO, with no jargon”.

6. In crew.jsonc, list the three agents in the “agents” array, and describe three tasks in the “tasks” array: collect information, draw conclusions, write the report. Put the report topic in a placeholder in curly braces, and set its default value in the “inputs” section.

7. Install the project dependencies with crewai install and run the team: crewai run. If the placeholder has no value in “inputs”, the program asks for it at launch.

This is what the team’s tasks can look like in substance, without the file syntax:

The researcher’s task. Description: find open information on the topic for the last year. Expected output: a list of 10 facts, each with a source, a link and a date.

The analyst’s task. Description: draw conclusions for the CEO from the list of facts. Expected output: 3 conclusions, each with the facts it rests on and a level of confidence.

The editor’s task. Description: write a report from the conclusions. Expected output: a two-page text with no jargon and a list of sources at the end. The “output_file” field saves the report to a file.

Note that you can check each expected output by eye in a minute. If you cannot check it, the agent will not know when the task is done either.

To keep data from going to outside services, give the agents an open model through Ollama. According to the CrewAI documentation: install Ollama, run the model, and in the model description (the LLM class) give its name with the “ollama/” prefix and the address http://localhost:11434, then add the dependency with uv add ‘crewai[litellm]’.

Keep the keys of outside services in the .env file, not in the agents’ text: the documentation advises this, and this way a key does not become public together with the project.

Order of work

CrewAI calls the team’s order of work a process. There are two processes, and you choose one when you create the team.

Sequential: tasks run in the order of the list, and the result of each becomes the context for the next. For a report this is the natural choice: the researcher, then the analyst, then the editor.

Hierarchical: tasks are not assigned in advance. A manager agent plans the work, hands out tasks by the agents’ skills, checks the results and decides whether the work is done. For this, the team gets a manager model (“manager_llm”) or its own manager agent (“manager_agent”).

If the analyst needs more than the result of the previous task, add the “context” field to its task with the list of tasks it relies on. This way the editor can see both the researcher’s findings and the analyst’s conclusions.

Start with the sequential process. Its course is known in advance, and an error is easy to trace to a step. The hierarchical process adds a participant that spends model calls itself and can itself make mistakes in assigning the work.

Turn on the “verbose” field for the agents: the detailed log shows what each agent did and at which step the team went wrong. How agent teams work in general and when you need them is covered in the article on multi-agent systems.

Where it breaks

On 25 June 2025 Gartner forecast that more than 40% of agentic AI projects will be canceled by the end of 2027 because of costs, unclear value and weak risk control. A team of agents falls into all three risks at once.

Costs. Each agent calls the model several times, and each has up to 20 attempts by default. Three agents on one task use many times more calls than one. Limit “max_iter” and “max_execution_time” (time per task in seconds).

Errors travel down the chain. If the researcher brings a wrong number, the analyst draws a conclusion from it, and the editor formats it neatly. Put a “guardrail” on tasks with numbers and “human_input” before the final report.

Blurred roles. If two agents have similar goals, they duplicate work. Split the team by result: each task gives its own document that you can check separately.

Delegation. With “allow_delegation” on, agents pass work to each other, and the course of the process is harder to predict. It is off by default; turn it on only when the task cannot be solved without it.

Start testing the team on topics where you know the right answer in advance: 5–10 of them are enough to see at which agent the quality drops. Do this before reports go to the CEO, and repeat it after every change of model or instructions. How to build such a set of checks is described on the page about agent testing.

Gartner also says that of thousands of “agent” vendors, only about 130 are real; the rest renamed chatbots and RPA, programs that repeat a person’s actions in an interface. A team of three CrewAI agents is built from open blocks. If someone charges for it as one-of-a-kind custom work, ask what the price is made of.

Often one agent with tools, built in code, solves the task without a team. Build a team when the roles really have different tools and different checks.

Sources and fact-checking

Checked by the editors on 16 October 2026.

  1. Wikipedia, December 2023 (en.wikipedia.org)
  2. Gartner, 25 June 2025 (gartner.com)
  3. CrewAI Docs, Installation, 2026 (docs.crewai.com)
  4. CrewAI Docs, Agents, 2026 (docs.crewai.com)
  5. CrewAI Docs, Tasks, 2026 (docs.crewai.com)
  6. CrewAI Docs, Processes, 2026 (docs.crewai.com)
  7. CrewAI Docs, LLMs, 2026 (docs.crewai.com)

Found a mistake? Tell us

Publications

Contact us