마이그레이션 가이드
LangChain, LangGraph, 커스텀 오케스트레이션에서 Vercel AI 스택으로 전환할 때의 개념 매핑과 전환 전략을 정리합니다.
기존 AI 오케스트레이션 프레임워크에서 Vercel 스택으로 전환할 때 가장 중요한 것은 1:1 기능 매핑이 아니라 아키텍처 패러다임의 차이를 이해하는 것입니다.
핵심 차이
| 관점 | LangChain / LangGraph | Vercel AI Stack |
|---|---|---|
| 철학 | Framework-first, 추상화 레이어 제공 | Code-first, 플랫폼 서비스 조합 |
| 오케스트레이션 | Graph DSL, Chain 추상화 | async/await + Workflow + AI SDK |
| 모델 관리 | 앱 내 provider 설정 | Gateway에서 중앙 제어 |
| 도구 실행 | 앱 프로세스 내 | Sandbox 격리 실행 가능 |
| 상태 관리 | Checkpoint / StateGraph | Workflow persistence |
| 배포 | 별도 인프라 필요 | Vercel 통합 배포 |
LangChain에서 전환
개념 매핑
| LangChain | Vercel AI SDK | 비고 |
|---|---|---|
ChatOpenAI | openai/gpt-5.4 | Gateway를 통한 호출 |
ChatPromptTemplate | system/user message 직접 구성 | 코드로 직접 관리 |
StructuredOutputParser | AI SDK structured output | Zod schema 기반 |
Tool | tool() from ai | schema + execute |
AgentExecutor | generateText + tool loop | 명시적 루프 제어 |
RetrievalQAChain | AI SDK tool + vector store 직접 호출 | chain 추상화 없이 직접 연결 |
ConversationChain | messages 배열 직접 관리 | 프레임워크 의존 제거 |
CallbackHandler | AI SDK telemetry | OpenTelemetry 호환 |
전환 예시: Chain → AI SDK
Before (LangChain)
from langchain.chat_models import ChatOpenAI
from langchain.chains import RetrievalQAChain
chain = RetrievalQAChain.from_chain_type(
llm=ChatOpenAI(model="gpt-4"),
retriever=vectorstore.as_retriever(),
)
result = chain.run("질문")After (AI SDK)
import { generateText, tool } from 'ai'
import { z } from 'zod'
const result = await generateText({
model: 'openai/gpt-5.4',
messages: [{ role: 'user', content: '질문' }],
tools: {
searchDocs: tool({
description: '문서를 검색합니다.',
inputSchema: z.object({ query: z.string() }),
execute: async ({ query }) => {
const docs = await vectorStore.search(query)
return docs.map((d) => d.content).join('\n')
},
}),
},
})LangGraph에서 전환
개념 매핑
| LangGraph | Vercel | 비고 |
|---|---|---|
StateGraph | Workflow + typed state | DSL 대신 코드 분기 |
node | Workflow step / AI SDK tool / subagent | 함수 단위로 직접 구현 |
edge | 코드 분기 / tool choice / event resume | conditional edge는 if/switch |
state / reducer | workflow payload + 사용자 정의 merge | 타입 안전성은 TypeScript로 |
checkpoint | Workflow persistence | 자동 제공 |
human_in_the_loop | defineHook / approval hook | Workflow의 강점 |
ToolNode | AI SDK tool | schema + execute |
전환 예시: StateGraph → Workflow
Before (LangGraph)
from langgraph.graph import StateGraph
graph = StateGraph(AgentState)
graph.add_node("classify", classify_node)
graph.add_node("research", research_node)
graph.add_node("respond", respond_node)
graph.add_conditional_edges("classify", route_fn)After (Vercel Workflow)
export async function agentWorkflow(input: AgentInput) {
'use workflow'
const classification = await classify(input)
if (classification.route === 'research') {
const research = await researchStep(classification)
return respond(research)
}
return respond(classification)
}
async function classify(input: AgentInput) {
'use step'
return classifyInput(input)
}
async function researchStep(classification: Classification) {
'use step'
return runResearch(classification)
}
async function respond(input: Classification | ResearchResult) {
'use step'
return generateResponse(input)
}커스텀 오케스트레이션에서 전환
직접 구현한 오케스트레이션 (Express + OpenAI SDK + Redis 등)에서 전환하는 경우:
| 기존 구현 | Vercel 대체 | 이점 |
|---|---|---|
| Express API + OpenAI SDK | Next.js Route Handler + AI SDK | 스트리밍, type safety |
| Redis 기반 작업 큐 | Vercel Queues | 인프라 관리 제거 |
| Cron + polling 기반 장기 작업 | Vercel Workflow | durable state, event resume |
| Docker 기반 코드 실행 | Vercel Sandbox | 관리형 격리 실행 |
| 직접 구현한 모델 fallback | AI Gateway | 중앙화된 정책 관리 |
| 자체 로깅/모니터링 | Vercel Observability + AI SDK telemetry | 통합 관측성 |
전환 전략
점진적 전환 (권장)
| 단계 | 전환 대상 | 목표 | 기간 예시 |
|---|---|---|---|
| 1 | 모델 호출 → AI Gateway | 비용/정책 중앙화 | 1~2주 |
| 2 | 모델 래퍼 → AI SDK | 스트리밍, telemetry 표준화 | 2~3주 |
| 3 | 장기 작업 → Workflow | durable execution 확보 | 2~4주 |
| 4 | 코드 실행 → Sandbox | 격리 실행 확보 | 1~2주 |
| 5 | chain/graph → 네이티브 구현 | 프레임워크 의존 제거 | 2~4주 |
전환 시 주의점
| 주의점 | 설명 |
|---|---|
| Chain 추상화 1:1 매핑하지 않기 | Vercel은 코드로 직접 구현하는 것이 관례 |
| 모든 것을 한 번에 바꾸지 않기 | Gateway → SDK → Workflow 순서로 점진적 전환 |
| 테스트/eval 먼저 준비하기 | 전환 전에 golden set을 만들어 품질 기준선 확보 |
| 기존 모니터링 병행하기 | 새 관측성 안정화까지 기존 도구 유지 |
실무 해석
LangChain에서 Vercel로 전환하는 핵심은 "같은 chain을 AI SDK로 다시 구현"이 아니라, "chain이라는 추상화 없이 AI SDK + Gateway + Workflow를 직접 조합"하는 것입니다. 코드량은 비슷하거나 줄어들지만, 각 계층의 책임이 더 명확해집니다.
전환 체크리스트
| 항목 | 완료 |
|---|---|
| 기존 시스템의 모델 호출 지점 목록화 | |
| golden set eval 준비 | |
| AI Gateway로 모든 모델 호출 중앙화 | |
| AI SDK로 generation/tool 호출 전환 | |
| 장기 실행 작업 Workflow 이전 | |
| 코드/파일 실행 Sandbox 이전 | |
| 기존 chain/graph 로직을 네이티브 코드로 전환 | |
| telemetry와 observability 확인 | |
| 전환 후 eval 결과와 기존 기준선 비교 |
ADR 스타일 결론
Decision
기존 프레임워크에서의 전환은 기능 1:1 매핑이 아니라 아키텍처 패러다임 전환으로 접근합니다. Gateway → AI SDK → Workflow → Sandbox 순서로 점진적으로 전환하고, 각 단계에서 eval 기준선을 유지합니다.