1. Too Many Agents
Beginners build 7-agent crews because the demo videos do. Don't. Each agent adds an LLM call, a coordination point, and a failure mode.
Rule: Start with 2 agents. Add a 3rd only when you can name a clear failure mode the new agent will fix.
2. Vague Roles & Goals
"Helper", "Assistant", "Expert" — these produce mush. Specific roles produce specific outputs.
Before / After
# ❌ Mush
Agent(role="Writer", goal="Write content")
# ✓ Sharp
Agent(
role="B2B SaaS Copywriter",
goal="Write 200-word LinkedIn posts that drive demo bookings",
)3. Weak expected_output
If the agent has to guess the output format, it will guess differently every run. Pin it down.
Pin the format
expected_output=(
"Markdown table: | Segment | Churn % | Top Driver |\n"
"Followed by exactly 3 paragraphs, one per segment, "
"each starting with the segment name in bold."
)4. Infinite Loops & Cost Overruns
Default max_iter=25 with GPT-4 is how people accidentally rack up $50 bills.
Tighten limits in dev
agent = Agent(role="...", goal="...", backstory="...", max_iter=5, max_execution_time=120)5. Tool Soup
Giving one agent 12 tools confuses the model. It picks wrong, wastes turns, and hits max_iter.
Rule: 2–4 tools per agent. If you need more, split the agent.
6. Delegation Without Boundaries
Setting allow_delegation=True on every agent creates an unbounded chain of "ask the next person" loops.
Rule: Only the manager (or one designated lead) gets allow_delegation=True. Everyone else: False.
7. No Eval Loop
You can't improve what you don't measure. Even 5 hand-graded test runs beats vibes.
Tiny eval harness
cases = [
{"topic": "RAG", "must_contain": ["retrieval", "embedding"]},
{"topic": "agents", "must_contain": ["tool", "task"]},
]
for case in cases:
out = str(crew.kickoff(inputs={"topic": case["topic"]})).lower()
for kw in case["must_contain"]:
assert kw in out, f"Missing {kw} for {case[\'topic\']}"
print("All cases passed.")Best-Practices Checklist
Agents have specific, domain-rooted roles
Every task has a concrete expected_output
max_iter set per agent (5–10 in dev)
2–4 tools per agent, with strong docstrings
Delegation off by default; sequential process by default
Verbose logging captured to file in prod
Eval harness with at least 5 cases before shipping
Notes
Best practices age with model releases
What worked on last quarter's default model may regress overnight. Re-run your eval harness after provider upgrades, not only after you change prompts.
Checklists only help if owners exist
Assign a single DRI for logging, secrets, and cost dashboards. Diffuse ownership is how verbose logs and shared API keys creep back into production.
Treat eval cases like product analytics events
Version your golden scenarios in git, tag failures with model IDs, and review trends monthly. Otherwise you cannot tell whether quality slipped or the world changed.
Smaller crews simplify incident response
During outages, fewer agents means fewer hypotheses. Resist the urge to add a "fixer" agent mid-incident; stabilize inputs and tools first.
CrewAI best practices FAQ
What are the most common CrewAI pitfalls?
Teams oversize crews, leave verbose logging on in production, skip eval harnesses, and ignore token ceilings. Start with two agents, add structure with clear task contracts, and measure cost per run before scaling traffic.
How many agents should a CrewAI crew start with?
Start with two agents and a sequential process until outputs are stable. Add a third agent only when you can name a failure mode it fixes, because each agent multiplies latency, cost, and coordination risk.
How do I stop role bleed between CrewAI agents?
Tighten role, goal, and backstory fields so responsibilities do not overlap, reduce shared tool access, and use explicit expected_output strings. When bleed persists, split tasks or serialize handoffs.
What should CrewAI production logging look like?
Capture structured traces, redact secrets, and avoid streaming raw prompts to end users. Use verbose mode locally, then switch to tracing or callbacks with sampling in production.
Why run an eval harness before shipping a CrewAI crew?
LLM outputs drift with model updates and prompt changes. A small golden set of scenarios catches regressions early and gives you a go or no-go signal before you expose automation to customers.
See also: DevShelfHub's CrewAI tool review for a product-level comparison, pricing notes, and links back into this tutorial series.