AutoGen 에이전트가 무한 루프에 빠지는 이유와 해결 방법

AutoGen 루프 디버깅 전에 알아두어야 할 중요한 플랫폼 변경 사항이 있습니다. 2026년 9월 현재, 공식 AutoGen 저장소는 유지 관리 모드로 전환되었습니다. 새로운 기능 추가보다는 유지 관리 작업이 진행될 예정이며, Microsoft는 새로운 프로젝트에 Microsoft Agent Framework 사용을 권장합니다. 공식 AutoGen 저장소는 여전히 Python 0.7.5를 현재 안정적인 버전으로 표시하고 있으며, Microsoft는 2026년 8월 25일에 AutoGen에서 Agent Framework로의 마이그레이션 가이드를 업데이트하여 게시했습니다. 하지만 이미 AutoGen을 프로덕션 환경에서 사용하고 있다면 아래의 문제 해결 기법은 여전히 ​​유용합니다. 자세한 내용은 공식 AutoGen 저장소 , 공식 AutoGen 릴리스 및 Microsoft의 AutoGen 마이그레이션 가이드를 참조하십시오 .

AutoGen 에이전트가 "무한 루프에 갇힌 것처럼 보이는" 이유는 일반적으로 다음 다섯 가지 중 하나입니다. 실행에 안정적인 종료 조건이 없거나, 다음 발언자 정책이 비효율적인 참가자를 계속 선택하거나, 도구 호출 후 가시적인 진행 상황이 생성되지 않거나, 에이전트 간에 핸드오버가 반복되거나, 애플리케이션이 계속해서 이전 상태를 재개하는 경우입니다. 가장 빠른 해결 방법은 모든 프롬프트를 다시 작성하는 것이 아닙니다. 먼저 실제로 어떤 루프가 발생하는지 파악한 다음, 강제 종료 조건을 추가하고, 실패하는 전환을 수정하면 됩니다.

빠른 진단: 어떤 종류의 루프가 나타나고 있나요?

1. 다른 디버깅 작업을 시작하기 전에 강제 종료 조건을 추가하세요.

AutoGen AgentChat은 팀 간의 제한을 유지하기 위해 내장된 종료 조건을 제공합니다. 안정적인 문서에는 MaxMessageTermination, TextMentionTermination, TokenUsageTermination, TimeoutTermination, HandoffTermination, SourceMatchTermination, ExternalTermination, StopMessageTermination, TextMessageTermination, FunctionCallTermination, 및 가 포함되어 있습니다 FunctionalTermination. AutoGen 공식 종료 문서를 참조하십시오 .

대부분의 프로덕션 워크플로에서는 의미론적 완료 조건 과 독립적인 안전 한계를 사용합니다. 중요한 연산자는 일반적으로 OR입니다. 작업이 정상적으로 완료되거나 안전 한계에 도달하면 실행이 중지되도록 하기 위함입니다.

from autogen_agentchat.conditions import (
    MaxMessageTermination,
    TextMentionTermination,
)

done = TextMentionTermination("TERMINATE")
safety_cap = MaxMessageTermination(max_messages=25)

termination = done | safety_cap

흔히 저지르는 실수 중 하나는 "완료되면 종료"라고만 하는 것입니다. 이렇게 하면 정확성은 모델링 동작에 맡겨지게 됩니다. 또 다른 실수는 &"둘 중 하나라도 만족하면 중지"라는 의미로 조건을 결합하는 것입니다. AutoGen은 AND와 OR 연산을 모두 지원하므로 의미 체계를 신중하게 선택해야 합니다.

이것이 해결하는 것

• 예상되는 완료 문구를 전혀 만들어내지 못하는 팀.
• 유용한 작업이 중단되었음에도 불구하고 계속해서 다른 스피커를 찾는 선택기.
• 자연스러운 끝이 없는 인수인계 사슬.
• 모델이나 도구의 예상치 못한 동작으로 인해 무한한 턴 소모가 발생할 수 있습니다.

하드캡은 회로 차단기일 뿐, 워크플로가 올바르다는 증거는 아닙니다. 만약 실행이 항상 하드캡에 걸려 중단된다면, 여전히 수정해야 할 논리적 문제가 있는 것입니다.

