개요
CrewAI는 두 가지 수준에서 계획할 수 있습니다:- 에이전트 계획: 에이전트가 자신의 작업에 대한 단계별 계획을 작성한 뒤, 각 단계를 실행하고 확인합니다.
Agent(planning_config=PlanningConfig(...))로 설정합니다. - Crew 계획: crew가 실행되기 전에
CrewPlanner가 모든 작업에 대한 계획을 작성하고 각 작업 설명에 추가합니다.Crew(planning=True)로 활성화합니다.
에이전트 계획
에이전트에PlanningConfig를 전달하면 계획이 활성화됩니다:
PlanningConfig가 있으면 계획이 활성화됩니다. 끄려면 planning_config를 설정하지 마세요.
동작 방식
에이전트가 작업을 시작하면 계획-실행 루프를 실행합니다:- 계획. 계획 LLM이
max_steps개 단계 이내로 작성하라는 지시를 받아 계획을 작성하고, 계획이 준비되었는지 알려줍니다. - 개선. 계획이 준비되지 않았다면, 준비될 때까지 또는
max_attempts에 도달할 때까지 계획을 개선합니다. - 실행. 각 단계는 todo 항목이 되어 자체 도구 루프에서 실행되며,
max_step_iterations와step_timeout으로 제한됩니다. - 관찰. 각 단계가 끝나면 에이전트가 결과를 확인합니다. 얼마나 확인할지는
reasoning_effort에 따라 달라집니다. - 재계획.
reasoning_effort에 따라, 단계가 실패하거나 계획이 더 이상 맞지 않으면 에이전트는 최대max_replans번까지 새 계획을 작성합니다. - 답변. 에이전트가 단계 결과로 최종 답변을 만듭니다.
max_attempts 이후에도 계획이 준비되지 않았거나 계획 LLM이 function calling을 지원하지 않으면, 에이전트는 표준 실행 루프로 동작합니다.
추론 노력 수준
reasoning_effort는 각 단계 이후에 일어나는 일을 제어합니다:
observe_steps는 모든 수준에서 LLM 검토 여부를 덮어씁니다: True는 "low"에 검토를 추가하고, False는 "medium"과 "high"에서 검토를 제거합니다. observe_steps=True이면 "low"도 검토 결과 실패한 단계에 새 계획이 필요하다고 판단될 때 재계획합니다.
설정 옵션
str
기본값:"medium"
각 단계 이후 에이전트가 얼마나 확인하고 적응할지:
"low", "medium", "high".bool
기본값:"None"
각 단계 이후 LLM 검토를 실행합니다.
None이면 "medium"과 "high"에서만 검토합니다.int
기본값:"None"
첫 계획을 포함한 최대 계획 시도 횟수입니다.
None이면 계획기가 계획을 준비 완료로 표시할 때까지 계속 개선하므로 LLM 호출이 늘어날 수 있습니다. 숫자를 지정해 제한하세요.int
기본값:"20"
계획기가 지키도록 요청받는 단계 수 제한입니다. 프롬프트에
{max_steps}로 전달되며, 반환된 계획에 강제되지는 않습니다. 1 이상이어야 합니다.int
기본값:"3"
에이전트가 답변을 확정하기 전 전체 재계획의 최대 횟수입니다.
0이면 재계획하지 않습니다.int
기본값:"15"
단일 단계의 최대 LLM 반복 횟수입니다. 값이 낮을수록 단계가 빨라지지만 덜 철저해집니다.
int
기본값:"None"
단일 단계의 최대 시간(초)이며, 단계 안의 각 LLM 호출 전에 확인됩니다. 초과하면 단계가 멈추고 그때까지의 결과를 반환합니다. 단계는 실패로 표시되지 않으며, 이미 실행 중인 LLM 호출이나 도구 호출은 중단되지 않습니다.
None이면 시간 제한이 없습니다.str | BaseLLM
기본값:"None"
계획과 각 단계 이후 검토에 사용할 LLM입니다.
None이면 에이전트의 LLM을 사용합니다.str
기본값:"None"
계획용 사용자 지정 시스템 프롬프트입니다.
None이면 기본 프롬프트를 사용합니다.str
기본값:"None"
첫 계획용 사용자 지정 프롬프트입니다. 아래의 사용자 지정 프롬프트를 참고하세요.
str
기본값:"None"
계획 개선용 사용자 지정 프롬프트입니다. 아래의 사용자 지정 프롬프트를 참고하세요.
사용자 지정 프롬프트
plan_prompt와 refine_prompt는 Python의 str.format으로 채워집니다. 사용할 수 있는 플레이스홀더는 다음과 같습니다:
프롬프트에
{max_steps}가 없으면 계획기에는 단계 수 제한이 전달되지 않습니다.
작업 없이 계획하기
Task나 Crew 없이 kickoff()로 에이전트를 직접 호출해도 계획이 실행됩니다. 입력 메시지가 작업 설명으로 사용됩니다:
planning=True 단축 설정
Agent(planning=True)는 제한된 저비용 설정을 활성화합니다. 이는 PlanningConfig(reasoning_effort="low", max_attempts=1)과 같습니다: 계획 시도는 한 번이며, 각 단계 이후 LLM 검토를 하지 않습니다.
planning_config도 함께 전달하면 해당 설정이 우선합니다.
계획이 실패할 때
에이전트가 계획하는 중에 오류가 발생하면, 오류를 로그에 남기고 계획 없이 작업을 실행합니다.reasoning=True와 max_reasoning_attempts는 더 이상 권장되지 않습니다. 마이그레이션 방법은 Reasoning을 참고하세요.Crew 계획
Crew 계획이 활성화되면, 작업이 실행되기 전에 모든 crew 정보가CrewPlanner로 전송됩니다. 플래너는 각 작업을 단계별로 계획하고 그 계획을 해당 작업 설명에 추가합니다.
Crew 계획 사용하기
Crew에planning=True를 추가하세요. crew를 시작할 때마다 CrewPlanner가 Result 탭과 같은 계획을 작성하고, 각 작업에 해당하는 부분을 그 작업 설명에 추가합니다:
계획 LLM
Crew 계획은 기본적으로gpt-5.4-mini를 사용합니다. 다른 모델을 사용하려면 planning_llm을 모델 이름 또는 LLM 인스턴스로 설정하세요. 예: Crew(..., planning=True, planning_llm="gpt-5").
