Planejamento

Visão geral

O CrewAI pode planejar em dois níveis:

Planejamento do agente: o agente escreve um plano passo a passo para o próprio trabalho e depois executa e verifica cada passo. Configure com Agent(planning_config=PlanningConfig(...)).
Planejamento da crew: antes de a crew rodar, um CrewPlanner escreve um plano para cada tarefa e o adiciona à descrição de cada tarefa. Ative com Crew(planning=True).

Você pode usar qualquer um deles, ou os dois juntos.

Planejamento do agente

Passe um PlanningConfig para um agente para ativar o planejamento:

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)

A presença de um PlanningConfig ativa o planejamento. Para desativá-lo, deixe planning_config sem valor.

Como funciona

Quando o agente inicia uma tarefa, ele executa um ciclo de planejar e executar:

Planejar. O LLM de planejamento escreve um plano, com a instrução de ficar dentro de max_steps passos, e informa se o plano está pronto.
Refinar. Se o plano não estiver pronto, o planejador o refina até que esteja pronto ou até atingir max_attempts.
Executar. Cada passo vira um item de todo e roda no próprio loop de ferramentas, limitado por max_step_iterations e step_timeout.
Observar. Depois de cada passo, o agente verifica o resultado. O quanto ele verifica depende de reasoning_effort.
Replanejar. Dependendo de reasoning_effort, um passo que falha ou um plano que deixa de servir faz o agente escrever um novo plano, até max_replans vezes.
Responder. O agente monta a resposta final a partir dos resultados dos passos.

O plano fica no estado de execução do agente. Ele não é adicionado à descrição da tarefa. A execução passo a passo precisa de um plano pronto com passos estruturados, que o planejador obtém por meio de function calling. Se o plano ainda não estiver pronto depois de max_attempts, ou se o LLM de planejamento não suportar function calling, o agente usa o loop de execução padrão.

Esforço de raciocínio

reasoning_effort controla o que acontece depois de cada passo:

Nível	Depois de cada passo	Custo
`"low"`	Uma verificação heurística, sem chamada extra ao LLM. Um passo que falha é marcado como falho e o agente segue em ordem, sem replanejar.	Mais rápido
`"medium"` (padrão)	Um LLM revisa o passo. Se o passo falhou e a revisão diz que o plano não funciona mais, o agente replaneja; caso contrário, marca o passo como falho e continua.	Equilibrado
`"high"`	Um LLM revisa o passo e depois decide se termina antes, replaneja ou refina os passos restantes.	Mais adaptável, mais lento

observe_steps substitui a revisão por LLM em qualquer nível: True a adiciona ao "low", e False a remove de "medium" e "high". Com observe_steps=True, o "low" também replaneja quando a revisão diz que um passo que falhou precisa de um novo plano.

Opções de configuração

str

padrão:"medium"

Quanto o agente verifica e se adapta depois de cada passo: "low", "medium" ou "high".

bool

padrão:"None"

Executa uma revisão por LLM depois de cada passo. None revisa apenas em "medium" e "high".

int

padrão:"None"

Número máximo de tentativas de planejamento, contando o primeiro plano. None continua refinando até o planejador marcar o plano como pronto, o que pode gerar mais chamadas ao LLM. Defina um número para limitar.

int

padrão:"20"

O limite de passos que o planejador deve respeitar. Ele é passado ao prompt como {max_steps} e não é aplicado ao plano retornado. Deve ser pelo menos 1.

int

padrão:"3"

Número máximo de replanejamentos completos antes de o agente finalizar a resposta. 0 desativa o replanejamento.

int

padrão:"15"

Número máximo de iterações do LLM em um único passo. Valores menores deixam os passos mais rápidos, porém menos completos.

int

padrão:"None"

Tempo máximo, em segundos, para um único passo, verificado antes de cada chamada ao LLM no passo. Quando ele é excedido, o passo para e retorna o que tem até então. O passo não é marcado como falho, e uma chamada ao LLM ou a uma ferramenta já em andamento não é interrompida. None significa sem limite de tempo.

