CrewAI 에이전트가 중복 작업을 실행하지 않도록 하는 방법: 실용적인 중복 제거 가이드

CrewAI 에이전트가 동일한 작업을 두 번 실행하는 것처럼 보이는 경우, 그 원인은 대개 단일 "작업 중복" 설정이 아닙니다. 반복은 작업 설명의 중복, 계층적 위임, 재시도 동작, 여러 개의 Flow 트리거, 반복적인 크루 시작 또는 멱등성 키로 보호되지 않은 부작용을 일으키는 도구로 인해 발생할 수 있습니다.

이 실무 참고 자료는 2026년 9월 13일에 CrewAI 공식 문서를 기준으로 검증되었습니다. 현재 문서는 CrewAI v1.15.14 버전을 기준으로 작성되었습니다. 가장 중요한 차이점은 다음과 같습니다. 한 번의 실행 내에서 중복된 추론을 방지하는 것과 여러 번의 실행에 걸쳐 동일한 비즈니스 작업이 두 번 발생하는 것을 방지하는 것은 다릅니다 . CrewAI는 작업 컨텍스트, 조건부 작업, 콜백, 플로우 상태, 영속성 및 도구 캐싱 기능을 제공하지만, 한 번만 수행되어야 하는 작업에 대해서는 명시적인 건너뛰기 조건을 설계해야 합니다.

빠른 진단: 왜 같은 작업이 두 번 발생하는 걸까요?

공식 참조: CrewAI 작업 , CrewAI 에이전트 및 CrewAI 흐름 .

1. 작업 단위당 소유자 한 명으로 시작하세요.

가장 간단하면서도 가장 효과적인 중복 방지 규칙은 각 의미 있는 작업 단위마다 한 명의 작업 담당자가 있어야 한다는 것입니다. 순차적인 CrewAI 프로세스에서 작업은 선언된 순서대로 실행됩니다. 이 context속성을 사용하면 나중에 실행되는 작업이 동일한 정보를 독립적으로 다시 찾는 대신 이전 작업의 출력을 사용할 수 있습니다.

일반적인 안티패턴은 개념적으로 다음과 같습니다.

research_task: "Research the customer and summarize findings"
analysis_task: "Research the customer, analyze findings, and recommend actions"
writer_task:   "Review the customer, research missing details, and write the report"

세 가지 작업 모두 검색 권한이 포함되어 있으므로 반복적인 검색이 예상됩니다. 더 간결한 검색 체인을 선호하세요.

from crewai import Agent, Crew, Process, Task

research_task = Task(
    description="Research the customer once and return verified facts and sources.",
    expected_output="Structured research notes with sources.",
    agent=researcher,
)

analysis_task = Task(
    description="Analyze only the research provided in context. Do not perform new research.",
    expected_output="Prioritized findings and recommendations.",
    agent=analyst,
    context=[research_task],
)

crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
)

CrewAI의 현재 작업 문서에서는 명시적으로 작업 종속성을 지원하며 context, 순차 프로세스는 나열된 순서대로 작업을 실행합니다. 공식 작업 종속성 문서 및 프로세스 문서를 참조하십시오 .

업무 경계 설정을 위한 실용적인 체크리스트

• 각 작업에 다른 작업과 다른 동사를 부여하세요. 예를 들어, 조사하다, 표준화하다, 분석하다, 작성하다, 검토하다 등이 있습니다.
• 중복 작업이 비용이 많이 드는 경우, 해당 작업이 수행해서는 안 되는 작업을 명시하십시오.
• 다음 작업에서 직접 활용할 수 있도록 예상 출력을 충분히 구체적으로 만드세요.
• context나중에 상담원에게 "필요하면 직접 조사하세요"라고 말하는 대신, 이전 결과를 전달하세요 .
• 검색, 데이터베이스 쓰기, 메시지 전송 또는 외부 API 호출을 특정 역할만 허용해야 하는 경우 작업 또는 에이전트 수준에서 도구를 제한합니다.

2. ConditionalTask를 사용하여 이미 완료된 작업은 건너뜁니다.

