CrewAI Best Practices

Q: What is the single highest-leverage practice?

Clear expected_output plus host-enforced caps. Most thrash is unbounded work against a fuzzy definition of done.

Ten practices for scoping roles, tasks, and tools so a crew converges reliably. Use them as a design rubric before kickoff and as a PR checklist after the first verbose runs.

How to Use This Checklist

Walk A when designing agents and tasks; B when wiring process, tools, and memory; C when operating in production.
Tick an item only when code or docs prove it, not when you intend to do it later.
Pair with Debugging a Crew That Won't Converge on an Answer when a run thrashs.
Re-check after adding agents, tools, hierarchical managers, or knowledge corpora.

A - Scope Roles and Tasks

1. Start with the smallest crew that can finish the job. One or two specialists beat a five-agent org chart for most pipelines.
2. Give every agent a single job title and one outcome-shaped goal. Multi-hat roles hide ownership bugs.
3. Write expected_output as an acceptance test. If a human could not grade it, neither can your eval harness.
4. Make handoffs explicit with context and structured intermediate notes. Do not hope the next agent "remembers."
5. Parameterize runs with kickoff(inputs=...) placeholders. Keep evergreen constraints in role text; keep ticket specifics in tasks.

B - Process, Tools, and Memory

6. Default to sequential process; adopt hierarchical only with a real management need. Pay manager tokens on purpose.
7. Attach least-privilege tools per agent. Discoverers search; writers draft; nobody gets the whole company API surface by default.
8. Bound loops in code (max_iter, timeouts, retries, product budgets). Prompt wishes are not stop conditions.
9. Separate memory, knowledge, and dialog history. Memory for learned facts, knowledge for curated docs, conversation state for chat turns.
10. Pin embedders and storage paths when memory/knowledge are on. Avoid silent dimension mismatches and ephemeral container data loss.

C - Operate and Improve

11. Log per-task outputs, tool args, and token usage on every staging run. Optimize with evidence.
12. Prefer replay/checkpoint of failed tails over full re-runs of expensive research. Save money while iterating.
13. Treat tool and retrieval text as untrusted. Never let fetched content redefine policy or expand privileges.
14. Eval intermediate artifacts, not only the final paragraph. Catch handoff rot early.
15. Delete agents and tools that do not change quality metrics. Complexity tax compounds every sprint.

Applying These Practices in Order

Scope (1-5): cheapest to fix on a whiteboard; most expensive after tool sprawl.
Mechanics (6-10): launch blockers for anything that spends real money or touches real systems.
Operate (11-15): how crews stay honest after the demo.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core "converge reliably" practices promised in the section summary. Items 11-15 extend them into operations.

What is the single highest-leverage practice?

Clear expected_output plus host-enforced caps. Most thrash is unbounded work against a fuzzy definition of done.

When is multi-agent justified?

When roles need different tools, trust levels, or success metrics you can name. Otherwise use one agent.

Should every production crew enable memory?

No. Enable memory when cross-run learning helps, with pinned storage and reset strategy for tests.

How do these practices map to Flows/chat?

Crews still need scoped roles/tasks/tools inside routes. Chat sessions add session ids and history discipline on top.

Do hierarchical crews need different best practices?

Same foundations, plus a sharp manager goal, distinct workers, and budget for review tokens.

How should we review crew PRs?

Read role strings, task contracts, tool allowlists, process choice, and caps before reading clever helper code.

What belongs in CI?

Golden intermediate shapes, max tokens/time, and a tiny crew smoke test with mocked tools when possible.

How often should we revisit agent count?

Whenever cost, latency, or failure rates rise. Agent count is a product decision, not a permanent architecture trophy.

Can best practices replace debugging?

No. They reduce incidents; the debugging cheatsheet still matters when loops appear.

Where should teams link this list?

Section close-out, crew README templates, and ADRs that introduce a new multi-agent workflow.

Is JSONC/YAML config required for quality?

No. Structure and contracts matter more than file format. Config helps review at scale.

The CrewAI Mental Model: Roles, Tasks, and Crews - foundations
CrewAI Basics - first pipeline
Defining Agent Roles, Goals, and Backstories - role craft
Sequential vs Hierarchical Crew Processes - process choice
Building a Custom Tool for a CrewAI Agent - tool design
CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - memory/knowledge
The CrewAI Chat API for Interactive Crew Sessions - multi-turn sessions
Debugging a Crew That Won't Converge on an Answer - thrash checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

