메인 콘텐츠로 건너뛰기

개요

CrewAI는 두 가지 수준에서 계획할 수 있습니다:
  • 에이전트 계획: 에이전트가 자신의 작업에 대한 단계별 계획을 작성한 뒤, 각 단계를 실행하고 확인합니다. Agent(planning_config=PlanningConfig(...))로 설정합니다.
  • Crew 계획: crew가 실행되기 전에 CrewPlanner가 모든 작업에 대한 계획을 작성하고 각 작업 설명에 추가합니다. Crew(planning=True)로 활성화합니다.
둘 중 하나만 사용하거나 함께 사용할 수 있습니다.

에이전트 계획

에이전트에 PlanningConfig를 전달하면 계획이 활성화됩니다:
PlanningConfig가 있으면 계획이 활성화됩니다. 끄려면 planning_config를 설정하지 마세요.

동작 방식

에이전트가 작업을 시작하면 계획-실행 루프를 실행합니다:
  1. 계획. 계획 LLM이 max_steps개 단계 이내로 작성하라는 지시를 받아 계획을 작성하고, 계획이 준비되었는지 알려줍니다.
  2. 개선. 계획이 준비되지 않았다면, 준비될 때까지 또는 max_attempts에 도달할 때까지 계획을 개선합니다.
  3. 실행. 각 단계는 todo 항목이 되어 자체 도구 루프에서 실행되며, max_step_iterations와 step_timeout으로 제한됩니다.
  4. 관찰. 각 단계가 끝나면 에이전트가 결과를 확인합니다. 얼마나 확인할지는 reasoning_effort에 따라 달라집니다.
  5. 재계획. reasoning_effort에 따라, 단계가 실패하거나 계획이 더 이상 맞지 않으면 에이전트는 최대 max_replans번까지 새 계획을 작성합니다.
  6. 답변. 에이전트가 단계 결과로 최종 답변을 만듭니다.
계획은 에이전트의 실행 상태에 보관됩니다. 작업 설명에는 추가되지 않습니다. 단계별 실행에는 구조화된 단계가 있는 준비된 계획이 필요하며, 계획기는 function calling으로 이를 얻습니다. 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").
기본 계획 LLM을 사용하면, 에이전트가 다른 제공자를 사용하더라도 crew 계획에는 유효한 OpenAI API 키가 필요합니다. OpenAI API 키가 설정되어 있지 않다면 planning_llm을 사용할 수 있는 모델로 설정하세요.