LangChain 시작하기 — 설치부터 첫 에이전트 빌드까지

2026년 현재 LangChain은 v0.3+ 체계로 안정화됐다. 핵심 패키지가 langchain-core, langchain-openai 등으로 분리되면서 설치 명령부터 구버전 튜토리얼과 달라졌다. 이 글은 파이썬(Python) 환경 세팅부터 LCEL(LangChain Expression Language, 체인을 선언형으로 조립하는 문법) 기반 첫 에이전트 실행까지 실제로 돌아가는 코드를 중심으로 정리했다. 2026년 6월 기준이다.

LangChain이 무엇인지, 왜 쓰는지

LangChain은 OpenAI, Anthropic, Google 등 여러 LLM(Large Language Model, 대규모 언어 모델)을 하나의 코드 구조로 연결해 주는 오픈소스 프레임워크다. 2022년 말 Harrison Chase가 처음 공개한 뒤 2026년 현재 GitHub 스타 10만 개를 넘겼다.

단순히 모델 API(Application Programming Interface, 프로그램끼리 데이터를 주고받는 약속된 창구)를 직접 호출하는 것과 달리, LangChain을 쓰면 검색 도구, 메모리, 외부 DB를 체인처럼 엮어서 “질문 → 웹 검색 → 답변 생성” 흐름을 코드 몇 줄로 구현할 수 있다. 재시도 로직, 프롬프트 관리, 출력 파싱 같은 공통 패턴을 라이브러리가 흡수해 준다. 2026년 기준 핵심 스택은 LCEL 체인 조립, LangGraph(그래프 구조 에이전트 설계), RAG(Retrieval-Augmented Generation, 외부 문서를 검색해 답변에 반영하는 방식) 세 가지다.

설치: pip 한 줄로 끝나지 않는 이유

예전 튜토리얼에는 pip install langchain 한 줄만 나온다. 그런데 v0.3 이후부터는 모델 제공사별 패키지가 분리됐다. OpenAI를 쓰려면 langchain-openai, Anthropic Claude를 쓰려면 langchain-anthropic을 따로 설치해야 한다. 이렇게 나눈 이유는 의존성 충돌을 줄이고, 쓰지 않는 제공사의 SDK(Software Development Kit, 특정 서비스를 쓰기 위한 도구 묶음)를 강제로 설치하지 않기 위해서다.

OpenAI 기반으로 시작하는 경우 아래 명령으로 필요한 패키지를 한 번에 설치한다.

pip install langchain langchain-openai langchain-community langgraph

패키지별 역할을 정리하면 다음과 같다.

Python 버전은 3.10 이상을 권장한다. 가상환경(venv 또는 conda)을 먼저 만들고 그 안에 설치하는 습관을 들여야 프로젝트마다 의존성이 꼬이지 않는다.

LCEL로 첫 체인 만들기

LCEL(LangChain Expression Language)은 파이프 연산자(|)로 체인 단계를 직렬 연결하는 문법이다. 프롬프트 → 모델 → 출력 파서를 이어 붙이면 된다. 구버전의 LLMChain보다 코드가 짧고 타입 힌트도 잘 통한다. 아래는 GPT-4o mini로 한국어 답변을 받아오는 최소 예시다.

from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

load_dotenv()  # .env 파일에서 OPENAI_API_KEY 로드

# 프롬프트 템플릿 정의
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant. Answer in Korean."),
    ("human", "{input}"),
])

# 모델 선택 (gpt-4o-mini: 비용 효율이 높은 소형 모델)
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# 파이프로 체인 연결: 프롬프트 | 모델 | 문자열 파서
chain = prompt | model | StrOutputParser()

# 실행
result = chain.invoke({"input": "LangChain을 한 줄로 설명해 줘."})
print(result)

ChatPromptTemplate은 시스템 역할과 사용자 입력을 분리 관리하는 프롬프트 객체, StrOutputParser()는 모델 응답에서 텍스트 문자열만 뽑는 파서(출력 변환기)다. 이 세 블록을 |로 이으면 체인이 완성된다.

도구를 쓰는 에이전트 빌드

단순 체인은 모델에게 질문하고 답을 받는 일방향 흐름이다. 에이전트(Agent)는 모델이 스스로 “어떤 도구를 언제 쓸지” 결정하게 만드는 구조다. “서울 날씨 알려줘”를 받으면 날씨 검색 도구를 호출하고 그 결과로 답변을 생성한다. 2026년 기준 권장 방식은 langgraph의 create_react_agent를 쓰는 것이다. 구버전 AgentExecutor는 여전히 동작하지만, 공식 문서는 LangGraph 기반으로 이전을 권장한다.

from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_community.tools.tavily_search import TavilySearchResults
from langgraph.prebuilt import create_react_agent

load_dotenv()

