LangChain으로 AI 에이전트 구축하기

LangChain 에이전트는 LangGraph를 기반으로 구축됩니다. 즉, 모델이 최종 답변을 반환할 때까지 루프(loop) 내에서 도구(tools)를 호출합니다. 상위 수준의 진입점은 createAgent이며, 모델, tool()로 정의된 도구들, 그리고 선택 사항인 systemPrompt를 전달하면 됩니다.

이 포스트는 Vercel AI SDK 에이전트 및 OpenAI Agents SDK 포스트와 동일한 **고객 지원 분류 에이전트 (support triage agent)**를 구축하여, 하나의 시나리오에서 SDK들을 비교할 수 있도록 합니다. 이 글은 Node.js용 LangChain 개요를 따르며, LangChain 시리즈의 #4번째 포스트(로더/청킹 및 pgvector를 이용한 RAG 파이프라인 이후)에 해당합니다.

사전 요구 사항 (Prerequisites)

• OpenAI 계정
• 생성된 API 키
• 결제 활성화
• Node.js 버전 26
• langchain, @langchain/openai, @langchain/core, 그리고 zod 설치:

npm i langchain @langchain/openai @langchain/core zod

• 환경 변수에 OPENAI_API_KEY 설정

멘탈 모델 (Mental model) - 턴(turns)과 에이전트 루프

**턴 (turn)**은 한 번의 모델 생성(generation)을 의미합니다. 해당 턴에서 모델은 다음 중 하나를 수행합니다:

• 최종 텍스트 (final text) 반환 (실행 종료)
• 도구 호출 (tool calls) 반환 (LangChain이 이를 실행하고 결과를 가지고 다음 턴을 시작함)

고객 지원 분류 에이전트의 전형적인 흐름: 사용자 질문 → 모델이 조회 도구(get_customer, get_invoice, search_knowledge_base) 호출 → 모델이 티켓을 생성하거나 에스컬레이션(escalates) → 최종 답변.

단일 턴에는 **여러 개의 병렬 도구 호출 (multiple parallel tool calls)**이 포함될 수 있습니다. invoke 또는 stream에서 recursionLimit을 설정하여 그래프 단계(graph steps)가 실행되는 횟수를 제한할 수 있습니다 (각 모델 생성과 도구 배치는 제한 횟수에 포함됩니다).

도구 정의하기 (Defining tools)

langchain의 tool()을 Zod schema와 함께 사용하고, 모델이 각 도구를 언제 호출해야 하는지 알 수 있도록 name과 description을 추가합니다:

import { tool } from 'langchain';
import { z } from 'zod';

...

LangChain은 schema를 사용합니다 (Vercel의 inputSchema나 OpenAI Agents의 parameters가 아닙니다). 핸들러(handler)는 검증된 입력을 첫 번째 인자로 받습니다.

createAgent

모델, 도구(tools), 그리고 분류(triage) 지침을 연결합니다:

import { createAgent } from 'langchain';

const agent = createAgent({
...

model은 프로바이더 문자열('gpt-5.5', 'openai:gpt-5.5')이거나 @langchain/openai에서 가져온 채팅 모델 인스턴스(chat model instance)일 수 있습니다.

Invoke

messages 배열을 전달하고 result.messages에서 최종 답변을 읽습니다:

const result = await agent.invoke({
  messages: [
    {
...

마지막 AI 메시지는 모든 도구 호출(tool calls)이 완료된 후의 에이전트 최종 답변입니다.

분류(triage) 시나리오 지원

프롬프트 예시:

고객 cus_1042가 송장 inv_8891에 대해 두 번 결제되었다고 말합니다. 어떻게 해야 하나요?

현실적인 체인(chain):

1. get_customer - 플랜 등급, 오픈된 티켓 수 확인
2. get_invoice - 금액, 상태, 결제 ID 확인
3. search_knowledge_base - 중복 결제 및 환불 정책 검색
4. create_support_ticket 또는 escalate_to_human - 조치 실행 또는 상담원 연결

데모는 인메모리 피스처(in-memory fixtures: 고객, 송장, 지식 베이스 문서)를 사용하므로 데이터베이스 없이도 스크립트가 실행됩니다.

멀티 도구 에이전트 (Multi-tool agent)

하나의 에이전트에 모든 분류 도구를 등록합니다:

import { createAgent } from 'langchain';
import {
  getCustomer,
...

result.messages를 조사하여 전체 추적(trace)을 확인하세요: 사용자 입력, AI 도구 호출 메시지, 도구 결과, 그리고 최종 AI 답변이 포함됩니다.

스트리밍 (Streaming)

agent.stream()은 그래프가 실행됨에 따라 상태 업데이트를 생성합니다. 각 단계 이후에 전체 메시지 목록을 받으려면 streamMode: 'values'를 사용하세요:

const stream = await agent.stream(
  {
    messages: [
...

토큰 단위 스트리밍(token-level streaming)을 위해서는 streamMode: 'messages' 또는 streamEvents를 사용하세요 (LangGraph streaming 참조).

LangChain을 선택해야 하는 시점

	LangChain createAgent	Vercel AI SDK	OpenAI Agents SDK
최적의 용도	RAG + LCEL + 에이전트(agents)를 하나의 스택으로 통합	이미 AI SDK를 사용 중인 TypeScript 앱	OpenAI 우선(OpenAI-first) 에이전트 기본 요소(primitives)
...
문서 로더(document loaders), 리트리버(retrievers), 그리고 에이전트(agents)가 하나의 생태계를 공유해야 할 때는 LangChain을 선택하세요. 더 넓은 LangChain의 표면적(surface) 없이 집중된 에이전트 레이어만을 원한다면 Vercel AI SDK 또는 OpenAI Agents SDK를 선택하세요.

데모 (Demo)

실행 가능한 스크립트(단일 도구 조회, 전체 분류(triage), 스트리밍)는 langchain-agents-nodejs-demo 폴더를 참조하세요.