str | BaseLLM

padrão:"None"

O LLM usado no planejamento e na revisão depois de cada passo. None usa o LLM do agente.

str

padrão:"None"

Prompt de sistema personalizado para o planejamento. None usa o prompt padrão.

str

padrão:"None"

Prompt personalizado para o primeiro plano. Veja Prompts personalizados abaixo.

str

padrão:"None"

Prompt personalizado para refinar um plano. Veja Prompts personalizados abaixo.

Este agente usa um modelo separado e mais barato para o planejamento e limita cada parte do ciclo:

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",
    ),
)

Prompts personalizados

plan_prompt e refine_prompt são preenchidos com str.format do Python. Estes placeholders estão disponíveis:

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

Se seus prompts não incluírem {max_steps}, o planejador não recebe nenhum limite de passos.

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}"
        ),
    ),
)

Qualquer outro placeholder, ou um { ou } literal, faz o planejamento falhar. O agente então registra o erro no log e roda sem plano. Escreva chaves literais como {{ e }}.

Planejamento sem tarefa

O planejamento também roda quando você chama um agente diretamente com kickoff(), sem uma Task ou uma Crew. A mensagem de entrada é usada como descrição da tarefa:

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)

O atalho `planning=True`

Agent(planning=True) ativa uma configuração limitada e de baixo custo. Ela equivale a PlanningConfig(reasoning_effort="low", max_attempts=1): uma tentativa de planejamento e nenhuma revisão por LLM depois de cada passo.

from crewai import Agent

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

Se você também passar planning_config, ele tem prioridade.

Quando o planejamento falha

Se ocorrer um erro enquanto o agente planeja, o erro é registrado no log e o agente executa a tarefa sem plano.

reasoning=True e max_reasoning_attempts estão obsoletos. Veja Reasoning para saber como migrar.

Planejamento da crew

Quando o planejamento da crew está ativado, todas as informações da crew são enviadas para um CrewPlanner antes de as tarefas rodarem. Ele planeja cada tarefa passo a passo e adiciona o plano à descrição dessa tarefa.

Usando o planejamento da crew

Adicione planning=True à sua Crew. Sempre que a crew é iniciada, o CrewPlanner escreve um plano como o da aba Result e adiciona a parte de cada tarefa à descrição dessa tarefa:

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]: Planejando a execução da crew
**Plano Passo a Passo para Execução das Tarefas**

**Tarefa Número 1: Realizar uma pesquisa aprofundada sobre LLMs de IA**

**Agente:** Pesquisador Sênior de Dados de LLMs de IA

**Objetivo do Agente:** Descobrir avanços de ponta em LLMs de IA

**Resultado Esperado da Tarefa:** Uma lista com 10 tópicos dos dados mais relevantes sobre LLMs de IA

**Ferramentas da Tarefa:** Nenhuma especificada

**Ferramentas do Agente:** Nenhuma especificada

**Plano Passo a Passo:**

1. **Definir o Escopo da Pesquisa:**

   - Determine as áreas específicas de LLMs de IA a focar, como avanços em arquitetura, casos de uso, considerações éticas e métricas de performance.

2. **Identificar Fontes Confiáveis:**

   - Liste fontes confiáveis para pesquisa em IA, incluindo periódicos acadêmicos, relatórios da indústria, conferências (ex: NeurIPS, ACL), laboratórios de pesquisa em IA (ex: OpenAI, Google AI) e bancos de dados online (ex: IEEE Xplore, arXiv).

3. **Coletar Dados:**

   - Procure pelos artigos, publicações e relatórios mais recentes publicados em 2024 e início de 2025.
   - Use palavras-chave como "Large Language Models 2025", "Avanços em LLM de IA", "Ética em IA 2025", etc.

4. **Analisar Resultados:**

   - Leia e resuma os principais pontos de cada fonte.
   - Destaque novas técnicas, modelos e aplicações introduzidos no último ano.

