Planning

Overview

CrewAI can plan at two levels:

Agent planning: an agent writes a step-by-step plan for its own work, then executes and checks each step. Configure it with Agent(planning_config=PlanningConfig(...)).
Crew planning: before the crew runs, a CrewPlanner writes a plan for every task and adds it to each task description. Enable it with Crew(planning=True).

You can use either one, or both together.

Agent planning

Pass a PlanningConfig to an agent to enable planning:

from crewai import Agent, Crew, PlanningConfig, Task

analyst = Agent(
    role="Market Analyst",
    goal="Explain market trends with clear evidence",
    backstory="You are an experienced analyst who breaks big questions into small, checkable steps.",
    planning_config=PlanningConfig(
        reasoning_effort="medium",
        max_attempts=3,
    ),
)

trends_task = Task(
    description="Identify the three most important trends in electric vehicle adoption over the last five years.",
    expected_output="A short report describing the top 3 trends, with one supporting fact for each.",
    agent=analyst,
)

crew = Crew(agents=[analyst], tasks=[trends_task])
result = crew.kickoff()

print(result)

The presence of a PlanningConfig turns planning on. To turn it off, leave planning_config unset.

How it works

When the agent starts a task, it runs a plan-and-execute loop:

Plan. The planning LLM writes a plan, asked to stay within max_steps steps, and says whether the plan is ready.
Refine. If the plan is not ready, the planner refines it until it is ready or max_attempts is reached.
Execute. Each step becomes a todo item and runs in its own tool loop, limited by max_step_iterations and step_timeout.
Observe. After each step, the agent checks the result. How much it checks depends on reasoning_effort.
Replan. Depending on reasoning_effort, a failed step or a plan that no longer fits makes the agent write a new plan, up to max_replans times.
Answer. The agent builds the final answer from the step results.

The plan is kept in the agent’s execution state. It is not added to the task description. Step-by-step execution needs a ready plan with structured steps, which the planner gets through function calling. If the plan is still not ready after max_attempts, or the planning LLM does not support function calling, the agent runs its standard execution loop instead.

Reasoning effort

reasoning_effort controls what happens after each step:

Level	After each step	Cost
`"low"`	A heuristic check with no extra LLM call. A failed step is marked as failed and the agent continues in order, without replanning.	Fastest
`"medium"` (default)	An LLM reviews the step. If the step failed and the review says the plan no longer works, the agent replans; otherwise it marks the step as failed and continues.	Balanced
`"high"`	An LLM reviews the step, then decides whether to finish early, replan, or refine the remaining steps.	Most adaptive, slowest

observe_steps overrides the LLM review at any level: True adds it to "low", and False removes it from "medium" and "high". With observe_steps=True, "low" also replans when the review says a failed step needs a new plan.

Configuration options

str

default:"medium"

How much the agent checks and adapts after each step: "low", "medium", or "high".

bool

default:"None"

Run an LLM review after each step. None reviews on "medium" and "high" only.

int

default:"None"

Maximum number of planning attempts, counting the first plan. None keeps refining until the planner marks the plan ready, which can add LLM calls. Set a number to bound it.

int

default:"20"

The step limit the planner is asked to respect. It is passed to the prompt as {max_steps} and is not enforced on the returned plan. Must be at least 1.

int

default:"3"

Maximum number of full replans before the agent finalizes its answer. 0 disables replanning.

int

default:"15"

Maximum LLM iterations for a single step. Lower values make steps faster but less thorough.

int

default:"None"

Maximum seconds for a single step, checked before each LLM call in the step. When it is exceeded, the step stops and returns what it has so far. The step is not marked as failed, and an LLM or tool call already running is not interrupted. None means no timeout.

str | BaseLLM

default:"None"

The LLM used for planning and for the review after each step. None uses the agent’s LLM.

str

default:"None"

Custom system prompt for planning. None uses the built-in prompt.

str

default:"None"

Custom prompt for the first plan. See Custom prompts below.

str

default:"None"

Custom prompt for refining a plan. See Custom prompts below.

Here is an agent that uses a separate, cheaper model for planning and bounds every part of the loop:

from crewai import Agent, PlanningConfig

