design-agent

What this skill does

# CrewAI Agent Design Guide

How to design effective agents with the right role, goal, backstory, tools, and configuration.

---

## The 80/20 Rule

**Spend 80% of your effort on task design, 20% on agent design.** A well-designed task elevates even a simple agent. But even the best agent cannot rescue a vague, poorly scoped task. Get the task right first (see the `design-task` skill), then refine the agent.

---

## 0. How Many Agents Do You Actually Need?

**Default to ONE agent.** Add more only when the task genuinely splits into work that requires:

- **Different tools or permissions** — e.g. one agent has Slack write access, another reads docs only.
- **Different personas the LLM must clearly switch between** — a writer's voice is not a researcher's voice.
- **Different LLMs** — a cheap model for mechanical steps, a stronger one for synthesis.
- **Different guardrails or output schemas** — separate agents make the contract per stage explicit.

**DO NOT add an agent just because the workflow has multiple steps.** A single agent can:
- Call multiple tools in sequence within one kickoff (search → scrape → summarize is one agent's loop).
- Produce structured multi-section output in one response.
- Iterate via its own tool-use loop without you orchestrating it as separate agents.

**Cost calculus:** every extra agent = at least one more LLM kickoff plus a context handoff. Splitting linear, single-persona work into multiple agents multiplies token cost and adds fragility for marginal quality wins.

### Anti-pattern: Sequential mechanical steps as separate agents

❌ Three agents for what is one researcher's job:
```python
source_finder = Agent(role="Finds URLs via Firecrawl search", tools=[firecrawl_search])
scraper       = Agent(role="Scrapes URLs via Firecrawl scrape", tools=[firecrawl_scrape])
writer        = Agent(role="Writes the report", ...)
```

✅ One researcher does the gathering loop; one writer synthesizes — two agents because the personas and LLMs genuinely differ:
```python
researcher = Agent(role="Web Researcher", tools=[firecrawl_search, firecrawl_scrape], llm="anthropic/claude-haiku-4-5")
writer     = Agent(role="Technical Report Writer",                                    llm="anthropic/claude-sonnet-4-6")
```
The researcher's task description tells it to search, then scrape, then return structured findings. One LLM loop, multiple tool calls.

### Anti-pattern: "Summarize then send" as two agents

❌ Two agents to read a string, summarize it, and post a Slack DM:
```python
summarizer       = Agent(role="Summarizer")
slack_messenger  = Agent(role="Slack Sender", apps=["slack"])
```

✅ One agent with the connector and a task that tells it to summarize on top, then DM:
```python
slack_dm_agent = Agent(
    role="Slack Reporter",
    goal="Post a Slack DM containing a one-paragraph summary plus the full markdown body.",
    apps=["slack"],
)
# Task: "Read the report below. Write a 2-3 sentence executive summary at the top.
#        Post a DM to {recipient_email} with the summary followed by the full body."
```

### Heuristic

> If two "agents" share the same persona, the same tool surface, and the same LLM, they are one agent with a longer task description.

### Once you've decided "one agent is enough"

Use `Agent.kickoff()` directly inside a Flow method — no `Crew`, no `Task` ceremony. The Flow owns sequencing and state; each step is a single agent kickoff. See **Section 4 — Agent.kickoff() — Direct Agent Execution** below for the full pattern, and the upstream docs at <https://docs.crewai.com/en/concepts/agents#direct-agent-interaction-with-kickoff>.

Quick shape:

```python
@listen(previous_step)
def my_step(self):
    agent = Agent(role="…", goal="…", backstory="…", tools=[...])
    result = agent.kickoff(
        messages=f"Use this prior step's output: {self.state.prior_field}",
        response_format=MyPydanticModel,  # optional
    )
    self.state.my_field = result.pydantic  # or result.raw
```

Reach for `Crew.kickoff()` *only* when a step genuinely benefits from multi-agent collaboration (delegation, hierarchical management, parallel specialists feeding one synthesis). For "one agent does one job", `Agent.kickoff()` inside a Flow listener is the right primitive.

Only after you've decided multi-agent is justified, read on for how to design each one.

---

## 1. The Role-Goal-Backstory Framework

Every agent needs three things: **who** it is, **what** it wants, and **why** it's qualified.

### Role — Who the Agent Is

The role defines the agent's area of expertise. **Be specific, not generic.**

| Bad | Good |
|---|---|
| `Researcher` | `Senior Data Researcher specializing in {topic}` |
| `Writer` | `Technical Blog Writer for developer audiences` |
| `Analyst` | `Financial Risk Analyst with regulatory compliance expertise` |

The role directly shapes how the LLM reasons. A "Senior Data Researcher" will produce different output than a "Research Assistant" even with the same task.

### Goal — What the Agent Wants

The goal is the agent's individual objective. It should be **outcome-focused with quality standards**.

| Bad | Good |
|---|---|
| `Do research` | `Uncover cutting-edge developments in {topic} and identify the top 5 trends with supporting evidence` |
| `Write content` | `Produce publication-ready technical articles that explain complex topics clearly for non-technical readers` |
| `Analyze data` | `Deliver actionable risk assessments with confidence levels and recommended mitigations` |

### Backstory — Why the Agent Is Qualified

The backstory establishes expertise, experience, values, and working style. It's the agent's "personality prompt."

```yaml
backstory: >
  You're a seasoned researcher with 15 years of experience in AI/ML.
  You're known for your ability to find obscure but relevant papers
  and synthesize complex findings into clear, actionable insights.
  You always cite your sources and flag uncertainty explicitly.
```

**What to include in a backstory:**
- Years/depth of experience
- Specific domain knowledge
- Working style and values (e.g., "always cites sources", "prefers concise output")
- Quality standards the agent holds itself to

**What NOT to include:**
- Implementation details (tools, models, config)
- Task-specific instructions (those go in the task description)
- Arbitrary personality traits that don't affect output quality

---

## 2. Agent Configuration Reference

### Essential Parameters

```python
Agent(
    role="...",              # Required: agent's expertise area
    goal="...",              # Required: what the agent aims to achieve
    backstory="...",         # Required: context and personality
    llm="openai/gpt-4o",    # Optional: defaults to OPENAI_MODEL_NAME env var or "gpt-4"
    tools=[...],             # Optional: list of tool instances
)
```

### Execution Control

```python
Agent(
    ...,
    max_iter=25,             # Max reasoning iterations per task (default: 25)
    max_execution_time=300,  # Timeout in seconds (default: None — no limit)
    max_rpm=10,              # Rate limit: max API calls per minute (default: None)
    max_retry_limit=2,       # Retries on error (default: 2)
    verbose=True,            # Show detailed execution logs (default: False)
)
```

**Tuning `max_iter`:**
- Default 25 is generous — most tasks finish in 3-8 iterations
- Lower to 10-15 to fail faster when tasks are well-defined
- If agent consistently hits max_iter, the task is too vague (fix the task, not the limit)

### Tool Configuration

```python
from crewai_tools import SerperDevTool, ScrapeWebsiteTool, FileReadTool

Agent(
    ...,
    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # Agent-level tools
)
```

**Key rules:**
- An agent with **no tools** will hallucinate data when asked to search, fetch, or read files — always provide tools for tasks that require external data
- Prefer **fewer, focused tools** over many tools — too many tools confuses the agent
- Tools can also be assi