ReAct Agent 디버깅 가이드

TAO 루프 로깅

ReAct 패턴의 핵심인 Thought-Action-Observation을 로깅하면 문제의 원인을 빠르게 찾을 수 있다.

import logging
logging.basicConfig(level=logging.DEBUG)

class DebugReActAgent:
    def __init__(self, llm, tools):
        self.llm = llm
        self.tools = {t.name: t for t in tools}
        self.trace = []

    def run(self, question):
        print(f"\n{'='*50}")
        print(f"질문: {question}")
        print('='*50)

        for step in range(1, 11):  # 최대 10 스텝
            thought, action, action_input = self._think(question)
            print(f"\n[Step {step}]")
            print(f"  Thought: {thought}")
            print(f"  Action: {action}")
            print(f"  Input: {action_input}")

            if action == "finish":
                print(f"  Final: {action_input}")
                return action_input

            observation = self._act(action, action_input)
            print(f"  Observation: {observation[:100]}...")  # 앞 100자

            self.trace.append({
                "step": step, "thought": thought,
                "action": action, "input": action_input,
                "observation": observation
            })

        return "최대 스텝 초과"

---

흔한 문제 진단표

증상	원인	해결
같은 Tool 반복 호출	종료 조건 없음, 프롬프트 미비	max_iterations 설정, 프롬프트에 "중복 금지" 추가
엉뚱한 Tool 선택	Tool description 불명확	description에 "언제 사용하는지" 명시
Observation 무시	프롬프트 지시 불충분	"이전 Observation을 반드시 활용" 추가
존재 않는 설비 코드 추측	Tool 에러 처리 미비	Tool에서 에러를 친절한 메시지로 반환
답변 생성 지연	Tool 과다 호출	캐싱 + 프롬프트 최적화

---

단계별 검증 체크리스트

□ Tool 정의 검증
  - name: 영문 소문자, 밑줄만 사용
  - description: 20자 이상, 사용 시점 명시
  - parameters: 타입과 설명 완비

□ 프롬프트 검증
  - 역할 정의 (제조 현장 AI)
  - 사용 가능한 Tool 목록
  - 금지 행동 (중복 조회 등)
  - 응답 형식 지정

□ 실행 검증
  - 단순 질문 (Tool 1회): 정상 동작?
  - 복합 질문 (Tool 3회): 체이닝 정상?
  - 에러 상황: 우아한 에러 메시지?

실무 팁: 배포 전 10가지 시나리오 테스트를 완료하고 trace를 저장해두면 이후 문제 발생 시 빠르게 비교할 수 있다.