이전 결과가 불완전할 때만 필요한 작업이라면, 에이전트가 작업을 반복할지 여부를 비공식적으로 결정하도록 하지 마십시오. CrewAI는 ConditionalTask이전 작업의 출력을 조건으로 받아들이고 조건이 거짓일 경우 실행을 건너뛸 수 있는 기능을 제공합니다.

공식 예제에서는 충분한 이벤트 레코드가 반환되었는지 확인하는 조건을 사용합니다. 이미 충분한 데이터가 있는 경우 추가 가져오기 작업은 건너뜁니다. CrewAI 조건부 작업을 참조하세요 .

from typing import List
from pydantic import BaseModel
from crewai import Agent, Crew, Task
from crewai.tasks.conditional_task import ConditionalTask
from crewai.tasks.task_output import TaskOutput

class ResearchOutput(BaseModel):
    sources: List[str]
    summary: str

def needs_more_sources(output: TaskOutput) -> bool:
    return len(output.pydantic.sources) < 5

research = Task(
    description="Find up to five authoritative sources about the topic.",
    expected_output="A structured research result.",
    agent=researcher,
    output_pydantic=ResearchOutput,
)

enrich = ConditionalTask(
    description="Find only the missing sources needed to reach five total.",
    expected_output="Additional authoritative sources only.",
    condition=needs_more_sources,
    agent=researcher,
)

이 패턴은 에이전트에게 "중복 작업을 피하세요"라고 지시하는 것보다 더 강력한데, 그 이유는 건너뛰기 결정이 다른 언어 모델의 판단이 아니라 결정론적인 파이썬 논리에 기반하기 때문입니다.

3. 위임이 명백한 중복을 초래하는 시점을 파악하십시오.

CrewAI는 순차적 프로세스와 계층적 프로세스를 모두 지원합니다. 계층적 팀 구성에서 관리자는 작업을 할당하고, 업무를 위임하고, 결과물을 검증하고, 작업 완료가 만족스러운지 판단합니다. 이러한 유연성은 작업 할당이 유동적이어야 할 때 유용하지만, 순차적 팀 구성에 비해 책임 소재가 명확하지 않다는 단점도 있습니다.

CrewAI의 에이전트 문서에는 현재 allow_delegation기본값이 로 설정되어 있다고 명시되어 있습니다 False. 에이전트가 다른 에이전트에게 작업을 인계해야 하는 경우가 아니라면 전문가의 경우 기본값을 유지하십시오. 계층적 프로세스에서는 관리자 자신이 위임에 대한 책임이 있습니다. 계층적 프로세스 가이드를 참조하십시오 .

중복 호출이 발생하는 승무원을 위한 안전한 시작점은 다음과 같습니다.

researcher = Agent(
    role="Researcher",
    goal="Collect evidence once and return it in structured form.",
    backstory="You gather evidence; you do not write the final report.",
    allow_delegation=False,
    max_iter=8,
    max_retry_limit=1,
)

writer = Agent(
    role="Writer",
    goal="Write from supplied context without doing fresh research.",
    backstory="You synthesize existing evidence into a final answer.",
    allow_delegation=False,
    max_iter=6,
)

그런 다음, 측정 가능한 이점을 제공하는 경우에만 위임 기능을 다시 추가하십시오. 계층적 오케스트레이션이 필요하지 않은 경우 Process.sequential작업 순서와 소유권이 명확하므로 디버깅이 더 쉽습니다.

4. 재시도와 중복 스케줄링을 혼동하지 마십시오.

반복적인 작업은 예상되는 재시도 동작입니다. CrewAI 작업 가드레일은 출력을 검증하고 검증에 실패할 경우 에이전트에 피드백을 보낼 수 있습니다. 현재 작업 문서에 따르면 guardrail_max_retries기본값은 3이며, 가드레일 실패 시 해당 제한까지 작업을 재시도합니다.

max_retry_limit에이전트는 실행 오류와 max_iter최적의 답변을 생성하기 전 최대 에이전트 반복 횟수 도 표시합니다 . 현재 에이전트 문서에는 기본값 max_iter이 20이고 기본 오류 재시도 제한이 2로 명시되어 있습니다.

이러한 메커니즘들은 서로 다른 문제들을 해결합니다.