2. 대화 형식에 그치지 않고, 기계가 완료 여부를 감지할 수 있도록 만드세요.

가장 강력한 종료 신호는 애플리케이션이 별도의 해석 없이 인식할 수 있는 신호입니다. 워크플로에 명확한 성공 이벤트가 있는 경우, 가장 유사한 종료 조건을 사용하십시오. 예를 들어, 특정 핸드오프는 `<handoff>`로 HandoffTermination, 특정 도구 완료는 `<tool complete>`로 FunctionCallTermination, 사용자 지정 로직은 `<custom_logic>`으로 감지할 수 있습니다 FunctionalTermination.

`--` 연산자를 사용할 경우 TextMentionTermination("TERMINATE"), 책임 소재를 명확히 하세요. 어떤 주체가 완료를 선언할 수 있는지, 그리고 어떤 검증된 조건에서 완료를 선언할 수 있는지를 구체적으로 명시해야 합니다. 모든 참여자에게 "만족할 때까지 계속하세요"와 같은 모호한 지시를 내리는 것은 피해야 합니다. 이러한 지시는 "만족"의 기준이 명확하지 않기 때문에 끝없는 수정과 재작업을 초래할 수 있습니다.

유용한 완료 계약은 구체적이어야 합니다. 예를 들어, "검토자는 초안에 필수 세 가지 섹션이 모두 포함되고 해결되지 않은 문제가 남아 있지 않을 때만 종료(TERMINATE) 신호를 보냅니다."와 같이 말입니다. 가능하다면 검토자가 애플리케이션이 확인할 수 있는 구조화된 상태를 생성하도록 하는 것이 더 좋습니다.

3. 모든 상담원 안내 메시지를 다시 작성하기 전에 SelectorGroupChat 라우팅을 수정하십시오.

SelectorGroupChat공유된 대화 컨텍스트에서 다음 화자를 선택하는 모델을 사용합니다. 안정적인 문서에서는 참가자 이름과 설명이 화자 선택에 사용되므로 중요하다고 명시하고 있습니다. 기본적으로 동일한 화자는 사용 가능한 에이전트가 한 명뿐인 경우를 제외하고는 연속해서 선택되지 않지만, 이 동작은 변경 가능합니다. AutoGen은 보다 확정적인 제어가 필요할 때 사용할 수 있는 옵션도 제공합니다. 자세한 내용은 SelectorGroupChat 공식 문서 allow_repeated_speaker=True를 참조 하십시오 .selector_funccandidate_func

같은 참가자가 계속해서 선택되는 경우, 다음 사항들을 순서대로 확인하세요.

• 에이전트 설명: 각 설명에는 에이전트의 기능과 선택 시점을 명시해야 합니다. 설명이 중복되면 라우팅이 불안정해집니다.
• 선택기 프롬프트: 모델이 안정적으로 적용될 수 있도록 라우팅 규칙을 충분히 간결하게 유지하십시오. AutoGen 설명서에서는 프롬프트에 조건이 많아지기 시작하면 사용자 지정 선택기를 사용하는 것을 명시적으로 권장합니다.
• 반복 화자 설정:allow_repeated_speaker 연속적인 발언이 정말로 필요한 경우가 아니면 꺼 두십시오 .
• 후보 제한: 특정 상태 이후에 유효한 에이전트가 두 개뿐인 경우, 모델이 모든 참여자 중에서 선택하도록 하는 대신 후보 집합을 제한합니다.
• 결정론적 전환:selector_func 워크플로가 대화로 위장한 상태 기계일 때 사용합니다 .

핵심적인 차이점은 간단합니다. 다음 화자에 대한 의미 판단이 진정으로 필요한 경우에는 LLM 기반 화자 선택을 사용하고, 워크플로 상태에 따라 다음 화자 순서가 결정되는 경우에는 결정론적 라우팅을 사용하십시오.

4. 진행 상황을 시각적으로 보여줌으로써 반복적인 도구 호출을 방지하세요.

