LangGraph 단계별 학습 예제

LangGraph 핵심 개념을 5단계로 익히는 예제. 로컬/사내 Qwen 또는 OpenAI gpt-4o-mini로 동작.

실행 가이드

1. 의존성 설치

pip install -r requirements.txt

가상환경 권장: python -m venv .venv && source .venv/bin/activate 후 설치.

2. 환경변수 설정

cp .env.example .env

.env를 열어 LLM_PROFILE을 고르고, 해당 프로파일 값만 채운다.

(A) 지금 바로 테스트 — OpenAI gpt-4o-mini

LLM_PROFILE=test
OPENAI_API_KEY=sk-...        # 본인 OpenAI 키
TEST_MODEL=gpt-4o-mini

(B) 회사 Qwen (사내 OpenAI 호환 엔드포인트)

LLM_PROFILE=endpoint
ENDPOINT_BASE_URL=http://사내주소:포트/v1
ENDPOINT_API_KEY=...
ENDPOINT_MODEL=qwen2.5-32b-instruct

코드는 그대로 두고 .env의 LLM_PROFILE만 바꾸면 test ↔ 회사 환경이 전환된다.

.env 대신 CLI 인자로 전달 (선택)

.env를 안 쓰고 실행할 때 파라미터로 바로 넘길 수 있다. CLI 인자 우선, 없으면 .env로 적용된다.

# test (OpenAI)
python step1_simple.py --profile test --model gpt-4o-mini --api-key sk-...

# 회사 Qwen
python step5_agent.py --profile endpoint --model qwen2.5-32b-instruct \
    --api-key KEY --base-url http://사내주소:포트/v1

사용 가능한 인자: --profile {test,endpoint}, --model, --api-key, --base-url (각 step에서 -h로 확인).

3. 단계별 실행

순서대로 하나씩 실행하며 개념을 쌓는다.

python step1_simple.py    # 단순 LLM 호출 (최소 그래프)
python step2_state.py     # 노드 간 State 전달 (요약->번역)
python step3_tool.py      # tool calling (calculator)
python step4_branch.py    # 조건부 분기 (라우팅)
python step5_agent.py     # ReAct 에이전트 루프 (도구 3개)

# gpt test
python3 step1_simple.py --profile test --model gpt-4o-mini --api-key {api-key}

# local llm (Ollama, OpenAI 호환 엔드포인트)
#   준비: ollama serve / ollama pull qwen2.5
python3 step1_simple.py --profile endpoint \
    --base-url http://localhost:11434/v1 \
    --api-key ollama \
    --model qwen2.5

# local llm (LM Studio)
#   준비: LM Studio에서 모델 로드 후 Local Server 시작
python3 step1_simple.py --profile endpoint \
    --base-url http://localhost:1234/v1 \
    --api-key lm-studio \
    --model {로드한-모델명}

로컬 LLM은 OpenAI 호환 엔드포인트라 endpoint 프로파일을 쓴다(--base-url 지정 필요). --api-key는 로컬 서버에선 보통 무시되지만 인자는 필요하므로 아무 값(ollama 등)이나 넣는다.

4. 기대 출력

단계	기대 출력
step1	LangGraph를 한 문장으로 설명하는 답변
step2	요약: ... / 번역: ... 두 줄
step3	3이랑 2를 합쳐줘 → 도구가 문자처럼 이어붙여 32 (덧셈 5 아님)
step4	계산 질문 → 계산 결과: 144, 일반 질문 → LLM 답변
step5	LLM이 LangGraph 출시일 판단 → release.txt에 랭그래프 출시일: YYYY-MM-DD 저장 → 읽어서 days_since로 경과일 계산 → 줄바꿔 랭그래프가 출시된지 N일 지남 덧붙임, (총 agent 호출 N회) 출력

모든 단계는 LLM 호출 전 보내는 메시지를 ===== [LLM 요청] LLM 호출 직전, 메시지 N개 ===== 형태로 로그에 출력한다(log_messages). 메시지 누적 개수와 AI의 도구 호출 요청(🔧 도구 호출 요청 -> ...)까지 보인다. step5 실행 후 notes/release.txt 파일이 생성된다. 파일 도구는 notes/ 폴더 안에서만 동작한다. step5는 LLM 지식(출시일)·도구(날짜 계산)·파일을 조합한 시나리오다. 출시일은 LLM 지식이라 정확하지 않을 수 있으나, 날짜 계산은 도구라 정확하다. step5는 도구를 그만 부르면 종료하며, 무한루프 방지를 위해 최대 MAX_STEPS(기본 8)회까지만 순환한다.

5. 테스트

LLM 없이 동작하는 로직(계산기 / 날짜계산 / 파일도구 경로제한 / 라우터)을 검증한다.

pytest -v

문제 해결

• [설정 오류] 환경변수 ... 가 필요합니다 → .env에 해당 프로파일 변수가 비어 있음.
• 알 수 없는 LLM_PROFILE → LLM_PROFILE은 test 또는 endpoint만 가능.
• 도구 호출(step3~5)이 동작 안 하면 → 모델이 function calling을 지원하는지 확인 (gpt-4o-mini, Qwen instruct 계열은 지원).

파일 구성

파일	역할
llm.py	LLM_PROFILE 기반 공용 LLM 생성 + 프롬프트 로그
step1_simple.py ~ step5_agent.py	단계별 예제 (각 단계가 쓰는 도구를 직접 들고 있음)
tests/	단위 테스트
docs.html	코드 설명 문서 (브라우저로 열기, 인터넷 불필요)

코드 설명 문서

docs.html을 브라우저로 열면 단계별 주요 코드 + 그래프 그림을 볼 수 있다.