andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-04-30 23:02:50 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

better core concepts

Browse Source
This commit is contained in:
lorenzejay
2026-02-19 11:33:49 -08:00
parent 801908356b
commit 21e9e7e8c9
8 changed files with 187 additions and 1189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/en/concepts/agents.mdx
View File

@@ -23,6 +23,17 @@ In the CrewAI framework, an `Agent` is an autonomous unit that can:
at creating content.
</Tip>
## When to Use Agents
- You need role-specific reasoning and decision-making.
- You need tool-enabled execution with delegated responsibilities.
- You need reusable behavioral units across tasks and crews.
## When Not to Use Agents
- Deterministic business logic in plain code is sufficient.
- A static transformation without reasoning is sufficient.
<Note type="info" title="Enterprise Enhancement: Visual Agent Builder">
CrewAI AMP includes a Visual Agent Builder that simplifies agent creation and configuration without writing code. Design your agents visually and test them in real-time.

25
docs/en/concepts/crews.mdx
View File

@@ -9,6 +9,17 @@ mode: "wide"
A crew in crewAI represents a collaborative group of agents working together to achieve a set of tasks. Each crew defines the strategy for task execution, agent collaboration, and the overall workflow.
## When to Use Crews
- You need multiple specialized agents collaborating on a shared outcome.
- You need process-level orchestration (`sequential` or `hierarchical`).
- You need task-level handoffs and context propagation.
## When Not to Use Crews
- A single agent can complete the work end-to-end.
- You do not need multi-step task decomposition.
## Crew Attributes
| Attribute | Parameters | Description |
@@ -417,3 +428,17 @@ crewai replay -t <task_id>
```
These commands let you replay from your latest kickoff tasks, still retaining context from previously executed tasks.
## Common Failure Modes
### Agents overlap responsibilities
- Cause: role/goal definitions are too broad.
- Fix: tighten role boundaries and task ownership.
### Hierarchical runs stall or degrade
- Cause: weak manager configuration or unclear delegation criteria.
- Fix: define a stronger manager objective and explicit completion criteria.
### Crew outputs are inconsistent
- Cause: expected outputs are underspecified across tasks.
- Fix: enforce structured outputs and stronger task contracts.

233
docs/en/concepts/flows.mdx
View File

@@ -19,6 +19,19 @@ Flows allow you to create structured, event-driven workflows. They provide a sea
4. **Flexible Control Flow**: Implement conditional logic, loops, and branching within your workflows.
## When to Use Flows
- You need deterministic orchestration and branching logic.
- You need explicit state transitions across multiple steps.
- You need resumable workflows with persistence.
- You need to combine crews, direct model calls, and Python logic in one runtime.
## When Not to Use Flows
- A single prompt/response call is sufficient.
- A single crew kickoff with no orchestration logic is sufficient.
- You do not need stateful multi-step execution.
## Getting Started
The example below shows a realistic Flow for support-ticket triage. It demonstrates features teams use in production: typed state, routing, memory access, and persistence.
@@ -767,201 +780,17 @@ This example demonstrates several key features of using Agents in flows:
3. **Tool Integration**: Agents can use tools (like `WebsiteSearchTool`) to enhance their capabilities.
## Adding Crews to Flows
## Multi-Crew Flows and Plotting
Creating a flow with multiple crews in CrewAI is straightforward.
Detailed build walkthroughs and project scaffolding are documented in guide pages to keep this concepts page focused.
You can generate a new CrewAI project that includes all the scaffolding needed to create a flow with multiple crews by running the following command:
- Build your first flow: [/en/guides/flows/first-flow](/en/guides/flows/first-flow)
- Master state and persistence: [/en/guides/flows/mastering-flow-state](/en/guides/flows/mastering-flow-state)
- Real-world chat-state pattern: [/en/learn/flowstate-chat-history](/en/learn/flowstate-chat-history)
```bash
crewai create flow name_of_flow
```
This command will generate a new CrewAI project with the necessary folder structure. The generated project includes a prebuilt crew called `poem_crew` that is already working. You can use this crew as a template by copying, pasting, and editing it to create other crews.
### Folder Structure
After running the `crewai create flow name_of_flow` command, you will see a folder structure similar to the following:
| Directory/File | Description |
| :--------------------- | :----------------------------------------------------------------- |
| `name_of_flow/` | Root directory for the flow. |
| ├── `crews/` | Contains directories for specific crews. |
| │ └── `poem_crew/` | Directory for the "poem_crew" with its configurations and scripts. |
| │ ├── `config/` | Configuration files directory for the "poem_crew". |
| │ │ ├── `agents.yaml` | YAML file defining the agents for "poem_crew". |
| │ │ └── `tasks.yaml` | YAML file defining the tasks for "poem_crew". |
| │ ├── `poem_crew.py` | Script for "poem_crew" functionality. |
| ├── `tools/` | Directory for additional tools used in the flow. |
| │ └── `custom_tool.py` | Custom tool implementation. |
| ├── `main.py` | Main script for running the flow. |
| ├── `README.md` | Project description and instructions. |
| ├── `pyproject.toml` | Configuration file for project dependencies and settings. |
| └── `.gitignore` | Specifies files and directories to ignore in version control. |
### Building Your Crews
In the `crews` folder, you can define multiple crews. Each crew will have its own folder containing configuration files and the crew definition file. For example, the `poem_crew` folder contains:
- `config/agents.yaml`: Defines the agents for the crew.
- `config/tasks.yaml`: Defines the tasks for the crew.
- `poem_crew.py`: Contains the crew definition, including agents, tasks, and the crew itself.
You can copy, paste, and edit the `poem_crew` to create other crews.
### Connecting Crews in `main.py`
The `main.py` file is where you create your flow and connect the crews together. You can define your flow by using the `Flow` class and the decorators `@start` and `@listen` to specify the flow of execution.
Here's an example of how you can connect the `poem_crew` in the `main.py` file:
```python Code
#!/usr/bin/env python
from random import randint
from pydantic import BaseModel
from crewai.flow.flow import Flow, listen, start
from .crews.poem_crew.poem_crew import PoemCrew
class PoemState(BaseModel):
sentence_count: int = 1
poem: str = ""
class PoemFlow(Flow[PoemState]):
@start()
def generate_sentence_count(self):
print("Generating sentence count")
self.state.sentence_count = randint(1, 5)
@listen(generate_sentence_count)
def generate_poem(self):
print("Generating poem")
result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count})
print("Poem generated", result.raw)
self.state.poem = result.raw
@listen(generate_poem)
def save_poem(self):
print("Saving poem")
with open("poem.txt", "w") as f:
f.write(self.state.poem)
def kickoff():
poem_flow = PoemFlow()
poem_flow.kickoff()
def plot():
poem_flow = PoemFlow()
poem_flow.plot("PoemFlowPlot")
if __name__ == "__main__":
kickoff()
plot()
```
In this example, the `PoemFlow` class defines a flow that generates a sentence count, uses the `PoemCrew` to generate a poem, and then saves the poem to a file. The flow is kicked off by calling the `kickoff()` method. The PoemFlowPlot will be generated by `plot()` method.
![Flow Visual image](/images/crewai-flow-8.png)
### Running the Flow
(Optional) Before running the flow, you can install the dependencies by running:
```bash
crewai install
```
Once all of the dependencies are installed, you need to activate the virtual environment by running:
```bash
source .venv/bin/activate
```
After activating the virtual environment, you can run the flow by executing one of the following commands:
```bash
crewai flow kickoff
```
or
```bash
uv run kickoff
```
The flow will execute, and you should see the output in the console.
## Plot Flows
Visualizing your AI workflows can provide valuable insights into the structure and execution paths of your flows. CrewAI offers a powerful visualization tool that allows you to generate interactive plots of your flows, making it easier to understand and optimize your AI workflows.
### What are Plots?
Plots in CrewAI are graphical representations of your AI workflows. They display the various tasks, their connections, and the flow of data between them. This visualization helps in understanding the sequence of operations, identifying bottlenecks, and ensuring that the workflow logic aligns with your expectations.
### How to Generate a Plot
CrewAI provides two convenient methods to generate plots of your flows:
#### Option 1: Using the `plot()` Method
If you are working directly with a flow instance, you can generate a plot by calling the `plot()` method on your flow object. This method will create an HTML file containing the interactive plot of your flow.
```python Code
# Assuming you have a flow instance
flow.plot("my_flow_plot")
```
This will generate a file named `my_flow_plot.html` in your current directory. You can open this file in a web browser to view the interactive plot.
#### Option 2: Using the Command Line
If you are working within a structured CrewAI project, you can generate a plot using the command line. This is particularly useful for larger projects where you want to visualize the entire flow setup.
```bash
crewai flow plot
```
This command will generate an HTML file with the plot of your flow, similar to the `plot()` method. The file will be saved in your project directory, and you can open it in a web browser to explore the flow.
### Understanding the Plot
The generated plot will display nodes representing the tasks in your flow, with directed edges indicating the flow of execution. The plot is interactive, allowing you to zoom in and out, and hover over nodes to see additional details.
By visualizing your flows, you can gain a clearer understanding of the workflow's structure, making it easier to debug, optimize, and communicate your AI processes to others.
### Conclusion
Plotting your flows is a powerful feature of CrewAI that enhances your ability to design and manage complex AI workflows. Whether you choose to use the `plot()` method or the command line, generating plots will provide you with a visual representation of your workflows, aiding in both development and presentation.
## Next Steps
If you're interested in exploring additional examples of flows, we have a variety of recommendations in our examples repository. Here are four specific flow examples, each showcasing unique use cases to help you match your current problem type to a specific example:
1. **Email Auto Responder Flow**: This example demonstrates an infinite loop where a background job continually runs to automate email responses. It's a great use case for tasks that need to be performed repeatedly without manual intervention. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow)
2. **Lead Score Flow**: This flow showcases adding human-in-the-loop feedback and handling different conditional branches using the router. It's an excellent example of how to incorporate dynamic decision-making and human oversight into your workflows. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow)
3. **Write a Book Flow**: This example excels at chaining multiple crews together, where the output of one crew is used by another. Specifically, one crew outlines an entire book, and another crew generates chapters based on the outline. Eventually, everything is connected to produce a complete book. This flow is perfect for complex, multi-step processes that require coordination between different tasks. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows)
4. **Meeting Assistant Flow**: This flow demonstrates how to broadcast one event to trigger multiple follow-up actions. For instance, after a meeting is completed, the flow can update a Trello board, send a Slack message, and save the results. It's a great example of handling multiple outcomes from a single event, making it ideal for comprehensive task management and notification systems. [View Example](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow)
By exploring these examples, you can gain insights into how to leverage CrewAI Flows for various use cases, from automating repetitive tasks to managing complex, multi-step processes with dynamic decision-making and human feedback.
Also, check out our YouTube video on how to use flows in CrewAI below!
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/MTb5my6VOT8"
title="CrewAI Flows overview"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
referrerPolicy="strict-origin-when-cross-origin"
allowFullScreen
></iframe>
For visualization:
- Use `flow.plot("my_flow_plot")` in code, or
- Use `crewai flow plot` in CLI projects.
## Running Flows
@@ -972,7 +801,7 @@ There are two ways to run a flow:
You can run a flow programmatically by creating an instance of your flow class and calling the `kickoff()` method:
```python
flow = ExampleFlow()
flow = SupportTriageFlow()
result = flow.kickoff()
```
@@ -1091,3 +920,21 @@ crewai flow kickoff
```
However, the `crewai run` command is now the preferred method as it works for both crews and flows.
## Common Failure Modes
### Router branch not firing
- Cause: returned label does not match a `@listen("label")` value.
- Fix: align router return strings with listener labels exactly.
### State fields missing at runtime
- Cause: untyped dynamic fields or missing kickoff inputs.
- Fix: use typed state and validate required fields in `@start()`.
### Prompt/token growth over time
- Cause: appending unbounded message history in state.
- Fix: apply sliding-window state and summary compaction patterns.
### Non-idempotent retries
- Cause: side effects executed on retried steps.
- Fix: add idempotency keys/markers to state and guard external writes.

