LangChain으로 AI 에이전트 구축 방법: 단계별 가이드

안전한 임시 작업 디렉토리 생성하기

LangChain으로 AI 에이전트 구축하기: 단계별 튜토리얼

단순히 텍스트를 생성하는 대규모 언어 모델(LLM)에서 실제로 행동을 취할 수 있는 AI 에이전트로의 전환은 현대 소프트웨어 엔지니어링에서 가장 중요한 발전 중 하나입니다. 에이전트 시스템은 환경을 인식하고, 결정을 내리며, 특정 목표를 달성하기 위해 도구를 사용하여 단순한 질문-응답 챗봇을 넘어섭니다. LangChain은 오픈소스 프레임워크로, LLM을 외부 데이터, 도구 및 다른 LLM과 연결하여 이러한 정교한 애플리케이션을 구축하기 위한 표준으로 자리 잡았습니다.

이 튜토리얼은 LangChain으로 AI 에이전트를 구축하는 방법에 대한 포괄적이고 단계별 가이드를 제공합니다. 기본 개념을 배우고 실제 구현을 진행하여 실제 작업을 수행할 수 있는 자율 에이전트를 직접 만들 수 있는 능력을 갖추게 됩니다.

배우게 될 내용

이 튜토리얼을 마치면 에이전트 AI와 LangChain 프레임워크의 핵심 원리를 이해하게 됩니다. 개발 환경을 설정하고, LLM에 연결하고, 사용자 정의 도구를 정의하고, 최신 create_agent API를 사용하여 기능적인 에이전트를 구축할 수 있습니다. 자연어 명령을 기반으로 로컬 파일 시스템과 상호작용할 수 있는 완전한 AI 에이전트를 구축하고 실행하게 되어, 더 복잡한 자동화를 만들기 위한 실용적인 기초를 다지게 됩니다.

1. LangChain 기본 개념 및 핵심 용어

코드를 살펴보기 전에 AI 에이전트가 무엇이고 LangChain이 어떻게 그 생성을 용이하게 하는지 이해하는 것이 필수적입니다. 핵심적으로 에이전트는 LLM을 추론 엔진으로 사용하는 시스템입니다. 에이전트는 사용자 요청을 받고, LLM에 작업을 결정하도록 요청하며, 해당 작업을 실행하고(종종 도구를 호출하여), 결과를 처리하여 응답을 구성합니다. 이 주기는 작업이 완료될 때까지 계속됩니다.

LangChain은 이 추론 루프를 구현하기 위한 표준 프레임워크를 제공하며, 특히 ReAct(Reason + Act) 프레임워크를 지원합니다. LangChain은 LangGraph 위에 구축된 고수준 도구로, LangGraph는 에이전트의 워크플로우와 상태를 세밀하게 제어할 수 있는 저수준 오케스트레이션 프레임워크입니다.

LangChain으로 에이전트를 구축하려면 네 가지 주요 구성 요소가 필요합니다:

1. LLM: 에이전트의 추론 엔진입니다.
2. 도구(Tools): 에이전트가 API, 데이터베이스 또는 파일 시스템과 같은 외부 세계와 상호작용할 수 있게 해주는 함수입니다.
3. 에이전트 루프(Agent Loop): LLM, 도구 및 상태를 관리하는 "두뇌" 오케스트레이션 계층입니다.
4. 메모리(체크포인팅): 에이전트의 상태를 유지하여 대화 스레드 내에서 과거 상호작용을 기억할 수 있게 해줍니다.

2. 개발 환경 설정하기

시작하려면 LangChain과 핵심 종속성을 설치해야 합니다. 이 튜토리얼은 Python에서 프로세스를 보여주지만, 개념과 고수준 패턴은 TypeScript 사용자에게도 유사합니다.

먼저 시스템에 Python 3과 Pip이 설치되어 있는지 확인하세요. Debian/Ubuntu 기반 시스템의 경우 다음 명령어를 사용할 수 있습니다. 다른 운영 체제의 경우 적절한 설치 방법을 따르세요.

sudo apt update
sudo apt install python3 python3-pip

다음으로, 주요 LangChain 패키지를 설치합니다. langchain 패키지는 핵심 프레임워크입니다. langchain-community에는 커뮤니티에서 유지 관리하는 도구가 포함되어 있으며, langgraph는 최신 에이전트 생성 API에 필요합니다.

pip install langchain langgraph langchain-community

3. 대규모 언어 모델 통합하기

에이전트 구축의 첫 번째 단계는 LLM에 연결하는 것입니다. LangChain은 Google Gemini, OpenAI, Anthropic 등을 포함한 수십 개의 모델 제공자를 지원합니다. 이 튜토리얼에서는 Google의 Gemini 모델을 사용합니다.

