getting-started

What this skill does

# CrewAI Getting Started & Architecture

How to choose the right abstraction, scaffold a project, and wire everything together.

---

## MANDATORY WORKFLOW — Read This First

**NEVER manually create crewAI project files.** Always scaffold with the CLI:

```bash
crewai create flow <project_name>
```

This is **not optional**. Even if you only need one crew, even if you know the file structure by heart — run the CLI first, then modify the generated files. Do NOT write `main.py`, `crew.py`, `agents.yaml`, `tasks.yaml`, or `pyproject.toml` by hand from scratch.

> **Why:** The CLI sets up correct imports, directory structure, pyproject.toml config, and boilerplate that is easy to get subtly wrong when done manually. The reference material below teaches you how the pieces work so you can *modify* scaffolded code, not so you can *replace* the scaffolding step.

**Workflow:**
1. Run `crewai create flow <name>` (use **underscores**, not hyphens)
2. Edit the generated YAML and Python files to match your use case
3. Run `crewai install` then `crewai run`

---

## 1. Choosing the Right Abstraction

crewAI has four levels of abstraction. Pick the simplest one that fits your need:

| Level | When to Use | Overhead | Example |
|---|---|---|---|
| `LLM.call()` | Single prompt, no tools, structured extraction | Lowest | Parse an email into fields |
| `Agent.kickoff()` | One agent with tools and reasoning, no multi-agent coordination | Low | Research a topic with web search |
| `Crew.kickoff()` | Multiple agents collaborating on related tasks | Medium | Research + write + review pipeline |
| `Flow` wrapping crews/agents/LLM calls | Production app with state, routing, conditionals, error handling | Full | Multi-step workflow with branching logic |

### Decision Flowchart

```
Do you need tools or multi-step reasoning?
├── No  → LLM.call()
└── Yes
    └── Do you need multiple agents collaborating?
        ├── No  → Agent.kickoff()
        └── Yes
            └── Do you need state management, routing, or multiple crews?
                ├── No  → Crew (but still scaffold as a Flow for future-proofing)
                └── Yes → Flow + Crew(s)
```

**Rule of thumb:** For any production application, **always start with a Flow**. You can embed `LLM.call()`, `Agent.kickoff()`, or `Crew.kickoff()` inside Flow steps. This gives you state management, error handling, and room to grow.

---

## 2. LLM.call() — Direct LLM Invocation

Use for simple, single-turn tasks where you don't need tools or agent reasoning.

```python
from crewai import LLM
from pydantic import BaseModel

class EmailFields(BaseModel):
    sender: str
    subject: str
    urgency: str

llm = LLM(model="openai/gpt-4o")

# Without response_format — returns a string
raw = llm.call(messages=[{"role": "user", "content": "Summarize this text..."}])
print(raw)  # str

# With response_format — returns the Pydantic object directly
result = llm.call(
    messages=[{"role": "user", "content": f"Extract fields from this email: {email_text}"}],
    response_format=EmailFields
)
print(result.sender)   # str — access Pydantic fields directly
print(result.urgency)  # str
```

**When NOT to use:** If you need tools, multi-step reasoning, or retries — use an Agent instead.

---

## 3. Agent.kickoff() — Single Agent Execution

Use when you need one agent with tools and reasoning, but don't need multi-agent coordination.

```python
from crewai import Agent
from crewai_tools import SerperDevTool
from pydantic import BaseModel

class ResearchFindings(BaseModel):
    main_points: list[str]
    key_technologies: list[str]

researcher = Agent(
    role="AI Researcher",
    goal="Research the latest AI developments",
    backstory="Expert AI researcher with deep technical knowledge.",
    llm="openai/gpt-4o",       # Optional: defaults to OPENAI_MODEL_NAME env var or "gpt-4"
    tools=[SerperDevTool()],
)

# Unstructured output
result = researcher.kickoff("What are the latest LLM developments?")
print(result.raw)            # str
print(result.usage_metrics)  # token usage

# Structured output with response_format
result = researcher.kickoff(
    "Summarize latest AI developments",
    response_format=ResearchFindings,
)
print(result.pydantic.main_points)
```

> **Note:** `Agent.kickoff()` wraps results — access structured output via `result.pydantic`. This differs from `LLM.call()`, which returns the Pydantic object directly.

**When NOT to use:** If you need multiple agents passing context to each other — use a Crew.

---

## 4. CLI Scaffold Reference

As stated above: **NEVER skip `crewai create flow`.** This section documents what the CLI generates so you know what to modify — not so you can recreate it by hand.

```bash
crewai create flow my_project
```

> **Warning:** Always use **underscores** in project names, not hyphens. `crewai create flow my-project` creates a directory that is not a valid Python identifier, causing `ModuleNotFoundError` on import. Use `my_project` instead.

This generates:

```
my_project/
├── src/my_project/
│   ├── crews/
│   │   └── my_crew/
│   │       ├── config/
│   │       │   ├── agents.yaml    # Agent definitions (role, goal, backstory)
│   │       │   └── tasks.yaml     # Task definitions (description, expected_output)
│   │       └── my_crew.py         # Crew class with @CrewBase
│   ├── tools/
│   │   └── custom_tool.py
│   ├── main.py                    # Flow class with @start/@listen
│   └── ...
├── .env                           # API keys (OPENAI_API_KEY, etc.)
└── pyproject.toml
```

> **Do not** use `crewai create crew` unless you are certain you will never need routing, state, or multiple crews. Prefer `crewai create flow` as the default.

---

## 5. YAML Configuration (agents.yaml & tasks.yaml)

The scaffold uses YAML files for agent and task definitions. This separates configuration from code and supports `{variable}` interpolation.

### agents.yaml

```yaml
researcher:
  role: >
    {topic} Senior Data Researcher
  goal: >
    Uncover cutting-edge developments in {topic}
  backstory: >
    You're a seasoned researcher with a knack for uncovering
    the latest developments in {topic}.
  # Optional overrides:
  # llm: openai/gpt-4o
  # max_iter: 20
  # max_rpm: 10

reporting_analyst:
  role: >
    {topic} Reporting Analyst
  goal: >
    Create detailed reports based on {topic} research findings
  backstory: >
    You're a meticulous analyst known for turning complex data
    into clear, actionable reports.
```

### tasks.yaml

```yaml
research_task:
  description: >
    Conduct thorough research about {topic}.
    Identify key trends, breakthrough technologies,
    and potential industry impacts.
  expected_output: >
    A detailed report with analysis of the top 5
    developments in {topic}, with sources and implications.
  agent: researcher

reporting_task:
  description: >
    Review the research and create a comprehensive report about {topic}.
  expected_output: >
    A polished report formatted in markdown with sections
    for each key finding.
  agent: reporting_analyst
  output_file: output/report.md
```

**Key rules:**
- `{variable}` placeholders are replaced at runtime via `crew.kickoff(inputs={...})`
- `expected_output` is always a **string** (never a Pydantic class name)
- `agent` value must match an agent key in `agents.yaml`
- In `Process.sequential`, each task auto-receives all prior task outputs as context
- For non-sequential deps, use `context=[other_task]` to explicitly pass output

---

## 6. Wiring It Together — crew.py

The `@CrewBase` decorator auto-loads YAML config files and collects `@agent` and `@task` methods.

```python
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool

@CrewBase
class ResearchCrew:
    """Research and reporting crew."""

    agents_config = "config/agents.yaml"
    tasks_config = "config/tasks.yaml"

    @agent
    def researcher(self) -> Agent: