23. 트러블슈팅과 프레임워크 선택 가이드

비유로 시작하기: 증상이 아니라 원인을 고친다

기침이 난다고 기침만 멈추는 약을 먹으면, 원인(감기·알레르기)은 그대로입니다. 에이전트 디버깅도 같습니다. "답이 이상하다"는 증상일 뿐, 원인은 프롬프트일 수도, 도구 설명일 수도, 메모리 설정일 수도 있습니다. 증상에서 원인으로 좁혀가는 사고가 핵심입니다.

흔한 오류와 해결책

강좌 전반에서 짚은 함정을 한자리에 모았습니다.

디버깅 사고법: 트레이스부터 본다

flowchart TD
    classDef step fill:#80DEEA,stroke:#00838F,color:#000
    classDef q fill:#FFE082,stroke:#F9A825,color:#000

    S[이상한 결과] --> T[트레이스·로그 확인]:::step
    T --> Q{어느 단계에서<br/>어긋났나?}:::q
    Q -->|도구 선택| P1[도구 설명 점검]:::step
    Q -->|도구 결과 해석| P2[결과를 모델에 전달?]:::step
    Q -->|분기·라우팅| P3[라우터·매니저 지시 점검]:::step
    Q -->|맥락 상실| P4[메모리 설정 점검]:::step

📌 핵심: 6장 트레이싱, n8n 실행 이력, LangGraph 상태 시각화 — 어떤 도구든 "무슨 일이 일어났는지 보는 창"이 있습니다. 추측으로 코드를 고치기 전에 먼저 트레이스를 읽으세요. 거의 모든 버그는 트레이스에 단서가 있습니다.

⚠️ 흔한 실수: 트레이스를 보지 않고 프롬프트를 무작정 바꾸는 것. 운 좋게 고쳐질 수 있지만, 원인을 모르면 같은 버그가 다른 형태로 재발합니다.

프레임워크 선택 가이드

이 강좌의 핵심 질문에 답할 차례입니다. "언제 무엇을 쓸까?" 정답은 하나가 아니라 작업 성격에 달렸습니다.

flowchart TD
    classDef q fill:#FFE082,stroke:#F9A825,color:#000
    classDef tool fill:#80DEEA,stroke:#00838F,color:#000

    Q1{코딩 없이<br/>비개발자도?}:::q
    Q1 -->|예| N[n8n<br/>노코드·업무 자동화]:::tool
    Q1 -->|아니오| Q2{흐름을 한 단계씩<br/>정밀 제어?}:::q
    Q2 -->|예| LG[LangGraph<br/>그래프·정밀 제어]:::tool
    Q2 -->|아니오| Q3{역할 분담이<br/>자연스러운가?}:::q
    Q3 -->|예| CR[CrewAI<br/>역할 기반 팀]:::tool
    Q3 -->|아니오| OAI[OpenAI Agents SDK<br/>최소 추상화·빠른 시작]:::tool

각 도구의 강점을 정리하면 이렇습니다.

💡 성능 참고: 벤치마크에 따르면 단순 QA에서는 CrewAI가 LangGraph보다 빠른 경우가 보고되었고, 복잡한 추론 작업에서는 LangGraph의 성공률이 더 높다는 결과도 있습니다. 즉 속도와 정밀도의 트레이드오프가 있으니, 자신의 실제 사용 사례로 벤치마크해 보고 고르는 것이 가장 확실합니다.

📌 핵심: 이들은 경쟁자가 아니라 도구 상자 안의 다른 공구입니다. 실제로 함께 쓰입니다 — n8n 워크플로 안에서 판단은 OpenAI 모델이 하고, 도구는 MCP 서버로 표준화하고, 복잡한 하위 흐름은 LangGraph로 짤 수 있습니다. 하나를 "정답"으로 고집하지 마세요.

통합 지도: 강좌에서 배운 것

flowchart TB
    classDef concept fill:#FFE082,stroke:#F9A825,color:#000
    classDef tool fill:#80DEEA,stroke:#00838F,color:#000
    classDef cross fill:#A5D6A7,stroke:#2E7D32,color:#000

    C[핵심 개념<br/>루프·메모리·도구·멀티에이전트·가드레일]:::concept
    C --> T1[OpenAI SDK]:::tool
    C --> T2[LangGraph]:::tool
    C --> T3[CrewAI]:::tool
    C --> T4[n8n]:::tool
    P[MCP<br/>도구 표준]:::cross
    P -.모든 도구에 연결.-> T1
    P -.-> T2
    P -.-> T3
    P -.-> T4
    X[횡단 원칙<br/>프롬프팅·비용·보안]:::cross
    X -.모든 도구에 적용.-> T1
    X -.-> T2
    X -.-> T3
    X -.-> T4

이 지도가 강좌의 결론입니다. 가운데 핵심 개념(1부)은 변하지 않습니다. 프레임워크(2·4·5·7부)는 그 개념을 각자의 방식으로 구현합니다. MCP(6부)는 도구를 모든 프레임워크에 표준으로 연결하고, 횡단 원칙(8부)은 어디서나 적용됩니다. 도구는 갈아타도 개념은 자산으로 남습니다.

이 장에서 배운 것

• 에이전트 버그는 증상이 아니라 원인을 고쳐야 한다. 트레이스를 먼저 읽고 원인을 좁힌다.
• 흔한 오류 대부분은 프롬프트·도구 설명·메모리·반복 제한·구조화 출력 설정에서 비롯된다.
• 프레임워크는 작업 성격으로 고른다: 노코드는 n8n, 정밀 제어는 LangGraph, 역할 분담은 CrewAI, 빠른 시작은 OpenAI SDK.
• 이들은 경쟁자가 아니라 함께 쓰는 공구다. 핵심 개념은 도구를 갈아타도 남는 자산이다.

✍️ 확인 문제

1. "답이 이상하다"는 증상에 대해, 추측으로 프롬프트를 고치기 전에 가장 먼저 해야 할 일은?
2. 비개발자 팀의 업무 자동화 속에 AI 판단 한 조각을 넣어야 한다. 어떤 도구가 적합하며 그 이유는?
3. "프레임워크를 갈아타도 1부의 개념은 자산으로 남는다"는 말의 의미를, 메모리 개념을 예로 설명하라.

이전 장: 22. 비용·토큰 관리와 보안
다음: 부록 · 치트시트·용어집·추가 학습