Devlog · AI Agent Study

LangGraph 프레임워크 공부 기록

오늘은 LangGraph 프레임워크를 공부했다. 처음에는 LangGraph가 단순히 LangChain의 확장 도구라고 생각했지만, 공부해보니 핵심은 조금 달랐다. LangGraph는 Agent가 어떤 순서로 생각하고, 어떤 조건에서 분기하고, 실패했을 때 어떻게 복구할지를 구조적으로 통제하는 프레임워크에 가깝다.

LLM을 중심에 두지 말고, StateGraph를 중심에 두고 LLM을 Node 안에 넣자.
01 · Core Understanding

오늘의 핵심 이해

LangGraph를 정리하면 다음과 같다.

LangGraph는 Agent의 실행 흐름을 State, Node, Edge로 나누어 관리하는 상태 기반 그래프 프레임워크다. LLM에게 맡길 부분과 코드가 통제할 부분을 그래프로 분리한다.

기존 Agent는 보통 이런 흐름에 가까웠다.

사용자 질문→ LLM 판단→ 도구 사용→ 답변 생성

이 방식은 데모를 만들 때는 빠르지만, 실제 운영에서는 LLM에게 너무 많은 판단을 맡긴다. 그래서 예측하기 어렵고 디버깅도 어려워진다.

LangGraph는 흐름을 더 명확하게 나눈다.

상태 저장→ 작업 단위 실행→ 조건 분기→ 반복 / 복구→ 검증 후 답변
즉, LangGraph의 핵심은 LLM 중심 설계가 아니라 흐름 중심 설계다.
02 · Components

LangGraph의 주요 구성 요소

오늘 가장 중요하게 이해한 개념은 네 가지다.

State Agent가 들고 다니는 현재 상태
Node 하나의 작업 단위
Edge 다음 작업으로 이동하는 연결선
Graph 전체 실행 흐름
03 · State

State란?

State는 Agent가 실행되는 동안 계속 들고 다니는 정보다.

예를 들어 Media AI Agent를 만든다면 State에는 이런 정보들이 들어갈 수 있다.

  • 사용자 질문
  • 질문 유형
  • 검색 결과
  • 도구 호출 결과
  • 최종 답변
  • 에러 여부
class AgentState(TypedDict):
    user_query: str
    chat_type: str
    retrieved_docs: list
    tool_results: list
    final_answer: str
    error: str | None

State를 공부하면서 느낀 점은, LangGraph에서는 Node보다 State 설계가 더 중요하다는 것이다. Node는 결국 State를 읽고, 필요한 값을 추가하거나 수정한다.

State 입력→ Node 실행→ 변경된 State 반환
State가 지저분하면 전체 Agent 구조도 지저분해진다. 그래서 State는 초반에 대충 만들면 안 된다.
04 · Node

Node란?

Node는 하나의 작업 단위다. 예를 들면 다음과 같은 것들이 모두 Node가 될 수 있다.

  • 질문 정규화
  • 질문 유형 분류
  • RAG 검색
  • 날씨 API 호출
  • 답변 생성
  • 답변 검증
  • Fallback 처리

나쁜 구조

classify_and_search_and_answer

이렇게 만들면 분류, 검색, 답변 생성이 한 함수 안에 다 섞인다. 문제가 생겼을 때 어디서 잘못됐는지 알기 어렵다.

좋은 구조

classify_intent
retrieve_documents
generate_answer
validate_answer
Node는 작고 명확해야 한다. 하나의 Node는 하나의 책임만 가져야 디버깅과 운영이 쉬워진다.
05 · Edge

Edge란?

Edge는 Node와 Node를 연결하는 흐름이다.

START→ classify_intent→ retrieve_documents→ generate_answer→ END

하지만 LangGraph의 진짜 장점은 조건 분기에 있다.

weather_node media_qa_node chit_chat_node fallback_node

Router는 “어디로 보낼까?”를 결정하지만, LangGraph는 그 다음까지 표현할 수 있다. 실패하면 어떻게 할지, 검색 결과가 부족하면 다시 찾을지, 검증에 실패하면 되돌릴지까지 구조화할 수 있다.

06 · Difference

기존 Agent와 LangGraph의 차이

