Graph 모듈 — 실험적 기능 고지 및 책임 범위

이 문서는 euleragent graph 모듈을 사용하기 전에 반드시 읽어야 합니다. 실험적 기능의 특성과 사용자 책임 범위를 명확히 이해한 후 사용하십시오.

1. 실험적 기능 고지

euleragent graph 모듈은 현재 실험적(Experimental) 상태로 제공됩니다. 이는 다음을 의미합니다.

1.1 API 안정성

Graph 모듈의 CLI 명령(graph list, graph show, graph validate, graph compile)은 현재 버전에서 동작하지만, 마이너 버전 업데이트에서도 예고 없이 변경될 수 있습니다.
Graph YAML 스키마의 필드명, 구조, 동작 방식이 변경될 수 있습니다. 특히 state_schema, parallel_groups, interrupt_before/after 필드는 설계가 진행 중입니다.
euleragent graph compile이 생성하는 IR(Intermediate Representation) JSON 형식은 아직 안정화되지 않았습니다. 이 형식에 의존하는 외부 도구를 만들지 마십시오.

1.2 기능 완성도

현재 구현 상태 (2026-02-23 기준):
  graph list     ✓ 동작
  graph show     ✓ 동작
  graph validate ✓ 동작 (병렬 에러 코드 14개 포함)
  graph compile  ✓ 동작 (LangGraph StateGraph IR 생성)
  graph run      ⚠ 실험적 — 일부 시나리오에서 미검증
  병렬 실행      ⚠ 실험적 — 경쟁 상태 가능성 있음
  interrupt hooks ⚠ 실험적 — LangGraph 체크포인트 의존

1.3 하위 호환성

실험적 모듈은 하위 호환성을 보장하지 않습니다. 버전 업그레이드 시 Graph YAML 파일을 재검증하고 재컴파일하는 것을 권장합니다.

# 버전 업그레이드 후 반드시 재검증
euleragent graph validate your_graph.yaml
euleragent graph compile your_graph.yaml --out compiled.json

2. 개발자 책임 원칙

2.1 병렬 실행의 비결정론적 특성

parallel_groups를 사용한 병렬 팬아웃/팬인은 본질적으로 비결정론적 실행을 포함합니다.

브랜치 A ──→ ┐
브랜치 B ──→ ┤ 조인 노드
브랜치 C ──→ ┘

위 구조에서 브랜치 A, B, C의 완료 순서는 보장되지 않습니다. 각 브랜치가 LangGraph 내부에서 독립적으로 실행되므로, 네트워크 지연, LLM 응답 속도, 시스템 부하에 따라 순서가 달라질 수 있습니다.

사용자 책임 사항: - 순서에 의존하는 로직을 병렬 브랜치에 넣지 말 것 - last_write 리듀서를 다수의 브랜치가 동일 키에 사용하지 말 것 (비결정론적 결과) - 병렬 실행 결과를 프로덕션에 사용하기 전에 충분한 반복 테스트를 수행할 것

2.2 경쟁 상태 (Race Condition)

LangGraph StateGraph는 공유 상태를 사용합니다. state_schema에 리듀서를 올바르게 선언하지 않으면 INVALID_CONCURRENT_GRAPH_UPDATE 예외가 발생하거나, 데이터 손실이 일어날 수 있습니다.

# 잘못된 예 — last_write는 여러 브랜치가 동시에 쓰면 결과가 비결정론적
state_schema:
  findings:
    type: list
    merge: last_write   # 위험! 브랜치 완료 순서에 따라 결과 달라짐

# 올바른 예 — append_list는 결정론적으로 모든 결과를 수집
state_schema:
  findings:
    type: list
    merge: append_list  # 안전: 모든 브랜치 결과가 리스트에 추가됨

2.3 부작용(Side Effect) 금지

병렬 브랜치 내에서 다음 도구는 사용이 금지됩니다.