디버깅 중에는 이러한 제한 값을 일시적으로 줄이십시오. 반복 오류가 사라지면 작업 유효성 검사 실패 원인 또는 에이전트가 다른 도구 반복이 필요하다고 판단한 이유를 검사하십시오. 프로덕션 환경에서 모든 재시도 값을 0으로 설정하지 마십시오. 일시적인 오류에는 재시도가 적절할 수 있습니다.

5. 프롬프트를 다시 작성하기 전에 실제로 실행된 내용을 추적하세요.

CrewAI는 여러 관찰 가능성 후크를 제공합니다. 승무원 수준에서 현재 문서에는 verbose, step_callback, task_callback, output_log_file, 추적 제어 기능이 포함되어 있습니다. 에이전트도 를 지원합니다 step_callback. 이러한 기능은 다음 네 가지 질문에 답하는 데 유용합니다.

• 스케줄러가 동일한 작업을 두 번 시작했습니까?
• 한 에이전트가 하나의 작업 내에서 여러 번 반복 작업을 수행했습니까?
• 안전장치가 출력을 거부하고 재시도를 트리거했습니까?
• 작업 자체는 한 번 실행되었는데도 도구 호출이 반복되었습니까?

초기 진단 실행을 위해 상세 출력 및 JSON 로그 파일 생성을 활성화하십시오.

crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
    verbose=True,
    output_log_file="logs/crew-run.json",
)

구조화된 카운터나 사용자 지정 원격 측정 데이터가 필요한 경우 콜백을 추가할 수 있습니다. CrewAI의 승무원 속성 문서를 참조하세요 .

6. 중복된 Flow 트리거 방지

플로우는 또 다른 유형의 반복을 도입합니다. CrewAI의 현재 플로우 문서에 따르면, 모든 만족된 @start()메서드는 플로우가 시작되거나 재개될 때 실행됩니다. 만약 여러 개의 무조건 시작 조건을 정의하고 그중 두 개가 결국 같은 크루를 시작하게 된다면, 중복은 크루 내부가 아니라 그래프에서 발생합니다.

마찬가지로, 리스너는 상위or_ 메서드에서 출력이 발생할 때마다 실행될 수 있습니다 . CrewAI의 예제에서는 상위 메서드에서 출력이 발생할 때마다 리스너가 한 번씩 실행되도록 설정되어 있습니다. 하위 작업이 여러 전제 조건이 모두 완료될 때까지 기다려야 하거나, 정확히 하나의 분기만 진행해야 할 때 이 리스너를 사용하십시오.and_@router()

두 번째 시작 메서드를 추가하기 전에 @start(), 그것이 정말 독립적인 진입점을 나타내는지 자문해 보세요. 그렇지 않다면, 하나의 시작 메서드와 명시적인 리스너를 사용하세요.

7. 실행 간 멱등성을 위한 자동 완성 키를 추가합니다.

이는 이메일 전송, 결제 수단 청구, CRM 기록 생성, 메시지 게시 또는 작업 시작과 같이 외부적인 부작용을 일으키는 작업에 가장 중요한 생산 패턴입니다.

CrewAI Flows는 구조화된 상태와 @persist데코레이터를 지원합니다. 지속성 기능을 통해 Flow는 재시작 후에도 상태를 복구할 수 있습니다. 그러나 지속된 상태만으로는 비즈니스 액션을 건너뛸지 여부를 결정할 수 없습니다. 따라서 자체적인 결정적 작업 키를 저장하고 부작용을 실행하기 전에 해당 키를 확인해야 합니다.

from hashlib import sha256
import json
from pydantic import BaseModel
from crewai.flow.flow import Flow, start
from crewai.flow.persistence import persist

class JobState(BaseModel):
    completed_keys: list[str] = []
    report: str = ""

def operation_key(customer_id: str, period: str) -> str:
    payload = {"customer_id": customer_id, "period": period}
    raw = json.dumps(payload, sort_keys=True).encode()
    return sha256(raw).hexdigest()