기존 Agent 방식

  • LLM이 알아서 판단한다
  • LLM이 알아서 도구를 고른다
  • LLM이 알아서 답변한다

LangGraph 방식

  • 흐름은 Graph가 통제한다
  • 판단이 필요한 부분에만 LLM을 사용한다
  • 각 단계는 Node로 분리한다
  • 실패 흐름도 명시적으로 설계한다

LLM에게 모든 것을 맡기면 유연해 보이지만, 운영 관점에서는 위험하다. LangGraph는 LLM의 자유도를 없애는 것이 아니라, 필요한 자유도만 남기고 나머지는 코드 구조로 안정화하는 방식이다.

07 · Structure

오늘 이해한 LangGraph 구조

START
↓
Normalize Question
↓
Determine Chat Type
↓
Weather Agent Media QA Agent General QA Agent ChitChat Agent
↓
Validate Answer→Final Answer→END

내 프로젝트에 적용하면

사용자 질문 → 질문 정규화 → 질문 유형 판단 → 유형별 Sub Agent 실행 → 답변 검증 → 최종 응답

날씨 질문

사용자 질문 → 날짜/위치 추출 → 날씨 API 호출 → 결과 정리 → 답변 생성

Media QA 질문

사용자 질문 → 질문 재작성 → 콘텐츠 검색 → 검색 결과 검증 → 답변 생성

ChitChat

사용자 질문 → 대화 맥락 확인 → 자연어 응답 생성

08 · Failure Flow

LangGraph에서 중요한 것은 실패 흐름이다

Agent 설계에서는 성공 흐름보다 실패 흐름이 더 중요하다. 실제 운영에서는 다음과 같은 상황이 자주 생긴다.

  • 질문 유형 분류 실패
  • 검색 결과 없음
  • 검색 결과가 질문과 맞지 않음
  • 도구 호출 실패
  • LLM 응답 파싱 실패
  • 사용자 정보 부족
  • 답변 검증 실패

LangGraph에서는 실패 흐름을 그래프에 넣을 수 있다.

Retrieve→ Grade Documents→ Is Enough?
Yes: Generate Answer No: Rewrite Query→ Retrieve Again
Retrieve → Grade → Rewrite → Retrieve Again → Generate

이 구조가 가능해진다는 점이 LangGraph를 써야 하는 가장 큰 이유 중 하나라고 느꼈다.

09 · First Principles

오늘의 제1원칙 정리

Assumption 01 Agent는 LLM이 알아서 판단해야 한다

반드시 맞는 말이 아니다. LLM이 모든 것을 판단하면 오히려 통제가 어려워진다. 본질은 LLM이 자유롭게 행동하는 것이 아니라, 문제를 정확한 단계로 나누고 필요한 곳에서만 LLM을 쓰는 것이다.

Assumption 02 RAG는 검색 후 답변하면 끝이다

실제 서비스에서는 검색 결과가 충분한지 확인해야 한다. 부족하다면 질문을 다시 쓰고, 다시 검색하고, 그래도 부족하면 fallback 해야 한다.

검색 → 평가 → 재검색 여부 판단 → 답변 → 검증

Assumption 03 라우터 하나면 Agent 구조가 완성된다

라우터는 시작일 뿐이다. 실제 Agent는 질문 유형, 도구 선택, 검색 방식, 검증 결과, 실패 처리 등 여러 단계에서 라우팅이 필요하다.

10 · Conclusion

오늘의 결론

오늘 LangGraph를 공부하면서 가장 크게 정리된 생각은 이것이다.

Agent는 LLM 하나가 알아서 움직이는 구조가 아니라, 상태와 흐름을 가진 실행 시스템이다.

LangGraph는 그 실행 시스템을 만들기 위한 프레임워크다. 앞으로 Agent를 설계할 때는 단순히 “어떤 프롬프트를 쓸까?”보다 먼저 다음을 고민해야겠다.

  • 어떤 State가 필요한가?
  • 어떤 Node로 쪼갤 것인가?
  • 어떤 조건에서 분기할 것인가?
  • 실패하면 어디로 되돌릴 것인가?
  • 어떤 지점에서 검증할 것인가?
  • 어떤 정보를 저장하고 이어갈 것인가?