현재 AgentChat에는 매개변수가 AssistantAgent있습니다 max_tool_iterations. 안정적인 API 문서에 따르면 기본값은 1이며, 이 값을 높이면 모델이 텍스트 응답을 반환하거나 최대값에 도달할 때까지 상담원이 순차적으로 도구를 호출할 수 있습니다. 즉, 단일 상담원 실행은 이 설정에 의해 제한되지만, 동일한 상담원이 팀에 의해 다시 선택되어 여러 차례에 걸쳐 동일한 실패한 도구 패턴을 반복할 수 있습니다. 자세한 내용은 공식 AssistantAgent API 참조를 확인하세요 .

agent = AssistantAgent(
    name="worker",
    model_client=model_client,
    tools=[lookup_tool],
    max_tool_iterations=3,
)

동일한 도구와 인수가 반복적으로 사용되는 경우, 반복 횟수 제한을 줄이는 것은 피해를 일시적으로 완화하는 데 그칠 뿐입니다. 근본적인 해결책은 대개 도구 계약에 있습니다. 모델은 호출이 성공했는지, 영구적으로 실패했는지, 일시적으로 실패했는지, 아니면 새로운 정보를 생성하지 않았는지 판단하는 데 필요한 충분한 정보를 갖춰야 합니다.

다음과 같이 간결하고 명확한 결과를 선호합니다.

{
    "status": "no_new_data",
    "query": "customer_123",
    "retryable": false,
    "reason": "record already checked",
    "next_action": "return_to_planner"
}

이는 "결과 없음"과 같은 일반적인 문자열보다 훨씬 유용합니다. 왜냐하면 모델은 동일한 호출을 반복하는 것이 진전이 아니라는 것을 알 수 있기 때문입니다. 부작용이 있는 도구의 경우, 애플리케이션 수준에서 멱등성을 추가하여 반복적인 호출이 동일한 티켓, 결제, 메시지 또는 데이터베이스 변경을 반복적으로 생성하지 못하도록 해야 합니다.

병렬 도구 호출도 확인하십시오.

안정적인 AssistantAgent참조 문서에서는 여러 도구 호출이 동시에 실행될 수 있으며, 지원되는 모델 클라이언트에서 병렬 도구 호출을 비활성화할 수 있다고 명시하고 있습니다. 또한 여러 개의 핸드오프가 감지될 경우 첫 번째 핸드오프만 실행되므로, 이러한 상황을 방지하기 위해 병렬 도구 호출을 비활성화할 것을 권장합니다. 워크플로에서 한 번에 하나의 작업만 수행하는 엄격한 상태 전환을 가정하는 경우, 병렬 호출로 인해 결과 상태를 이해하기가 더 어려워질 수 있습니다.

5. 스웜 스타일 팀에서 핸드오프 탁구를 중단하세요

핸드오프 루프는 일반적으로 다음과 같습니다. 에이전트 A는 에이전트 B가 더 적합하다고 판단하고, 에이전트 B는 불완전한 컨텍스트를 확인하고 작업을 다시 에이전트 A에게 보냅니다. 그리고 두 선택 모두 로컬에서는 영원히 타당한 것으로 유지됩니다. 문제는 어느 모델이 "틀렸다"는 것이 아닙니다. 핸드오프 정책에 소유권과 최종 상태가 결여되어 있는 것입니다.

모든 핸드오프에 명확한 조건과 대상이 더 이상 진행할 수 없을 때 발생하는 상황에 대한 규칙을 부여하여 문제를 해결하세요. 사용자 상호 작용 워크플로의 경우, HandoffTermination(target="user")제어권이 애플리케이션이나 담당자에게 돌아가야 할 때 팀의 작업을 중지하도록 설계되었습니다. AutoGen의 휴먼 인 더 루프(Human-in-the-Loop) 관련 문서에서도 Swarm 워크플로는 사용자 핸드오프 후 의도적인 재개 동작이 필요하다고 설명합니다. 자세한 내용은 공식 휴먼 인 더 루프 문서를 참조하세요 .

훌륭한 인수인계 계약서에는 다음 사항이 포함됩니다.