Gemini 콘솔에서 API 키가 필요합니다. 키를 받으면 Google GenAI 통합 패키지를 설치하고 환경을 설정할 수 있습니다.

pip install -qU "langchain[google-genai]"

이제 모델을 초기화하는 Python 코드를 작성할 수 있습니다. getpass 모듈은 API 키를 안전하게 입력받는 데 사용됩니다.

import getpass
import os
from langchain.chat_models import init_chat_model
from langchain_core.messages import HumanMessage, SystemMessage

if not os.environ.get("GOOGLE_API_KEY"):
    os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter API key for Google Gemini: ")

model = init_chat_model("gemini-2.0-flash", model_provider="google_genai")

간단한 쿼리로 모델을 호출하여 설정을 테스트할 수 있습니다.

response = model.invoke("When did the French Revolution start?")
print(response.content)

4. 에이전트를 위한 도구 정의하기

도구는 에이전트를 강력하게 만드는 요소입니다. 도구를 통해 LLM은 텍스트 생성 이상의 작업을 수행할 수 있습니다. 이 튜토리얼에서는 LangChain의 FileManagementToolkit을 사용하여 로컬 컴퓨터에서 파일을 관리할 수 있는 에이전트를 구축합니다.

FileManagementToolkit은 이미 설치한 langchain-community 패키지의 일부입니다. 이 툴킷을 사용하면 에이전트가 수행할 수 있는 파일 작업(예: 읽기, 쓰기, 파일 나열)을 지정할 수 있습니다.

필요한 모듈을 가져오고 도구를 정의합니다. 전체 파일 시스템에 대한 자유로운 접근 권한을 부여하는 대신 에이전트를 임시 디렉토리로 제한하는 것은 중요한 보안 관행입니다.

from langchain_community.agent_toolkits import FileManagementToolkit
from tempfile import TemporaryDirectory

working_directory = TemporaryDirectory()

# 선택된 도구와 루트 디렉토리로 툴킷 초기화
tools = FileManagementToolkit(
    root_dir=str(working_directory.name),
    selected_tools=["read_file", "write_file", "list_directory"],
).get_tools()

5. create_agent로 에이전트 구축하기

LLM과 도구가 준비되었으면 이제 에이전트를 구축할 수 있습니다. LangChain에서 에이전트를 구축하는 현대적이고 권장되는 방법은 create_agent 함수를 사용하는 것입니다.

이 함수는 모델과 도구 목록을 받아 추론 루프를 관리하는 에이전트 실행기를 생성합니다. 이는 프로세스를 단순화하여 수동으로 ReAct 에이전트와 실행기를 만들 필요가 없게 해줍니다.

from langchain.agents import create_agent

# "model" 및 "tools" 변수는 이전 단계에서 가져옵니다.
agent = create_agent(
    model=model,
    tools=tools
)

이 한 줄의 코드로 정교한 에이전트가 생성됩니다. 에이전트는 모델을 사용하여 사용자 입력에 따라 호출할 도구를 결정합니다. 복잡한 작업을 수행하기 위해 여러 도구 호출을 연결할 수 있습니다.

⚠️ 중요: LangChain은 create_react_agent와 같은 오래된 에이전트 생성 방법과 함께 사용할 수 있지만, create_agent API는 현대적이고 권장되는 접근 방식이며 새로운 에이전트를 구축할 때 기본 선택이 되어야 합니다.

6. 첫 번째 에이전트 실행하기

에이전트가 구축되었으므로 사용자 메시지로 호출하여 실행할 수 있습니다. 다음 명령어는 에이전트의 파일 시스템 상호작용 능력을 보여줍니다.

먼저 에이전트에게 현재 작업 디렉토리의 파일을 나열하도록 요청합니다. 이 시점에서 디렉토리는 비어 있습니다.

input_message = {"role": "user", "content": "List files in the current working directory"}
response = agent.invoke({"messages": [input_message]})

for message in response["messages"]:
    message.pretty_print()

다음으로, 에이전트에게 sample-file.txt라는 파일을 생성하도록 지시합니다.

input_message = {"role": "user", "content": "Create a file named sample-file.txt"}
response = agent.invoke({"messages": [input_message]})

for message in response["messages"]:
    message.pretty_print()

마지막으로, 에이전트에게 파일을 다시 나열하도록 요청합니다. 이제 sample-file.txt가 존재함을 보여줍니다.

input_message = {"role": "user", "content": "List files in the current working directory"}
response = agent.invoke({"messages": [input_message]})

for message in response["messages"]:
    message.pretty_print()

보시다시피, 에이전트는 자연어 명령을 성공적으로 해석하고, 적절한 도구(list_directory, write_file)를 호출하며, 수행된 작업에 대한 피드백을 제공했습니다. 이것은 LangChain으로 AI 에이전트를 구축하는 방법에 대한 기본적이지만 강력한 데모입니다.

