{"name":"getting-started","url":"https://skills.sh/crewaiinc/skills/getting-started","install":"npx skills add crewaiinc/skills","sdk":"crewai","key":"crewai/getting-started","description":"CrewAI architecture decisions and project scaffolding. Use when starting a new crewAI project, choosing between LLM.call() vs Agent.kickoff() vs Crew.kickoff() vs Flow, scaffolding with 'crewai create flow', setting up YAML config (agents.yaml, tasks.yaml), wiring @CrewBase crew.py, writing Flow main.py with @start/@listen, building experimental conversational Flows with handle_turn()/chat(), or using {variable} interpolation.","hasContent":true,"content":"---\nname: getting-started\ndescription: \"CrewAI architecture decisions and project scaffolding. Use when starting a new crewAI project, choosing between LLM.call() vs Agent.kickoff() vs Crew.kickoff() vs Flow, scaffolding with 'crewai create flow', setting up YAML config (agents.yaml, tasks.yaml), wiring @CrewBase crew.py, writing Flow main.py with @start/@listen, building experimental conversational Flows with handle_turn()/chat(), or using {variable} interpolation.\"\n---\n\n# CrewAI Getting Started & Architecture\n\nHow to choose the right abstraction, scaffold a project, and wire everything together.\n\n---\n\n## MANDATORY WORKFLOW — Read This First\n\n**NEVER manually create crewAI project files.** Always scaffold with the CLI:\n\n```bash\ncrewai create flow <project_name>\n```\n\nThis 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.\n\n> **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.\n\n**Workflow:**\n1. Run `crewai create flow <name>` (use **underscores**, not hyphens)\n2. Edit the generated YAML and Python files to match your use case\n3. Run `crewai install` then `crewai run`\n\n---\n\n## 1. Choosing the Right Abstraction\n\ncrewAI has five common abstraction choices. Pick the simplest one that fits your need:\n\n| Level | When to Use | Overhead | Example |\n|---|---|---|---|\n| `LLM.call()` | Single prompt, no tools, structured extraction | Lowest | Parse an email into fields |\n| `Agent.kickoff()` | One agent with tools and reasoning, no multi-agent coordination | Low | Research a topic with web search |\n| `Crew.kickoff()` | Multiple agents collaborating on related tasks | Medium | Research + write + review pipeline |\n| `Flow` wrapping crews/agents/LLM calls | Production app with state, routing, conditionals, error handling | Full | Multi-step workflow with branching logic |\n| Conversational `Flow` | Multi-turn chat where each user line re-runs a Flow with the same session id | Full + experimental | Support assistant with routed chat, research, and escalation turns |\n\n### Decision Flowchart\n\n```\nDo you need tools or multi-step reasoning?\n├── No  → LLM.call()\n└── Yes\n    └── Do you need multiple agents collaborating?\n        ├── No  → Agent.kickoff()\n        └── Yes\n            └── Do you need state management, routing, or multiple crews?\n                ├── No  → Crew (but still scaffold as a Flow for future-proofing)\n                └── Yes → Flow + Crew(s)\n\nDo users send multiple chat messages in one session?\n└── Yes → Conversational Flow with handle_turn(message, session_id=...)\n```\n\n**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.\n\nFor chat applications, start with a conversational `Flow` rather than trying to make `Crew.kickoff()` or `Flow.kickoff()` act like a chat loop. The conversational surface is experimental, but it is the intended API for multi-turn sessions: call `flow.handle_turn(message, session_id=...)` for every user line, or `flow.chat()` for a local terminal REPL. Official guide: <https://docs.crewai.com/en/guides/flows/conversational-flows>.\n\n---\n\n## 2. LLM.call() — Direct LLM Invocation\n\nUse for simple, single-turn tasks where you don't need tools or agent reasoning.\n\n```python\nfrom crewai import LLM\nfrom pydantic import BaseModel\n\nclass EmailFields(BaseModel):\n    sender: str\n    subject: str\n    urgency: str\n\nllm = LLM(model=\"openai/gpt-4o\")\n\n# Without response_format — returns a string\nraw = llm.call(messages=[{\"role\": \"user\", \"content\": \"Summarize this text...\"}])\nprint(raw)  # str\n\n# With response_format — returns the Pydantic object directly\nresult = llm.call(\n    messages=[{\"role\": \"user\", \"content\": f\"Extract fields from this email: {email_text}\"}],\n    response_format=EmailFields\n)\nprint(result.sender)   # str — access Pydantic fields directly\nprint(result.urgency)  # str\n```\n\n**When NOT to use:** If you need tools, multi-step reasoning, or retries — use an Agent instead.\n\n---\n\n## 3. Agent.kickoff() — Single Agent Execution\n\nUse when you need one agent with tools and reasoning, but don't need multi-agent coordination.\n\n```python\nfrom crewai import Agent\nfrom crewai_tools import SerperDevTool\nfrom pydantic import BaseModel\n\nclass ResearchFindings(BaseModel):\n    main_points: list[str]\n    key_technologies: list[str]\n\nresearcher = Agent(\n    role=\"AI Researcher\",\n    goal=\"Research the latest AI developments\",\n    backstory=\"Expert AI researcher with deep technical knowledge.\",\n    llm=\"openai/gpt-4o\",       # Optional: defaults to OPENAI_MODEL_NAME env var or \"gpt-4\"\n    tools=[SerperDevTool()],\n)\n\n# Unstructured output\nresult = researcher.kickoff(\"What are the latest LLM developments?\")\nprint(result.raw)            # str\nprint(result.usage_metrics)  # token usage\n\n# Structured output with response_format\nresult = researcher.kickoff(\n    \"Summarize latest AI developments\",\n    response_format=ResearchFindings,\n)\nprint(result.pydantic.main_points)\n```\n\n> **Note:** `Agent.kickoff()` wraps results — access structured output via `result.pydantic`. This differs from `LLM.call()`, which returns the Pydantic object directly.\n\n**When NOT to use:** If you need multiple agents passing context to each other — use a Crew.\n\n---\n\n## 4. CLI Scaffold Reference\n\nAs 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.\n\n```bash\ncrewai create flow my_project\n```\n\n> **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.\n\nThis generates:\n\n```\nmy_project/\n├── src/my_project/\n│   ├── crews/\n│   │   └── my_crew/\n│   │       ├── config/\n│   │       │   ├── agents.yaml    # Agent definitions (role, goal, backstory)\n│   │       │   └── tasks.yaml     # Task definitions (description, expected_output)\n│   │       └── my_crew.py         # Crew class with @CrewBase\n│   ├── tools/\n│   │   └── custom_tool.py\n│   ├── main.py                    # Flow class with @start/@listen\n│   └── ...\n├── .env                           # API keys (OPENAI_API_KEY, etc.)\n└── pyproject.toml\n```\n\n> **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.\n\n---\n\n## 5. YAML Configuration (agents.yaml & tasks.yaml)\n\nThe scaffold uses YAML files for agent and task definitions. This separates configuration from code and supports `{variable}` interpolation.\n\n### agents.yaml\n\n```yaml\nresearcher:\n  role: >\n    {topic} Senior Data Researcher\n  goal: >\n    Uncover cutting-edge developments in {topic}\n  backstory: >\n    You're a seasoned researcher with a knack for uncovering\n    the latest developments in {topic}.\n  # Optional overrides:\n  # llm: openai/gpt-4o\n  # max_iter: 20\n  # max_rpm: 10\n\nreporting_analyst:\n  role: >\n    {topic} Reporting Analyst\n  goal: >\n    Create detailed reports based on {topic} research findings\n  backstory: >\n    You're a meticulous analyst known for turning complex data\n    into clear, actionable reports.\n```\n\n### tasks.yaml\n\n```yaml\nresearch_task:\n  description: >\n    Conduct thorough research about {topic}.\n    Identify key trends, breakthrough technologies,\n    and potential industry impacts.\n  expected_output: >\n    A detailed report with analysis of the top 5\n    developments in {topic}, with sources and implications.\n  agent: researcher\n\nreporting_task:\n  description: >\n    Review the research and create a comprehensive report about {topic}.\n  expected_output: >\n    A polished report formatted in markdown with sections\n    for each key finding.\n  agent: reporting_analyst\n  output_file: output/report.md\n```\n\n**Key rules:**\n- `{variable}` placeholders are replaced at runtime via `crew.kickoff(inputs={...})`\n- `expected_output` is always a **string** (never a Pydantic class name)\n- `agent` value must match an agent key in `agents.yaml`\n- In `Process.sequential`, each task auto-receives all prior task outputs as context\n- For non-sequential deps, use `context=[other_task]` to explicitly pass output\n\n---\n\n## 6. Wiring It Together — crew.py\n\nThe `@CrewBase` decorator auto-loads YAML config files and collects `@agent` and `@task` methods.\n\n```python\nfrom crewai import Agent, Crew, Process, Task\nfrom crewai.project import CrewBase, agent, crew, task\nfrom crewai_tools import SerperDevTool\n\n@CrewBase\nclass ResearchCrew:\n    \"\"\"Research and reporting crew.\"\"\"\n\n    agents_config = \"config/agents.yaml\"\n    tasks_config = \"config/tasks.yaml\"\n\n    @agent\n    def researcher(self) -> Agent:\n        return Agent(\n            config=self.agents_config[\"researcher\"],\n            tools=[SerperDevTool()],\n        )\n\n    @agent\n    def reporting_analyst(self) -> Agent:\n        return Agent(\n            config=self.agents_config[\"reporting_analyst\"],\n        )\n\n    @task\n    def research_task(self) -> Task:\n        return Task(config=self.tasks_config[\"research_task\"])\n\n    @task\n    def reporting_task(self) -> Task:\n        return Task(\n            config=self.tasks_config[\"reporting_task\"],\n            context=[self.research_task()],  # Explicit dependency (optional in sequential)\n            output_file=\"output/report.md\",\n        )\n\n    @crew\n    def crew(self) -> Crew:\n        return Crew(\n            agents=self.agents,  # auto-collected by @agent\n            tasks=self.tasks,    # auto-collected by @task\n            process=Process.sequential,\n            verbose=True,\n        )\n```\n\n**Important:** Method names must match YAML keys. `def researcher(self)` maps to the `researcher:` key in `agents.yaml`.\n\n---\n\n## 7. Flows — The Production Foundation\n\nFlows are the recommended way to build production crewAI applications. They provide state management, conditional routing, human-in-the-loop, and persistence — wrapping crews, agents, and LLM calls into a coherent workflow.\n\n### Basic Flow — main.py\n\n```python\nfrom crewai.flow.flow import Flow, listen, start\nfrom pydantic import BaseModel\nfrom .crews.research_crew.research_crew import ResearchCrew\n\nclass ResearchState(BaseModel):\n    topic: str = \"\"\n    report: str = \"\"\n\nclass ResearchFlow(Flow[ResearchState]):\n\n    @start()\n    def begin(self):\n        print(f\"Starting research on: {self.state.topic}\")\n\n    @listen(begin)\n    def run_research(self):\n        result = ResearchCrew().crew().kickoff(\n            inputs={\"topic\": self.state.topic}\n        )\n        self.state.report = result.raw\n\ndef kickoff():\n    flow = ResearchFlow()\n    flow.kickoff(inputs={\"topic\": \"AI Agents\"})\n\nif __name__ == \"__main__\":\n    kickoff()\n```\n\n**Key points:**\n- `flow.kickoff(inputs={\"topic\": \"AI Agents\"})` populates `self.state.topic` (keys must match Pydantic field names). The YAML `{variable}` substitution happens later, when you call `crew.kickoff(inputs={\"topic\": self.state.topic})` inside a Flow step. The chain is: **flow inputs → state → crew inputs → YAML substitution**.\n- Each `@listen` method runs after its dependency completes\n- State persists across all Flow steps — use it to pass data between crews\n\n### State Management — Structured vs Unstructured\n\n**Structured (recommended for production):**\n```python\nfrom pydantic import BaseModel\n\nclass MyState(BaseModel):\n    topic: str = \"\"\n    research: str = \"\"\n    draft: str = \"\"\n    approved: bool = False\n\nclass MyFlow(Flow[MyState]):\n    ...\n```\n\n**Unstructured (quick prototyping):**\n```python\nclass MyFlow(Flow):  # No type parameter — state is a dict\n    @start()\n    def begin(self):\n        self.state[\"topic\"] = \"AI\"  # dict-style access\n```\n\nUse structured state for type safety, IDE autocompletion, and validation. Use unstructured only for throwaway prototypes.\n\n### Using Agent.kickoff() Inside Flows (Common Pattern)\n\nMany production Flows skip Crews entirely and orchestrate individual agents via `Agent.kickoff()`. This gives you fine-grained control — each Flow step calls a specific agent, passes state, and stores the result. The Flow handles orchestration; agents handle reasoning.\n\n```python\nfrom crewai import Agent, LLM\nfrom crewai.flow.flow import Flow, listen, start\nfrom crewai_tools import SerperDevTool, ScrapeWebsiteTool\nfrom pydantic import BaseModel\n\nclass ResearchState(BaseModel):\n    query: str = \"\"\n    raw_research: str = \"\"\n    analysis: str = \"\"\n    report: str = \"\"\n\nclass DeepResearchFlow(Flow[ResearchState]):\n\n    @start()\n    def gather_research(self):\n        \"\"\"Agent with tools does the actual searching.\"\"\"\n        researcher = Agent(\n            role=\"Senior Research Analyst\",\n            goal=\"Find comprehensive, factual information about the given topic\",\n            backstory=\"You're an expert researcher who always cites sources and flags uncertainty.\",\n            tools=[SerperDevTool(), ScrapeWebsiteTool()],\n            llm=\"openai/gpt-4o\",\n        )\n        result = researcher.kickoff(\n            f\"Research this topic thoroughly: {self.state.query}\"\n        )\n        self.state.raw_research = result.raw\n\n    @listen(gather_research)\n    def analyze_findings(self):\n        \"\"\"A different agent analyzes the raw research — no tools needed.\"\"\"\n        analyst = Agent(\n            role=\"Data Analyst\",\n            goal=\"Extract key insights, patterns, and actionable recommendations\",\n            backstory=\"You turn raw data into clear, structured analysis.\",\n            llm=\"openai/gpt-4o\",\n        )\n        result = analyst.kickoff(\n            f\"Analyze these research findings and extract key insights:\\n\\n{self.state.raw_research}\"\n        )\n        self.state.analysis = result.raw\n\n    @listen(analyze_findings)\n    def write_report(self):\n        \"\"\"A writer agent produces the final deliverable.\"\"\"\n        writer = Agent(\n            role=\"Technical Writer\",\n            goal=\"Produce clear, actionable reports for non-technical readers\",\n            backstory=\"You specialize in making complex information accessible.\",\n            llm=\"openai/gpt-4o\",\n        )\n        result = writer.kickoff(\n            f\"Write a comprehensive report based on this analysis:\\n\\n{self.state.analysis}\"\n        )\n        self.state.report = result.raw\n```\n\n**Why this pattern works well:**\n- Each agent is purpose-built for its step — narrow role, specific tools\n- The Flow manages state and sequencing — no crew overhead\n- Easy to add routing, human review, or retry logic between steps\n- You can mix `Agent.kickoff()`, `LLM.call()`, and `Crew.kickoff()` freely\n\n**When to use Agent.kickoff() vs Crew.kickoff() in a Flow:**\n\n| Use `Agent.kickoff()` when | Use `Crew.kickoff()` when |\n|---|---|\n| Each step is a distinct agent with different tools | Multiple agents need to collaborate on ONE task |\n| You want the Flow to control sequencing | Agents need to pass context to each other within a step |\n| Steps are independent and don't need inter-agent delegation | You need hierarchical process with a manager |\n| You want maximum control over what data flows between steps | The sub-workflow is self-contained and reusable |\n\n### Agent.kickoff() with Structured Output in Flows\n\nCombine `response_format` with state for typed data flow between agents:\n\n```python\nclass Insights(BaseModel):\n    key_points: list[str]\n    recommendations: list[str]\n    confidence: float\n\nclass AnalysisFlow(Flow[AnalysisState]):\n\n    @start()\n    def research(self):\n        researcher = Agent(role=\"Researcher\", goal=\"...\", backstory=\"...\", tools=[SerperDevTool()])\n        result = researcher.kickoff(\n            f\"Research {self.state.topic}\",\n            response_format=Insights,\n        )\n        # result.pydantic gives you the typed Insights object\n        self.state.key_points = result.pydantic.key_points\n        self.state.recommendations = result.pydantic.recommendations\n```\n\n### Mixing Abstractions in a Flow\n\nA Flow can combine all crewAI abstractions in a single workflow:\n\n```python\nclass ProductFlow(Flow[ProductState]):\n\n    @start()\n    def classify_request(self):\n        # LLM.call() for simple classification\n        llm = LLM(model=\"openai/gpt-4o\")\n        self.state.category = llm.call(\n            messages=[{\"role\": \"user\", \"content\": f\"Classify: {self.state.request}\"}],\n            response_format=Category\n        ).category\n\n    @router(classify_request)\n    def route_by_category(self):\n        if self.state.category == \"simple\":\n            return \"quick_answer\"\n        return \"deep_research\"\n\n    @listen(\"quick_answer\")\n    def handle_simple(self):\n        # Agent.kickoff() for single-agent work\n        agent = Agent(role=\"Helper\", goal=\"Answer quickly\", backstory=\"...\")\n        result = agent.kickoff(self.state.request)\n        self.state.answer = result.raw\n\n    @listen(\"deep_research\")\n    def handle_complex(self):\n        # Crew.kickoff() for multi-agent collaboration\n        result = ResearchCrew().crew().kickoff(\n            inputs={\"topic\": self.state.request}\n        )\n        self.state.answer = result.raw\n```\n\n### Flow Routing with `@router`\n\nUse `@router` for conditional branching — return a string label, and `@listen(\"label\")` binds to branches:\n\n```python\nfrom crewai.flow.flow import Flow, listen, router, start, or_\n\nclass QualityFlow(Flow[QAState]):\n\n    @start()\n    def generate_content(self):\n        result = WriterCrew().crew().kickoff(inputs={\"topic\": self.state.topic})\n        self.state.draft = result.raw\n\n    @router(generate_content)\n    def check_quality(self):\n        llm = LLM(model=\"openai/gpt-4o\")\n        score = llm.call(\n            messages=[{\"role\": \"user\", \"content\": f\"Rate 1-10: {self.state.draft}\"}],\n            response_format=QualityScore\n        )\n        if score.rating >= 7:\n            return \"approved\"\n        return \"needs_revision\"\n\n    @listen(\"approved\")\n    def publish(self):\n        self.state.published = True\n\n    @listen(\"needs_revision\")\n    def revise(self):\n        result = EditorCrew().crew().kickoff(\n            inputs={\"draft\": self.state.draft}\n        )\n        self.state.draft = result.raw\n```\n\n### Converging Branches with `or_()` and `and_()`\n\n```python\nfrom crewai.flow.flow import Flow, listen, start, or_, and_\n\nclass ParallelFlow(Flow[MyState]):\n\n    @start()\n    def fetch_data_a(self):\n        ...\n\n    @start()\n    def fetch_data_b(self):\n        ...\n\n    # Runs when BOTH fetches complete\n    @listen(and_(fetch_data_a, fetch_data_b))\n    def merge_results(self):\n        ...\n\n    # Runs when EITHER source provides data\n    @listen(or_(fetch_data_a, fetch_data_b))\n    def process_first_available(self):\n        ...\n```\n\n### Flow Persistence with `@persist`\n\nFor long-running workflows that need to survive restarts:\n\n```python\nfrom crewai.flow.flow import Flow, start, listen, persist\nfrom crewai.flow.persistence import SQLiteFlowPersistence\n\n@persist(SQLiteFlowPersistence())  # Class-level: persists all methods\nclass LongRunningFlow(Flow[MyState]):\n\n    @start()\n    def step_one(self):\n        self.state.data = \"processed\"\n\n    @listen(step_one)\n    def step_two(self):\n        # If the process crashes here, restarting with the same\n        # state ID will resume from after step_one\n        ...\n```\n\n### Conversational Flows with `handle_turn()` (Experimental)\n\nUse a conversational `Flow` when the product is a chat session: support assistants, routed research helpers, onboarding wizards, or any UI where the same user sends multiple turns.\n\nCore model:\n- Each user message is a **new Flow run** with the **same session id**\n- `handle_turn(message, session_id=...)` appends the user line to `state.messages`, resets per-turn execution tracking, and calls `kickoff(inputs={\"id\": session_id})` internally\n- `Flow.kickoff()` does **not** accept `user_message=` or `session_id=` keyword args\n- Route chat turns with `route_turn()` plus `@listen(\"ROUTE\")` handlers\n- Call `append_assistant_message(reply)` in handlers so the next turn sees assistant history\n- Wrap owned loops in `try/finally` and call `finalize_session_traces()`; `flow.chat()` does this for local REPLs\n\n```python\nfrom uuid import uuid4\n\nfrom crewai import Agent, Flow\nfrom crewai.flow import listen\nfrom crewai.experimental.conversational import (\n    ConversationConfig,\n    ConversationState,\n)\n\n\n@ConversationConfig(defer_trace_finalization=True)\nclass SupportFlow(Flow[ConversationState]):\n    conversational = True\n\n    def research_agent(self) -> Agent:\n        return Agent(\n            role=\"Support Research Specialist\",\n            goal=\"Answer the user's current research question with accurate sources.\",\n            backstory=\"You are precise, evidence-driven, and explicit about uncertainty.\",\n            tools=[...],\n        )\n\n    def route_turn(self, context):\n        message = (self.state.current_user_message or \"\").lower()\n        if \"docs\" in message or \"crewai\" in message:\n            return \"CREWAI_DOCS\"\n        if \"research\" in message or \"search\" in message:\n            return \"RESEARCH\"\n        return \"converse\"\n\n    @listen(\"CREWAI_DOCS\")\n    def handle_docs(self):\n        \"\"\"Look up CrewAI documentation for framework/API questions.\"\"\"\n        reply = \"I would query the CrewAI docs here.\"\n        self.append_assistant_message(reply)\n        return reply\n\n    @listen(\"RESEARCH\")\n    def handle_research(self):\n        \"\"\"Fresh research, current lookups, and tool-backed investigation.\"\"\"\n        result = self.research_agent().kickoff(self.state.current_user_message)\n        reply = result.raw\n        self.append_assistant_message(reply)\n        return reply\n\n\nflow = SupportFlow()\nsession_id = str(uuid4())\n\ntry:\n    flow.handle_turn(\"What can you do?\", session_id=session_id)\n    flow.handle_turn(\"Check the CrewAI docs for flows.\", session_id=session_id)\nfinally:\n    flow.finalize_session_traces()\n```\n\nUse `RouterConfig` when you want LLM-driven routing. The router catalog is auto-built from `@listen(\"ROUTE\")` handlers and their docstrings, so do not duplicate the route list in the router prompt.\n\nSee [Conversational Flows](references/conversational-flows.md) for the full lifecycle, routing, persistence, and trace guidance.\n\n### Human-in-the-Loop with `@human_feedback`\n\n```python\nfrom crewai.flow.flow import Flow, start, listen, router\nfrom crewai.flow.human_feedback import human_feedback\n\nclass ApprovalFlow(Flow[ReviewState]):\n\n    @start()\n    def generate_draft(self):\n        result = WriterCrew().crew().kickoff(inputs={\"topic\": self.state.topic})\n        self.state.draft = result.raw\n\n    @human_feedback(\n        message=\"Review the draft and provide feedback\",\n        emit=[\"approved\", \"needs_revision\"],\n        llm=\"openai/gpt-4o\",\n        default_outcome=\"approved\"\n    )\n    @listen(generate_draft)\n    def review_step(self):\n        return self.state.draft\n\n    @listen(\"approved\")\n    def publish(self):\n        ...\n\n    @listen(\"needs_revision\")\n    def revise(self):\n        feedback = self.last_human_feedback\n        # Use feedback.feedback_text for revision\n        ...\n```\n\n### Flow Visualization\n\n```python\nflow = MyFlow()\nflow.plot()             # Display in notebook\nflow.plot(\"my_flow\")    # Save as my_flow.png\n```\n\n---\n\n## 8. Variable Interpolation with `inputs`\n\nThe `{variable}` pattern is how you make crews reusable.\n\n```python\n# Variables flow through: kickoff → YAML templates → agent/task prompts\ncrew.kickoff(inputs={\n    \"topic\": \"AI Agents\",\n    \"current_year\": \"2025\",\n    \"target_audience\": \"developers\",\n})\n```\n\nIn YAML, `{topic}` and `{current_year}` get replaced:\n\n```yaml\nresearch_task:\n  description: >\n    Research {topic} trends for {current_year},\n    targeting {target_audience}.\n```\n\n**Common mistakes:**\n- Forgetting to pass a variable that's referenced in YAML → results in literal `{variable}` in the prompt\n- Using Jinja2 syntax `{{ }}` instead of single-brace `{ }` → crewAI uses single braces\n- Passing variables that don't match any YAML placeholder → silently ignored\n\n---\n\n## 9. Running Your Project\n\n```bash\n# Install dependencies\ncrewai install\n\n# Run the flow\ncrewai run\n```\n\nOr run directly:\n\n```bash\ncd my_project\nuv run src/my_project/main.py\n```\n\n---\n\n## 10. Quick Diagnostic Checklist\n\n| Symptom | Likely Cause | Fix |\n|---|---|---|\n| `{topic}` appears literally in agent output | Missing `inputs=` in `kickoff()` | Pass `crew.kickoff(inputs={\"topic\": \"...\"})` |\n| `KeyError` on `self.agents_config['name']` | Method name doesn't match YAML key | Ensure `@agent def researcher` matches `researcher:` in YAML |\n| `ModuleNotFoundError` on import | Wrong path or hyphens in project name | Use underscores; check `from .crews.crew_name.crew_name import CrewClass` |\n| Crew runs but Flow state is empty | Not writing results back to `self.state` | Assign crew output to `self.state.field` in the `@listen` method |\n| `Process.SEQUENTIAL` raises `AttributeError` | Uppercase enum | Use lowercase: `Process.sequential` |\n| Agent ignores tools | Tools assigned to agent but task needs them | Move tools to task level or verify agent has the right tools |\n| Agent fabricates search results | No tools assigned — agent can't actually search | Add `tools=[SerperDevTool()]` or equivalent; an agent with no tools will hallucinate data |\n| `@listen` never fires | Listener string doesn't match router return value, or passed a string instead of method reference | `@router` must return the exact string `@listen(\"label\")` expects; for method chaining use `@listen(method_ref)` not `@listen(\"method_name\")` |\n| Flow step runs twice unexpectedly | Multiple `@start()` methods or `or_` listener | Use `and_()` if you need all upstream steps to complete first |\n| `AuthenticationError` or `API key not found` | Missing env var | Set `OPENAI_API_KEY` (and `SERPER_API_KEY` for search tools) in `.env` |\n| Agent retries endlessly on structured output | Pydantic model too complex for the LLM | Simplify the model, reduce nesting, or use a more capable `llm` |\n| Agent loops to `max_iter` without finishing | Task description too vague or conflicting with `expected_output` | Make `expected_output` specific and achievable; lower `max_iter` to fail faster |\n| Flow state not updating across steps | Using unstructured state without proper key access | Switch to structured Pydantic state or ensure dict keys are consistent |\n| `@router` return value ignored | Method not decorated with `@router` | Use `@router(condition)` not `@listen(condition)` for branching methods |\n| `Flow.kickoff(user_message=..., session_id=...)` fails | Conversational kwargs are not accepted by `kickoff()` | Use `flow.handle_turn(message, session_id=...)` for chat messages |\n| Chat history missing assistant replies | Handler returned text but did not record it on older/explicit paths | Call `self.append_assistant_message(reply)` inside route handlers |\n| Trace never exports for chat session | Deferred conversational trace was not finalized | Call `flow.finalize_session_traces()` in `finally`, or use `flow.chat()` |\n| Follow-up chat modeled with `@human_feedback` | Human feedback approves a step output, not the next user message | Use conversational `handle_turn()` for follow-up chat lines |\n\n---\n\n## References\n\nFor deeper dives into specific topics, see:\n\n- [Flow Routing, Persistence, Streaming & Human Feedback](references/flow-routing.md) — complete `@router`, `or_()`, `and_()`, `@persist`, streaming, and `@human_feedback` patterns\n- [Conversational Flows](references/conversational-flows.md) — experimental multi-turn Flow API with `handle_turn()`, `chat()`, `ConversationConfig`, router behavior, persistence, and tracing\n- [MCP Servers](references/mcp-servers.md) — prefer official MCP servers over native tools; setup, DSL integration, and known official servers\n- [Tools Catalog](references/tools-catalog.md) — all 80+ built-in tools with imports, env vars, and common combos (use as fallback when no MCP server exists)\n\nFor related skills:\n\n- **design-agent** — agent Role-Goal-Backstory framework, parameter tuning, tool assignment, memory & knowledge configuration\n- **design-task** — task description/expected_output best practices, guardrails, structured output, dependencies\n- **ask-docs** — query the live CrewAI documentation MCP server for questions not covered by these skills\n","contentSource":"https://raw.githubusercontent.com/crewaiinc/skills/main/skills/getting-started/SKILL.md","contentFetchedAt":"2026-07-27T09:00:57.876Z"}