CrewAI guide: agents, tasks, flows, and deployment

CrewAI is a framework for assigning tasks to specialized agents, bringing them together in teams, and managing their work through flows. You define responsibilities, available tools, expected results, and program transitions. Reliability then depends on the models, checks, and permissions you choose.

Understand the building blocks before assembling a team

In CrewAI, an agent combines a role, a goal, instructions, and a language model. A task describes the work to be done and the expected deliverable. A crew brings agents and tasks together under an execution process.

A flow operates at a different level: it organizes the application’s steps. You can use it to validate data, run a crew, perform a Python check, and request approval. This separation helps distinguish decisions delegated to the model from rules enforced by your software.

Building block	Responsibility	Design example
Agent	Perform work using a role and tools	Extract facts from a document set
Task	Define a request and its expected result	Produce a list of facts with their sources
Crew	Organize the agents’ work	Run extraction followed by drafting
Flow	Control program steps and state	Validate the documents before starting the team
Tool	Provide access to an external function	Read an authorized document

These building blocks are not human colleagues. Assigning an agent a reviewer role does not establish that it will catch the writer’s mistakes. Both agents may share the same limitations or accept a claim without evidence.

Start by identifying why you need multiple agents. If extraction followed by a programmatic check meets the requirement, adding a team may mainly increase the number of exchanges. The guide to multi-agent systems explores this architectural choice.

Define roles and tasks you can verify

An agent’s main fields include role, goal, backstory, llm, and tools. Settings such as allow_delegation, max_iter, and max_execution_time constrain its behavior. The agent documentation, accessed on October 24, 2026, explains their scope.

Use the role to establish a responsibility, the goal to define success, and the instructions to set boundaries. Avoid fictional biographies intended to give the model authority. Use operational instructions instead: extract only information present in the documents, preserve its provenance, and flag anything missing.

A task should describe its input, the work required, and its output. CrewAI uses fields including description and expected_output; context identifies results from earlier tasks. Structured outputs and guardrails are also covered in the task documentation.

For a document set, you might request a list of claims with their references, followed by a summary based on that list. Specify that missing sources must remain visible. A general instruction to produce high-quality work does not define a result you can check.

Separate format checks from content checks. Your code can verify that a field exists or an identifier is valid. Establishing whether a claim matches a document requires comparing it with the source. A structured output makes it easier to pass information between steps, but does not guarantee that the content is true.

Choose an execution process

CrewAI documents sequential and hierarchical processes. The sequential process follows task order; the hierarchical process assigns coordination to a manager configured through manager_llm or manager_agent. These mechanisms are explained in the process documentation.

Criterion	Sequential	Hierarchical
Organization	Order defined in the configuration	Assignments controlled by a manager
Responsibilities	Explicit assignments	Work distributed according to agent capabilities
Troubleshooting	Inspect each step in order	Also inspect coordination decisions
Potential use	A known processing sequence	Assignments that vary with the document set

Start with a sequential process. It makes it easier to identify the task that loses information or produces an unusable response. Introduce a manager only when dynamic assignment addresses a problem you have observed.

Apply the same care to delegation. It can help when an agent needs a specialist contribution, but every exchange adds context and work to inspect. Define responsibilities and stopping conditions before enabling it.

Choose the architecture before choosing the framework. The CrewAI and LangGraph comparison helps you examine their differences, while the article on AI agent frameworks places these approaches in a broader context.

Prepare the environment and your first exercise

The installation documentation accessed on October 24, 2026, requires Python 3.10 or later, but earlier than 3.14. It uses uv to install the CLI and manage the project. These requirements and the commands below come from the official installation guide.

You will also need access to your chosen model provider and credentials for any external services. Check their terms of use, limits, and where they send data. Choose a provider before sending confidential documents.

For the first exercise, use a short set of nonsensitive documents. The proposed goal is to turn a note into a sourced summary, without web browsing, messaging, or writing to a business application. This scope lets you inspect the agents’ work without immediately depending on several integrations.

Define the expected result before installing anything: an accurate summary, references to the documents, and a list of missing information. Keep a manually written reference answer as well, so you can compare omissions and additions.

Finally, distinguish the globally installed CLI from the library used by the project. Updating the former does not automatically update the latter. Keep the project’s dependency files so you can reproduce the environment that produced a result.

Install and configure your first crew

1. Check Python and install the CLI

Check your interpreter:

python3 --version

If uv is missing, the documentation provides this installation command for macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

For Windows, it provides:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install the CLI and confirm it is available:

uv tool install crewai
uv tool list

If installation reports a PATH problem, the documented command is:

uv tool update-shell

2. Generate the project

The official project creation syntax is:

crewai create crew <your_project_name>

Replace the name in angle brackets with your project name. Then open the generated folder in your editor.

The current documentation favors JSONC: agents are defined in agents/, and the team is defined in crew.jsonc. Tutorials using crew.py, config/agents.yaml, and config/tasks.yaml follow the classic approach, which remains supported through the --classic option.

3. Adapt the generated files

For this exercise, define an extraction agent and a summarization agent. The first should collect facts and their references; the second should write only from that collection. Start with delegation disabled.

In crew.jsonc, place extraction before drafting and make their dependency explicit. Keep identifiers consistent across files. Supply the required input variables and the configuration for your chosen model.

Keep keys in .env and verify that the file is excluded from the repository. A key should never appear in agent instructions or a shared example.

4. Install dependencies and run

From the project root:

crewai install
crewai run

Inspect the deliverable and intermediate steps. Your first target is an execution you can understand: known inputs, identifiable tasks, saved output, and visible errors. An elegant response is not enough to validate the team.

Connect tools with limited permissions

A tool turns a model decision into a software call. Its description should explain its purpose, arguments, and return value. The CrewAI tool documentation covers available tools and how agents use them.

Add tools gradually. Start with read access limited to a directory, then introduce the searches or business services you need. Each additional connection creates another possible source of failure: authentication, stale data, service outages, or an oversized result.

For a custom tool, validate arguments in code. An instruction to stay within scope does not replace an actual check of the authorized path, account, or operation. Return actionable errors instead of ambiguous results that the agent might interpret as success.

Tool calling also needs an output contract: distinguish an empty result from denied access or a service failure. These situations require different responses.

If you choose an MCP connection, examine the exposed tools and the server’s permissions before integrating it. A shared protocol does not grant blanket access.

Keep sensitive actions behind a controlled step. For a message, present the exact recipient and content for approval. For a write to a business system, check the current state and prevent duplicates. Approval of the overall goal alone is too vague.

Use flows to control the application

Flows have state and methods connected through events. @start() defines an entry point, @listen() reacts to a step, and @router() provides conditional routing. Persistence is available through @persist, as described in the flow documentation.

The following teaching example adapts these mechanisms. It separates preparation from validation without calling a model:

from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel


class EtatDossier(BaseModel):
    texte: str = ""
    statut: str = "nouveau"


class DossierFlow(Flow[EtatDossier]):
    @start()
    def preparer(self):
        self.state.texte = "Document de démonstration"
        self.state.statut = "prepare"
        return self.state.texte

    @listen(preparer)
    def verifier(self, texte):
        if not texte.strip():
            raise ValueError("Document vide")
        self.state.statut = "verifie"
        return self.state.statut


resultat = DossierFlow().kickoff()
print(resultat)

In an application, you could insert the crew after document validation, then check its output before passing it on. Keep deterministic rules in code: whether an input exists, whether an identifier has the right format, whether access is permitted, or whether a destination is authorized.

Also define explicit business states: documents received, analysis completed, approval pending, publication completed. Avoid storing only a text history that is difficult to interpret when execution resumes.

Test persistence together with external effects. Restoring a flow’s state does not, by itself, prevent a message or write operation from being repeated. Assign an operation identifier and check whether the action has already succeeded before attempting it again.

Manage context, knowledge, and memory

A task’s useful context is not necessarily the entire available history. Pass along the information it needs, together with its provenance. An overly compressed summary can remove a caveat; a complete document set can bury the decisive passages.

Separate three categories in your design: data supplied with the request, reference documents, and information retained between runs. They have different lifetimes and access rules.

For document summarization, maintain a mapping between each claim and its source passage. If an intermediate agent rephrases the facts, pass along the references too. The writer must be able to find the supporting evidence.

