Vercel AI SDK v7: TypeScript 애플리케이션 계층에는 강하지만 AI 기반 전체는 아니다
Vercel AI SDK는 여러 모델 제공업체를 공통 TypeScript API로 다루고 텍스트 생성, 구조화 출력, 스트리밍 UI, 도구 호출을 구현하는 라이브러리다. 2026년 8월 19일 기준 주 계열은 [email protected]이며 Node.js 22 이상과 Apache-2.0 라이선스를 확인했다.
오픈 소스 SDK, 별도 계약인 AI Gateway, 선택형 UI 구성요소 AI Elements, Vercel 호스팅과 관측 기능은 서로 다른 제품이다. 이를 모두 SDK 기능이라고 부르면 데이터 경로, 비용, 보관 기간, 이전 가능성을 잘못 판단하게 된다.
도입 평가는 단순히 모델을 바꿀 수 있는지가 아니라 교체 뒤에도 도구 인자, 중지 조건, 오류, 사용량, 화면 상태가 의도대로 동작하는지 확인해야 한다. 공통 타입이 모델 행동까지 같게 만들지는 않는다.
2026년 제품 경계
| 확인 항목 | 확인된 사실 | 의사결정 영향 |
|---|---|---|
| 주 계열 | [email protected], Node.js 22 이상 | 오래된 v5/v6 예제를 그대로 복사하지 않는다 |
| 에이전트 | ToolLoopAgent와 stopWhen | 중지 조건과 최대 반복 횟수를 명시한다 |
| 통신 | Core, UI transport, provider package | 화면 상태와 서버 상태를 나눠 시험한다 |
| 별도 제품 | AI Gateway, AI Elements, Vercel Cloud | 가격, 보관, 장애 범위를 따로 확인한다 |
useChat은 v5 이후 통신 구조가 달라졌다. 검색으로 찾은 코드가 컴파일되더라도 현재 상태 관리와 재연결 설계에 맞는다는 보장은 없다. 잠금 파일과 이전 문서를 함께 보관해야 한다.
안전한 이전과 평가 절차
- 패키지, provider, Node.js, 프레임워크 버전을 고정한다.
- 일반 답변, 구조화 출력, 도구 호출, 취소, 재연결을 포함한 평가 시나리오를 만든다.
- 도구 JSON Schema, 인가, 확인 화면, 멱등성을 SDK 바깥에서 구현한다.
- 구버전과 신버전을 같은 입력으로 실행해 결과뿐 아니라 이벤트 순서와 사용량을 비교한다.
- 시간 초과, 429, 스트림 중단, provider 장애를 의도적으로 만든다.
- 소수 사용자부터 단계적으로 전환하고 즉시 되돌릴 경로를 남긴다.
| 평가 축 | 측정 방법 | 통과 조건 |
|---|---|---|
| 정확성 | 고정 과제로 구조와 근거를 비교 | 중대한 의미 차이가 없음 |
| 도구 안전 | 인자, 권한, 중복 실행을 기록 | 무단·중복 실행이 없음 |
| 운영 | p95, 취소, 재연결, 오류율 | 기존 기준 충족 |
| 비용 | 성공 처리 단위로 총비용 계산 | 예산 한도와 경고가 작동 |
운영 환경에서 놓치기 쉬운 한계
provider 추상화는 이전 작업을 줄이지만 모델 품질, 도구 선택, 구조화 출력의 엄격성까지 표준화하지 않는다. provider를 바꿀 때마다 회귀 시험이 필요하다.
MCP나 외부 도구를 연결하면 프롬프트 주입이 실제 동작으로 이어질 수 있다. 읽기와 쓰기를 분리하고 되돌릴 수 없는 작업에는 사람 승인을 둔다.
실험적 OpenTelemetry 연동은 입력과 출력이 기록될 수 있다. 민감정보 마스킹, 사용자 고지, 보관 기간을 먼저 정한다.
Gateway는 편리하지만 직접 provider를 호출하는 구성과 장애·청구 경로가 다르다. 비상 우회 경로도 시험해야 한다.
대안과의 역할 구분
| 선택지 | 적합한 용도 | 주요 주의점 |
|---|---|---|
| Vercel AI SDK | TypeScript에서 AI 기능과 UI 구성 | 장기 상태와 업무 흐름은 별도 설계 |
| OpenAI Agents SDK | OpenAI 중심 agent, handoff, tracing | provider 중립성이 낮음 |
| LangGraph | 장기 상태, 분기, 재개가 필요한 처리 | 학습과 운영 설계가 무거움 |
| 직접 API | 단일 provider의 작은 기능 | 교체성과 공통 UI를 직접 구현 |
TypeScript 제품에서 생성, 스트림, 도구 실행을 공통화하려면 유력하다. 복잡한 장기 업무까지 SDK 하나가 관리해 준다고 기대하면 설계가 부족해진다.
처음에는 Core와 필요한 provider package만 사용하고 Gateway나 추가 UI는 운영 효과를 측정한 뒤 채택하는 편이 안전하다.
자주 묻는 질문
무료인가요?
SDK는 Apache-2.0 오픈 소스다. 모델 API, AI Gateway, Vercel 인프라 비용은 별도다.
provider를 바꾸면 결과도 같나요?
아니다. 호출 형식은 같아도 추론, 도구 선택, 거부, 사용량은 달라진다.
v5 useChat 코드를 그대로 쓸 수 있나요?
상태 관리와 통신 구조가 달라 공식 이전 문서에 따른 확인이 필요하다.
MCP는 안전한가요?
연결만으로 안전해지지 않는다. 권한 분리, 승인, 감사, 입력 불신 원칙이 필요하다.
AI Gateway가 필수인가요?
아니다. provider package에서 직접 호출할 수 있다.
어떤 팀에 맞나요?
TypeScript 중심으로 AI 기능과 화면을 같은 제품에서 관리하려는 팀에 맞는다.
확인한 1차 자료
- 근거 자료 1: github.com/vercel/ai
- 근거 자료 2: github.com/vercel/ai/releases
- 근거 자료 3: github.com/vercel/ai/blob/main/LICENSE
- 근거 자료 4: ai-sdk.dev/docs/ai-sdk-core/generating-text
- 근거 자료 5: ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
- 근거 자료 6: ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent
- 근거 자료 7: ai-sdk.dev/docs/ai-sdk-ui/transport
- 근거 자료 8: ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
- 근거 자료 9: ai-sdk.dev/docs/ai-sdk-core/mcp-tools
- 근거 자료 10: ai-sdk.dev/docs/ai-sdk-core/telemetry
- 근거 자료 11: vercel.com/docs/ai-gateway
- 근거 자료 12: vercel.com/docs/ai-gateway/pricing
- 근거 자료 13: elements.ai-sdk.dev
- 근거 자료 14: docs.langchain.com/oss/javascript/langgraph/overview
- 근거 자료 15: github.com/openai/openai-node
- 근거 자료 16: openai.github.io/openai-agents-js/
독립 검토일: 2026년 8월 21일. 버전, 가격, 실험 기능은 바뀔 수 있으므로 도입 시 공식 문서를 다시 확인해야 한다.