LangChain 사용법, 에이전트 만드는 최소 구성부터

TL;DR

• LangChain 사용법의 중심은 create_agent 하나다. 모델, 도구, 시스템 프롬프트를 넘기면 에이전트가 만들어진다.
• LangChain, LangGraph, Deep Agents는 층이 다르다. 기능이 다 갖춰진 쪽부터 쓰려면 Deep Agents, 세밀하게 조립하려면 LangChain, 흐름을 직접 그리려면 LangGraph다.
• 프레임워크는 무료지만 추적·평가 도구인 LangSmith는 좌석당 과금이다. 무료 등급은 1인, 월 기본 트레이스 5,000건까지다.

LangChain 사용법을 처음 볼 때 헷갈리는 건 이름이 여러 개라는 점이다.
LangChain, LangGraph, LangSmith, Deep Agents가 같은 문서 안에 섞여 나온다.
정리하면 앞의 셋은 층이 다른 도구이고, LangSmith는 그 위에서 무슨 일이 벌어졌는지 보는 도구다.

공식 문서가 개념을 한 줄로 정리해뒀다.
에이전트는 모델에 하네스를 씌운 것이다.
하네스란 모델 호출 주위를 감싸는 모든 것을 뜻한다.
프롬프트, 도구, 그리고 동작을 다듬는 미들웨어.
LangChain이 제공하는 create_agent는 그 하네스를 최소한으로 만들어 놓고 필요한 만큼 붙이게 하는 함수다.
아래는 설치부터 첫 에이전트 실행, 그리고 어느 층을 골라야 하는지까지를 공식 문서 기준으로 정리한 것이다.

LangChain, LangGraph, Deep Agents가 나뉘는 층

공식 문서의 구분은 이렇다.

• Deep Agents: 필요한 것이 대부분 들어 있는 상위 패키지. 컨텍스트 자동 압축, 가상 파일 시스템, 하위 에이전트 생성 같은 기능이 기본으로 붙는다. LangChain 에이전트 위에 얹혀 있다.
• LangChain: create_agent로 하네스를 직접 조립하는 층. 자기 상황에 맞게 도구와 미들웨어를 고른다.
• LangGraph: 결정적 흐름과 에이전트적 판단을 섞어야 할 때 쓰는 하위 오케스트레이션 프레임워크. 노드와 엣지로 흐름을 그린다.

처음이라면 위에서 아래로 내려오는 순서가 낫다.
기본 구성으로 돌려보고, 통제가 더 필요해지면 한 층 내려간다.
반대로 처음부터 LangGraph로 시작하면 만들 것이 많아 진도가 나가지 않는다.

LangChain 사용법, 첫 에이전트까지

설치는 패키지 하나다.

uv add langchain

pip을 쓴다면 pip install -qU langchain "langchain[openai]" 형태로 모델 제공사 확장을 함께 지정한다.

모델만 호출해보는 최소 코드는 이렇다.

from langchain.chat_models import init_chat_model

model = init_chat_model("openai:gpt-5.5")
result = model.invoke("Hello, world!")

여기에 도구를 붙이면 에이전트가 된다.
공식 문서의 예제는 날씨 조회 함수를 도구로 넘긴다.

from langchain.agents import create_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.5",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

함수의 독스트링이 도구 설명으로 쓰인다는 점이 중요하다.
모델이 이 도구를 언제 부를지 판단하는 근거가 그 문장이라, 설명이 모호하면 도구를 안 부르거나 엉뚱한 때 부른다.

모델 문자열은 제공사:모델명 형식이다.
OpenAI, Anthropic, Google, OpenRouter, Fireworks, Baseten, Ollama, Azure, AWS Bedrock, Hugging Face를 지원한다.
Ollama가 목록에 있다는 건 로컬 모델로도 같은 코드가 돈다는 뜻이다.

도구를 설계할 때 지키면 좋은 것

에이전트 품질의 상당 부분이 도구 설계에서 갈린다.

이름과 설명을 사람이 읽는 문서처럼 쓴다. “get_user”보다 “이메일로 사용자 정보를 조회한다”가 낫다.
모델은 이 텍스트만 보고 판단한다.

인자를 좁게 잡는다.
자유 문자열 하나를 받는 도구는 모델이 무엇을 넣어야 할지 몰라 실패한다.
타입이 명확한 인자로 나누면 호출 정확도가 올라간다.

