> ## Documentation Index > Fetch the complete documentation index at: https://docs.crewai.com/llms.txt > Use this file to discover all available pages before exploring further. # Planning > Learn how to make agents plan before they act with PlanningConfig, and how to plan a whole crew with Crew(planning=True). ## 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: ```python theme={null} 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: 1. **Plan.** The planning LLM writes a plan, asked to stay within `max_steps` steps, and says whether the plan is ready. 2. **Refine.** If the plan is not ready, the planner refines it until it is ready or `max_attempts` is reached. 3. **Execute.** Each step becomes a todo item and runs in its own tool loop, limited by `max_step_iterations` and `step_timeout`. 4. **Observe.** After each step, the agent checks the result. How much it checks depends on `reasoning_effort`. 5. **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. 6. **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 **reasoning\_effort** `str` (default: medium) How much the agent checks and adapts after each step: `"low"`, `"medium"`, or `"high"`. **observe\_steps** `bool` (default: None) Run an LLM review after each step. `None` reviews on `"medium"` and `"high"` only. **max\_attempts** `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. **max\_steps** `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. **max\_replans** `int` (default: 3) Maximum number of full replans before the agent finalizes its answer. `0` disables replanning. **max\_step\_iterations** `int` (default: 15) Maximum LLM iterations for a single step. Lower values make steps faster but less thorough. **step\_timeout** `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. **llm** `str | BaseLLM` (default: None) The LLM used for planning and for the review after each step. `None` uses the agent's LLM. **system\_prompt** `str` (default: None) Custom system prompt for planning. `None` uses the built-in prompt. **plan\_prompt** `str` (default: None) Custom prompt for the first plan. See Custom prompts below. **refine\_prompt** `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: ```python theme={null} 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. ```python theme={null} 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}" ), ), ) ``` > [!WARNING] > > 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: ```python theme={null} 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. ```python theme={null} 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. > [!NOTE] > > `reasoning=True` and `max_reasoning_attempts` are deprecated. See [Reasoning](https://docs.crewai.com/edge/en/concepts/reasoning.md) 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: ```python Code theme={null} 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() ``` ````markdown Result theme={null} [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")`. > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.