이 저장소는 고급 Jupyter 노트북 컬렉션을 통해 LangGraph 학습 여정을 이어갑니다. 동적 도구 로딩 (dynamic tool loading), 장기 메모리 관리 (long-term memory management), 인간 참여형 제어 (human-in-the-loop control), 그리고 병렬 실행 (parallel execution)을 포함한 실제 에이전트 아키텍처에 초점을 맞춥니다. 이미 기초를 파악한 개발자들을 위해 설계된 이 시리즈는 LangGraph 및 LangChain을 사용하여 확장 가능하고 프로덕션 준비가 된 (production-ready) AI 워크플로우를 구축하는 데 도움을 줍니다.

git clone git@github.com:esurovtsev/langgraph-advanced.git
cd langgraph-advanced

의존성을 관리하기 위해 가상 환경 (virtual environment)을 사용하는 것을 권장합니다:

python3 -m venv .venv
source .venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

• 순서대로 레슨을 따라가세요 (스크립트 또는 노트북).
• 각 레슨에는 동반되는 비디오 튜토리얼이 제공됩니다.
• 설명과 코드 주석이 각 개념을 이해하는 데 도움을 줄 것입니다.

각 레슨에는 전용 비디오 튜토리얼이 제공됩니다. 링크는 레슨이 공개됨에 따라 제공될 예정입니다.

사전 구축된 에이전트 (Prebuilt Agents)(01_prebuilt-agents.ipynb)- LangGraph 내 사전 구축된 에이전트의 아키텍처와 워크플로우에 대한 심층 분석

• ReAct 에이전트 패턴 설명: 행동(act), 관찰(observe), 추론(reason), 그리고 이러한 단계들이 어떻게 에이전트 로직의 중추를 형성하는지 설명

• 저수준 API (low-level APIs)를 사용하여 LLM에 도구를 정의하고 바인딩하는 방법을 시연하며, 주식 심볼 조회 및 금융 데이터 검색과 같은 실질적인 예시를 포함

• 시스템 및 도구 노드, 라우팅 (routing), 메모리 관리를 포함하여 에이전트 실행을 위한 상태 그래프 (state graph) 구축 과정을 안내

• 실제 시나리오: 기업(예: Tesla)의 금융 데이터를 가져오고 분석하는 에이전트를 구축하여, 전체 추론 및 도구 호출 루프를 보여줌

• LangGraph Advanced – 사전 구축된 에이전트와 메모리를 사용하여 AI 에이전트 구축

Dynamic Models & Prompt Customization (동적 모델 및 프롬프트 커스터마이징) (02_dynamic-models-prompts.ipynb)

• 동적 모델 선택 및 역할 전환을 통해 적응형 AI 에이전트를 생성하는 고급 기술

• 작업 복잡도에 따라 서로 다른 LLM을 선택하는 문맥 인식 모델 선택 (예: 분석에는 GPT-4, 요약에는 GPT-4o-mini 사용) 구현

• 사용자 질의에 대응하여 에이전트의 역할과 행동을 조정하는 동적 프롬프트 수정자 (Prompt Modifiers) 생성

• 두 기술을 결합하여 금융 상담가, 교사 또는 요약가 역할 사이를 전환할 수 있는 정교한 에이전트 구축

• 실제 사례: 질의 복잡도에 따라 기반 모델과 페르소나를 모두 조정하는 금융 분석 에이전트 구축

• LangGraph Advanced – 동적 모델 선택 및 역할 전환을 통한 AI 에이전트 구축

Structured Output with Prebuilt Agents (사전 구축된 에이전트를 활용한 구조화된 출력) (03_structured_output_with_prebuilt_agents.ipynb)

• 단순 채팅 텍스트가 아닌 기계 판독 가능한 결과가 필요한 프로덕션 앱에서 구조화된 출력 (Structured Output)이 중요한 이유

• Pydantic 스키마 (예: FinancialInfo)를 정의하고 이를 create_react_agent (v2)의 response_format을 통해 전달

• 구조화된 응답을 생성하기 위해 추가된 그래프 단계(graph step)를 이해하고 에이전트 상태 (Agent State)에서 이에 접근하는 방법

• 트레이드오프 (Trade-offs): 추가적인 LLM 호출 비용 발생; 대안으로는 스키마를 도구 (Tool)로 취급하거나, 추가 호출 없이 JSON을 캡처하기 위해 커스텀 상태를 사용하는 포스트 모델 훅 (Post-model hook) 활용

• 실제 사례: company_name, stock_symbol, current_price, market_cap, summary, risk_assessment와 같은 JSON 필드를 생성하는 TSLA 분석

• LangGraph Advanced – 사전 구축된 LangGraph API를 사용하여 AI 에이전트에서 구조화된 출력 생성

Human-in-the-Loop Interruption with Prebuilt Agents (사전 구축된 에이전트를 활용한 Human-in-the-Loop 중단) (04_prebuilt_hitl_dynamic_interrupt.ipynb)

• 위험한 작업 (예: 시장가/지정가 주문 실행)에 대해 언제, 왜 인간의 승인을 추가해야 하는가
• 두 가지 접근 방식:
  • 정적 (Static): interrupt_before=["tools"]를 사용하여 도구 노드 실행 전에 항상 일시 중지 (단순하지만 입도가 거침)
  • 동적 (Dynamic): post_model_hook 내부에서 interrupt(...)를 발생시킴

LLM이 위험한 도구 호출 (tool call)을 제안할 때

• 정적 (Static):

• 구현 세부 사항:

  • RISK_TOOLS = {"place_order"}를 유지
  • 마지막 AIMessage.tool_calls를 검사
  • 체크포인터 (예: InMemorySaver)를 활성화하고 thread_id를 전달하여 실행을 일시 중지 및 재개할 수 있도록 함
  • 응답에서 중단 페이로드 (interruption payload)를 읽어 승인 UI를 렌더링한 후, 결정 사항을 담은 Command(...)로 재개

• 유지 사항:

• 재개 경로:

  • 승인 (Approve): 도구를 정상적으로 실행하도록 진행
  • 거절 (Decline): “Action cancelled by human”과 같은 ToolMessage를 주입하고 도구를 실행하지 않은 채 에이전트 흐름을 계속 진행

• 실제 사례: 승인/거절 흐름을 통한 TSLA 주식 매수 과정을 엔드 투 엔드 (end-to-end)로 시연

• LangGraph Advanced – 사전 구축된 AI 에이전트에서 동적 Human in the Loop 중단 사용하기

Supervisor 아키텍처를 활용한 멀티 에이전트 시스템 (Multi-Agent Systems with Supervisor Architecture) (05_multi_agent_supervisor.ipynb)

• 전문화된 워커 (worker)들 사이에서 작업을 위임하는 Supervisor 주도형 멀티 에이전트 시스템 구축

• 짧은 근거와 함께 하나의 기업을 선정하는 research_agent (Tavily + Wikipedia) 정의

• 예산 범위 내에서 거래를 실행하는 trading_agent (티커 조회, yfinance를 통한 시장 데이터, 주문 배치) 정의

• create_supervisor를 사용하여 라우팅 (routing), 핸드오프 (handoff), 가드레일 (guardrails)을 오케스트레이션하고, 그래프를 확인 및 분석 (xray)

• current_timestamp 도구를 통해 공유된 시간 컨텍스트를 설정하고, 최신성을 위해 한 줄짜리 “NOW” 노트를 게시

• 라우팅 규칙: 주제가 모호한 경우 → 연구 (research); 명확한 기업 + 작업/예산 → 거래 (trading); 핵심 세부 정보가 누락된 경우 한 번 질문

• 핸드오프 (Handoff): 연구에서 선택된 기업을 거래로 전달; 데이터 조작 방지; 위임된 단계와 결과 요약

• 실제 흐름: AI/재생 에너지에 $1,000 투자 — 연구 에이전트가 기업을 선정하면, 거래 에이전트가 주문 규모를 결정하고 매수 주문을 실행

• LangGraph Advanced – Supervisor 아키텍처를 활용한 멀티 에이전트 AI 시스템 구축