실패를 문자열로 돌려준다.
예외를 던져 프로세스를 죽이는 대신 “그런 사용자가 없습니다” 같은 문장을 돌려주면 모델이 다음 시도를 조정한다.

도구 개수를 줄인다.
스무 개를 주면 고르는 데서 실수가 늘어난다.
관련 없는 도구는 별도 하위 에이전트로 빼는 편이 낫다.

LangSmith와 추적, 그리고 요금

프레임워크 자체는 오픈소스다.
깃허브에 공개돼 있고 별이 14만 개를 넘겼다.
돈이 붙는 쪽은 LangSmith다.

종량 단위는 두 가지다.
작업과 연산에 붙는 LCU가 1개당 $1.50, 트레이스와 저장에 붙는 LSU가 1개당 $1.00이다.
배포 실행 자원도 LCU로 환산되는데, 런타임 연산은 vCPU-시간당 0.045 LCU, 메모리는 GiB-시간당 0.006 LCU로 표기돼 있다.

VC 투자를 받은 스타트업에는 최대 $10,000 크레딧을 주는 프로그램이 별도로 있다.

추적을 붙여야 하는 이유

에이전트는 실패해도 그럴듯한 답을 내놓는다.
그래서 로그 없이 개발하면 무엇이 잘못됐는지 알아내는 데 시간이 다 든다.

LangSmith를 붙이면 실행 하나가 단계별로 남는다.
어떤 프롬프트가 들어갔고, 어떤 도구를 어떤 인자로 불렀고, 무엇을 돌려받았는지가 순서대로 보인다.
이 기록을 데이터셋으로 바꿔 평가에 쓰는 흐름도 제품에 들어 있다.

최근에는 이 위에 자동 진단을 얹었다.
Engine이라는 기능이 프로덕션 트레이스를 지켜보다 반복되는 문제를 찾아 수정안을 제안한다.
별도로 LLM Gateway가 모델 호출과 지출, 민감 정보를 통제하는 층을 맡는다.

미들웨어로 동작을 다듬는 층

create_agent가 최소 하네스라는 말은 기본 상태로는 모델과 도구만 연결돼 있다는 뜻이다.
실제 서비스에 넣으려면 그 주변에 붙일 것이 생긴다.
공식 문서가 그 자리를 미들웨어라고 부른다.

붙이게 되는 것들은 대개 비슷하다.

• 대화가 길어질 때 앞부분을 요약해 컨텍스트를 줄이는 처리. 그대로 두면 토큰이 계속 늘어난다.
• 민감한 동작 앞에 사람의 승인을 받는 단계. 결제나 삭제처럼 되돌릴 수 없는 도구가 있으면 필요해진다.
• 도구 호출 실패를 처리하는 규칙. 몇 번까지 다시 시도할지, 실패를 모델에 어떻게 알릴지 정한다.
• 입력과 출력을 검사하는 층. 형식이 정해진 응답이 필요할 때 구조를 강제한다.

이 항목들을 직접 만들 것인지, 이미 갖춰진 상위 패키지를 쓸 것인지가 층을 고르는 실제 기준이 된다.
컨텍스트 압축과 하위 에이전트 생성 같은 기능이 기본으로 들어 있는 쪽을 고르면 이 작업이 줄어든다.

모델을 바꿔가며 비교할 때

모델 문자열 하나로 제공사를 바꿀 수 있다는 점은 비교 실험을 쉽게 만든다.
같은 도구와 프롬프트를 두고 모델만 바꿔 결과를 대조하는 구성이 가능하다.

주의할 점은 도구 호출 동작이 모델마다 다르다는 것이다.
어떤 모델은 도구를 적극적으로 부르고, 어떤 모델은 먼저 답부터 하려 한다.
같은 프롬프트가 모델을 바꾸면 다르게 작동하므로, 비교할 때는 결과물뿐 아니라 도구 호출 횟수와 실패 횟수도 함께 본다.

비용도 같은 방식으로 비교한다.
응답 품질이 조금 낮아도 호출 단가가 낮은 모델이 전체 작업에서는 유리한 경우가 있다.
실제 작업 샘플 스무 건 정도로 재보면 감이 아니라 숫자로 고를 수 있다.

한계와 안 맞는 경우

