How to Use CrewAI for Role-based agent definitions

CrewAI works well for role-based agent definitions when you run it like production work: locked brief, SOURCE facts, then review before publish. CrewAI is a framework for orchestrating role-based AI agent teams that collaborate on research, content, and analysis tasks, with defined agents, tasks, and tools. Confirm live plans and docs on crewai.com. Test on sandbox data first. Start at /explore/crewai.

This guide focuses on role-based agent definitions in detail. Related CrewAI articles: /blog/how-to-use-crewai-for-task-and-tool-orchestration, /blog/how-to-use-crewai-for-research-crew-workflows, /blog/how-to-use-crewai-for-content-crew-workflows.

When this workflow is the right job

Use role-based agent definitions when the deliverable is specifically this CrewAI job. Switch to task and tool orchestration when that workflow already owns the asset.

Step by step workflow

1. Brief Role-based agent definitions

Write what must stay true for role-based agent definitions in CrewAI before settings or spend.

Brief: Role-based agent definitions
Keep: verified SOURCE facts only
Avoid: invented pricing or features
Success: one reviewable output

2. Open CrewAI for Role-based agent definitions

Use the CrewAI surface that owns role-based agent definitions. Do not mix a neighboring workflow in the same pass.

Surface: Role-based agent definitions
Start: pilot with one representative input
Plans: www.crewai.com

3. Pilot Role-based agent definitions

Run a single role-based agent definitions pilot. Score clarity, grounding, and whether the output is reviewable.

Pilot: Role-based agent definitions
[ ] SOURCE facts match
[ ] Output reviewable
[ ] Settings logged

4. Refine Role-based agent definitions

Change one role-based agent definitions dimension only. Save a template from the best run.

Refine: Role-based agent definitions
Change: one control only
Keep: SOURCE and success criteria

Practical role-based agent definitions examples

Edge-case check

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Edge-case check".

Objective:
Define a multi-agent or agentic run for Edge-case check with human gates.

Inputs:
- Goal for Edge-case check
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Edge-case check → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Edge-case check with roles, gates, and a successful pilot log.

Decision log

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Decision log".

Objective:
Define a multi-agent or agentic run for Decision log with human gates.

Inputs:
- Goal for Decision log
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Decision log → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Decision log with roles, gates, and a successful pilot log.

Rate limit

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Rate limit".

Objective:
Define a multi-agent or agentic run for Rate limit with human gates.

Inputs:
- Goal for Rate limit
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Rate limit → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Rate limit with roles, gates, and a successful pilot log.

Error alert

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Error alert".

Objective:
Define a multi-agent or agentic run for Error alert with human gates.

Inputs:
- Goal for Error alert
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Error alert → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Error alert with roles, gates, and a successful pilot log.

Stop condition

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Stop condition".

Objective:
Define a multi-agent or agentic run for Stop condition with human gates.

Inputs:
- Goal for Stop condition
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Stop condition → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Stop condition with roles, gates, and a successful pilot log.

Shared memory note

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Shared memory note".

Objective:
Define a multi-agent or agentic run for Shared memory note with human gates.

Inputs:
- Goal for Shared memory note
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Shared memory note → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Shared memory note with roles, gates, and a successful pilot log.

Code exec off

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Code exec off".

Objective:
Define a multi-agent or agentic run for Code exec off with human gates.

Inputs:
- Goal for Code exec off
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Code exec off → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Code exec off with roles, gates, and a successful pilot log.

Human approve send

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Human approve send".

Objective:
Define a multi-agent or agentic run for Human approve send with human gates.

Inputs:
- Goal for Human approve send
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Human approve send → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Human approve send with roles, gates, and a successful pilot log.

Eval rubric

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Eval rubric".

Objective:
Define a multi-agent or agentic run for Eval rubric with human gates.

Inputs:
- Goal for Eval rubric
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Eval rubric → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Eval rubric with roles, gates, and a successful pilot log.

Multi-turn plan

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Multi-turn plan".

Objective:
Define a multi-agent or agentic run for Multi-turn plan with human gates.

Inputs:
- Goal for Multi-turn plan
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Multi-turn plan → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Multi-turn plan with roles, gates, and a successful pilot log.

Failure branch

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Failure branch".

Objective:
Define a multi-agent or agentic run for Failure branch with human gates.

Inputs:
- Goal for Failure branch
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Failure branch → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Failure branch with roles, gates, and a successful pilot log.

Owner per step

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Owner per step".

Objective:
Define a multi-agent or agentic run for Owner per step with human gates.

Inputs:
- Goal for Owner per step
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Owner per step → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Owner per step with roles, gates, and a successful pilot log.