7. 에이전트에 메모리 추가하기

상태 비저장 에이전트의 주요 한계 중 하나는 호출이 완료된 후 모든 컨텍스트를 잊어버린다는 것입니다. 과거 상호작용을 기억할 수 있는 대화형 에이전트를 만들려면 메모리를 추가해야 합니다. 이는 에이전트의 상태를 저장하는 "체크포인터"를 통해 달성됩니다.

LangGraph는 간단한 인메모리 체크포인터인 MemorySaver 클래스를 제공합니다. 프로덕션 환경에서는 PostgresSaver 또는 MongoDB 기반 체크포인터와 같은 더 강력한 옵션을 사용하겠지만, MemorySaver는 테스트 및 개발에 완벽합니다.

먼저 체크포인터를 가져오고 초기화합니다.

from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()

다음으로, checkpointer를 인수로 전달하여 에이전트를 다시 생성합니다.

agent_with_memory = create_agent(
    model=model,
    tools=tools,
    checkpointer=checkpointer
)

메모리를 사용하려면 구성에서 thread_id를 지정해야 합니다. 이 thread_id는 대화 ID 역할을 하여 에이전트가 각각의 개별 대화에 대해 별도의 메모리를 유지할 수 있게 해줍니다.

config = {"configurable": {"thread_id": "user-123"}}

agent_with_memory.invoke(
    {"messages": [{"role": "user", "content": "My name is Alice"}]},
    config=config
)

result = agent_with_memory.invoke(
    {"messages": [{"role": "user", "content": "What is my name?"}]},
    config=config
)
# 에이전트 응답: "Your name is Alice."
print(result["messages"][-1].content)

이 간단한 추가로 에이전트가 컨텍스트를 가지고 대화를 할 수 있게 되어 훨씬 더 지능적이고 유용하게 느껴집니다.

8. 기본을 넘어서: 멀티 에이전트 시스템

더 나아가면 단일 에이전트로는 너무 복잡한 작업에 직면할 수 있습니다. LangChain은 특화된 에이전트들이 협력하여 문제를 해결하는 정교한 멀티 에이전트 시스템 구축을 지원합니다. 이는 복잡한 워크플로우를 위한 강력한 아키텍처 패턴입니다.

하위 에이전트(Subagents) 는 주요 감독 에이전트가 여러 특화된 하위 에이전트를 조정하고 이를 도구로 호출하는 핵심 멀티 에이전트 패턴입니다. 예를 들어, 한 하위 에이전트는 연구를 담당하고, 다른 하나는 콘텐츠 생성을, 세 번째는 작업 검토를 담당할 수 있습니다.

패턴	작동 방식
하위 에이전트(Subagents)	주요 에이전트가 하위 에이전트를 도구로 조정합니다. 모든 라우팅은 주요 에이전트를 통과하며, 주요 에이전트가 각 하위 에이전트를 호출할 시기를 결정합니다.
핸드오프(Handoffs)	도구 호출이 다른 에이전트나 구성으로 전환을 트리거하는 상태 기반 동적 동작 변경입니다.
스킬(Skills)	특화된 프롬프트와 지식이 단일 에이전트의 컨텍스트에 온디맨드로 로드됩니다.
라우터(Router)	라우팅 단계가 입력을 분류하고 하나 이상의 특화된 에이전트로 전달하여 처리합니다.

올바른 패턴을 선택하는 것이 중요합니다. 예를 들어, 하위 에이전트 아키텍처는 병렬 실행 및 분산 개발에 탁월한 반면, 핸드오프 패턴은 단일 대화에서 반복적인 사용자 요청에 더 효율적입니다. 개인 비서 애플리케이션에서 하위 에이전트 패턴을 사용하면 컨텍스트 격리가 가능해집니다. 각 하위 에이전트는 깨끗한 컨텍스트 창에서 작업을 수행하여 주요 에이전트의 메모리가 비대해지는 것을 방지합니다.

출처

1. Chris Tozzi. "Build an AI agent with LangChain in this beginner tutorial." TechTarget, 2025년 9월.
2. "Quickstart" LangChain 공식 문서.
3. "Multi-agent" LangChain 공식 문서.
4. "Workflows and agents" LangChain 공식 문서.
5. "langchain-fundamentals" LangChain Skills 문서, GitHub.
6. "How to Build an AI Agent with LangChain and LangGraph: Build an Autonomous Starbucks Agent." freeCodeCamp, 2025년 12월.
7. "Subagents" LangChain 공식 문서.
8. "LangChain Python Tutorial: A Complete Guide for 2026." The JetBrains Blog, 2026년 3월.

— Editorial Team