• 단순한 한 번의 모델 호출. 프롬프트 하나 보내고 답을 받는 작업에 프레임워크를 얹으면 층만 늘어난다.
• 추상화를 걷어내고 직접 통제하고 싶은 경우. 라이브러리가 감싸는 부분이 많아 동작을 추적하려면 내부를 봐야 하는 순간이 온다.
• 버전 변화가 부담스러운 환경. 생태계가 빠르게 움직여 API가 바뀌는 일이 있다. 버전을 고정하고 올릴 때 확인하는 습관이 필요하다.
• 화면으로 만들고 싶은 팀. 코드가 아니라 캔버스에서 조립하고 싶다면 Dify 사용법 쪽이 맞는다.

제품 만들 때 가져갈 설계

첫째는 층을 나눠 이름을 붙인 방식이다.
같은 문제를 세 가지 추상화 수준으로 제공하고, 각각을 언제 쓰는지 문서 첫머리에서 정리해준다.
사용자가 자기 상황을 먼저 판단하게 만드는 구조다.

둘째는 프레임워크는 열고 관측을 파는 구조다.
오픈소스로 채택을 늘리고, 프로덕션에서 필요해지는 추적과 평가를 유료로 붙인다.
개발자가 돈을 내는 시점이 도입 시점이 아니라 운영 시점이라는 점을 이용한 배치다.

셋째는 모델 지정을 문자열 하나로 줄인 것이다. openai:gpt-5.5처럼 제공사와 모델을 한 줄에 적게 하면, 모델을 갈아끼우는 비용이 한 줄 수정으로 떨어진다.

버전을 다루는 습관

생태계가 빠르게 움직이는 만큼 버전 관리에 신경 쓸 부분이 있다.
패키지 버전을 고정해두고, 올릴 때는 변경 사항을 확인한 뒤 적용하는 편이 안전하다.

특히 에이전트 구성 방식은 시간이 지나며 정리돼왔다.
오래된 예제 코드를 그대로 가져오면 지금 문서와 다른 함수를 쓰는 경우가 있으므로, 공식 문서의 현재 페이지를 기준으로 삼는 게 낫다.

의존성 범위도 좁게 잡는다.
모델 제공사별 확장을 필요한 것만 설치하면 설치 시간과 충돌 가능성이 함께 줄어든다.

실행 체크리스트

1. 만들려는 것이 단순 호출인지 도구를 쓰는 에이전트인지 먼저 판단합니다.
2. Deep Agents, LangChain, LangGraph 중 어느 층에서 시작할지 정합니다.
3. 패키지를 설치하고 모델 제공사 확장을 함께 지정합니다.
4. init_chat_model로 모델 호출부터 확인합니다.
5. 도구 함수를 만들고 독스트링에 언제 쓰는 도구인지 적습니다.
6. create_agent로 모델과 도구, 시스템 프롬프트를 묶습니다.
7. 도구 개수를 다섯 개 안팎으로 유지하고 인자 타입을 좁힙니다.
8. 추적을 붙여 실행 단계를 남깁니다. 무료 등급은 월 5,000 트레이스입니다.
9. 대표 입력을 정해 프롬프트 수정 전후를 같은 조건에서 비교합니다.

자주 묻는 질문

LangChain은 무료인가요

프레임워크는 오픈소스로 무료입니다.
추적과 평가 도구인 LangSmith는 무료 Developer 등급이 좌석 1개와 월 기본 트레이스 5,000건까지이고, 그 위는 좌석당 월 $39부터입니다.

LangChain과 LangGraph는 무엇이 다른가요

LangChain은 create_agent로 에이전트 하네스를 조립하는 층이고, LangGraph는 결정적 흐름과 에이전트적 판단을 섞어 흐름을 직접 설계하는 하위 프레임워크입니다.

어떤 모델을 쓸 수 있나요

OpenAI, Anthropic, Google, OpenRouter, Fireworks, Baseten, Ollama, Azure, AWS Bedrock, Hugging Face를 지원합니다.
모델은 제공사:모델명 형식 문자열로 지정합니다.

로컬 모델로도 돌아가나요

Ollama가 지원 목록에 있어 같은 코드로 로컬 모델을 쓸 수 있습니다.
로컬 실행 환경 구성은 별도로 준비해야 합니다.

참고한 곳

• LangChain 공식 홈
• LangChain overview 문서
• LangSmith Plans and Pricing
• langchain-ai/langchain GitHub