Trace export

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Trace export".

Objective:
Define a multi-agent or agentic run for Trace export with human gates.

Inputs:
- Goal for Trace export
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Trace export → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Trace export with roles, gates, and a successful pilot log.

Pilot then scale

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Pilot then scale".

Objective:
Define a multi-agent or agentic run for Pilot then scale with human gates.

Inputs:
- Goal for Pilot then scale
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Pilot then scale → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Pilot then scale with roles, gates, and a successful pilot log.

Coder agent

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Coder agent".

Objective:
Define a multi-agent or agentic run for Coder agent with human gates.

Inputs:
- Goal for Coder agent
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Coder agent → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Coder agent with roles, gates, and a successful pilot log.

Reviewer agent

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Reviewer agent".

Objective:
Define a multi-agent or agentic run for Reviewer agent with human gates.

Inputs:
- Goal for Reviewer agent
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Reviewer agent → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Reviewer agent with roles, gates, and a successful pilot log.

HITL gate

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "HITL gate".

Objective:
Define a multi-agent or agentic run for HITL gate with human gates.

Inputs:
- Goal for HITL gate
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for HITL gate → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for HITL gate with roles, gates, and a successful pilot log.

Tool allowlist

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Tool allowlist".

Objective:
Define a multi-agent or agentic run for Tool allowlist with human gates.

Inputs:
- Goal for Tool allowlist
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Tool allowlist → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Tool allowlist with roles, gates, and a successful pilot log.

Sandbox sample

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Sandbox sample".

Objective:
Define a multi-agent or agentic run for Sandbox sample with human gates.

Inputs:
- Goal for Sandbox sample
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Sandbox sample → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Sandbox sample with roles, gates, and a successful pilot log.

Retry cap

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Retry cap".

Objective:
Define a multi-agent or agentic run for Retry cap with human gates.

Inputs:
- Goal for Retry cap
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Retry cap → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Retry cap with roles, gates, and a successful pilot log.

Role charter

Scenario:
A builder configures Role-based agent definitions in CrewAI with focus "Role charter".

Objective:
Define a multi-agent or agentic run for Role charter with human gates.

Inputs:
- Goal for Role charter
- Agent roles
- Tool allowlist
- Stop/approval conditions

Workflow:
Define roles → Connect tools → Pilot Role-based agent definitions for Role charter → Review → Cap retries → Scale

Requirements:
- Stay within verified CrewAI capabilities; do not invent features.
- Confirm live plan notes on www.crewai.com before promising volume.
- Change one variable between iterations.
- Human-review before external publish, send, billing, or clinical/legal use.
- Test on sandbox data before production volume.

Expected output:
A documented Role-based agent definitions setup for Role charter with roles, gates, and a successful pilot log.

How to improve role-based agent definitions

Cut noise from role-based agent definitions by removing extra adjectives while preserving SOURCE facts in CrewAI.

Raise quality by insisting on a single success check before debating style.

Make review easier by labeling fields that must never change.

Speed iteration by cloning the last good run and altering only one control.

Stabilize outputs by pinning settings after the pilot is approved.

Reduce rework by rejecting drafts that invent claims.

Improve handoffs by recording which control produced the best result.

Harden the workflow by testing an incomplete input before trusting defaults.

Prompting and usage guidance

Name the role-based agent definitions job, audience, and success check before opening CrewAI.

Paste only verified facts under SOURCE so CrewAI cannot invent details.

Specify the deliverable shape up front.

Call out fixed details versus flexible style choices.

Ask CrewAI to flag unsupported claims before you accept the draft.

Limitations to respect

Check CrewAI plan gates for role-based agent definitions on www.crewai.com before you promise timelines.

Keep drafts unpublished until a human confirms SOURCE facts.

CrewAI can be wrong. Treat role-based agent definitions as provisional until review.

If documentation is silent on a claim, leave it out rather than guessing.

Practical tips for this workflow

Pilot once before batching role-based agent definitions in CrewAI.

Keep a reusable template with variables for role-based agent definitions.

Separate creative instructions from SOURCE facts.

Log settings from the best run.

Common mistakes

• Skipping the pilot run before scaling volume
• Inventing pricing, quotas, or features not on official pages
• Mixing unrelated workflows in one session
• Publishing without a human review gate

Treat role-based agent definitions in CrewAI as a production workflow: brief, pilot, refine, then ship with review. Related reading: /blog/how-to-use-crewai-for-task-and-tool-orchestration, /blog/how-to-use-crewai-for-research-crew-workflows, /blog/how-to-use-crewai-for-content-crew-workflows.