CrewAI models a multi-agent system as a small company: you define employees (agents), assign them tasks, and group them into a crew that runs a process. That metaphor is the framework's real strength—it lets you express a role-based workflow without writing an execution graph by hand. It is also the framework's main risk, because "hire more agents" feels productive even when a single agent would do the job for a fraction of the cost. This guide covers what CrewAI does well, a runnable example, and the production concerns that decide whether a crew earns its keep. It was last technically reviewed on July 16, 2026.

Key Takeaways

  • CrewAI's abstractions—Agent, Task, Crew, Process—make role-based workflows fast to express.
  • A crew is worth it over a single agent only when roles need different tools, when independent work can run in parallel, or when separate people own separate steps.
  • sequential runs tasks in order; hierarchical adds a manager agent that delegates. Neither is inherently parallel.
  • A backstory shapes tone and behavior. It does not enforce permissions—tools do.
  • Treat search results and any tool output as untrusted input, not as facts to be repeated verbatim.
  • Set max_iter and keep low-level executors non-delegating to avoid delegation loops.

Why (and When) to Use CrewAI

The common failure of a naive multi-agent setup is not a weak model; it is several agents with vague roles talking past each other, looping, or drifting off task. CrewAI addresses this by forcing structure:

  • Roles and backstories give each agent a narrow remit, which reduces off-topic output.
  • Typed tasks with an explicit expected_output make the deliverable checkable.
  • A process (sequential or hierarchical) makes the control flow explicit instead of emergent.
  • A tool ecosystem integrates with the broader LangChain tool library.

That structure is genuinely useful. But be honest about the alternative: if your workflow is a fixed sequence—research, then write—a single agent with the same instructions and tools often produces the same result more cheaply, and a deterministic pipeline is more reliable still. As the multi-agent systems guide in this series argues, a crew earns its coordination cost when roles need different permission boundaries, when work can genuinely run in parallel, or when different people own and evaluate different steps—not simply because a task has multiple stages.

The Four Core Concepts

  • Agent — a worker with a role, a goal, a backstory, and a set of tools. The backstory shapes behavior; the tools define what the agent can actually do.
  • Task — a unit of work with a description and, crucially, an expected_output that states what "done" looks like.
  • Crew — the container that coordinates agents and tasks and selects the process.
  • Process — the execution model. Process.sequential runs tasks in the declared order, passing each output forward as context. Process.hierarchical introduces a manager agent that plans and delegates. Delegation is dynamic routing, not parallel execution.

A Runnable Market-Research Crew

We will build a two-agent crew that researches a topic and writes a report. The example is intentionally small so the mechanics are visible.

Environment

bash 
pip install crewai langchain-openai duckduckgo-search

Set the API key in your environment rather than in code, and read the model name from the environment because model identifiers are perishable:

bash 
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="gpt-4o"

Define the Agents

The backstory sets each agent's tone and priorities. Note what it does not do: it does not grant or restrict capability. The researcher can search because it has search_tool; the writer cannot, because it does not.

python 
import os
from crewai import Agent, Task, Crew, Process
from langchain_openai import ChatOpenAI
from langchain_community.tools import DuckDuckGoSearchRun

llm = ChatOpenAI(model=os.environ.get("OPENAI_MODEL", "gpt-4o"), temperature=0.3)
search_tool = DuckDuckGoSearchRun()

researcher = Agent(
    role="Senior AI Industry Analyst",
    goal="Find and analyze current market dynamics for AI coding assistants",
    backstory=(
        "You extract core data and competitive structure from fragmented "
        "sources, and you record where each claim came from."
    ),
    verbose=True,
    allow_delegation=False,  # a leaf executor should not delegate
    tools=[search_tool],
    llm=llm,
)

writer = Agent(
    role="Chief Tech Columnist",
    goal="Turn research into a clear, well-structured report",
    backstory=(
        "You write plainly, and you never state a fact the research did "
        "not support."
    ),
    verbose=True,
    allow_delegation=True,  # the writer may ask the researcher for more
    llm=llm,
)

