What is train()?
Crew.train(n_iterations, filename) is CrewAI's built-in supervised fine-tuning loop for a whole crew: each iteration calls kickoff(), surfaces outputs to a human rater, records thumbs-up/down or richer labels, and appends that signal to a pickle file you ship with the project or load in CI. On later kickoffs the runtime replays stored preferences so agents steer toward phrasing, structure, and tool choices that previously scored well — without you hand-editing prompts for every edge case.
Treat training as an offline data-collection job, not a live API path. The loop blocks for human input, so it belongs on a developer machine or a dedicated review queue — never behind a user-facing HTTP handler. Version the pickle like any artifact: name files after the crew schema version and pin the crewai release you trained against so embeddings and tool contracts stay aligned.
Pair train() with test() once you have a baseline: training improves mean quality while testing guards against regressions when you change tasks, tools, or models. After a major crew refactor, consider re-running training rather than assuming old feedback still applies.
Use Cases
- • Iterative quality improvement
- • Domain adaptation
Key Features
- ✓ Human-in-loop training
- ✓ Persisted across runs
- ✓ Replayed by kickoff()
When NOT to Use
Production runs — train offline, run kickoff() in prod.
Notes
Human latency dominates cost
Wall-clock time is usually waiting on reviewers, not LLM tokens. Schedule training in focused blocks, reuse the same raters for consistent labels, and cap n_iterations so the loop finishes before context on the task evaporates.
Pickle portability and security
Pickles execute on load. Treat training files like credentials: store in private object storage, never accept arbitrary uploads into train(), and regenerate after dependency upgrades that touch serialization.
Model and tool drift
Feedback collected on gpt-4.1 may not transfer cleanly after you switch providers or add tools. Re-validate with test() whenever the crew graph changes materially.
Contrast with prompt-only iteration
train() captures implicit preferences across many runs. If you only need a one-off instruction tweak, editing YAML or task descriptions is cheaper than spinning a training loop.
Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| n_iterations | int | No | How many training runs to execute. |
| filename | str | No | File where collected feedback is persisted. |
Code Examples
CLI
crewai train -n 5 -f trained.pklPython call after assembling a crew
from crewai import Crew, Agent, Task, Process
crew = Crew(agents=[...], tasks=[...], process=Process.sequential)
crew.train(n_iterations=3, filename='./artifacts/legal_review.pkl')Fixture that wipes training state between tests
import os
import pytest
@pytest.fixture
def trained_path(tmp_path):
p = tmp_path / 'train.pkl'
yield str(p)
if p.exists():
p.unlink()When to Use
When agent output is inconsistent and you want supervised tuning.
Common Mistakes
❌ Training in production with live users in the loop
✅ Train offline; deploy the resulting pickle.
Related: @tool decorator reference, Agent class reference, and the first Crew tutorial.
train() FAQ
What is train() in CrewAI?
Iteratively runs the crew and collects human feedback to improve agent behavior. Crew.train(n_iterations, filename) is CrewAI's built-in supervised fine-tuning loop for a whole crew: each iteration calls kickoff(), surfaces outputs to a human rater, records thumbs-up/down or richer labels, and appends that signal to a pickle file you ship with the project or load in CI. On later kickoffs the runtime replays stored preferences so agents steer toward phrasing, structure, and tool choices that previously scored well — without you hand-editing prompts for eve…
Which CrewAI types expose the method train()?
DevShelfHub documents train() on Crew. The reference maps it to Python module crewai.Crew — pin your installed crewai version and match imports to the snippet on this page.
When should I use train()?
When agent output is inconsistent and you want supervised tuning.
When should I avoid train()?
Production runs — train offline, run kickoff() in prod.
How do I call train() from Python?
crew.train(n_iterations=5, filename='trained.pkl')
Where can I explore more CrewAI API reference pages?
Open the CrewAI API reference index on DevShelfHub to search classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.