본문으로 바로가기
리옵트 핸드북
리옵트 핸드북
Vercel 엔터프라이즈 AI 플랫폼

플랫폼 기초

플랫폼 아키텍처AI SDK 런타임AI Gateway 제어면

실행 런타임

Workflow 장기 실행Sandbox 실행 격리MCP 데이터 계층Queues & 비동기 작업 관리

프롬프트 & 품질

프롬프트 엔지니어링 & 가드레일RAG & 검색 증강 생성관측성·평가

운영 체계

보안·거버넌스비용·안정성배포 전략 & AI CI/CD

실전 시나리오

고객지원 에이전트 아키텍처내부 리서치 에이전트 아키텍처승인형 백오피스 자동화코딩 오케스트레이션

오케스트레이션 패턴

그래프 중심 오케스트레이션실무 오케스트레이션 플레이북멀티 에이전트 아키텍처

부록

마이그레이션 가이드레퍼런스검증 리포트업데이트 내역
핸드북›Vercel 엔터프라이즈 AI›마이그레이션 가이드
한국어English

마이그레이션 가이드

LangChain, LangGraph, 커스텀 오케스트레이션에서 Vercel AI 스택으로 전환할 때의 개념 매핑과 전환 전략을 정리합니다.

핵심 요약

  • LangChain/LangGraph 전환은 기능 1:1 매핑이 아니라 framework-first에서 code-first로 가는 패러다임 전환으로 접근합니다.
  • ChatPromptTemplate은 message 직접 구성, AgentExecutor는 generateText+tool loop, StateGraph는 Workflow+typed state로 대응합니다.
  • 전환 순서는 Gateway -> AI SDK -> Workflow -> Sandbox -> 프레임워크 의존 제거 단계로 점진 진행합니다.
  • 전환 전에 golden set eval을 만들어 품질 기준선을 확보하고 각 단계에서 기존 기준선과 비교합니다.
  • chain/graph 추상화를 1:1로 다시 구현하지 말고, 새 관측성이 안정화될 때까지 기존 모니터링을 병행합니다.

기존 AI 오케스트레이션 프레임워크에서 Vercel 스택으로 전환할 때는 1:1 기능 매핑보다 아키텍처 패러다임의 차이를 먼저 이해해야 합니다.

핵심 차이

관점LangChain / LangGraphVercel AI Stack
철학Framework-first, 추상화 레이어 제공Code-first, 플랫폼 서비스 조합
오케스트레이션Graph DSL, Chain 추상화async/await + Workflow + AI SDK
모델 관리앱 내 provider 설정Gateway에서 중앙 제어
도구 실행앱 프로세스 내Sandbox 격리 실행 가능
상태 관리Checkpoint / StateGraphWorkflow persistence
배포별도 인프라 필요Vercel 통합 배포

LangChain에서 전환

개념 매핑

LangChainVercel AI SDK비고
ChatOpenAIopenai/gpt-5.4Gateway를 통한 호출
ChatPromptTemplatesystem/user message 직접 구성코드로 직접 관리
StructuredOutputParserAI SDK structured outputZod schema 기반
Tooltool() from aischema + execute
AgentExecutorgenerateText + tool loop명시적 루프 제어
RetrievalQAChainAI SDK tool + vector store 직접 호출chain 추상화 없이 직접 연결
ConversationChainmessages 배열 직접 관리프레임워크 의존 제거
CallbackHandlerAI SDK telemetryOpenTelemetry 호환

전환 예시: 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에서 전환

개념 매핑

LangGraphVercel비고
StateGraphWorkflow + typed stateDSL 대신 코드 분기
nodeWorkflow step / AI SDK tool / subagent함수 단위로 직접 구현
edge코드 분기 / tool choice / event resumeconditional edge는 if/switch
state / reducerworkflow payload + 사용자 정의 merge타입 안전성은 TypeScript로
checkpointWorkflow persistence자동 제공
human_in_the_loopdefineHook / approval hookWorkflow의 강점
ToolNodeAI SDK toolschema + 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 SDKNext.js Route Handler + AI SDK스트리밍, type safety
Redis 기반 작업 큐Vercel Queues인프라 관리 제거
Cron + polling 기반 장기 작업Vercel Workflowdurable state, event resume
Docker 기반 코드 실행Vercel Sandbox관리형 격리 실행
직접 구현한 모델 fallbackAI Gateway중앙화된 정책 관리
자체 로깅/모니터링Vercel Observability + AI SDK telemetry통합 관측성

전환 전략

점진적 전환 (권장)

단계전환 대상목표기간 예시
1모델 호출 → AI Gateway비용/정책 중앙화1~2주
2모델 래퍼 → AI SDK스트리밍, telemetry 표준화2~3주
3장기 작업 → Workflowdurable execution 확보2~4주
4코드 실행 → Sandbox격리 실행 확보1~2주
5chain/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 기준선을 유지합니다.

관련 문서

  • AI SDK Introduction
  • AI SDK Agents Overview
  • AI Gateway Overview
  • Workflow Docs
  • Vercel Sandbox Docs

관련 문서

업데이트 내역

이 핸드북의 변경 이력과 반영 근거를 기록합니다.

검증 리포트

링크, 최신성, 추론 구간, 소스 간 충돌 여부를 점검한 결과를 기록합니다.

프레임워크 비교와 선택

AI 에이전트 오케스트레이션 패턴 · LangGraph, CrewAI, AutoGen, OpenAI Agents SDK, Vercel AI SDK, Mastra 비교

Ch13. Observability와 Deployment

엔터프라이즈 Eve 에이전트 개발 · Eve의 OpenTelemetry, Workflow tags, Vercel/self-host 배포, 운영 점검 절차를 정리한다.

SDK 56 브레이킹 체인지 총정리

Expo 엔터프라이즈 프로덕션 · React Native 0.85, Hermes V1, Expo Router 분리, 플랫폼 요구사항, 마이그레이션 체크리스트

멀티 에이전트 아키텍처

AI SDK의 subagent, tool delegation, 역할 분리를 활용한 멀티 에이전트 패턴을 정리합니다.

레퍼런스

이 핸드북의 근거가 된 공식 문서, 공식 블로그, 공개 X 신호를 계층별로 정리합니다.

On this page

핵심 차이LangChain에서 전환개념 매핑전환 예시: Chain → AI SDKLangGraph에서 전환개념 매핑전환 예시: StateGraph → Workflow커스텀 오케스트레이션에서 전환전환 전략점진적 전환 (권장)전환 시 주의점전환 체크리스트ADR 스타일 결론관련 문서