5. **Organizar as Informações:**

   - Categorize as informações em tópicos relevantes (ex: novas arquiteturas, implicações éticas, aplicações no mundo real).
   - Garanta que cada tópico seja conciso, mas informativo.

6. **Criar a Lista:**

   - Compile os 10 dados mais relevantes em itens de uma lista.
   - Revise a lista para garantir clareza e relevância.

**Saída Esperada:**

Uma lista com 10 tópicos dos dados mais relevantes sobre LLMs de IA.

---

**Tarefa Número 2: Revise o contexto obtido e expanda cada tópico em uma seção completa para um relatório**

**Agente:** Analista de Relatórios de LLMs de IA

**Objetivo do Agente:** Criar relatórios detalhados baseados na análise de dados e pesquisa sobre LLMs de IA

**Resultado Esperado da Tarefa:** Um relatório completo com os principais tópicos, cada um com uma seção completa de informações. Formatado em markdown sem '```'

**Ferramentas da Tarefa:** Nenhuma especificada

**Ferramentas do Agente:** Nenhuma especificada

**Plano Passo a Passo:**

1. **Revisar os Tópicos:**
   - Leia atentamente a lista dos 10 tópicos fornecida pelo Pesquisador Sênior de Dados de LLMs de IA.

2. **Esboçar o Relatório:**
   - Crie um esboço com cada tópico como título principal da seção.
   - Planeje subseções sob cada título para abordar diferentes aspectos do tema.

3. **Pesquisar Detalhes Adicionais:**
   - Para cada tópico, conduza pesquisa adicional, se necessário, para reunir informações mais detalhadas.
   - Busque estudos de caso, exemplos e dados estatísticos para embasar cada seção.

4. **Redigir Seções Detalhadas:**
   - Expanda cada tópico em uma seção abrangente.
   - Certifique-se de que cada seção inclua introdução, explicação detalhada, exemplos e conclusão.
   - Utilize formatação markdown para títulos, subtítulos, listas e ênfase.

5. **Revisar e Editar:**
   - Revise o relatório para garantir clareza, coerência e correção.
   - Garanta uma sequência lógica de uma seção para a outra.
   - Formate o relatório conforme os padrões markdown.

6. **Finalizar o Relatório:**
   - Certifique-se de que o relatório está completo, com todas as seções expandidas e detalhadas.
   - Faça uma última verificação de formatação e ajustes necessários.

**Saída Esperada:**
Um relatório completo com os principais tópicos, cada um com uma seção cheia de informações. Formatado em markdown sem '```'.

LLM de planejamento

O planejamento da crew usa gpt-5.4-mini por padrão. Defina planning_llm com o nome de um modelo ou uma instância de LLM para usar outro modelo, por exemplo Crew(..., planning=True, planning_llm="gpt-5").

Com o LLM de planejamento padrão, o planejamento da crew precisa de uma chave de API da OpenAI válida, mesmo que seus agentes usem outros provedores. Se você não tiver uma chave de API da OpenAI configurada, defina planning_llm com um modelo ao qual você tenha acesso.

Começando

Guias

Conceitos-Chave

Integração MCP

Ferramentas

Observabilidade

Aprenda

Telemetria

Visão geral

Planejamento do agente

Como funciona

Esforço de raciocínio

Opções de configuração

Prompts personalizados

Planejamento sem tarefa

O atalho `planning=True`

Quando o planejamento falha

Planejamento da crew

Usando o planejamento da crew

LLM de planejamento

​Visão geral

​Planejamento do agente

​Como funciona

​Esforço de raciocínio

​Opções de configuração

​Prompts personalizados

​Planejamento sem tarefa

​O atalho planning=True

​Quando o planejamento falha

​Planejamento da crew

​Usando o planejamento da crew

​LLM de planejamento

Visão geral

Planejamento do agente

Como funciona

Esforço de raciocínio

Opções de configuração

Prompts personalizados

Planejamento sem tarefa

O atalho `planning=True`

Quando o planejamento falha

Planejamento da crew

Usando o planejamento da crew

LLM de planejamento