@persist
class ReportFlow(Flow[JobState]):

    @start()
    def run_report(self):
        key = operation_key("customer-123", "2026-09")

        if key in self.state.completed_keys:
            return self.state.report

        result = reporting_crew.kickoff(
            inputs={"customer_id": "customer-123", "period": "2026-09"}
        )

        self.state.report = result.raw
        self.state.completed_keys.append(key)
        return self.state.report

CrewAI 문서에 따르면 @persistFlow 상태는 재시작 후에도 저장되며, 동일한 상태 ID로 다시 시작하면 최신 스냅샷이 다시 로드됩니다. 자세한 내용은 CrewAI Flow 지속성 문서를 참조하십시오 .

중요한 프로덕션 주의 사항: 위 예시는 일반적인 워크플로 중복 제거에는 유용하지만, 재정적 또는 법적으로 중요한 부작용에는 충분하지 않습니다. 외부 작업이 성공적으로 완료된 후 완료 키가 저장되기 전에 프로세스가 충돌할 수 있습니다. 강력한 '정확히 한 번만 실행'과 유사한 동작을 위해서는 외부 트랜잭션 저장소 또는 대상 API 자체의 멱등성 키를 사용하고, 가능한 경우 작업을 원자적으로 기록하십시오.

8. 반복되는 도구 호출은 캐시에 저장하되, 캐시를 작업의 멱등성으로 오해하지 마십시오.

CrewAI 에이전트와 크루는 캐싱 기능을 제공하며 cache, 공식 문서에서는 이를 도구 실행 결과 캐싱이라고 설명합니다. 현재 에이전트 문서에서는 캐싱이 기본적으로 활성화되어 있으며, 성능 지침에서는 도구를 반복적으로 사용할 경우 캐싱을 활성화 상태로 유지하는 것을 권장합니다.

이는 에이전트가 동일한 비용이 많이 드는 검색이나 확정적 도구 호출을 두 번 이상 수행할 때 도움이 됩니다. 하지만 두 번 호출한다고 해서 팀의 작업이 자동으로 건너뛰어지는 것은 아닙니다crew.kickoff() . 해당 작업은 여전히 ​​실행 그래프에 포함됩니다.

반복적인 읽기 작업에는 캐시를 사용하고, 반복적인 쓰기 작업에는 멱등성 키를 사용하십시오.

9. 메모리는 반복적인 탐색을 줄여주지만, 작업을 완전히 없애지는 않습니다.

CrewAI의 통합 메모리 시스템은 작업 후 사실을 저장하고 작업 전에 관련 컨텍스트를 불러옵니다. 현재 문서에 따르면 승무원 메모리가 활성화된 경우 작업 출력에서 ​​개별 사실이 추출되고 관련 메모리가 이후 작업 프롬프트에 주입됩니다.

이는 특히 작성자가 연구자가 이미 발견한 내용을 알아야 할 때 불필요한 재발견을 줄일 수 있습니다. 하지만 메모리는 검색 컨텍스트이지 건너뛰기 플래그가 아닙니다. 명시적으로 예약된 작업은 팀 또는 흐름 로직에서 달리 결정하지 않는 한 계속 실행됩니다.

"우리가 이미 알고 있는 것은 무엇인가?"를 판단할 때는 메모리를 사용하고, "이 작업이 실행되어야 하는가?"를 판단할 때는 상태 또는 조건부 작업을 사용하십시오. CrewAI 메모리를 참조하십시오 .

10. 구조화된 출력을 사용하여 건너뛰기 결정의 신뢰성을 높이세요.

자연어 출력은 결정론적 워크플로 제어에 사용하기 어렵습니다. CrewAI 작업은 Pydantic 또는 JSON 형식으로 출력을 반환할 수 있습니다. 구조화된 결과를 통해 output_pydantic추가 output_json작업, 검토, 에스컬레이션 또는 다른 작업이 필요한지 여부를 쉽게 판단할 수 있습니다.

예를 들어, 다음을 반환하세요:

{
  "status": "complete",
  "sources_found": 7,
  "missing_fields": [],
  "needs_review": false
}

그러면 다른 상담원에게 문단 해석을 요청하는 대신 필드를 기준으로 경로를 지정합니다. 이렇게 하면 일반적으로 중복 작업과 프롬프트 모호성이 모두 줄어듭니다.