researcher = Agent(
    role="Researcher",
    goal="Produce well-sourced research summaries",
    backstory="You are a meticulous researcher.",
    planning_config=PlanningConfig(
        reasoning_effort="high",
        max_attempts=2,
        max_steps=8,
        max_replans=2,
        max_step_iterations=10,
        step_timeout=120,
        llm="gpt-5.4-mini",
    ),
)

Custom prompts

plan_prompt and refine_prompt are filled in with Python’s str.format. These placeholders are available:

Prompt	Placeholders
`plan_prompt`	`{role}`, `{goal}`, `{backstory}`, `{description}`, `{expected_output}`, `{tools}`, `{max_steps}`
`refine_prompt`	`{role}`, `{goal}`, `{backstory}`, `{current_plan}`, `{max_steps}`

If your prompts leave out {max_steps}, the planner is given no step limit.

from crewai import Agent, PlanningConfig

writer = Agent(
    role="Technical Writer",
    goal="Write clear documentation",
    backstory="You turn complex systems into readable guides.",
    planning_config=PlanningConfig(
        max_attempts=2,
        plan_prompt=(
            "You are {role}. Your goal: {goal}.\n"
            "Plan how to complete this task in at most {max_steps} steps.\n"
            "Task: {description}\n"
            "Expected output: {expected_output}\n"
            "Available tools: {tools}"
        ),
        refine_prompt=(
            "You are {role}. Improve this plan and keep it to at most "
            "{max_steps} steps:\n{current_plan}"
        ),
    ),
)

Any other placeholder, or a literal { or }, makes planning fail. The agent then logs the error and runs without a plan. Write literal braces as {{ and }}.

Planning without a task

Planning also runs when you call an agent directly with kickoff(), without a Task or a Crew. The input message is used as the task description:

from crewai import Agent, PlanningConfig

planner = Agent(
    role="Travel Planner",
    goal="Plan practical trips",
    backstory="You plan efficient itineraries.",
    planning_config=PlanningConfig(reasoning_effort="low", max_attempts=1),
)

result = planner.kickoff("Plan a two-day trip to Lisbon on a mid-range budget.")

print(result.raw)

The `planning=True` shortcut

Agent(planning=True) enables a bounded, low-cost configuration. It is the same as PlanningConfig(reasoning_effort="low", max_attempts=1): one planning attempt and no LLM review after each step.

from crewai import Agent

agent = Agent(
    role="Data Analyst",
    goal="Analyze data and provide insights",
    backstory="You are an expert data analyst.",
    planning=True,
)

If you also pass planning_config, it takes precedence.

When planning fails

If an error occurs while the agent is planning, the error is logged and the agent runs the task without a plan.

reasoning=True and max_reasoning_attempts are deprecated. See Reasoning for how to migrate.

Crew planning

When crew planning is enabled, all crew information is sent to a CrewPlanner before the tasks run. It plans each task step by step and adds the plan to that task’s description.

Using crew planning

Add planning=True to your Crew. Each time the crew is kicked off, the CrewPlanner writes a plan like the one in the Result tab and adds each task’s part to that task’s description:

from crewai import Agent, Crew, Process, Task

researcher = Agent(
    role="AI LLMs Senior Data Researcher",
    goal="Uncover cutting-edge developments in AI LLMs",
    backstory="You find the most relevant new work in AI LLMs.",
)

reporting_analyst = Agent(
    role="AI LLMs Reporting Analyst",
    goal="Create detailed reports based on AI LLMs data analysis and research findings",
    backstory="You turn research findings into clear reports.",
)

research_task = Task(
    description="Conduct a thorough research about AI LLMs",
    expected_output="A list with 10 bullet points of the most relevant information about AI LLMs",
    agent=researcher,
)

reporting_task = Task(
    description="Review the context you got and expand each topic into a full section for a report",
    expected_output="A fully fledged report with the main topics, each with a full section of information. Formatted as markdown.",
    agent=reporting_analyst,
)

# Assemble your crew with planning capabilities
my_crew = Crew(
    agents=[researcher, reporting_analyst],
    tasks=[research_task, reporting_task],
    process=Process.sequential,
    planning=True,
)

