Day 1 · 작성자 Kunal Hore (@KunalOnTech)

빠른 이동 (Quick Jump)

• 왜 이것을 공개적으로 학습하는가
• 오늘의 지도
• 1. 상태 (State)
• 2. 노드 (Nodes)
• 3. 엣지 (Edges)
• 4. 구축 및 실행 — 전체 실습
• Kunal의 인터뷰 코너
• 오늘의 핵심 요약 (Today's Takeaway)

대부분의 코드는 자신이 어디를 거쳐왔는지에 대한 기억 없이, 위에서 아래로 한 번씩 실행됩니다. 실제 의사결정은 직선으로 움직이지 않습니다. 때로는 뒤로 돌아가 루프(loop)를 돌기도 하고, 방금 일어난 일에 따라 분기(branch)하기도 합니다. 스크립트는 실행 중간에 멈춰서 재고할 수 없습니다. 하지만 **그래프 (graph)**는 가능합니다.

단순히 실행만 하는 대신, 멈추고, 결정하고, 다시 돌아올 수 있는 코드라는 그 단 하나의 차이점이 바로 LangGraph가 존재하는 이유 전체입니다.

앞으로 며칠 동안 여러분이 LangGraph에 익숙해질 수 있도록 모든 주제를 다룰 것입니다. 오늘은 저의 학습 첫날이며, 배우는 과정에서 얻는 모든 것을 공유할 것입니다. 오늘은 세 가지 기초 요소, 즉 그래프가 기억하는 것 (상태 (state)), 한 단계로 간주되는 것 (노드 (node)), 그리고 이러한 단계들이 어떻게 연결되는지 (엣지 (edge))에 대해 다룹니다. 우리는 단순히 말로만 설명하지 않을 것입니다. 실제 코드로 작은 실습을 직접 구축해 볼 것입니다. 왜냐하면 저는 항상 이론만이 아니라 직접 만들어보면서 배운다고 믿기 때문입니다.

Kunal의 한 줄 평: "앞으로만 나아가는 코드는 생각할 수 없다. 되돌아올 수 있는 코드는 생각할 수 있다."

이것이 오늘의 핵심 요지입니다. 그 외의 모든 것들 — TypedDict, 함수 시그니처 (function signatures), 엣지 구문 (edge syntax) — 은 단지 그 하나의 아이디어를 Python에서 실현하기 위한 메커니즘일 뿐입니다.

왜 이것을 공개적으로 학습하는가

저는 LangGraph를 기초부터 — 하루에 하나의 개념씩 — 배우고 있습니다. 지름길은 없으며, 이미 알고 있는 척하지도 않습니다. 매일 배우는 것은 그날 바로 공유합니다. 성공한 순간, 혼란스러웠던 순간, "아, 그게 이 뜻이었구나" 하는 순간들, 그 모든 것을 말이죠.

저의 목표는 간단합니다:

• 하루에 하나의 개념을 일상적인 비유를 들어 설명하기 — 전문 용어의 벽을 세우지 않음
• 매일 실제 코드 작성하기, 왜냐하면 이론만이 아니라 직접 만들어보면서 배우기 때문
• 누군가 나에게 설명해 주었으면 했던 방식 그대로 쓰기

저와 함께 학습하신다면 여러분의 목표는 다음과 같습니다: 이 시리즈가 끝날 때쯤이면, 우리 모두는 단순히 한 번 응답하는 것을 넘어 스스로 결정하고, 분기하고, 재시도하며, 루프(loop)를 돌 수 있는 상태 유지형 AI 에이전트 (stateful AI agents)를 설계하고 구축할 수 있게 될 것입니다.

저 또한 배우면서 진행하는 과정이기에, 무언가를 놓치거나 세부 사항을 틀릴 수도 있습니다. 만약 읽으시다가 제가 간과한 부분이 있다고 느껴지신다면 댓글로 남겨주세요. 이는 제가 성장하는 데 진심으로 도움이 되며, 이 시리즈를 따라오는 모든 분에게 더 나은 콘텐츠를 만드는 밑거름이 됩니다.

군더더기 없이. 하루에 한 입씩.

대상 독자: 일반적인 Python 함수 작성이 익숙하면서, 에이전트 프레임워크 (agent frameworks)가 내부적으로 실제로 어떻게 작동하는지 궁금한 분들. LangChain이나 LangGraph에 대한 사전 경험은 필요하지 않습니다. 제로(zero) 상태에서 시작합니다.

LangChain을 먼저 알아야 하나요? 아니요. LangGraph는 상태 유지형 워크플로우 (stateful workflows)를 위한 그래프 엔진으로서 그 자체로 독립적인 존재입니다. LangChain에 익숙하다면 도움이 되겠지만, 이 시리즈의 어떤 페이지를 보더라도 필수 조건은 아닙니다.

오늘의 지도

1. 상태 (State) — 사실 관계; 그래프가 기억하도록 허용된 것
2. 노드 (Nodes) — 하나의 동작; 상태를 업데이트하는 함수
3. 엣지 (Edges) — 동작이 일어나는 순서; 무엇 다음에 무엇이 실행될 것인가
4. 빌드 및 실행 (Build & Run) — 이를 하나로 연결하고, 컴파일하고, 첫 번째 그래프를 실행하기

1. 상태 (State)

저녁 8시입니다. 배가 고픕니다. 지금 당신의 머릿속에 떠오르는 첫 번째 생각은 바로 배고픔입니다. 당신의 뇌는 '음식 앱을 열자'라고 생각합니다. 이제 뇌는 한 가지 사실을 더 알게 되었습니다: 앱이 열렸다는 사실입니다. 앱을 둘러보다가 식당을 하나 고릅니다. 당신의 뇌가 붙잡고 있는 정보가 하나 더 추가됩니다: 어떤 식당인지 말이죠. 메뉴를 고릅니다. 또 하나의 정보가 추가됩니다. 주문을 완료합니다. 하나 더 추가됩니다.

과정을 마칠 때쯤, 당신의 뇌는 더 이상 하나의 생각만을 품고 있지 않습니다. 다섯 가지 생각을 동시에 품고 있습니다: 배가 고프다는 것, 앱이 열려 있다는 것, 어떤 식당인지, 어떤 메뉴인지, 그리고 주문이 완료되었는지 여부입니다.

당신의 뇌가 추적하고 있는 이러한 정보들의 집합 — 그것이 바로 상태 (state) 입니다.

상태는 단순히 사실들이 흩어져 있는 더미가 아닙니다. 그것은 고정된 형태를 가집니다. 즉, 각각 고정된 타입을 가진 고정된 필드(field)들의 목록이며, 코드에서는 TypedDict를 사용하는 클래스 (class)로 정의됩니다.

from typing import TypedDict

class FoodOrderState(TypedDict):
...

이것을 기억하세요:

• TypedDict가 실제로 하는 일 — TypedDict는 클래스를 사용하여 딕셔너리 (dictionary)의 형태를 기술하는 방법입니다. 새로운 종류의 객체를 생성하는 것이 아닙니다. 런타임 (runtime) 시점에 여러분의 상태 (state)는 여전히 일반적인 딕셔너리입니다. TypedDict가 추가하는 것은 계약 (contract)입니다. 즉, 어떤 키가 반드시 존재해야 하는지, 그리고 각 키가 어떤 타입을 보유해야 하는지를 Python (및 개발자)에게 정확히 알려줍니다.
• 이것이 여기서 중요한 이유 — 모든 노드 (node)는 상태에 대해 동일한 형태를 사용합니다. 따라서 TypedDict는 코드가 실행되기 전에 에디터 (editor)와 LangGraph가 두 가지 간단한 사항을 확인할 수 있도록 도와줍니다. 즉, 존재하지 않는 필드 (field)를 읽고 있지 않은지, 그리고 필드에 잘못된 타입의 값을 넣고 있지 않은지를 확인합니다.

2. 노드 (Nodes)

여러분의 뇌는 다섯 가지 사실 — 배고픔, 앱 열림, 식당, 요리, 주문 완료 — 을 보유하고 있었습니다. 이 사실들 중 어느 것도 스스로 채워지지 않았습니다. 각각은 여러분이 행한 어떤 일의 결과였습니다. 배고픔을 느꼈고, 앱을 열었으며, 식당을 선택했습니다.

이러한 각각의 동작을 우리는 **노드 (node)**라고 부릅니다. 즉, 현재의 상태 (state)를 입력받아, 그중 한 가지를 변경하고, 업데이트된 상태를 다시 내보내는 함수 (function)입니다.

코드에서의 노드:

def feel_hungry(state: FoodOrderState) -> FoodOrderState:
    state["mood"] = "hungry"
    return state

등록하기:

graph.add_node("feel_hungry", feel_hungry)

이것을 기억하세요:

• add_node는 두 개의 인자 (argument)를 받습니다 — 첫 번째는 레이블 (label)로, 엣지 (edge)를 연결할 때 이 노드를 참조하기 위해 사용되는 문자열 (string)입니다. 두 번째는 실제로 실행되는 함수 (function)입니다. 두 값이 반드시 일치할 필요는 없지만, 순수하게 가독성을 위해 동일하게 유지하는 것이 관례입니다.
• 노드는 상태를 변경할 수 있는 유일한 요소입니다 — 노드는 Python 함수가 할 수 있는 모든 일 — 출력 (print), API 호출, 또는 파일 쓰기 — 을 할 수 있습니다. 하지만 그래프 (graph)는 여러분의 노드가 반환하는 상태만을 전달합니다. 반환된 상태에 포함하지 않은 모든 것은 다른 노드에서 사용할 수 없습니다.

3. 엣지 (Edges)

그 행동들이 일어난 순서 — 배고픔을 느끼고, 앱을 열고, 둘러보는 것 — 그 시퀀스(sequence)가 바로 **엣지 (Edge)**입니다. 엣지는 하나의 노드를 다른 노드에 연결하며, 노드가 종료된 후 그래프가 따라갈 경로를 정의합니다. 만약 가능한 경로가 여러 개라면, 라우팅 (routing) 단계에서 그래프가 앞으로 나아가기 전에 어떤 엣지를 탈지 결정합니다.

코드에서의 엣지:

# feel_hungry가 종료된 후, 다음으로 open_app을 실행
graph.add_edge("feel_hungry", "open_app")

4. 빌드 및 실행 — 전체 실습

문제 정의: 음식을 주문하는 사람을 그래프로 모델링합니다 — 5가지 사실을 추적하는 공유 상태 (shared state), 각 사실을 하나씩 업데이트하는 5개의 노드, 그리고 배고픔을 느끼는 것부터 주문이 완료될 때까지 정해진 순서로 실행되는 엣지들로 구성합니다.

우리 그래프가 따라갈 정확한 경로는 다음과 같습니다:

START
  │
  ▼
...

# Imports — 그래프 빌더와 TypedDict 베이스 클래스
from langgraph.graph import StateGraph, START, END
from typing import TypedDict
...

출력 (Output):

{
    'mood': 'hungry',
    'app_opened': True,
...

모든 노드는 공유 상태의 한 조각을 업데이트했습니다. 마법 같은 일은 일어나지 않았습니다. 그래프는 단순히 시작부터 끝까지 동일한 딕셔너리 (dictionary)를 들고 노드들을 하나씩 거쳐갔을 뿐입니다.

Kunal의 인터뷰 코너

오늘의 수업에 대해 누군가 실제로 물어볼 법한 네 가지 질문입니다. 조용히 읽어 내려갈 때는 드러나지 않는 공백들을 드러내 주는 질문들입니다. 이것들은 암기해야 할 정의가 아닙니다. 각 질문에는 면접관이 듣고 싶어 하는 구조인 **답변 프레임워크 (answer framework)**가 함께 제공됩니다. 클릭하기 전에 직접 답해 보세요.

Q1. LangGraph 워크플로우 (workflow)와 일반적인 Python 스크립트의 차이점은 무엇인가요?

· 답변 프레임워크: 두 가지를 대조하기 → 머릿속에 그려지는 그림 제시하기

· 답변: 일반적인 Python 스크립트에서는 일들이 직선상에서 차례대로 실행됩니다. LangGraph를 사용하면 훨씬 유연합니다. 마치 플로우차트 (flowchart)처럼, 여기저기 건너뛰거나 다양한 순서로 작업을 실행할 수 있다고 생각하면 됩니다.

Q2. LangGraph에서 상태 (State)란 무엇인가요?

· 답변 프레임워크: 쉬운 말로 정의하기 → 그것이 무엇을 가능하게 하는지 설명하기

· 답변: 상태 (State)는 기본적으로 모든 노드 (Node)가 접근하고 업데이트할 수 있는 공유 노트와 같습니다. 이는 노드들이 서로 대화하고 현재 진행 상황을 기억할 수 있도록 돕습니다.

Q3. LangGraph에서 노드 (Node)란 무엇인가요?

· 답변 프레임워크: 역할 정의하기 → 동작 설명하기

· 답변: 노드 (Node)는 하나의 특정한 일을 수행하는 작은 작업 단위입니다. 현재의 상태 (State)를 확인하고, 자신의 할 일을 수행한 뒤, 필요에 따라 상태 (State)를 업데이트합니다.

Q4. LangGraph에서 엣지 (Edge)란 무엇인가요?

· 답변 프레임워크: 비유 들기 → 제어하는 대상 명시하기

· 답변: 엣지 (Edge)는 두 노드 (Node)를 연결하는 화살표와 같습니다. 노드들이 실행되는 순서를 결정합니다.

_"노트를 확인하지 않고 이 네 가지 질문에 답할 수 있다면, Day 1 내용은 실제로 머릿속에 남은 것입니다."

오늘의 핵심 요약 (Today's Takeaway)

오늘 배운 것 중 딱 세 가지만 기억해야 한다면, 다음을 기억하세요:

LangGraph의 나머지 모든 요소는 이 세 가지 개념을 기반으로 구축됩니다. 이것들을 한 번 마스터하면 나머지는 훨씬 쉬워집니다.

다음 단계 → Day 2: 조건부 엣지 (Conditional Edges)

함께하고 계신가요? LinkedIn · YouTube: @kunalontech에서 저와 연결하세요.