• 대상이 보유한 정확한 능력;
• 인수인계를 정당화하는 증거;
• 목표가 성공했을 경우 반환해야 하는 값;
• 필요한 정보가 없을 경우 대상이 해야 할 일은 무엇인가?
• 작업을 변경하지 않고 되돌려 보내는 것을 금지합니다.

6. GraphFlow의 반복문을 명시적인 종료가 필요한 실제 루프처럼 취급하십시오.

GraphFlow의도적인 반복, 조건부 분기 및 루프 종료를 지원합니다. 안정적인 API는 루프가 결국 종료되는 조건이 있을 때만 유효하다고 설명하며, 빌더는 그래프 구조의 유효성을 검사합니다. 또한 이 기능은 실험적인 기능으로 표시되어 있습니다. 구조적으로 유효한 루프라도 종료 조건에 논리적으로 도달할 수 없는 경우 너무 오래 실행될 수 있으므로, 독립적인 종료 조건을 설정하거나 루프 주변에 전환 제한을 두는 것이 좋습니다. 자세한 내용은 AutoGen 팀의 공식 API 참조를 확인하세요 .

이는 특히 "작성자 → 검토자 → 작성자" 구조에서 중요합니다. 검토자에게 "완벽해질 때까지 계속 개선하라"고 지시하면, 최종 목표가 결코 달성되지 않을 수 있습니다. 주관적인 완벽함 대신 필수 항목 포함, 유효성 검사 통과, 중대한 결함 없음, 최대 수정 횟수 충족과 같은 구체적인 평가 기준을 적용하는 것이 좋습니다.

7. 다음 작업이 관련이 없을 경우 상태를 초기화합니다.

AgentChat 상담원과 팀은 상태를 유지합니다. AutoGen의 안정적인 문서에 따르면 팀은 실행 간에 대화 컨텍스트를 유지하여 관련 작업이 계속될 수 있도록 하며, reset()팀 및 참여자 상태를 지우는 기능도 제공합니다. 이러한 동작은 작업 연속성에 유용하지만, 관련 없는 작업이 이전 컨텍스트, 미완료된 위임 또는 이전 가정을 상속받는 경우 무한 루프처럼 보일 수 있습니다.

await team.reset()
result = await team.run(task=new_unrelated_task)

안정적인 상담원 API는 발신자에게 전체 대화 기록을 수동으로 다시 재생하는 대신 각 통화에서 새로운 메시지만 전달하도록 경고합니다. 상담원이 상태를 유지하면서 전체 기록을 다시 주입하면 맥락이 중복되고 반복적인 행동이 강화될 수 있습니다.

8. 최종 텍스트뿐만 아니라 전환 과정도 기록하십시오.

반복 실행이 어려운 경우, 매 턴마다 다음 네 가지 질문에 답할 수 있도록 충분한 정보를 기록하세요. 누가 행동했는지, 왜 선택되었는지, 어떤 행동을 시도했는지, 그리고 그 후에 무엇이 바뀌었는지. AutoGen은 추적 및 관찰 기능을 지원하며, 안정적인 추적 가이드에서 AgentChat 팀 추적 방법을 보여줍니다. 자세한 내용은 AutoGen 공식 추적 문서를 참조하세요 .

최소한 다음 내용을 기록하십시오:

• 실행 ID 및 턴 번호;
• 메시지 출처 및 메시지 유형;
• 선정된 연사와 가능한 후보자;
• 도구 이름과 인수의 해시값 또는 정규화된 형식;
• 도구 상태 및 상태 변경 여부;
• 핸드오프 소스 및 대상;
• 종료 조건 결과;
• TaskResult.stop_reason달리기가 끝날 때.

"동일한 동작, 동일한 상태" 감지는 매우 효과적인 진단 방법입니다. 동일한 에이전트가 동일한 도구를 동일한 인수로 호출하고 공유 상태 해시가 여러 턴 동안 변경되지 않으면 실행을 중지하고 진행이 없는 루프로 표시합니다. 이 검사는 AutoGen에 내장된 기능이 아니라 애플리케이션 로직에 포함되어야 하지만, 토큰이나 메시지 제한으로는 사후에만 파악할 수 있는 유형의 오류를 포착할 수 있습니다.