# Run the crew
my_crew.kickoff()

[2024-07-15 16:49:11][INFO]: Planning the crew execution
**Step-by-Step Plan for Task Execution**

**Task Number 1: Conduct a thorough research about AI LLMs**

**Agent:** AI LLMs Senior Data Researcher

**Agent Goal:** Uncover cutting-edge developments in AI LLMs

**Task Expected Output:** A list with 10 bullet points of the most relevant information about AI LLMs

**Task Tools:** None specified

**Agent Tools:** None specified

**Step-by-Step Plan:**

1. **Define Research Scope:**

   - Determine the specific areas of AI LLMs to focus on, such as advancements in architecture, use cases, ethical considerations, and performance metrics.

2. **Identify Reliable Sources:**

   - List reputable sources for AI research, including academic journals, industry reports, conferences (e.g., NeurIPS, ACL), AI research labs (e.g., OpenAI, Google AI), and online databases (e.g., IEEE Xplore, arXiv).

3. **Collect Data:**

   - Search for the latest papers, articles, and reports published in 2024 and early 2025.
   - Use keywords like "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025", etc.

4. **Analyze Findings:**

   - Read and summarize the key points from each source.
   - Highlight new techniques, models, and applications introduced in the past year.

5. **Organize Information:**

   - Categorize the information into relevant topics (e.g., new architectures, ethical implications, real-world applications).
   - Ensure each bullet point is concise but informative.

6. **Create the List:**

   - Compile the 10 most relevant pieces of information into a bullet point list.
   - Review the list to ensure clarity and relevance.

**Expected Output:**

A list with 10 bullet points of the most relevant information about AI LLMs.

---

**Task Number 2: Review the context you got and expand each topic into a full section for a report**

**Agent:** AI LLMs Reporting Analyst

**Agent Goal:** Create detailed reports based on AI LLMs data analysis and research findings

**Task Expected Output:** A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'

**Task Tools:** None specified

**Agent Tools:** None specified

**Step-by-Step Plan:**

1. **Review the Bullet Points:**
   - Carefully read through the list of 10 bullet points provided by the AI LLMs Senior Data Researcher.

2. **Outline the Report:**
   - Create an outline with each bullet point as a main section heading.
   - Plan sub-sections under each main heading to cover different aspects of the topic.

3. **Research Further Details:**
   - For each bullet point, conduct additional research if necessary to gather more detailed information.
   - Look for case studies, examples, and statistical data to support each section.

4. **Write Detailed Sections:**
   - Expand each bullet point into a comprehensive section.
   - Ensure each section includes an introduction, detailed explanation, examples, and a conclusion.
   - Use markdown formatting for headings, subheadings, lists, and emphasis.

5. **Review and Edit:**
   - Proofread the report for clarity, coherence, and correctness.
   - Make sure the report flows logically from one section to the next.
   - Format the report according to markdown standards.

6. **Finalize the Report:**
   - Ensure the report is complete with all sections expanded and detailed.
   - Double-check formatting and make any necessary adjustments.

**Expected Output:**
A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'.

Planning LLM

Crew planning uses gpt-5.4-mini by default. Set planning_llm to a model name or an LLM instance to use another model, for example Crew(..., planning=True, planning_llm="gpt-5").

With the default planning LLM, crew planning needs a valid OpenAI API key, even if your agents use other providers. If you don’t have an OpenAI API key configured, set planning_llm to a model you can access.

Get Started

Guides

Core Concepts

MCP Integration

Tools

Observability

Learn

Telemetry

Overview

Agent planning

How it works

Reasoning effort

Configuration options

Custom prompts

Planning without a task

The `planning=True` shortcut

When planning fails

Crew planning

Using crew planning

Planning LLM

​Overview

​Agent planning

​How it works

​Reasoning effort

​Configuration options

​Custom prompts

​Planning without a task

​The planning=True shortcut

​When planning fails

​Crew planning

​Using crew planning

​Planning LLM

Overview

Agent planning

How it works

Reasoning effort

Configuration options

Custom prompts

Planning without a task

The `planning=True` shortcut

When planning fails

Crew planning

Using crew planning

Planning LLM