1011
docs/en/concepts/llms.mdx
View File

File diff suppressed because it is too large Load Diff

25
docs/en/concepts/planning.mdx
View File

@@ -10,6 +10,17 @@ mode: "wide"
The planning feature in CrewAI allows you to add planning capability to your crew. When enabled, before each Crew iteration,
all Crew information is sent to an AgentPlanner that will plan the tasks step by step, and this plan will be added to each task description.
## When to Use Planning
- Tasks require multi-step decomposition before execution.
- You need more consistent execution quality on complex tasks.
- You want transparent planning traces in crew runs.
## When Not to Use Planning
- Tasks are simple and deterministic.
- Latency and token budget are strict and planning overhead is not justified.
### Using the Planning Feature
Getting started with the planning feature is very easy, the only step required is to add `planning=True` to your Crew:
@@ -31,7 +42,7 @@ my_crew = Crew(
From this point on, your crew will have planning enabled, and the tasks will be planned before each iteration.
<Warning>
When planning is enabled, crewAI will use `gpt-4o-mini` as the default LLM for planning, which requires a valid OpenAI API key. Since your agents might be using different LLMs, this could cause confusion if you don't have an OpenAI API key configured or if you're experiencing unexpected behavior related to LLM API calls.
Planning model defaults can vary by version and environment. To avoid implicit provider dependencies, set `planning_llm` explicitly in your crew configuration.
</Warning>
#### Planning LLM
@@ -152,4 +163,14 @@ A list with 10 bullet points of the most relevant information about AI LLMs.
**Expected Output:**
A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'.
```
</CodeGroup>
</CodeGroup>
## Common Failure Modes
### Planning adds cost/latency without quality gains
- Cause: planning enabled for simple tasks.
- Fix: disable `planning` for straightforward pipelines.
### Unexpected provider authentication errors
- Cause: implicit planner model/provider assumptions.
- Fix: set `planning_llm` explicitly and ensure matching credentials are configured.

23
docs/en/concepts/processes.mdx
View File

@@ -12,11 +12,20 @@ mode: "wide"
These processes ensure tasks are distributed and executed efficiently, in alignment with a predefined strategy.
</Tip>
## When to Use Each Process
- Use `sequential` when task order is fixed and outputs feed directly into the next task.
- Use `hierarchical` when you need a manager to delegate and validate work dynamically.
## When Not to Use Hierarchical
- You do not need dynamic delegation.
- You cannot provide a reliable `manager_llm` or `manager_agent`.
## Process Implementations
- **Sequential**: Executes tasks sequentially, ensuring tasks are completed in an orderly progression.
- **Hierarchical**: Organizes tasks in a managerial hierarchy, where tasks are delegated and executed based on a structured chain of command. A manager language model (`manager_llm`) or a custom manager agent (`manager_agent`) must be specified in the crew to enable the hierarchical process, facilitating the creation and management of tasks by the manager.
- **Consensual Process (Planned)**: Aiming for collaborative decision-making among agents on task execution, this process type introduces a democratic approach to task management within CrewAI. It is planned for future development and is not currently implemented in the codebase.
## The Role of Processes in Teamwork
Processes enable individual agents to operate as a cohesive unit, streamlining their efforts to achieve common objectives with efficiency and coherence.
@@ -59,9 +68,17 @@ Emulates a corporate hierarchy, CrewAI allows specifying a custom manager agent
## Process Class: Detailed Overview
The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`). The consensual process is planned for future inclusion, emphasizing our commitment to continuous development and innovation.
The `Process` class is implemented as an enumeration (`Enum`), ensuring type safety and restricting process values to the defined types (`sequential`, `hierarchical`).
## Conclusion
The structured collaboration facilitated by processes within CrewAI is crucial for enabling systematic teamwork among agents.
This documentation has been updated to reflect the latest features, enhancements, and the planned integration of the Consensual Process, ensuring users have access to the most current and comprehensive information.
## Common Failure Modes
### Hierarchical process fails at startup
- Cause: missing `manager_llm` or `manager_agent`.
- Fix: provide one of them explicitly in crew configuration.
### Sequential process produces weak outputs
- Cause: task boundaries/context are underspecified.
- Fix: improve task descriptions, expected outputs, and task context chaining.

