퀵스타트
퀵스타트 (Quickstart)
LangChain을 처음 접할 때, "뭘 설치하고 어떻게 시작하지?"가 가장 큰 고민이에요. 이 퀵스타트는 몇 분 만에 완전히 동작하는 AI 에이전트를 만드는 과정을 보여드릴게요. 빠르게 감을 잡고 나면 그다음부터는 자유롭게 응용하면 돼요.
의존성 설치 (Install dependencies)
따라 하기 위해 다음 패키지들을 설치하세요. uv를 쓰는 경우:
uv python pin 3.11
uv init
uv add langchain
uv sync
pip를 쓰는 경우(Python 3.11+ 별도 설치 필요):
# Install Python 3.11+ separately if needed.
pip install -U langchain
가상환경을 쓰는 경우:
# Install Python 3.11+ separately if needed.
python3.11 -m venv .venv
source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -U langchain
API 키 설정 (Set up API keys)
지원되는 모델 제공자 중 아무 데서나 API 키를 받으세요. (예: Google Gemini, OpenAI) API 키는 셸이나 .env 파일에 설정하면 돼요. 예를 들어 OpenAI는:
export OPENAI_API_KEY="your-api-key"
또는 .env 파일에:
OPENAI_API_KEY=your-api-key
지원되는 채팅 모델 통합의 전체 목록은 아래를 참고하세요. .env 파일을 불러오려면 python-dotenv의 load_dotenv()를 쓰면 됩니다.
LangSmith Gateway 사용 시: LangSmith Gateway는 대부분의 주요 제공자를 LangSmith를 통해 라우팅해요. 자체 제공자 키를 가져오거나, Gateway Credits로 제공자 키 없이 모델에 접근할 수 있습니다.
기본 에이전트 만들기 (Build a basic agent)
질문에 답하고 도구를 호출할 수 있는 단순한 에이전트부터 만들어 볼게요. 이 예시의 에이전트는 선택한 언어 모델, 도구로 쓸 기본 날씨 함수, 그리고 행동을 안내하는 간단한 프롬프트를 사용해요.
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)
Google Gemini는 모델 문자열만 다릅니다.
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="google_genai:gemini-2.5-flash-lite",
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)
Anthropic(Claude), OpenRouter, Fireworks, Baseten, Ollama, Azure, AWS Bedrock, HuggingFace 등 각 제공자별 모델 문자열과 설치 패키지는 원문 문서의 코드 탭에서 확인할 수 있어요. create_agent 사용법은 동일합니다.
출력 탭을 보면 LangChain 에이전트가 답을 주긴 하지만 추정치(estimate)라는 걸 알 수 있어요. 이 질문에 답할 도구가 에이전트에 없기 때문이죠. 프롬프트가 너무 길다는 오류가 날 수도 있어요. 반면 deep agent는 그런 작업을 이렇게 처리합니다.
- 내장
write_todos도구로 접근을 계획해요. fetch_text_from_url도구로 파일을 로드해 정보를 모아요.- 파일시스템 도구(
grep,read_file)로 컨텍스트를 관리해요. - 복잡한 하위 작업을 전문화된 서브에이전트에 위임하려면 필요에 따라 서브에이전트를 생성해요.
LangChain 에이전트는 이와 비슷한 수준의 서비스를 얻으려면 더 많은 기능을 직접 구현해야 하고, 그 과정에서 필요에 따라 커스터마이즈할 수 있어요.
에이전트 호출 트레이스하기 (Trace agent calls)
LangChain으로 만드는 대부분의 흥미로운 애플리케이션은 LLM 호출을 많이 해요. 애플리케이션이 복잡해질수록 에이전트 안에서 정확히 무슨 일이 일어나는지 검사할 수 있는 게 중요해집니다. 이걸 하는 가장 좋은 방법은 LangSmith예요.
LangSmith 계정에 가입하고 다음을 설정해 트레이스 로깅을 시작하세요.
export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."
설정 후 스크립트를 다시 실행하고 LangSmith에서 에이전트 호출 동안 무슨 일이 있었는지 검사하면 돼요.
LangSmith로 에이전트를 트레이싱하는 방법을 더 알고 싶다면 LangSmith documentation을 참고하세요. 트레이스를 모니터링하고 문제를 감지하며 수정안을 제안하는 LangSmith Engine도 설정하는 걸 권장합니다.
다음 단계 (Next steps)
이제 여러분의 에이전트는 다음을 할 수 있어요.
- 컨텍스트 이해와 대화 기억
- 도구 지능적으로 사용
- 일관된 형식으로 구조화된 응답 제공
- 컨텍스트를 통한 사용자별 정보 처리
- 상호작용 전반에 걸친 대화 상태 유지
- 계획·연구·종합 (deep agents 전용)
계속해서 배우려면: