Graph 모듈 튜토리얼 — 목차

⚠️ 실험적 기능 경고 (Experimental Warning)

euleragent graph 모듈은 현재 실험적(experimental) 상태입니다. 이 모듈의 API, YAML 스키마, 동작 방식은 마이너 버전 업데이트에서도 예고 없이 변경될 수 있습니다. 연구 및 프로토타이핑 목적으로는 자유롭게 활용할 수 있지만, 프로덕션 미션 크리티컬 시스템에 적용할 경우 충분한 테스트와 검증 과정을 거친 후 사용하시기 바랍니다.

⚠️ 병렬 실행 주의사항

parallel_groups를 사용한 병렬 팬아웃/팬인 실행은 경쟁 상태(race condition), 비결정론적 결과, 예상치 못한 LangGraph 내부 동작을 초래할 수 있습니다. 병렬 브랜치가 공유 상태 키(state key)에 접근할 때는 반드시 적절한 리듀서(reducer)를 선언해야 하며, euleragent graph validate 명령으로 사전 검증을 완료한 후 실행하십시오. 모든 병렬 실행의 결과에 대한 검증 책임은 사용자에게 있습니다.

튜토리얼 목록

튜토리얼 설명

00_disclaimer.md — 실험적 기능 고지 (필독)

Graph 모듈을 사용하기 전에 반드시 읽어야 하는 고지 문서입니다. 실험적 기능의 범위, 개발자 책임 원칙, LangGraph 버전 의존성, 안전한 사용 방법을 설명합니다.

01_concepts.md — Graph vs Pattern 개념

Pattern과 Graph의 관계를 설명합니다. Graph는 Pattern의 완전한 상위 집합으로, 무엇이 추가되었는지 (state_schema, parallel_groups, interrupt hooks, LangGraph 통합)와 YAML-to-LangGraph 컴파일 파이프라인을 다룹니다.

02_linear_graph.md — 선형 그래프

병렬 기능 없이 가장 단순한 Graph YAML을 작성합니다. LangGraph 컴파일 결과를 확인하고 Pattern과 비교합니다.

03_judge_route.md — Judge 라우팅

2-route 및 3-route judge 패턴을 Graph에서 구현합니다. LangGraph의 add_conditional_edges로 컴파일되는 과정을 이해합니다.

04_bounded_loop.md — 경계 있는 루프

max_iterations로 루프를 안전하게 경계 짓는 방법을 배웁니다. UNBOUNDED_CYCLE 에러를 시연합니다.

05_interrupt_hooks.md — Interrupt Hooks

interrupt_before와 interrupt_after를 사용해 특정 노드에서 실행을 일시 정지합니다. HITL force_tool 방식과의 차이를 이해합니다.

06_state_schema.md — State Schema 상세

5가지 type과 5가지 merge 전략의 조합을 완전히 이해합니다. LangGraph 리듀서로 컴파일되는 과정과 타입+전략 호환성 표를 다룹니다.

07_parallel_basics.md — 병렬 실행 기초

2개 브랜치의 가장 단순한 팬아웃/팬인 패턴을 만듭니다. 병렬 관련 에러 코드를 직접 시연합니다.

08_parallel_advanced.md — 고급 병렬 패턴

3개 이상의 브랜치와 복잡한 상태 설계를 다룹니다. 브랜치별 독립 state key 사용과 공유 key의 안전한 merge 전략을 마스터합니다.

09_parallel_with_quality.md — 종합 예제 (캡스톤)

병렬 팬아웃/팬인과 Judge 품질 루프를 결합한 프로덕션 수준의 그래프를 만듭니다. 지금까지 배운 모든 개념을 통합합니다.

10_reference.md — 완전 레퍼런스

Graph YAML 전체 필드 테이블, 에러 코드 목록, 타입+Merge 호환성 매트릭스, 안전한 병렬 설계 체크리스트를 제공합니다.

권장 학습 순서

필독: 00_disclaimer.md
        ↓
개념 이해: 01_concepts.md
        ↓
기초 실습: 02_linear_graph.md → 03_judge_route.md → 04_bounded_loop.md
        ↓
중급 기능: 05_interrupt_hooks.md → 06_state_schema.md
        ↓
병렬 실행: 07_parallel_basics.md → 08_parallel_advanced.md
        ↓
종합 실습: 09_parallel_with_quality.md
        ↓
참조 문서: 10_reference.md (필요할 때 참조)

완전 초보자라면 순서대로 한 파일씩 따라가는 것을 권장합니다. 이미 Pattern 튜토리얼을 완료한 사용자라면 01_concepts.md에서 차이점을 확인한 뒤 06_state_schema.md부터 시작해도 됩니다.

사전 준비 (Prerequisites)

Graph 모듈 튜토리얼을 시작하기 전에 다음을 완료했는지 확인하세요.

필수 완료 튜토리얼

• docs/tutorials/basic/01_*.md — euleragent 기본 설치 및 CLI 사용
• docs/tutorials/pattern/01_*.md — Pattern 개념 이해
• docs/tutorials/pattern/02_*.md — Pattern YAML 작성
• docs/tutorials/pattern/03_*.md — Pattern validate 및 실행

필수 소프트웨어

# Python 3.10 이상
python --version

# euleragent 설치 (editable 모드)
pip install -e .

# LangGraph 버전 확인 (1.0.9 이상 필요)
pip show langgraph | grep Version

# graph 모듈 사용 가능 확인
euleragent graph --help

LangGraph 버전 정보

이 튜토리얼은 LangGraph 1.0.9 이상을 기준으로 작성되었습니다. LangGraph의 StateGraph API는 버전에 따라 달라질 수 있으며, 특히 다음 메서드들이 버전별로 시그니처가 다를 수 있습니다.

# LangGraph 설치/업그레이드
pip install "langgraph>=1.0.9"

# 설치 확인
python -c "import langgraph; print(langgraph.__version__)"

Graph 모듈 CLI 빠른 참조

# 사용 가능한 그래프 목록 조회
euleragent graph list

# 그래프 구조 확인
euleragent graph show <경로_또는_ID>

# 그래프 유효성 검사
euleragent graph validate <경로_또는_ID>
euleragent graph validate <경로_또는_ID> --format json

# LangGraph IR로 컴파일
euleragent graph compile <경로_또는_ID>
euleragent graph compile <경로_또는_ID> --out compiled.json

이 튜토리얼에서 사용하는 예제 파일 위치

튜토리얼에서 작성하는 YAML 파일은 작업 디렉터리 내 examples/graphs/ 아래에 정리합니다.

examples/graphs/
  linear/        # 선형 그래프 예제
  loops/         # 루프 패턴 예제
  parallel/      # 병렬 패턴 예제
  capstone/      # 종합 예제

각 튜토리얼에서 파일 경로를 명시하므로, 그대로 따라 생성하면 됩니다.