실용적이고 안전한 기준선

기존 AutoGen AgentChat 애플리케이션의 경우, 보수적인 기준선은 다음과 같습니다.

• 항상 하드 메시지, 턴, 타임아웃 또는 토큰 상한을 설정하십시오.
• 해당 상한선을 의미 있는 완료 조건과 결합하고, OR 연산자를 사용하여 두 조건 중 하나라도 충족되면 실행을 중지하도록 합니다.
• max_tool_iterations요원이 여러 단계의 도구 사용 순서가 정말로 필요한 경우가 아니라면 규모를 작게 유지하세요 .
• 성공, 진행 없음, 재시도 가능한 오류 및 영구 오류를 구분하는 구조화된 도구 결과를 반환합니다.
• 워크플로에 필요한 경우가 아니면 반복해서 말하는 것을 허용하지 마십시오.
• 결정론적 워크플로에는 결정론적 선택기를 사용하십시오.
• 인수인계에 명확한 소유권과 최종 경로를 부여하십시오.
• 관련 없는 작업 간에 팀을 재설정합니다.
• 동작의 변화를 추적하고 상태 변화 없이 반복되는 동작을 감지합니다.

하지 말아야 할 일

모든 루프를 단순히 25에서 100으로 올리는 방식으로 해결하지 마십시오. max_messages이는 실패 비용만 변경할 뿐 논리는 바꾸지 않습니다. 종료 조건이 실제로 팀에 연결되었는지 확인하기 전에 더 긴 시스템 프롬프트를 추가하지 마십시오. 두 명의 상담원이 "최종 검토"를 동시에 담당하도록 하지 마십시오. 다음 모델 호출에서 재시도 여부를 결정해야 하는 경우 모호한 도구 문자열을 반환하지 마십시오. 그리고 결국 중지되는 실행을 정상이라고 가정하지 마십시오. 항상 안전 한계에 도달하는 워크플로도 여전히 오작동하고 있는 것입니다.

패치를 계속하는 대신 마이그레이션을 해야 할 시점은 언제일까요?

기존 AutoGen 애플리케이션을 유지 관리하는 경우 이러한 수정 사항이 적합하며 현재 설명서도 계속 사용할 수 있습니다. 하지만 새 시스템을 구축하거나 오케스트레이션을 대폭 재작성해야 하는 경우에는 유지 관리 모드 상태에 따라 결정이 달라집니다. Microsoft는 이제 신규 사용자에게 Microsoft Agent Framework를 권장하며, 해당 마이그레이션 설명서에서는 AutoGen의 이벤트 기반 코어 및 상위 수준 팀에서 유형화된 그래프 기반 워크플로로의 전환을 설명합니다. 이는 AutoGen 루프를 즉시 마이그레이션해야 한다는 의미는 아니지만, AutoGen 관련 오케스트레이션 작업을 심층적으로 수행하는 데 드는 비용과 지원되는 후속 버전으로 전환하는 비용을 비교하여 고려해야 한다는 의미입니다.

따라서 가장 빠르고 확실한 디버깅 경로는 실행 범위를 제한하고, 반복되는 전환을 식별하고, 진행 상황을 관찰 가능하게 만든 다음, 종료를 확정적으로 만드는 것입니다. 이 네 가지 요소가 갖춰지면 대부분의 "무한" 자동 생성 루프는 재현 및 수정이 가능한 일반적인 워크플로 버그가 됩니다.

공식 참고 자료

• Microsoft AutoGen 저장소 - 현재 유지 관리 모드 알림.
• AutoGen 릴리스 — 안정적인 Python 릴리스 정보입니다.
• AutoGen AgentChat 종료 가이드 .
• AutoGen SelectorGroupChat 가이드 .
• AutoGen AssistantAgent API 참조 .
• AutoGen 팀 가이드 .
• Microsoft AutoGen에서 Agent Framework로의 마이그레이션 가이드 — 2026년 8월 25일 업데이트.