대부분의 에이전트 코드는 간단하게 시작하지만 자체 재시도 때문에 무너집니다. LLM을 연결하고 도구를 제공하면 워크플로우가 루프를 돌거나, 분기하거나, 사람의 개입을 위해 일시 중지해야 하는 순간 직선형 스크립트는 와해됩니다. LangGraph는 바로 이러한 혼란을 위해 구축된 프레임워크입니다. LangGraph는 에이전트를 공유 상태를 가진 그래프로 모델링하여, 복잡한 if 문 대신 루프와 분기가 일급 구조가 됩니다. 이 가이드는 LangGraph가 무엇인지, 어떤 문제를 해결하는지, 그리고 에이전트가 실제 서비스를 호출할 때 API 테스트가 어떻게 적용되는지 설명합니다.
LangGraph란 무엇인가
LangGraph는 장기 실행되는 상태 저장 에이전트를 구축하기 위한 저수준 오케스트레이션 프레임워크이자 런타임입니다. LangChain 팀인 LangChain Inc에서 구축했지만, 고유한 초점을 가진 별도의 라이브러리입니다. pip install -U langgraph 명령어로 단독으로 설치할 수 있으며, LangChain 생태계의 나머지 부분 없이도 사용할 수 있습니다.
핵심 아이디어는 간단합니다. 에이전트를 그래프로 설명합니다. 노드는 작업을 수행하고(모델 호출, 도구 실행, 데이터 변환), 엣지는 다음에 무엇을 실행할지 결정합니다. 공유 상태 객체는 모든 노드를 통해 흐르며, 각 노드는 이를 읽고 다시 쓸 수 있습니다. 엣지는 뒤로 향할 수 있기 때문에 그래프는 순환할 수 있습니다. 이것이 일반적인 체인이 잘 처리하지 못하는 부분입니다.
LangChain의 이전 Chain 추상화를 사용해 봤다면, 차이점은 제어 흐름의 형태입니다. 체인은 파이프라인입니다: 1단계, 2단계, 3단계, 완료. 그래프는 노드가 현재 상태를 검사한 다음, 다른 분기로 이동하거나, 재시도를 위해 루프백하거나, 병렬로 실행되는 여러 노드로 분산하여 결과를 병합할 수 있도록 합니다. 실제 에이전트에는 이러한 기능이 필요합니다. 왜냐하면 "추론, 행동, 관찰, 다시 추론"은 선형적인 과정이 아니라 루프이기 때문입니다.
LangGraph가 해결하는 문제
에이전트 워크플로우는 본질적으로 순환적입니다. 에이전트는 도구를 호출하고, 결과를 확인한 다음, 작업이 완료되었는지 결정하고, 완료되지 않았다면 다시 시도합니다. 이를 중첩된 조건문으로 모델링하면 빠르게 읽기 어려워지며, 프로덕션 에이전트가 실제로 필요로 하는 기능을 추가하면 더욱 악화됩니다:
- 정지 조건이 있는 루프. 영원히 실행되지 않고 작업이 완료될 때까지 도구를 계속 호출합니다.
- 상태에 따른 분기. 모델이 반환한 내용에 따라 다른 노드로 라우팅합니다.
- 영속성. 충돌, 타임아웃 또는 재시작 후에도 마지막 정상 지점에서 다시 시작합니다.
- Human-in-the-loop (인간 개입). 일시 중지하고 사람이 상태를 검사하거나 편집한 다음 계속 진행합니다.
- 스트리밍. 토큰과 중간 단계를 완료 시점에만 내보내는 것이 아니라 발생하는 즉시 내보냅니다.
LangGraph는 이 모든 기능을 수동으로 구현하는 대신 내장 기능으로 제공합니다. 내구성 있는 실행을 지원하는 상태 머신을 얻으므로, 에이전트가 몇 분 또는 몇 시간 동안 실행되다가 중단된 지점부터 다시 시작할 수 있습니다.
핵심 개념: 그래프, 상태, 노드, 엣지
네 가지 기본 요소가 프레임워크의 대부분을 구성합니다. 다음은 이들이 어떻게 조화를 이루는지입니다.
상태(State)는 전체 실행에서 공유되는 유형 지정 객체입니다. 스키마(종종 TypedDict)를 사용하여 형태를 정의하며, LangGraph는 각 노드의 업데이트를 여기에 병합합니다. 일반적인 시작점은 실행 중인 채팅 메시지 목록을 담는 미리 구축된 스키마인 MessagesState입니다.
노드(Nodes)는 함수입니다. 각 노드는 현재 상태를 받아 부분 업데이트를 반환합니다. add_node()를 사용하여 등록합니다.
엣지(Edges)는 노드를 연결합니다. add_edge()를 사용하는 일반적인 엣지는 항상 A에서 B로 이동합니다. add_conditional_edges()를 사용하는 조건부 엣지는 상태를 읽고 다음 노드의 이름을 반환하는 라우팅 함수를 실행하는데, 이것이 "모델이 도구를 요청하면 실행하고, 그렇지 않으면 종료한다"와 같은 내용을 표현하는 방식입니다.
START와 END는 실행이 시작되고 멈추는 특별한 마커입니다.
다음은 최소한의 그래프 형태입니다. 의사 코드 수준이지만, API 이름은 실제입니다.
from langgraph.graph import StateGraph, START, END, MessagesState
def call_model(state: MessagesState):
response = model.invoke(state["messages"])
return {"messages": [response]}
def should_continue(state: MessagesState) -> str:
last = state["messages"][-1]
return "tools" if last.tool_calls else END
builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model") # 루프 백
graph = builder.compile()
add_edge("tools", "model") 라인이 바로 순환 부분입니다. 도구 실행 후 제어권은 모델로 돌아가며, 모델은 더 많은 도구를 호출하거나 멈출 수 있습니다. 이 루프가 LangGraph가 존재하는 전체 이유입니다.
영속성 및 human-in-the-loop (인간 개입)
체크포인터로 그래프를 컴파일하면 각 단계 후에 상태 스냅샷을 저장합니다. 설정에 thread_id를 전달하면 LangGraph는 다음 호출 시 해당 스레드의 최신 체크포인트를 복원합니다. 노드는 변경되지 않으며, 런타임이 저장 및 복원을 처리합니다.
from langgraph.checkpoint.memory import InMemorySaver
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)
InMemorySaver는 개발용으로는 충분합니다. 재시작 후에도 유지되는 기능을 위해 LangGraph는 데이터베이스 기반 저장소(단일 서버용 SQLite, 다중 인스턴스 스케일용 Postgres)를 제공합니다. 상태가 내구성을 가지므로, human-in-the-loop (인간 개입) 기능도 거의 무료로 얻을 수 있습니다. 선택한 지점에서 그래프를 중단하고, 사람이 현재 상태를 검사하거나 편집할 수 있도록 표시한 다음, 정확히 그 체크포인트부터 다시 시작할 수 있습니다. 승인 게이트, 수동 수정, "확실합니까?" 단계는 모두 이를 기반으로 합니다.
스트리밍 기능으로 완성됩니다. LangGraph는 실행이 진행됨에 따라 모델 토큰과 노드 수준 업데이트를 스트리밍할 수 있으므로, UI는 로딩 스피너만 보여주는 대신 에이전트가 생각하는 과정을 표시할 수 있습니다.
LangGraph와 LangChain의 관계
이 부분에서 사람들이 혼란스러워하므로, 직접적으로 설명하겠습니다. LangChain은 더 넓은 도구 키트입니다: 모델 래퍼, 프롬프트 템플릿, 검색기, 문서 로더, 그리고 수백 개의 제공업체와의 통합 기능입니다. LangGraph는 해당 도구 키트의 에이전트 부분 아래에 있는 오케스트레이션 레이어입니다.
LangGraph를 사용하기 위해 LangChain이 필요하지 않습니다. 상태, 노드, 엣지를 정의하고 노드 내에서 원하는 모델 클라이언트를 호출할 수 있습니다. LangChain의 모델 및 도구 추상화가 편리하고, LangGraph의 사전 빌드된 create_react_agent 헬퍼(langgraph.prebuilt에 있음)가 사용자 정의 그래프가 필요하지 않을 때 몇 줄의 코드로 작동하는 도구 호출 에이전트를 제공하기 때문에 많은 팀이 이 둘을 함께 사용합니다.
| LangChain | LangGraph | |
|---|---|---|
| 역할 | 구성 요소 및 통합 | 오케스트레이션 및 런타임 |
| 제어 흐름 | 선형 체인 | 순환 및 분기가 있는 그래프 |
| 내장 상태 | 제한적 | 공유, 유형 지정, 내구성 |
| 영속성 / 재개 | 주요 초점 아님 | 체크포인터 + 스레드 ID |
| 가장 적합한 용도 | 모델 호출 및 도구 구성 | 상태 저장, 다단계 에이전트 |
현재 사용자에게 드리는 한 가지 참고 사항: LangGraph v1.0 라인(2025년 말부터 안정화)은 사전 빌드된 에이전트 헬퍼를 langchain.agents.create_agent 쪽으로 이동시키고 있으므로, 이전 스니펫을 복사하기 전에 설치된 버전과 공식 참조 문서에서 정확한 임포트 경로를 확인하십시오. 여기서는 처음부터 사용자 정의 에이전트를 구축하는 것도 유용한 기술입니다. 더 넓은 관점에서 사용자 정의 AI 에이전트 구축에 대한 저희의 안내서를 참조하십시오.
LangGraph 플랫폼 및 스튜디오
오픈 소스 라이브러리가 핵심이지만, 일단 배포하고 나면 두 가지 인접한 제품이 중요합니다.
LangGraph Studio는 시각적 에이전트 IDE입니다. 그래프를 렌더링하고, 실행하며, 모든 노드의 상태를 보여주므로 노드와 엣지를 통해 실행 단계를 볼 수 있습니다. 순환과 조건부 라우팅이 있는 어떤 것이든, 에이전트가 실제로 취한 경로를 보는 것이 로그 라인을 읽는 것보다 훨씬 좋습니다.
LangGraph Platform은 관리형 배포 측면입니다: 에이전트를 위한 API 엔드포인트, 장기 실행을 위한 내장 영속성, 그리고 자체 호스팅부터 클라우드에서 완전히 관리되는 옵션까지 다양한 호스팅 옵션을 제공합니다. 이 라이브러리를 사용하기 위해 반드시 필요한 것은 아니지만, 직접 에이전트를 실행하는 대신 프로덕션 환경에서 에이전트를 위한 인프라를 원할 때 유용합니다.
LangGraph를 언제 사용해야 하는가
에이전트에 실제 제어 흐름이 있을 때 LangGraph를 활용하십시오. 좋은 지표는 다음과 같습니다:
- 작업이 순차적이지 않고 루프를 이룰 때 (도구 호출, 확인, 반복).
- 모델이 결정한 내용에 따라 분기해야 할 때.
- 실행 시간이 길 수 있으며, 충돌 후에도 복구하고 재개되기를 원할 때.
- 실행 도중 사람이 무언가를 승인하거나 편집해야 할 때.
- 상태를 공유하는 여러 액터 또는 하위 에이전트를 조정할 때.
단일 모델 호출이나 짧은 선형 체인으로 작업이 완료될 때는 사용하지 마십시오. "이 텍스트 요약"과 같은 작업에는 그래프가 불필요한 오버헤드입니다. 진정으로 분기하고 순환하는 워크플로우에 이 구조를 사용하십시오.
API 테스트 및 목업(Mocking)의 적용 지점
이것은 개발 팀을 괴롭히는 부분입니다. LangGraph 에이전트는 호출하는 API만큼만 신뢰할 수 있으며, LLM 엔드포인트와 모든 도구 API(검색, CRM, 자체 백엔드) 등 많은 API를 호출합니다. LangGraph는 이러한 호출을 오케스트레이션할 뿐, 테스트하지는 않습니다. 그것은 별개의 작업이며, 바로 Apidog가 필요한 부분입니다.
두 가지 문제가 빠르게 나타납니다. 첫째, 모든 테스트 실행에서 실제 API를 호출하면 토큰이 소모되고 속도 제한에 걸립니다. 에이전트가 의존하는 API를 목업(mock)하여 그래프 로직을 반복하는 동안 도구 엔드포인트가 확정적이고 즉각적인 응답을 반환하도록 할 수 있습니다. 동일한 방식으로 LLM 엔드포인트를 목업하면 라우팅 테스트를 위해 토큰 비용을 지불할 필요가 없습니다.
둘째, 노드는 응답 형태를 가정합니다. 도구의 API 필드 이름이 조용히 변경되면 조건부 엣지가 잘못된 것을 읽고 에이전트가 루프에 빠지거나 멈출 수 있습니다. API 단언(assertions)으로 이러한 계약을 명확히 하면, 변경 사항이 그래프에 도달하기 전에 감지할 수 있습니다. 그리고 에이전트가 스테이징 및 프로덕션 환경에서 키를 처리하기 때문에, 환경에서 관리하면 노드 코드에서 비밀이 노출되는 것을 방지할 수 있습니다. 완전한 에이전트 중심 워크플로우를 원한다면, AI 에이전트를 위한 Apidog 테스트 하네스가 처음부터 끝까지 안내합니다. 분명히 말하자면, 이 모든 것이 에이전트를 오케스트레이션하는 것은 아닙니다. Apidog는 에이전트 아래의 API를 테스트하고 목업합니다.
자주 묻는 질문
LangGraph가 LangChain을 대체하는가요? 아닙니다. LangGraph는 오케스트레이션 런타임이며, LangChain은 더 넓은 구성 요소 및 통합 집합입니다. 이들은 같은 팀의 별개의 라이브러리이며, LangChain 없이 LangGraph를 실행하거나 함께 사용할 수 있습니다. LangGraph는 일반적인 체인이 어려워하는 상태 저장, 순환적 제어 흐름을 처리합니다.
LangGraph를 시작하기 위해 LangChain을 알아야 하나요? 아닙니다. StateGraph를 정의하고, 노드와 엣지를 추가하고, 노드 내에서 원하는 모델 클라이언트를 호출할 수 있습니다. LangChain의 모델 래퍼는 편리하지만, 필수는 아닙니다. 핵심 그래프 기본 요소부터 시작하고 필요할 때만 나머지를 추가하십시오.
LangGraph는 호출 간에 어떻게 내용을 기억하나요? 체크포인터를 통해 기억합니다. 체크포인터로 그래프를 컴파일하고 thread_id를 전달하면, LangGraph는 각 단계 후에 상태 스냅샷을 저장한 다음, 해당 스레드의 다음 호출 시 이를 복원합니다. 이를 통해 노드 로직을 변경하지 않고도 대화 기억 및 충돌 복구를 얻을 수 있습니다.
에이전트가 호출하는 API를 어떻게 테스트하나요? 그래프와는 별도로 테스트하고 목업(mock)하세요. 개발 중에 실행이 빠르고 비용이 들지 않도록 LLM 및 도구 엔드포인트를 목업하고, 변경된 필드로 인해 노드가 고장 나지 않도록 응답 형태를 단언(assert)하세요. ChatGPT API 테스트에 대한 저희 가이드는 에이전트가 의존하는 정확한 부분인 인증, 스트리밍 및 도구 호출을 다룹니다.
요약
LangGraph는 루프를 돌고, 분기하고, 영속성을 가지며, 인간을 위해 일시 중지하는 에이전트에 필요한 누락된 구조를 제공합니다. 워크플로우를 공유 상태를 가진 그래프로 모델링하고, 메모리 및 복구를 위해 체크포인터에 의존하며, 디버그 및 배포 준비가 되면 Studio와 Platform을 사용하십시오. 프레임워크는 오케스트레이션을 처리합니다. 에이전트가 호출하는 API는 여전히 자체 안전망이 필요하므로, 개발 비용을 절감하고 도구 계약의 신뢰성을 유지하기 위해 Apidog에서 이를 목업하고 테스트하십시오. 에이전트가 실제 엔드포인트를 호출하기 전에 엔드포인트를 목업하고 응답을 단언하려면 Apidog를 다운로드하십시오.