> ## 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. # Planejamento > Aprenda como fazer agentes planejarem antes de agir com PlanningConfig e como planejar uma crew inteira com Crew(planning=True). ## 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: ```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) ``` 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: 1. **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. 2. **Refinar.** Se o plano não estiver pronto, o planejador o refina até que esteja pronto ou até atingir `max_attempts`. 3. **Executar.** Cada passo vira um item de todo e roda no próprio loop de ferramentas, limitado por `max_step_iterations` e `step_timeout`. 4. **Observar.** Depois de cada passo, o agente verifica o resultado. O quanto ele verifica depende de `reasoning_effort`. 5. **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. 6. **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 **reasoning\_effort** `str` (default: medium) Quanto o agente verifica e se adapta depois de cada passo: `"low"`, `"medium"` ou `"high"`. **observe\_steps** `bool` (default: None) Executa uma revisão por LLM depois de cada passo. `None` revisa apenas em `"medium"` e `"high"`. **max\_attempts** `int` (default: 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. **max\_steps** `int` (default: 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. **max\_replans** `int` (default: 3) Número máximo de replanejamentos completos antes de o agente finalizar a resposta. `0` desativa o replanejamento. **max\_step\_iterations** `int` (default: 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. **step\_timeout** `int` (default: 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. **llm** `str | BaseLLM` (default: None) O LLM usado no planejamento e na revisão depois de cada passo. `None` usa o LLM do agente. **system\_prompt** `str` (default: None) Prompt de sistema personalizado para o planejamento. `None` usa o prompt padrão. **plan\_prompt** `str` (default: None) Prompt personalizado para o primeiro plano. Veja Prompts personalizados abaixo. **refine\_prompt** `str` (default: 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: ```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", ), ) ``` ### 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. ```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] > > 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: ```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) ``` ### 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. ```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, ) ``` 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. > [!NOTE] > > `reasoning=True` e `max_reasoning_attempts` estão obsoletos. Veja [Reasoning](https://docs.crewai.com/edge/pt-BR/concepts/reasoning.md) 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: ```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]: 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")`. > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.