2. LangGraph 기본기
그래프를 이루는 세 부품
이 차시를 마치면
State·Node·Edge 로 프로그램의 흐름을 그려 봅니다.
LangGraph 를 이루는 세 가지 기본 요소를 익힙니다. 이 셋을 이해하면 나머지는 그 위에 얹힙니다.
LangGraph 는 무엇인가
오래 돌아가면서 앞선 내용을 기억해야 하는 Agent 를 만들 때, LangGraph 는 실행 순서를 직접 그리게 해 주는 도구입니다. 흔히 "낮은 수준(low-level)"이라고 부르는데, 기능이 모자라다는 뜻이 아닙니다. 알아서 해 주는 부분이 적은 대신 어디서 무엇이 실행될지를 내가 정한다는 뜻입니다.
아홉 가지 개념과 비유
| 개념 | 정의 | 초보자용 비유 |
|---|---|---|
| State | 그래프 실행 전체에서 공유되는 현재 데이터 | 여러 담당자가 함께 쓰는 공동 작업노트 |
| Node | State 를 받아 일한 뒤, 무엇을 어떻게 바꿀지 갱신값으로 돌려주는 단위 | 업무 단계 하나를 맡은 담당자 |
| Edge | 어떤 Node 다음에 어떤 Node 가 실행되는지 결정하는 연결 | 다음 담당자에게 넘기는 규칙 |
| Conditional Edge | State 를 보고 다음 Node 를 동적으로 선택 | 조건문이 있는 갈림길 |
| Reducer | 여러 갱신값이 같은 키에 들어올 때의 덮어쓰기, 누적, 병합 규칙 | 여러 사람의 수정을 합치는 규칙 |
| Checkpointer | 각 단계의 State 스냅샷을 저장 | 자동 저장 기능 |
| Thread | Checkpoint 가 묶이는 실행 단위. thread_id 가 핵심 식별자 | 작업 건 번호 |
| Interrupt | Node 실행 중 의도적으로 멈추고 외부 입력을 받은 뒤 재개 | 승인 대기 |
| Store | Thread 를 넘어서는 장기 기억과 앱 수준 정보 저장 | 부서 공용 캐비닛 |
raw/03_IMAGES/README_이미지출처.md)머릿속에 그려 둘 그림
START
↓
[node A] --state update-->
↓
[router] ──조건1→ [node B]
└────조건2→ [node C]
↓
END
State 에 둘 것과 두지 말 것
State 에는 "그래프의 다음 판단에 필요한 현재 작업 정보"를 둡니다.
| 좋은 예 | 피해야 할 예 |
|---|---|
messages, current_question, retrieved_docs, approved, draft, retry_count |
무제한으로 증가하는 모든 raw log · State 판단에 필요 없는 대용량 binary · Thread 간 공유되어야 하는 사용자 profile 을 무조건 Thread State 에 저장 |
이 구분은 보안에서도 중요합니다. State 에 넣은 값은 Checkpoint 저장소에 남기 때문입니다. 개인정보 원문을 State 에 담으면 Checkpoint 저장소가 개인정보 저장소가 됩니다. 분석
Node 는 단일 책임으로
Node 는 가능한 한 하나의 일만 하도록 만듭니다.
| 좋음 | 나쁨 |
|---|---|
retrieve_documents, judge_relevance, write_answer, request_approval |
do_everything |
비유
한 사람이 접수, 심사, 승인, 발송을 모두 하면 어디서 잘못됐는지 알 수 없습니다. 단계를 나누면 어느 단계에서 멈췄는지가 바로 보입니다. 나중에 승인 단계만 사람에게 넘기는 일도 쉬워집니다.
Edge 두 종류
고정 Edge 는 처리 순서가 정해져 있고, Conditional Edge 는 상태를 보고 경로를 선택합니다.
from typing import Literal
def route_after_grade(state) -> Literal["generate", "rewrite"]:
"""관련도가 기준을 넘으면 답을 쓰고, 아니면 질문을 고쳐 다시 검색한다."""
return "generate" if state["relevance_score"] >= 0.8 else "rewrite"
조건부 분기에는 반드시 종료 조건이 있어야 합니다. 다시 검색하는 경로를 만들었다면 몇 번까지 다시 할지 정해야 합니다. 이 규칙은 3번 트랙에서 자세히 다룹니다.
이 차시의 파이썬 코드는 개념을 보이려고 떼어 놓은 예시 조각입니다. 문법 검사는 통과하지만 그대로 돌려서 결과를 확인한 코드는 아닙니다. 실행까지 검증한 코드는 4번과 6번 트랙에 있으며, 그 차시에는 무엇을 어떻게 확인했는지 따로 적어 두었습니다.