LangChain 빠른 시작

LangChain 빠른 시작 (Quickstart)

이 퀵스타트는 몇 분 안에 완전히 동작하는 AI 에이전트를 만들어 보는 가이드예요. 도구를 호출하고 질문에 답하는 기본 에이전트를 바닥부터 구성하면서, LangChain의 설치부터 모델 연동, 실행, 추적(tracing)까지 한 번에 익힐 수 있어요.

에이전트를 처음 만들어 보는 분이라면 이 순서 그대로 따라 하면 돼요. 설치 → API 키 설정 → 기본 에이전트 구현 → 실행 확인 → LangSmith 추적 순서예요.

출처: LangChain Quickstart 공식 문서

1. 의존성 설치하기

먼저 langchain 패키지를 설치해요. uv나 pip, 또는 venv 방식 모두 가능해요.

# pip 방식
pip install -U langchain

# uv 방식
uv python pin 3.11
uv init
uv add langchain
uv sync

Python 3.11 이상이 필요하다는 점만 기억해 두세요.

2. API 키 설정하기

지원하는 모델 프로바이더(예: Google Gemini, OpenAI)에서 API 키를 발급받아요. 셸이나 .env 파일에 설정하면 돼요.

export OPENAI_API_KEY="your-api-key"
# 또는 .env 파일에
# OPENAI_API_KEY=your-api-key

.env 파일을 로드하려면 python-dotenv의 load_dotenv()를 쓰면 돼요.

3. 기본 에이전트 만들기

질문에 답하면서 도구를 호출할 수 있는 간단한 에이전트를 만들어 봐요. 이 예제는 언어 모델, 간단한 날씨 함수(도구), 그리고 행동을 안내하는 간단한 프롬프트로 구성돼요.

# pip install -qU langchain "langchain[openai]"
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",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
)
print(result["messages"][-1].content_blocks)

create_agent가 에이전트, get_weather가 도구, system_prompt가 행동 원칙을 담당해요. 에이전트가 도구를 호출한 결과를 바탕으로 최종 답변을 만들어 내는 걸 확인할 수 있어요.

4. 에이전트 호출 추적하기 (LangSmith)

에이전트가 내부에서 하는 많은 LLM 호출을 들여다보고 싶다면 LangSmith로 추적할 수 있어요.

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

이렇게 설정하고 스크립트를 다시 실행하면, 각 호출이 어떻게 라우팅되고 어디에서 실패했는지를 LangSmith 콘솔에서 확인할 수 있어요.

이후 학습 방향

이제 기본 에이전트를 만들었으니 계속해서 메모리 관리, 프로덕션 배포, 구조화 응답 같은 주제로 확장해 나가면 돼요. 에이전트가 맥락을 이해하고, 도구를 지능적으로 쓰고, 일관된 구조화 응답을 만들고, 대화 상태를 유지하는 것까지 다룰 수 있게 돼요.

더 알아보기