권장되는 중복 방지 구성

일반적인 연구-보고서 작성 과정을 고려할 때, 보수적으로 시작하는 것이 좋습니다.

researcher = Agent(
    role="Researcher",
    goal="Collect evidence once.",
    backstory="Owns external research.",
    allow_delegation=False,
    max_iter=8,
    max_retry_limit=1,
    cache=True,
)

analyst = Agent(
    role="Analyst",
    goal="Analyze supplied evidence only.",
    backstory="Does not repeat research.",
    allow_delegation=False,
    max_iter=6,
)

crew = Crew(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process=Process.sequential,
    verbose=True,
    cache=True,
    output_log_file="logs/run.json",
)

그런 다음 요구 사항이 필요할 때만 복잡성을 추가하십시오.

• 여러 작업이나 실행 간에 정보를 재사용해야 하는 경우 메모리를 추가하세요 .
• 이전 출력 결과가 불완전한 경우에만 작업이 실행되어야 할 때 ConditionalTask 를 추가합니다 .
• 관리자를 동적으로 배정해야 하는 경우에는 계층적 프로세스를 사용하십시오 .
• 동료에게 작업을 인계해야 하는 에이전트에 대해서만 위임 기능을 활성화하십시오 .
• 출력 품질에 대한 안전장치를 추가하되 , 안전장치 실패 시 의도적으로 재시도가 발생하도록 허용합니다.
• 재시작 시에도 상태가 유지되어야 하는 경우 Flow 지속성 기능 을 추가하세요 .
• 중복되는 부작용이 허용되지 않는 경우 외부 멱등성 계층을 추가하십시오 .

최종 문제 해결 체크리스트

• Task승무원 작업 목록에 동일한 항목이 두 번 기재되어 있습니까 ?
• 두 개의 작업 설명이 동일한 연구 또는 도구 사용을 승인하는 것입니까?
• 나중에 실행되는 작업이 이전에 실행된 작업을 context대신 처리할 수 있나요?
• 반복되는 작업은 무엇일까요 ConditionalTask?
• 순차적인 오케스트레이션으로도 충분한데 계층적인 오케스트레이션을 사용하고 계신가요?
• allow_delegation필요하지 않은 에이전트에서 활성화되어 있습니까 ?
• 가드레일 거부로 인해 재시도가 발생하는 건가요?
• max_iter하나의 작업이 여러 유사한 도구 호출을 수행할 수 있을 만큼 충분히 큰 규모 인가요 ?
• 여러 @start()메서드 또는 or_리스너가 동일한 하위 팀에 신호를 보내고 있습니까?
• 두 번째 실행은 kickoff()의도적인 새 실행을 나타내는 것입니까, 아니면 실수로 중복 실행된 것을 나타내는 것입니까?
• 혹시 메모리나 캐시를 마치 작업 수준의 멱등성 제어처럼 사용하고 계신가요?
• 외부 쓰기 작업에 결정론적 멱등성 키가 있습니까?
• 로그를 통해 중복이 작업, 에이전트 단계, 도구 또는 흐름 수준에서 발생했는지 여부를 확인할 수 있습니까?

결론적으로

CrewAI의 중복 작업을 중지하는 것은 대부분 오케스트레이션 문제입니다. 작업 소유권을 명확히 하고, 작업을 연결하고 context, 이미 완료된 작업은 조건부로 건너뛰고, 위임 범위를 좁히고, 재시도가 의도적인 경우를 파악하고, 프롬프트를 변경하기 전에 실행 내역을 추적하십시오. Flow 및 프로덕션 환경의 부작용을 방지하려면 한 단계 더 나아가 확정적인 완료 키를 저장하거나 외부 멱등성 메커니즘을 사용하십시오.

유용한 사고 모델은 간단합니다. 맥락은 재발견을 방지하고, 조건은 불필요한 작업을 방지하며, 캐시는 도구의 반복적인 연산을 방지하고, 멱등성은 부작용의 반복을 방지합니다 . 이들은 서로 관련된 문제를 해결하지만, 상호 대체할 수는 없습니다.