What is AgentPlanner?
AgentPlanner is the implementation behind Crew(planning=True, planning_llm=...). Before iterations advance, it reads the crew's agents, tasks, and descriptions, asks the planning LLM for a coordinated step list, and prepends that plan to every task description so each agent sees the same playbook. That shared context reduces duplicated work and contradictory assumptions at the cost of an extra LLM call per planning cycle.
The planner is not a replacement for Flow-level routing or for per-agent reasoning=True; it is a shallow, crew-wide preamble. It works best when tasks are loosely coupled but need a consistent ordering narrative (research → outline → draft) and worst when tasks are independent embarrassingly parallel units where the plan adds noise. Choose planning_llm deliberately: a small fast model saves money but may emit vague plans; a larger model costs more but stabilizes cross-task references.
Operationally, treat planning as part of your token budget. Log CrewOutput.token_usage with planning on and off to quantify overhead. If plans rarely change between kicks, cache the generated plan text externally and inject it via task description templates instead of enabling the automatic planner for every run.
When to Use
Complex multi-step crews where coordination overhead hurts quality more than the extra planning LLM call.
Use Cases
- • Cross-task coherence
- • Complex pipelines
- • Reducing duplicated agent assumptions
Key Features
- ✓ Pre-iteration plan
- ✓ Plan injected per task
- ✓ Optional dedicated planning_llm
When NOT to Use
Short linear pipelines, tight latency budgets, or when Flow @router already encodes your branching.
Notes
Double counting LLM calls
Planning issues its own completion before task work begins. Combining planning=True with reasoning=True on large crews can multiply costs quickly — profile on representative inputs before enabling both everywhere.
Stale plans on dynamic inputs
The planner sees a snapshot of descriptions at planning time. If upstream tools mutate critical context later, the preamble may be stale. Refresh descriptions or disable planning for highly dynamic tool-heavy crews.
planning_llm defaults
If planning_llm is omitted, CrewAI falls back according to version defaults, which may differ from your agents' primary LLM. Set planning_llm explicitly so cost and capability are predictable.
Import
# Indirect: Crew(planning=True)Code Examples
Enable with a dedicated planning model
from crewai import Crew, Process
crew = Crew(
agents=[researcher, writer],
tasks=[gather, draft],
process=Process.sequential,
planning=True,
planning_llm='openai/gpt-4o-mini',
verbose=True,
)Compare cost: toggle planning in config
import os
planning_on = os.environ.get('CREW_PLANNING', '0') == '1'
crew = Crew(
agents=agents,
tasks=tasks,
planning=planning_on,
planning_llm='openai/gpt-4o' if planning_on else None,
)Pair with verbose tracing to inspect injected plans
crew = Crew(
agents=[researcher, editor],
tasks=[outline, polish],
planning=True,
planning_llm='openai/gpt-4o',
verbose=2,
)Common Mistakes
❌ Enabling planning + reasoning everywhere without measuring tokens
✅ Toggle flags per environment and inspect CrewOutput.token_usage for regressions.
❌ Expecting AgentPlanner to enforce tool order
✅ Use explicit Task.context dependencies or Flow orchestration — the planner only emits narrative guidance.
AgentPlanner FAQ
What is AgentPlanner in CrewAI?
Internal planner that runs when Crew(planning=True) — produces a step-by-step plan prepended to each task. AgentPlanner is the implementation behind Crew(planning=True, planning_llm=...). Before iterations advance, it reads the crew's agents, tasks, and descriptions, asks the planning LLM for a coordinated step list, and prepends that plan to every task description so each agent sees the same playbook. That shared context reduces duplicated work and contradictory assumptions at the cost of an extra LLM call per planning cycle. The planner is not a replacement for Flow-level routi…
Which package defines the CrewAI class AgentPlanner?
DevShelfHub maps AgentPlanner to Python module crewai.agents.planner (package path crewai.agents.planner in this reference). Pin your installed crewai version and match imports to the snippet on this page.
When should I use AgentPlanner?
Complex multi-step crews where coordination overhead hurts quality more than the extra planning LLM call.
When should I avoid using AgentPlanner?
Short linear pipelines, tight latency budgets, or when Flow @router already encodes your branching.
How do I import AgentPlanner in Python?
# Indirect: Crew(planning=True)
Where can I explore more CrewAI API reference pages?
Open the CrewAI API reference index on DevShelfHub to search 58 classes, 30 methods, and 16 decorators, each with runnable examples, parameters, common mistakes, and cross-links.