[LLM] LangGraph에서 GraphRecursionError 해결하기: 올바른 상태 관리의 중요성
LangGraph에서 GraphRecursionError 해결하기: 올바른 상태 관리의 중요성
LangGraph를 사용하여 에이전트 워크플로우를 구축할 때 가장 자주 마주치는 오류 중 하나는 GraphRecursionError이다. 이 오류는 그래프가 종료 조건에 도달하지 못하고 최대 반복 횟수를 초과할 때 발생한다. 오늘은 이 오류의 주요 원인과 해결 방법을 실제 사례를 통해 살펴보겠다.
문제 상황: 무한 재귀 발생
LangGraph를 사용하여 계획 수립 및 실행 에이전트를 구현하는 중 다음과 같은 오류가 발생했다:
GraphRecursionError: Recursion limit of 10 reached without hitting a stop condition.
You can increase the limit by setting the `recursion_limit` config key.이 오류는 그래프가 종료 조건에 도달하지 못하고 계속해서 같은 노드를 순환하고 있음을 의미한다. 대부분의 경우, 이는 상태(state) 관리에 문제가 있다는 신호이다.
주요 원인 분석
코드를 분석해보니 다음과 같은 문제점들이 확인되었다:
1. 상태 업데이트 불완전: PlanExecute 타입 정의 문제
문제의 핵심은 PlanExecute 상태 객체와 그 업데이트 방식에 있었다. 원래 코드에서는:
class PlanExecute(TypedDict):
input: str
plan: List[str]
past_steps: List[Tuple[str, str]]
response: str # 타입 힌트만 있고 실제로는 항상 채워지지 않음이 상태 정의는 response 필드가 필수인 것처럼 보이지만, 실제로는 이 필드가 언제 채워지는지 명확하지 않았다. 더 큰 문제는 종료 조건이 이 필드에 의존한다는 점이었다:
def should_end(state: PlanExecute):
if "response" in state and state["response"]:
return END
else:
return "agent"2. 반환 값 누락: execute_step 함수 문제
또 다른 중요한 문제는 execute_step 함수가 실행된 계획 단계를 제거하지만, 업데이트된 계획을 반환하지 않는다는 점이었습니다:
async def execute_step(state: PlanExecute):
# ... 코드 생략 ...
return {
"past_steps": [(task, response_content)],
# "plan": remaining_plan, # 이 라인 누락
}이로 인해 상태의 plan 필드가 갱신되지 않고, 그래프는 계속해서 같은 단계를 수행하려고 시도했다.
3. 애매한 응답 구조: edited_planner 반환 값 문제
마지막으로, edited_planner가 반환하는 Act 객체의 구조가 명확하지 않아, 종료 조건을 제대로 트리거하지 못했다:
class Act(BaseModel):
action: Union[Response, Plan] = Field(...)이 구조는 Union 타입을 사용하여 복잡성을 증가시켰고, 타입 체크가 제대로 이루어지지 않았다.
해결 방법: 명확한 상태 관리
이 문제를 해결하기 위한 핵심은 다음과 같다:
1. 타입 정의 개선: Optional 타입 사용
class PlanExecute(TypedDict):
input: str
plan: List[str]
past_steps: List[Tuple[str, str]]
response: Optional[str] # Optional로 명시하여 필수가 아님을 표시이렇게 함으로써 response 필드가 있을 수도, 없을 수도 있다는 것을 명확히 했다.
2. 상태 업데이트 보장: 모든 필요한 필드 반환
async def execute_step(state: PlanExecute):
# ... 코드 생략 ...
return {
"past_steps": state.get("past_steps", []) + [(task, response_content)],
"plan": remaining_plan, # 남은 계획을 명시적으로 반환
}이제 execute_step 함수는 실행 후 남은 계획을 명시적으로 반환하므로, 상태가 올바르게 갱신된다.
3. 명확한 응답 구조: Act 클래스 개선
class Act(BaseModel):
action_type: str = Field(description="'response' 또는 'plan'")
response: Optional[str] = Field(default=None)
steps: Optional[List[str]] = Field(default=None)
@property
def action(self):
if self.action_type == "response":
return Response(response=self.response)
else:
return Plan(steps=self.steps)이렇게 하면 응답 구조가 명확해지고, 종료 조건을 올바르게 트리거할 수 있다.
4. 종료 조건 강화
def should_end(state: PlanExecute):
# response가 있고 빈 문자열이 아닌 경우에만 종료
if "response" in state and state["response"] and state["response"].strip():
return END
# 또는 계획이 비어있으면 종료 (선택적)
elif "plan" in state and len(state.get("plan", [])) == 0:
return END
else:
return "agent"더 엄격한 종료 조건을 추가하여 그래프가 적절히 종료되도록 했다.
결론
LangGraph를 사용하여 복잡한 에이전트 워크플로우를 구축할 때 GraphRecursionError는 흔히 발생하는 오류이다. 이 오류를 해결하는 핵심은 상태 객체의 명확한 정의와 완전한 상태 업데이트를 보장하는 것이다. 특히 종료 조건에 사용되는 필드들이 올바르게 설정되고 업데이트되는지 확인하는 것이 중요하다.
올바른 상태 관리만으로도 대부분의 GraphRecursionError 문제를 해결할 수 있으며, 더 안정적이고 예측 가능한 LangGraph 애플리케이션을 구축할 수 있다.