• 멀티 에이전트 시스템에서의 Supervisor + Human-in-the-Loop (HITL) (06_supervisor_with_hitl.ipynb)

  • Supervisor 주도의 위임(delegation)과 자식 에이전트(예: trading_agent) 내부의 HITL 승인을 결합합니다.

  • 체크포인터(checkpointer)가 부모에 의해 소유된 경우, 자식 에이전트의 중단(interruption)은 Supervisor로 전달됩니다. 동일한 thread_id를 사용하여 (자식이 아닌) Supervisor를 호출함으로써 실행을 재개합니다.

  • 구현: trading_agent는 post_model_hook (halt_on_risky_tools)을 사용하여 RISKY_TOOLS = {"place_order"}를 감지하고 interrupt({"awaiting": name, "args": {...}})를 호출합니다.

  • 거절 시, “Cancelled by human…”과 같은 ToolMessage를 주입하고 도구를 실행하지 않은 채 계획을 계속합니다.

  • Supervisor는 InMemorySaver() (.compile(checkpointer=...)) 및 output_mode="full_history"로 컴파일되며, xray를 통해 라우팅을 시각화합니다.

  • Supervisor와만 상호작용합니다. 재개하려면 Command(resume={"approved": True|False})와 안정적인 configurable.thread_id를 사용합니다.

  • response["__interrupt__"]를 검사하여 승인 UI를 렌더링하며, 헬퍼 함수인 print_tool_approval(...)은 도구와 매개변수를 보여줍니다.

  • 공유 시간 컨텍스트: current_timestamp를 한 번 호출하고, 에이전트 간의 최신성 유지를 위해 스레드에 한 줄의 "NOW" 노트를 게시합니다.

  • 테스트 흐름: 승인 경로, 거절 경로, 요청 업데이트(예: "NVIDIA 주식 3주만 매수")를 테스트하고 동일한 스레드 내에서 계속 진행합니다.

  • 실제 흐름: 주문 실행 전 승인 게이트를 거쳐 $1,000를 투자합니다. Supervisor는 리서치 → 트레이딩을 조정하고 일시 중지/재개를 처리합니다.

  • LangGraph Advanced – 멀티 에이전트 AI 시스템에서 Supervisor 아키텍처와 Human-in-the-Loop을 결합합니다.

  • Supervisor 주도의 위임과 자식 에이전트 내부의 HITL 승인을 결합합니다 (예:

• Supervisor 아키텍처를 사용하여 멀티 에이전트 AI 시스템에 장기 메모리 추가하기 (07_supervisor_long_term_memory.ipynb)

  • 사용자별 주문 내역을 위해 Supervisor와 자식 에이전트 전반에 걸쳐 InMemoryStore를 사용하여 지속성 메모리(persistent memory)를 통합합니다.
  • 메모리 도구 정의: get_order_history (user_id별 과거 주문 조회)

namespace) 및 add_order_to_history (심볼, 주식 수, 가격을 포함한 새로운 거래 기록).

• Research agent (리서치 에이전트): web_search 및 wiki_search 도구를 사용하여 공개적으로 거래 가능한 단 하나의 기업을 추천하며, "CHOSEN_COMPANY: "로 종료합니다.

• Portfolio agent (포트폴리오 에이전트): lookup_stock_symbol, fetch_stock_data_raw, place_order를 사용하여 추천된 정확한 기업에 대한 거래를 실행하고, add_order_to_history를 통해 기록합니다.

• Supervisor (슈퍼바이저): 리서치(아이디어 도출용) 또는 포트폴리오(실행용)로 작업을 위임합니다. get_global_store()를 통한 공유 저장소와 current_timestamp로부터의 시간적 컨텍스트 (temporal context)를 사용합니다.

• User isolation (사용자 격리): 메모리 접근을 위해 user_id namespace를 사용합니다. 사용자의 저장소에 접근하려면 get_user_store()를 사용합니다.

• Real-world flow (실제 워크플로우): EV 또는 AI 산업에 $1,000를 투자합니다. 리서치 에이전트가 기업을 선정하면, 포트폴리오 에이전트가 거래를 수행하고 기록합니다. 이후 메모리를 사용하여 "내가 몇 주를 보유하고 있는가?"라고 질문합니다.

• LangGraph Advanced – Supervisor 아키텍처를 활용한 멀티 에이전트 AI 시스템에 장기 메모리 (Long Term Memory) 추가하기

• 다음을 사용하여 지속성 메모리 (persistent memory)를 통합합니다.

• Supervisor 아키텍처에서의 커스텀 핸드오프 (Custom Handoffs in Supervisor Architecture) (08_supervisor_custom_handoff.ipynb)

  • 타겟팅된 위임 (targeted delegation) 및 공유 컨텍스트를 통해 작업 추론 (task reasoning) 능력을 향상시킵니다.
  • 명시적인 task_instructions를 전달하고 Command(goto=...)를 통해 제어 흐름을 라우팅하기 위해 create_task_instructions_handoff_tool(...)을 사용하여 커스텀 핸드오프 도구를 정의합니다.
  • 핸드오프 과정에서 task_instructions를 전달할 수 있도록 TaskState(AgentState)로 에이전트 상태 (agent state)를 확장합니다. 에이전트 및 슈퍼바이저를 컴파일할 때 state_schema=TaskState를 사용합니다.
  • 도구 내부에서 현재 상태에 접근하고, 엑스레이 트레이싱 (xray tracing)을 위한 핸드오프 메타데이터 (METADATA_KEY_HANDOFF_DESTINATION)가 포함된 ToolMessage를 발행하기 위해 InjectedState 및 InjectedToolCallId를 사용합니다.
  • 슈퍼바이저 도구에는 current_timestamp, get_order_history, 그리고 두 개의 핸드오프 도구 (portfolio 및 research로의 핸드오프)가 포함됩니다.

) 정밀한 하위 작업(sub-tasks)을 안내합니다 - Portfolio 및 research 에이전트는 이전 도구들(lookup, yfinance를 통한 market data, search)을 재사용하는 반면, supervisor는 가격을 가져올지 또는 메모리를 조회할지를 조율(orchestrate)합니다.