Define the Tasks

The value of a task is in its expected_output. A vague deliverable produces a vague result; a specific one gives the agent—and you—a checkable target.

python 
research_task = Task(
    description=(
        "Investigate the current competitive landscape of AI coding "
        "assistants. For each product, note its distinctive claim and the "
        "source of that claim."
    ),
    expected_output=(
        "A comparison of at least three products, each with its stated "
        "strengths, weaknesses, and a source link. Mark unverified claims."
    ),
    agent=researcher,
)

write_task = Task(
    description=(
        "Using only the research output, write an analytical report with an "
        "introduction, the market landscape, a product comparison, and a "
        "clearly labeled outlook section."
    ),
    expected_output=(
        "A well-structured Markdown report that repeats no claim the "
        "research marked as unverified."
    ),
    agent=writer,
)

Assemble and Run

python 
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,  # output of each task feeds the next
    verbose=True,
)

result = crew.kickoff()
print(result)

In a sequential crew, the researcher's output becomes the writer's context automatically. This is the case worth naming plainly: research → write is a fixed pipeline, so this crew is a fine way to learn CrewAI but buys little over a single agent given the same two prompts. It becomes a real multi-agent case when the writer must delegate back for missing evidence, when steps branch on the result, or when a manager routes work dynamically.

Sequential vs Hierarchical

To let a manager agent plan and delegate, switch the process and provide a manager_llm:

python 
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.hierarchical,
    manager_llm=ChatOpenAI(model=os.environ.get("OPENAI_MODEL", "gpt-4o")),
)

Hierarchical mode is more flexible but also more expensive and harder to debug: the manager adds model calls, and delegation can loop. It pays off when the task decomposition is not known in advance. When the steps are fixed, sequential is cheaper and easier to reason about.

Integrating Tools Safely

CrewAI's reach comes from the LangChain tool ecosystem: an agent can query a SQL database, read repository issues, or run a local script. Each of those is also an expansion of the blast radius, so treat tool access as a security decision, not a convenience.

  • Least privilege per agent. Give each agent only the tools its role needs. A research agent that only reads should not hold write or shell tools. The role string does not enforce this; the tools list does.
  • Tool output is untrusted input. A web search returns whatever a page says, including content crafted to manipulate a model. Do not let an agent treat retrieved text as authorized instructions or as verified fact—validate and attribute it.
  • Authentication is not authorization. If a tool wraps an internal API, enforce object-level and tenant-level access control inside the tool, on every call. A crew that can reach an endpoint is not the same as a crew that is allowed to act on a given record.
  • Sandbox anything that executes code. Local script execution should run in an isolated environment, never directly on a host with production credentials.

FAQ

What if agents pass work back and forth or loop?

This is the classic symptom of unconstrained delegation. Tighten responsibility boundaries in each backstory, set a task's max_iter, and keep leaf executors non-delegating (allow_delegation=False). If a loop persists, the decomposition is probably wrong—simplify before adding control.

Can CrewAI and AutoGen be used together?

Architecturally they compete, but either can be wrapped as a tool node inside the other. Choose CrewAI when you want explicit role-based process control; see LangGraph vs AutoGen for how the alternatives compare on stateful control.

How do I keep the crew from repeating unverified claims?

Make provenance part of the expected_output: require each research claim to carry a source, mark unverified ones, and instruct the writer to omit anything unmarked. Then evaluate the actual output against real tasks—a polished report can still be wrong, so outcome verification, not fluent prose, is the release gate.

Conclusion

CrewAI turns a multi-agent system into something you can reason about as an organization, and that abstraction is its real value: roles, tasks, and a visible process. Use it when roles need different tools, when work can run in parallel, or when different people own different steps—and reach for a single AI agent or a deterministic pipeline when the workflow is just a fixed sequence. As with any agent, the discipline that makes it safe is the same: least privilege per agent, untrusted tool output, and evaluation against real outcomes.

Primary Sources