crewai

CrewAI Best Practices

This document outlines the definitive best practices for developing with CrewAI, ensuring your multi-agent systems are maintainable, performant, and production-ready. Adhere to these guidelines for all new and existing CrewAI projects.

1. Code Organization and Structure

Always modularize your agents, tasks, and crews into dedicated Python modules. This promotes reusability, version control, and clear separation of concerns.

1.1. Dedicated Modules for Agents, Tasks, and Crews

Always separate definitions. Agents belong in agents.py, tasks in tasks.py, and the crew orchestration in crew.py (or main.py).

❌ BAD: Monolithic file

# main.py
from crewai import Agent, Task, Crew
researcher = Agent(role='Researcher', ...)
research_task = Task(description='Research topic', agent=researcher, ...)
crew = Crew(agents=[researcher], tasks=[research_task], ...)

✅ GOOD: Modular structure

# agents.py
from crewai import Agent
from tools import search_tool # Assume tools.py exists

class ResearchAgents:
    def senior_researcher(self) -> Agent:
        return Agent(
            role='Senior Researcher',
            goal='Uncover critical insights and data points.',
            backstory='Expert in data analysis and synthesis.',
            verbose=True, allow_delegation=False, tools=[search_tool]
        )

# tasks.py
from crewai import Task
from agents import ResearchAgents

class ResearchTasks:
    def __init__(self):
        self.agents = ResearchAgents()

    def research_topic(self, topic: str) -> Task:
        return Task(
            description=f"Conduct comprehensive research on '{topic}'.",
            expected_output='A detailed report summarizing key findings.',
            agent=self.agents.senior_researcher(),
            async_execution=False
        )

# crew.py
from crewai import Crew, Process
from agents import ResearchAgents
from tasks import ResearchTasks

class MyCrew:
    def __init__(self, topic: str):
        self.topic = topic
        self.agents = ResearchAgents()
        self.tasks = ResearchTasks()

    def run(self):
        crew = Crew(
            agents=[self.agents.senior_researcher()],
            tasks=[self.tasks.research_topic(self.topic)],
            process=Process.sequential,
            verbose=2
        )
        return crew.kickoff()

if __name__ == "__main__":
    result = MyCrew("AI Agent Frameworks in 2025").run()
    print(result)