• 데모: "내 투자 성과가 어때?" → supervisor가 주문 내역(order history)을 검색하고, 현재 가격을 가져오도록 portfolio 에이전트에게 위임한 후, 성과를 요약합니다.

• 라우팅(routing)과 핸드오프(handoffs)를 시각화하기 위해 InMemorySaver() 및 output_mode="full_history"로 컴파일합니다. - LangGraph Advanced – Supervisor 아키텍처에서 커스텀 핸드오프를 사용하여 멀티 에이전트 AI 시스템 개선하기

계층적 멀티 레벨 Supervisor 아키텍처 및 Swarm AI 에이전트 구축(09_supervisor_hierarchy_and_swarm.ipynb)

• supervisor가 다른 supervisor를 제어하는 계층적 멀티 레벨 supervisor 아키텍처를 생성합니다.

• 전문화된 에이전트들을 하위 supervisor로 추출합니다: portfolio_supervisor (symbol_lookup, market_data, order_execution, record_keeping) 및 research_supervisor (web_search, wiki_search).

• 엔드 투 엔드(end-to-end) 워크플로우를 위해 research_supervisor, portfolio_supervisor, timestamp, history 에이전트를 조율하는 super_supervisor를 구축합니다.

• 계층 구조 없이 에이전트 간의 병렬 핸드오프(예: web_search ↔ market_data)를 위해 create_swarm()을 사용하여 swarm AI 에이전트를 구현합니다. - 라우팅(routing)과 핸드오프(handoffs)를 시각화하기 위해 InMemorySaver() 및 output_mode="full_history"로 컴파일합니다.

Supervisor 아키텍처를 통해 하위 에이전트를 도구(Tools)로 변환하여 멀티 에이전트 AI 시스템 단순화하기(10_supervisor_as_tools.ipynb)

• 하위 에이전트들이 메시지 리스트를 공유하는 대신 도구(tools)로 변환되는 대안적인 supervisor 아키텍처입니다.
• RunnableConfig를 사용하여 하위 에이전트의 격리된 실행을 호출하고, 작업을 전달하며, 마지막 AIMessage 응답을 반환하는 research_agent_tool 및 trading_agent_tool과 같은 @tool 함수를 정의합니다. - Supervisor는 current_timestamp, research_agent_tool, trading_agent_tool을 포함하는 도구들을 가진 단일 create_react_agent입니다.

; 제어 하에 있는 하위 에이전트(sub-agents)가 없음. - 장점: 격리된 실행 (메시지 혼선 없음), 더 쉬운 병렬화 (parallelism), 명확한 작업 정의.

• 전통적인 메시지 공유 방식 감독자(shared-message supervisors)의 단점: 긴 스레드가 에이전트를 혼란스럽게 함, 병렬화가 어려움, 상태 공유 (state sharing) 문제.
• 데모: AI 기업에 $1,000 투자 → 감독자가 연구 도구(research tool) 호출 (격리됨: web_search/wiki_search → MSFT 추천) → 거래 도구(trading tool) 호출 (격리됨: lookup/fetch/place → 주문 실행) → 요약.
• LangGraph Advanced – 감독자 아키텍처(Supervisor Architecture)를 통해 하위 에이전트를 도구로 변환하여 멀티 에이전트 AI 시스템 단순화하기

바닥부터 커스텀 감독자 구축하기(11_supervisor_from_scratch.ipynb)

• 두 가지 방식으로 감독자 구현: 상위 수준 API (high-level API) 및 하위 수준 LangGraph 프리미티브 (low-level LangGraph primitives).
• 상위 수준: research 및 portfolio 에이전트와 함께 create_supervisor(...)를 사용하고, current_timestamp, get_order_history 도구를 추가하며, InMemorySaver 및 output_mode="full_history"로 컴파일합니다.
• 하위 수준: StateGraph(MessagesState)를 사용하여 커스텀 그래프를 구축하고, 명시적인 START → supervisor 엣지(edge)를 설정하며, research / portfolio에서 supervisor로 돌아오는 리턴 엣지(return edges)와 목적지 ("research", "portfolio", END)를 지정합니다.