CrewAI Best Practices

Ten practices for scoping roles, tasks, and tools so a crew converges reliably. Use them as a design rubric before kickoff and as a PR checklist after the first verbose runs.

How to Use This Checklist

Walk A when designing agents and tasks; B when wiring process, tools, and memory; C when operating in production.
Tick an item only when code or docs prove it, not when you intend to do it later.
Pair with Debugging a Crew That Won't Converge on an Answer when a run thrashs.
Re-check after adding agents, tools, hierarchical managers, or knowledge corpora.

A - Scope Roles and Tasks

1. Start with the smallest crew that can finish the job. One or two specialists beat a five-agent org chart for most pipelines.
2. Give every agent a single job title and one outcome-shaped goal. Multi-hat roles hide ownership bugs.
3. Write expected_output as an acceptance test. If a human could not grade it, neither can your eval harness.
4. Make handoffs explicit with context and structured intermediate notes. Do not hope the next agent "remembers."
5. Parameterize runs with kickoff(inputs=...) placeholders. Keep evergreen constraints in role text; keep ticket specifics in tasks.

B - Process, Tools, and Memory

6. Default to sequential process; adopt hierarchical only with a real management need. Pay manager tokens on purpose.
7. Attach least-privilege tools per agent. Discoverers search; writers draft; nobody gets the whole company API surface by default.
8. Bound loops in code (max_iter, timeouts, retries, product budgets). Prompt wishes are not stop conditions.
9. Separate memory, knowledge, and dialog history. Memory for learned facts, knowledge for curated docs, conversation state for chat turns.
10. Pin embedders and storage paths when memory/knowledge are on. Avoid silent dimension mismatches and ephemeral container data loss.

C - Operate and Improve

11. Log per-task outputs, tool args, and token usage on every staging run. Optimize with evidence.
12. Prefer replay/checkpoint of failed tails over full re-runs of expensive research. Save money while iterating.
13. Treat tool and retrieval text as untrusted. Never let fetched content redefine policy or expand privileges.
14. Eval intermediate artifacts, not only the final paragraph. Catch handoff rot early.
15. Delete agents and tools that do not change quality metrics. Complexity tax compounds every sprint.

Applying These Practices in Order

Scope (1-5): cheapest to fix on a whiteboard; most expensive after tool sprawl.
Mechanics (6-10): launch blockers for anything that spends real money or touches real systems.
Operate (11-15): how crews stay honest after the demo.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core "converge reliably" practices promised in the section summary. Items 11-15 extend them into operations.

What is the single highest-leverage practice?

Clear expected_output plus host-enforced caps. Most thrash is unbounded work against a fuzzy definition of done.

When is multi-agent justified?

When roles need different tools, trust levels, or success metrics you can name. Otherwise use one agent.

Should every production crew enable memory?

No. Enable memory when cross-run learning helps, with pinned storage and reset strategy for tests.

How do these practices map to Flows/chat?

Crews still need scoped roles/tasks/tools inside routes. Chat sessions add session ids and history discipline on top.

Do hierarchical crews need different best practices?

Same foundations, plus a sharp manager goal, distinct workers, and budget for review tokens.

How should we review crew PRs?

Read role strings, task contracts, tool allowlists, process choice, and caps before reading clever helper code.

What belongs in CI?

Golden intermediate shapes, max tokens/time, and a tiny crew smoke test with mocked tools when possible.

How often should we revisit agent count?

Whenever cost, latency, or failure rates rise. Agent count is a product decision, not a permanent architecture trophy.

Can best practices replace debugging?

No. They reduce incidents; the debugging cheatsheet still matters when loops appear.

Where should teams link this list?

Section close-out, crew README templates, and ADRs that introduce a new multi-agent workflow.

Is JSONC/YAML config required for quality?

No. Structure and contracts matter more than file format. Config helps review at scale.

The CrewAI Mental Model: Roles, Tasks, and Crews - foundations
CrewAI Basics - first pipeline
Defining Agent Roles, Goals, and Backstories - role craft
Sequential vs Hierarchical Crew Processes - process choice
Building a Custom Tool for a CrewAI Agent - tool design
CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends - memory/knowledge
The CrewAI Chat API for Interactive Crew Sessions - multi-turn sessions
Debugging a Crew That Won't Converge on an Answer - thrash checklist

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

CrewAI Best Practices

Search Documentation

CrewAI Best Practices