금지 도구	이유	에러 코드
`shell.exec`	병렬 셸 실행으로 파일 시스템 충돌 위험	`PARALLEL_SIDE_EFFECT_FORBIDDEN`
`file.write`	동일 파일 동시 쓰기로 데이터 손상 위험	`PARALLEL_SIDE_EFFECT_FORBIDDEN`

이 제약은 graph validate로 강제됩니다. 병렬 브랜치에서 파일 쓰기가 필요하다면 조인 노드 이후에 수행하십시오.

2.4 감사(Audit) 책임

euleragent는 모든 실행에 대해 감사 로그(input.json, messages.jsonl, tool_calls.jsonl, approvals.jsonl)를 생성합니다. 그러나 병렬 실행 환경에서 이 로그의 순서가 인터리빙될 수 있습니다. 로그를 분석할 때 타임스탬프를 기준으로 정렬하여 해석하십시오.

3. LangGraph 버전 의존성

Graph 모듈은 LangGraph 1.0.9 이상이 필요합니다. 이보다 낮은 버전에서는 StateGraph API가 다르게 동작하여 컴파일 실패 또는 실행 오류가 발생합니다.

3.1 버전 확인 방법

pip show langgraph | grep Version
# 출력 예: Version: 1.0.9

3.2 버전별 차이

항목	LangGraph 0.x	LangGraph 1.0.x
StateGraph 생성	`StateGraph(state_schema)`	`StateGraph(TypedDict)`
리듀서 선언	별도 메서드	`Annotated` 타입 어노테이션
interrupt 지원	미지원	`interrupt_before/after` 파라미터
체크포인트	실험적	안정화

3.3 euleragent와 LangGraph 버전 매핑

# euleragent가 요구하는 LangGraph 버전 확인
pip show euleragent | grep -A 20 "Requires"

# 또는 pyproject.toml / setup.cfg 확인
cat pyproject.toml | grep langgraph

3.4 LANGGRAPH_COMPILE_FAILED 에러

Graph YAML은 유효하지만 LangGraph 버전 불일치로 컴파일이 실패할 경우 LANGGRAPH_COMPILE_FAILED 에러가 발생합니다. 이 에러는 Graph YAML의 문제가 아니라 환경 설정 문제이므로 LangGraph 버전을 먼저 확인하십시오.

# 에러 발생 시 진단 순서
euleragent doctor            # 전체 환경 진단
pip show langgraph           # LangGraph 버전 확인
pip install "langgraph>=1.0.9"  # 필요 시 업그레이드
euleragent graph compile your_graph.yaml  # 재시도

4. 권장 사용 시나리오

4.1 적합한 사용 시나리오

다음 상황에서 euleragent graph 모듈을 자유롭게 사용하십시오.

시나리오	설명
연구 프로젝트	병렬 데이터 수집, 복수 LLM 관점 비교
개발 환경	새로운 워크플로우 프로토타이핑
내부 도구	팀 내부 자동화 (충분한 테스트 후)
교육 목적	LangGraph StateGraph 학습
배치 처리	결과가 누락돼도 재실행 가능한 작업

4.2 주의가 필요한 시나리오

다음 상황에서는 충분한 검증 후 사용하십시오.

시나리오	주의 사항
프로덕션 API	충분한 스테이징 테스트 필수
금융/결제 워크플로우	순차 실행(Pattern)을 우선 고려
법적 효력 있는 문서 생성	결과 품질 사람이 직접 검토 필수
외부 서비스 연동	멱등성(idempotency) 보장 확인

4.3 부적합한 시나리오

다음 상황에서는 euleragent graph 대신 euleragent pattern을 사용하십시오.

재현 가능성이 절대적으로 필요한 경우 (법적 감사 등)
병렬 실행이 실제로 필요하지 않은 단순 순차 작업
LangGraph 없이 실행해야 하는 환경

5. 안전한 사용 방법

5.1 사전 검증 필수

Graph YAML을 실행하기 전에 반드시 graph validate를 먼저 실행하십시오.

# 단계 1: 유효성 검사
euleragent graph validate my_graph.yaml

# 단계 2: JSON 형식으로 상세 검사
euleragent graph validate my_graph.yaml --format json | python -m json.tool