23
docs/en/concepts/testing.mdx
View File

@@ -9,9 +9,20 @@ mode: "wide"
Testing is a crucial part of the development process, and it is essential to ensure that your crew is performing as expected. With crewAI, you can easily test your crew and evaluate its performance using the built-in testing capabilities.
## When to Use Testing
- Before promoting a crew to production.
- After changing prompts, tools, or model configurations.
- When benchmarking quality/cost/latency tradeoffs.
## When Not to Rely on Testing Alone
- For safety-critical deployments without human review gates.
- When test datasets are too small or unrepresentative.
### Using the Testing Feature
We added the CLI command `crewai test` to make it easy to test your crew. This command will run your crew for a specified number of iterations and provide detailed performance metrics. The parameters are `n_iterations` and `model`, which are optional and default to 2 and `gpt-4o-mini` respectively. For now, the only provider available is OpenAI.
Use the CLI command `crewai test` to run repeated crew executions and compare outputs across iterations. The parameters are `n_iterations` and `model`, which are optional and default to `2` and `gpt-4o-mini`.
```bash
crewai test
@@ -47,3 +58,13 @@ A table of scores at the end will show the performance of the crew in terms of t
| Execution Time (s) | 126 | 145 | **135** | | |
The example above shows the test results for two runs of the crew with two tasks, with the average total score for each task and the crew as a whole.
## Common Failure Modes
### Scores fluctuate too much between runs
- Cause: high sampling randomness or unstable prompts.
- Fix: lower temperature and tighten output constraints.
### Good test scores but poor production quality
- Cause: test prompts do not match real workload.
- Fix: build a representative test set from real production inputs.

25
docs/en/concepts/tools.mdx
View File

@@ -10,6 +10,17 @@ mode: "wide"
CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers.
This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools.
## When to Use Tools
- Agents need external data or side effects.
- You need deterministic actions wrapped in reusable interfaces.
- You need to connect APIs, files, databases, or browser actions into agent workflows.
## When Not to Use Tools
- The task can be solved entirely from prompt context.
- The external side effect cannot be made safe or idempotent.
## What is a Tool?
A tool in CrewAI is a skill or function that agents can utilize to perform various actions.
@@ -285,3 +296,17 @@ writer1 = Agent(
Tools are pivotal in extending the capabilities of CrewAI agents, enabling them to undertake a broad spectrum of tasks and collaborate effectively.
When building solutions with CrewAI, leverage both custom and existing tools to empower your agents and enhance the AI ecosystem. Consider utilizing error handling,
caching mechanisms, and the flexibility of tool arguments to optimize your agents' performance and capabilities.
## Common Failure Modes
### Tool schema mismatch
- Cause: model-generated arguments do not match tool signature.
- Fix: tighten tool descriptions and validate input schemas.
### Repeated side effects
- Cause: retries trigger duplicate writes/actions.
- Fix: add idempotency keys and deduplication checks in tool logic.
### Tool timeouts under load
- Cause: unbounded retries or slow external services.
- Fix: set explicit timeout/retry policy and graceful fallbacks.