> ## 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. # 계획 > PlanningConfig로 에이전트가 행동하기 전에 계획하도록 하는 방법과 Crew(planning=True)로 crew 전체를 계획하는 방법을 알아보세요. ## 개요 CrewAI는 두 가지 수준에서 계획할 수 있습니다: * **에이전트 계획**: 에이전트가 자신의 작업에 대한 단계별 계획을 작성한 뒤, 각 단계를 실행하고 확인합니다. `Agent(planning_config=PlanningConfig(...))`로 설정합니다. * **Crew 계획**: crew가 실행되기 전에 `CrewPlanner`가 모든 작업에 대한 계획을 작성하고 각 작업 설명에 추가합니다. `Crew(planning=True)`로 활성화합니다. 둘 중 하나만 사용하거나 함께 사용할 수 있습니다. ## 에이전트 계획 에이전트에 `PlanningConfig`를 전달하면 계획이 활성화됩니다: ```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) ``` `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`는 각 단계 이후에 일어나는 일을 제어합니다: | 수준 | 각 단계 이후 | 비용 | | - | - | - | | `"low"` | 추가 LLM 호출 없이 휴리스틱으로 확인합니다. 실패한 단계는 실패로 표시되고, 재계획 없이 순서대로 진행합니다. | 가장 빠름 | | `"medium"` (기본값) | LLM이 단계를 검토합니다. 단계가 실패했고 검토 결과 계획이 더 이상 통하지 않는다고 판단되면 재계획하고, 그렇지 않으면 단계를 실패로 표시하고 계속 진행합니다. | 균형 | | `"high"` | LLM이 단계를 검토한 뒤, 일찍 끝낼지, 재계획할지, 남은 단계를 개선할지 결정합니다. | 가장 적응적, 가장 느림 | `observe_steps`는 모든 수준에서 LLM 검토 여부를 덮어씁니다: `True`는 `"low"`에 검토를 추가하고, `False`는 `"medium"`과 `"high"`에서 검토를 제거합니다. `observe_steps=True`이면 `"low"`도 검토 결과 실패한 단계에 새 계획이 필요하다고 판단될 때 재계획합니다. ### 설정 옵션 **reasoning\_effort** `str` (default: medium) 각 단계 이후 에이전트가 얼마나 확인하고 적응할지: `"low"`, `"medium"`, `"high"`. **observe\_steps** `bool` (default: None) 각 단계 이후 LLM 검토를 실행합니다. `None`이면 `"medium"`과 `"high"`에서만 검토합니다. **max\_attempts** `int` (default: None) 첫 계획을 포함한 최대 계획 시도 횟수입니다. `None`이면 계획기가 계획을 준비 완료로 표시할 때까지 계속 개선하므로 LLM 호출이 늘어날 수 있습니다. 숫자를 지정해 제한하세요. **max\_steps** `int` (default: 20) 계획기가 지키도록 요청받는 단계 수 제한입니다. 프롬프트에 `{max_steps}`로 전달되며, 반환된 계획에 강제되지는 않습니다. 1 이상이어야 합니다. **max\_replans** `int` (default: 3) 에이전트가 답변을 확정하기 전 전체 재계획의 최대 횟수입니다. `0`이면 재계획하지 않습니다. **max\_step\_iterations** `int` (default: 15) 단일 단계의 최대 LLM 반복 횟수입니다. 값이 낮을수록 단계가 빨라지지만 덜 철저해집니다. **step\_timeout** `int` (default: None) 단일 단계의 최대 시간(초)이며, 단계 안의 각 LLM 호출 전에 확인됩니다. 초과하면 단계가 멈추고 그때까지의 결과를 반환합니다. 단계는 실패로 표시되지 않으며, 이미 실행 중인 LLM 호출이나 도구 호출은 중단되지 않습니다. `None`이면 시간 제한이 없습니다. **llm** `str | BaseLLM` (default: None) 계획과 각 단계 이후 검토에 사용할 LLM입니다. `None`이면 에이전트의 LLM을 사용합니다. **system\_prompt** `str` (default: None) 계획용 사용자 지정 시스템 프롬프트입니다. `None`이면 기본 프롬프트를 사용합니다. **plan\_prompt** `str` (default: None) 첫 계획용 사용자 지정 프롬프트입니다. 아래의 사용자 지정 프롬프트를 참고하세요. **refine\_prompt** `str` (default: None) 계획 개선용 사용자 지정 프롬프트입니다. 아래의 사용자 지정 프롬프트를 참고하세요. 다음 에이전트는 계획에 별도의 저렴한 모델을 사용하고 루프의 모든 부분을 제한합니다: ```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", ), ) ``` ### 사용자 지정 프롬프트 `plan_prompt`와 `refine_prompt`는 Python의 `str.format`으로 채워집니다. 사용할 수 있는 플레이스홀더는 다음과 같습니다: | 프롬프트 | 플레이스홀더 | | - | - | | `plan_prompt` | `{role}`, `{goal}`, `{backstory}`, `{description}`, `{expected_output}`, `{tools}`, `{max_steps}` | | `refine_prompt` | `{role}`, `{goal}`, `{backstory}`, `{current_plan}`, `{max_steps}` | 프롬프트에 `{max_steps}`가 없으면 계획기에는 단계 수 제한이 전달되지 않습니다. ```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] > > 다른 플레이스홀더나 리터럴 `{` 또는 `}`가 있으면 계획이 실패합니다. 그러면 에이전트는 오류를 로그에 남기고 계획 없이 실행됩니다. 리터럴 중괄호는 `{{`와 `}}`로 작성하세요. ### 작업 없이 계획하기 `Task`나 `Crew` 없이 `kickoff()`로 에이전트를 직접 호출해도 계획이 실행됩니다. 입력 메시지가 작업 설명으로 사용됩니다: ```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) ``` ### `planning=True` 단축 설정 `Agent(planning=True)`는 제한된 저비용 설정을 활성화합니다. 이는 `PlanningConfig(reasoning_effort="low", max_attempts=1)`과 같습니다: 계획 시도는 한 번이며, 각 단계 이후 LLM 검토를 하지 않습니다. ```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, ) ``` `planning_config`도 함께 전달하면 해당 설정이 우선합니다. ### 계획이 실패할 때 에이전트가 계획하는 중에 오류가 발생하면, 오류를 로그에 남기고 계획 없이 작업을 실행합니다. > [!NOTE] > > `reasoning=True`와 `max_reasoning_attempts`는 더 이상 권장되지 않습니다. 마이그레이션 방법은 [Reasoning](https://docs.crewai.com/edge/ko/concepts/reasoning.md)을 참고하세요. ## Crew 계획 Crew 계획이 활성화되면, 작업이 실행되기 전에 모든 crew 정보가 `CrewPlanner`로 전송됩니다. 플래너는 각 작업을 단계별로 계획하고 그 계획을 해당 작업 설명에 추가합니다. ### Crew 계획 사용하기 Crew에 `planning=True`를 추가하세요. crew를 시작할 때마다 `CrewPlanner`가 **Result** 탭과 같은 계획을 작성하고, 각 작업에 해당하는 부분을 그 작업 설명에 추가합니다: ```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]: Planning the crew execution **작업 실행을 위한 단계별 계획** **작업 번호 1: AI LLM에 대해 철저히 조사하기** **에이전트:** AI LLMs 시니어 데이터 리서처 **에이전트 목표:** AI LLM의 최신 개발 동향 파악 **작업 예상 결과:** AI LLM에 대한 가장 관련성 높은 정보 10가지가 포함된 리스트 **작업 도구:** 명시되지 않음 **에이전트 도구:** 명시되지 않음 **단계별 계획:** 1. **조사 범위 정의:** - 아키텍처의 발전, 사용 사례, 윤리적 고려사항, 성능 측정 기준 등 AI LLM의 특정 영역을 결정합니다. 2. **신뢰할 수 있는 출처 식별:** - 학술지, 산업 리포트, 컨퍼런스(예: NeurIPS, ACL), AI 연구소(예: OpenAI, Google AI), 온라인 데이터베이스(예: IEEE Xplore, arXiv) 등 AI 연구를 위한 평판 좋은 출처를 나열합니다. 3. **데이터 수집:** - 2024년 및 2025년 초에 발표된 최신 논문, 기사, 리포트를 검색합니다. - "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025"와 같은 키워드를 사용합니다. 4. **발견 사항 분석:** - 각 출처에서 핵심 내용을 읽고 요약합니다. - 지난 1년간 소개된 새로운 기술, 모델, 애플리케이션 등을 강조합니다. 5. **정보 정리:** - 정보를 관련 주제별로 분류합니다(예: 새로운 아키텍처, 윤리적 영향, 실세계 적용 등). - 각 핵심 포인트는 간결하면서도 정보가 풍부하도록 합니다. 6. **리스트 작성:** - 가장 관련성 높은 10가지 정보를 불릿 포인트로 정리합니다. - 리스트가 명확하고 적절한지 검토합니다. **예상 결과:** AI LLM에 대한 가장 관련성 높은 정보 10가지를 담은 불릿 포인트 리스트. --- **작업 번호 2: 받은 컨텍스트를 검토하고 각 주제를 리포트의 전체 섹션으로 확장하기** **에이전트:** AI LLMs 리포팅 애널리스트 **에이전트 목표:** AI LLM 데이터 분석 및 연구 결과를 기반으로 상세 리포트를 작성 **작업 예상 결과:** 주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이) **작업 도구:** 명시되지 않음 **에이전트 도구:** 명시되지 않음 **단계별 계획:** 1. **불릿 포인트 검토:** - AI LLMs 시니어 데이터 리서처가 제공한 10가지 불릿 포인트 리스트를 꼼꼼히 읽습니다. 2. **리포트 개요 작성:** - 각 불릿 포인트를 주요 섹션 제목으로 삼아 개요를 만듭니다. - 각 주요 제목 아래 하위 섹션을 기획하여 해당 주제의 다양한 측면을 다룹니다. 3. **추가 세부 사항 조사:** - 각 불릿 포인트별로, 더 자세한 정보를 수집하기 위해 필요 시 추가 조사를 진행합니다. - 각 섹션을 뒷받침할 사례 연구, 예시, 통계자료 등을 찾습니다. 4. **상세 섹션 작성:** - 각 불릿 포인트를 포괄적인 섹션으로 확장합니다. - 각 섹션에는 도입, 상세 설명, 예시, 결론이 포함되어야 합니다. - 제목, 부제목, 리스트, 강조 등 마크다운 포맷을 사용합니다. 5. **검토 및 편집:** - 리포트의 명확성, 일관성, 정확성을 위해 교정합니다. - 리포트가 각 섹션에서 논리적으로 자연스럽게 흐르는지 확인합니다. - 마크다운 기준에 맞게 포맷을 맞춥니다. 6. **리포트 최종화:** - 모든 섹션이 확장되고 상세하게 작성되어 완전한 리포트가 되었는지 확인합니다. - 포맷을 다시 확인하고 필요한 경우 수정합니다. **예상 결과:** 주요 주제별로 각 섹션이 포함된 완전한 리포트 (마크다운 형식, '```' 없이). ```` ### 계획 LLM Crew 계획은 기본적으로 `gpt-5.4-mini`를 사용합니다. 다른 모델을 사용하려면 `planning_llm`을 모델 이름 또는 `LLM` 인스턴스로 설정하세요. 예: `Crew(..., planning=True, planning_llm="gpt-5")`. > [!WARNING] > > 기본 계획 LLM을 사용하면, 에이전트가 다른 제공자를 사용하더라도 crew 계획에는 유효한 OpenAI API 키가 필요합니다. OpenAI API 키가 설정되어 있지 않다면 `planning_llm`을 사용할 수 있는 모델로 설정하세요. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.