# 단계 3: 컴파일 확인
euleragent graph compile my_graph.yaml --out compiled.json

# 단계 4: 컴파일 결과 검토
cat compiled.json | python -m json.tool | head -50

5.2 병렬 브랜치 수 최소화

병렬 브랜치 수가 증가할수록 디버깅 난이도와 비결정론적 위험이 증가합니다.

권장: 2~3개 브랜치
주의: 4~6개 브랜치 (충분한 테스트 필요)
위험: 7~8개 브랜치 (정말 필요한지 재검토)
제한: 8개 초과 불가 (PARALLEL_BRANCH_LIMIT_EXCEEDED 에러)

5.3 상태 스키마 신중 설계

state_schema는 병렬 실행의 안전성을 결정하는 핵심 요소입니다.

# 권장 설계 패턴
state_schema:
  # 여러 브랜치가 결과를 수집할 때 → append_list
  findings:
    type: list
    merge: append_list

  # 여러 브랜치가 숫자를 합산할 때 → sum_int
  result_count:
    type: integer
    merge: sum_int

  # 하나의 브랜치만 쓸 때 → last_write (단일 브랜치만)
  summary:
    type: string
    merge: last_write

  # 두 브랜치가 같은 string key를 쓰면 → concat_str 고려
  combined_text:
    type: string
    merge: concat_str

5.4 단계적 도입

처음 Graph 모듈을 도입할 때는 다음 순서로 점진적으로 확장하십시오.

1단계: 선형 그래프 (parallel_groups 없음)
   → Pattern과 동일하게 동작, LangGraph 통합만 추가
2단계: 2-브랜치 병렬 (단순한 상태 스키마)
   → 기본 팬아웃/팬인 검증
3단계: interrupt hooks 추가
   → 중요 노드에서 일시 정지, 상태 검사
4단계: 3+ 브랜치, 복잡한 상태 (충분한 테스트 후)

6. 지원 범위

6.1 커뮤니티 지원

euleragent graph 모듈은 커뮤니티 기여를 환영합니다.

버그 리포트: GitHub Issues에 다음 정보와 함께 제출
euleragent 버전 (euleragent --version)
LangGraph 버전 (pip show langgraph)
문제가 발생한 Graph YAML (민감 정보 제거 후)
euleragent graph validate --format json 출력
오류 메시지 전체
기능 요청: GitHub Issues에 enhancement 레이블로 제출
Pull Request: 기여 가이드라인(CONTRIBUTING.md) 참조

6.2 지원하지 않는 항목

다음 사항은 현재 지원 범위 밖입니다.

실험적 기능으로 인한 프로덕션 장애에 대한 보상
LangGraph 버전 0.x와의 호환성
Graph 모듈 내 graph run 명령의 완전한 안정성 보장 (현재 실험적)
중첩 parallel_groups (flat 구조만 지원)

6.3 이슈 제출 템플릿

## 환경
- euleragent 버전:
- LangGraph 버전:
- Python 버전:
- OS:

## 문제 설명

## 재현 방법
1.
2.
3.

## 예상 동작

## 실제 동작

## Graph YAML (민감 정보 제거)
```yaml
...

에러 메시지

...

```

요약: 핵심 원칙 5가지

먼저 validate — graph validate를 실행하지 않은 Graph YAML은 실행하지 마십시오.
리듀서 설계 신중히 — 병렬 브랜치가 공유하는 모든 state key는 append_list 또는 sum_int를 우선 검토하십시오.
부작용 금지 — 병렬 브랜치에서 file.write, shell.exec을 사용하지 마십시오.
브랜치 수 최소화 — 2~3개 브랜치로 시작하고, 꼭 필요한 경우에만 늘리십시오.
결과 항상 검증 — 병렬 실행 결과는 비결정론적일 수 있으므로, 최종 결과물을 사람이 직접 검토하는 단계를 워크플로우에 포함시키십시오.

다음 튜토리얼: 01_concepts.md — Graph vs Pattern: 무엇이 다른가?