ImportError / ModuleNotFoundError
builtins.ImportError: cannot import name 'agent' / 'task' / 'crew' from 'crewai.project'
Stack trace
Traceback (most recent call last):
File "my_crew.py", line 2, in <module>
from crewai.project import agent, task, crew, CrewBase
ModuleNotFoundError: cannot import name 'agent' from 'crewai.project' (/usr/local/lib/python3.11/site-packages/crewai/project.py)
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "my_crew.py", line 1, in <module>
from crewai import Agent, Task, Crew, agent, task, crew
ImportError: cannot import name 'agent' from 'crewai' (/usr/local/lib/python3.11/site-packages/crewai/__init__.py) Why it happens
CrewAI introduced the @agent, @task, and @crew decorators and CrewBase class in version 0.55.0 as part of a major refactor to enable class-based crew definitions with method decorators. If you're running crewai<0.55.0, these decorators do not exist in the module. Additionally, the decorators are only available when properly imported from crewai.project after the package has been updated and installed correctly: typos in the import path or importing from the wrong submodule causes Python to raise ImportError.
Detection
Run `pip show crewai` to check your installed version before attempting to use decorators. Add `import crewai; print(crewai.__version__)` at the top of your script to log the version at runtime. Check that your virtual environment is activated and matches the crewai version in requirements.txt.
Causes & fixes
crewai version is <0.55.0 and does not include the @agent, @task, @crew decorators
Upgrade crewai to v0.55.0 or later: `pip install --upgrade crewai>=0.55.0`. Verify with `pip show crewai` and restart your Python interpreter.
Importing decorators from wrong submodule (crewai instead of crewai.project)
Change import from `from crewai import agent, task, crew` to `from crewai.project import agent, task, crew, CrewBase`. The decorators are only exposed in crewai.project.
CrewBase class not imported, causing decorator methods to fail or not be recognized
Always import CrewBase alongside the decorators: `from crewai.project import agent, task, crew, CrewBase`. Your crew class must inherit from CrewBase for decorators to work.
Virtual environment is stale or crewai installation is incomplete after pip install
Deactivate and reactivate your virtual environment. Run `pip install --upgrade --force-reinstall crewai>=0.55.0` to force a clean install. Then restart your Python interpreter and IDE.
Code: broken vs fixed
#!/usr/bin/env python3
# BROKEN: importing decorators from wrong module — crewai<0.55 or wrong import path
from crewai import Agent, Task, Crew, agent, task, crew # ❌ ImportError: cannot import name 'agent'
from crewai.project import CrewBase
import os
class MyCrew(CrewBase):
@agent # ❌ Decorator fails because 'agent' is not imported
def researcher(self) -> Agent:
return Agent(
role="Researcher",
goal="Research AI topics",
backstory="Expert researcher",
llm="gpt-4o-mini"
)
@task
def research_task(self) -> Task:
return Task(
description="Research generative AI",
expected_output="Research summary",
agent=self.researcher()
)
if __name__ == "__main__":
crew = MyCrew().crew()
crew.kickoff()#!/usr/bin/env python3
# FIXED: proper imports from crewai.project + CrewBase inheritance (crewai>=0.55.0)
from crewai.project import agent, task, crew, CrewBase # ✅ Correct: decorators from crewai.project
from crewai import Agent, Task, Crew, Process
import os
class MyCrew(CrewBase):
"""MyCrew crew definition with @agent, @task, @crew decorators."""
@agent
def researcher(self) -> Agent:
return Agent(
role="Researcher",
goal="Research AI topics",
backstory="Expert researcher",
llm="gpt-4o-mini"
)
@task
def research_task(self) -> Task:
return Task(
description="Research generative AI",
expected_output="Research summary",
agent=self.researcher()
)
@crew
def crew(self) -> Crew:
"""Create and return the Crew."""
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True
)
if __name__ == "__main__":
crew_instance = MyCrew().crew()
crew_instance.kickoff()
print("Crew execution completed successfully.")Workaround
If you cannot upgrade crewai immediately, use the pre-0.55 Task/Agent/Crew pattern without decorators: define Agent and Task objects directly, then pass them to Crew() without using @agent/@task/@crew decorators. Create a Crew instance with `crew = Crew(agents=[...], tasks=[...])` and call `crew.kickoff()`. This works on all versions but lacks the cleaner decorator syntax and CrewBase class organization.
Prevention
Lock your crewai version in requirements.txt to >=0.55.0 to ensure all team members and CI/CD environments use the decorator-enabled version. Add a version check at the top of your crew entry point: `import crewai; assert crewai.__version__ >= '0.55.0', f'crewai>=0.55.0 required, got {crewai.__version__}'`. Use type hints and IDE autocomplete (which will fail on wrong imports) to catch import mistakes before runtime.