Enable persistent memory only after identifying what it should retain and why. Define a retention period, a deletion procedure, and separation between users. A useful preference in one case can become an inappropriate instruction in another.

Prompt injection also affects documents agents read. External text may ask them to change the rules or use a tool. Treat that text as data to analyze, and enforce permissions in the application. The guide to securing an AI agent explains these protections.

Measure quality and cost per case

Evaluate the complete workflow on representative cases: incomplete documents, contradictions, missing sources, and unavailable tools. Include cases where the correct response is to request clarification or decline an action.

Measure source fidelity, omissions, format compliance, and operational success separately. A result can be factually correct yet unusable by the next application. It can also follow the format perfectly while containing a false claim.

Compare the team with a simpler solution using the same inputs. Keep multiple agents if their contribution improves observed results or supports a necessary check. An appealing division of responsibilities on paper is not a measurement.

For the budget, add model calls, external services, hosting, and review time. Calculate that expense per accepted case, including failures and retries. The model pricing calculator helps estimate the token-related portion.

Set limits on iterations, execution time, and retries. Keep a record of configuration changes and their associated results. Change one element at a time when investigating a decline in performance.

Deploy and monitor the workflow

You can run the application on your own infrastructure or consider CrewAI AMP. The platform offers managed deployment, API access, and execution traces, according to the official CrewAI AMP overview.

Criterion	Infrastructure operated by your team	CrewAI AMP
Environment	You prepare and maintain execution	Infrastructure managed by the platform
Integration	You build the access service	API access provided
Monitoring	You organize logs and alerts	Built-in traces and logs
Budget	Estimate hosting and operating costs	Check the offering’s terms

Before deployment, reproduce the local environment, keep secrets separate, and assign responsibility for incidents. A deployed application must be able to reject a request, stop cleanly, and retain enough information to explain a failure.

For AMP, the official deployment guide documents this sequence from a prepared project:

crewai login
crewai deploy create
crewai deploy status
crewai deploy logs

The creation step detects repository information and variables in .env intended for the platform, among other details. Review their contents and destination before running this operation.

In production, track errors, duration, retries, and cost per run. Protect logs: they may contain sensitive documents or results. Finally, test reverting to a previous configuration. Our directory of agents and frameworks provides further options to compare.

Common problems

The command cannot be found. Check that the CLI appears in the uv tool list, then apply the PATH fix described in the installation section. Reopen the terminal before continuing.

The files do not match the tutorial. Identify the project format: JSONC or classic Python/YAML. Use the corresponding documentation and avoid mixing structures during the first exercise.

An agent or task cannot be found. Compare the identifiers declared in crew.jsonc with those in the agent files. Also check that context dependencies refer to earlier tasks.

The model responds, but tools fail. Test service authentication, arguments, and the returned format separately. A successful text response does not validate the entire integration.

The summary invents information. First inspect the facts passed to the writer. If the error is already present there, strengthen comparisons with the documents and explicitly allow missing information to be reported.

Resuming execution repeats an action. Check the distinction between saved state and a completed external operation. Add duplicate protection before enabling the workflow again.

Prelaunch checklist

Frequently asked questions

Do you need programming skills to use CrewAI?

JSONC configuration lets you describe a team without writing all its orchestration in Python. You still need to understand dependencies, API keys, and runtime errors. Building custom tools and operating an application independently require development skills.

Does CrewAI work with a local model?

That depends on the provider, its interface, and the capabilities of your chosen model. Check compatibility in the documentation for your installed version, then test tool calls and expected outputs. A model that handles conversation may still fail in an agent loop.

What is the difference between a crew and a flow?

A crew brings together agents working on a shared set of tasks. A flow defines how the program runs, including its state and transitions. An application can use a flow to coordinate several crews.

Is CrewAI free?

The framework is distributed under the MIT license, according to the site's October 2026 review. Using it can still incur costs for models, external tools, and hosting. CrewAI AMP is a separate platform offering whose terms should be checked.

Can a CrewAI workflow resume after an interruption?

Flows provide mechanisms for persisting their state. You also need to account for tools that have already run: restoring state does not guarantee that an external write will never be repeated. Test interruptions before deploying to production.

CrewAI reference guide: agent teams, tasks, tools, flows, and deployment