# 사용할 도구 목록 (Tavily: 실시간 웹 검색 도구)
tools = [TavilySearchResults(max_results=3)]

# 모델
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# ReAct 방식의 에이전트 생성
# ReAct = Reasoning + Acting: 생각하고 → 행동하고 → 결과 관찰을 반복
agent = create_react_agent(model, tools)

# 실행
response = agent.invoke({
    "messages": [("human", "2026년 LangChain 최신 버전이 뭐야?")]
})
print(response["messages"][-1].content)

Tavily 검색 도구를 쓰려면 pip install tavily-python을 추가로 설치하고 TAVILY_API_KEY 환경변수를 설정해야 한다. Tavily는 LLM 연동에 최적화된 웹 검색 API로, 무료 플랜에서 월 1,000건 호출을 제공한다.

자주 만나는 오류와 해결법

처음 실행할 때 마주치는 오류 세 가지와 해결법이다.

① openai.AuthenticationError — API 키가 없거나 잘못됐을 때 나온다. .env 파일에 OPENAI_API_KEY=sk-...를 넣고 load_dotenv()를 코드 상단에서 호출했는지 확인한다.

② ModuleNotFoundError: No module named ‘langchain_openai’ — langchain-openai를 빠뜨렸을 때 나온다. pip install langchain-openai로 추가 설치하면 된다.

③ pydantic.ValidationError — 프롬프트 템플릿 변수 이름과 invoke()에 넘기는 딕셔너리 키가 다를 때 발생한다. {input}으로 정의했다면 chain.invoke({"input": "..."})처럼 키를 정확히 맞춰야 한다.

LangSmith(LangChain 제공 디버깅, 추적 플랫폼)를 연동하면 체인 각 단계의 데이터 흐름을 시각적으로 확인할 수 있다. LANGCHAIN_TRACING_V2=true와 LANGCHAIN_API_KEY를 환경변수에 추가하면 자동으로 추적 로그가 쌓인다.

첫 에이전트 이후 확장 방향

에이전트가 돌아가면 세 방향으로 확장하게 된다. 첫째, 메모리다. 예시 코드는 대화 이력을 기억하지 못한다. LangGraph의 상태 관리를 추가하면 이전 대화를 이어받을 수 있다. 둘째, RAG(검색 보강 생성)다. 사내 문서를 벡터 DB(텍스트를 숫자로 변환해 유사도로 검색하는 저장소)에 넣어두고, 질문과 관련된 조각을 꺼내 프롬프트에 붙이는 방식이다. FAISS, Chroma 등을 langchain-community로 연결할 수 있다. 셋째, 멀티 에이전트다. 역할별로 분리된 에이전트들이 그래프 구조로 협력하는 LangGraph 설계로, 복잡한 다단계 태스크에 적합하다.

자주 묻는 질문 FAQ

Q1) LangChain과 LlamaIndex의 차이는 무엇인가요?

LangChain은 에이전트, 멀티 도구 체인, 대화 흐름 관리에 강점이 있고, LlamaIndex는 문서 인덱싱과 RAG 파이프라인 구축에 특화돼 있다. 두 라이브러리를 함께 쓰는 프로젝트도 많다. 에이전트 중심이라면 LangChain, 문서 검색 중심이라면 LlamaIndex가 더 간결하다.

Q2) OpenAI API 없이 로컬 모델로 LangChain을 쓸 수 있나요?

가능하다. Ollama를 로컬에 설치하고 langchain-community의 ChatOllama를 쓰면 인터넷 연결 없이 Llama, Mistral 같은 오픈소스 모델을 돌릴 수 있다. API 비용 없이 실험하고 싶을 때 유용하다.

Q3) LangGraph를 반드시 써야 하나요?

단순한 체인이나 단일 도구 에이전트라면 LangGraph 없이도 충분하다. 다만 에이전트가 루프를 돌거나(같은 도구를 여러 번 호출), 조건에 따라 다른 경로를 타야 한다면 LangGraph가 훨씬 다루기 편하다. 2026년 기준 공식 문서도 복잡한 에이전트에는 LangGraph 사용을 권장한다.

Q4) 비용이 걱정되는데 어떤 모델을 쓰면 좋나요?

gpt-4o-mini는 GPT-4o 대비 입력 토큰당 비용이 약 15분의 1 수준이고, 대부분의 정보 추출, 요약, 분류 태스크에서 충분한 성능을 낸다. 프로토타입 단계에서는 mini로 시작하고, 복잡한 추론이 필요한 경우에만 full 모델로 전환하는 방식을 권장한다.

Q5) Python이 아닌 JavaScript에서도 LangChain을 쓸 수 있나요?

LangChain.js가 공식적으로 제공된다. npm install langchain @langchain/openai로 설치하며, Python 버전과 거의 동일한 API 구조를 갖고 있다. Node.js 기반 서버나 Next.js 프로젝트에서 쓸 수 있다.