Defining Agent Roles, Goals, and Backstories

Every CrewAI agent is steered by three strings: role, goal, and backstory.

Together they act as a job description the model cannot ignore as easily as a vague system prompt.

Summary

Write role as a crisp title, goal as a measurable outcome, and backstory as constraints plus taste - then pair them with least-privilege tools and tight task expected_output so behavior stays testable.

Recipe

1. Name the job, not the personality brand ("Research Analyst", not "GeniusBot").
2. Write a goal as a single outcome the agent optimizes ("produce citable notes", not "be helpful").
3. Add a backstory with domain, quality bar, and hard refusals (what it will not invent).
4. Align tools with that role only.
5. Mirror the goal in the task's expected_output so acceptance criteria match the job.
6. Use {placeholders} for run-specific topics; keep evergreen constraints in goal/backstory.
7. Review a verbose run and rewrite any line that did not change behavior.

Working Example

from crewai import Agent, Task, Crew, Process
 
researcher = Agent(
    role="{topic} Research Analyst",
    goal=(
        "Deliver accurate, source-aware notes an engineer can trust. "
        "Prefer precision over coverage when time is limited."
    ),
    backstory=(
        "You spent years fact-checking technical claims. "
        "You never invent URLs or statistics. "
        "When evidence is thin, you say so in one line and move on."
    ),
    allow_delegation=False,
    max_iter=10,
    verbose=True,
)
 
writer = Agent(
    role="Staff Technical Writer",
    goal=(
        "Turn research notes into a scannable brief for senior engineers. "
        "Preserve caveats; do not add new facts."
    ),
    backstory=(
        "You write for people who skim. "
        "Short paragraphs, concrete nouns, no marketing language. "
        "If notes conflict, you surface the conflict instead of picking a side."
    ),
    allow_delegation=False,
    verbose=True,
)
 
research = Task(
    description="Research {topic}. Capture 5 facts with confidence labels.",
    expected_output="Markdown bullets: fact | why it matters | confidence (high/med/low).",
    agent=researcher,
)
 
draft = Task(
    description="Write a 3-paragraph brief on {topic} using only the research notes.",
    expected_output="Markdown with three paragraphs and a 'Caveats' section.",
    agent=writer,
    context=[research],
)
 
crew = Crew(
    agents=[researcher, writer],
    tasks=[research, draft],
    process=Process.sequential,
    verbose=True,
)
 
print(crew.kickoff(inputs={"topic": "agent evaluation harnesses"}).raw)

Deep Dive

What each field is for

The model uses these fields as standing orders. Tasks are the ticket for this run. If goal and expected_output disagree, expect thrash.

Patterns that work

Specialist split. One role owns discovery; another owns packaging. Different tools, different success metrics.

Quality bar in the goal. Phrases like "prefer precision over coverage" change tool use and length more than adjectives in the backstory.

Refusal clauses in the backstory. "Never invent URLs" and "do not add facts not in notes" reduce confident hallucination at handoff boundaries.

Parameterized role titles. role="{topic} Research Analyst" keeps identity relevant without rewriting the agent class.

What to put in the task instead

Do not stuff one-off formatting rules only into the backstory if they apply to a single ticket. Put run-specific instructions in description and expected_output. Keep role text stable so you can reuse the agent across crews.

Hierarchy note

In hierarchical crews, workers still need sharp roles. The manager routes work; it does not magically fix overlapping goals. If two workers both "own the full report," the manager will bounce work or duplicate effort.

Gotchas

1. Role salad. "Researcher-writer-reviewer" is three agents wearing one coat. Split them.
2. Goals that describe activities, not outcomes. "Search the web a lot" is not a goal; "produce five verified facts" is.
3. Backstory cosplay without constraints. Flavor text that never mentions quality or refusals rarely changes traces.
4. Tools that contradict the role. A writer with broad web search will re-research instead of drafting.
5. Ignoring allow_delegation. Accidental true turns a specialist into a middle manager.
6. Copy-pasting the same three fields on every agent. If strings are identical, you paid for multi-agent theater.
7. Never re-reading verbose traces. Role text is a prompt product - iterate with evidence.

Alternatives

FAQs

Related

Related: The CrewAI Mental Model: Roles, Tasks, and Crews

Related: CrewAI Basics

Related: Sequential vs Hierarchical Crew Processes

Related: CrewAI Best Practices

Related: Debugging a Crew That Won't Converge on an Answer

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.