Vercel AI SDK 4.0 완전 정복: 스트리밍과 Tool Calling으로 AI 앱 만들기

streamText에서 await를 빼라고? Vercel AI SDK 4.0은 기존 3.x 사용자들의 코드를 상당히 뒤흔드는 업데이트입니다. 하지만 그 대가로 얻는 것—실시간 스트리밍 Tool Calling, PDF 문서 처리, 심지어 Claude의 Computer Use까지—을 보면 마이그레이션할 수밖에 없습니다.

Vercel AI SDK 4.0, 무엇이 달라졌나

2024년 11월 18일에 릴리스된 AI SDK 4.0은 월간 2천만 다운로드를 넘긴 JavaScript/TypeScript AI 툴킷의 메이저 업데이트입니다. 핵심 변경점은 세 가지로 요약됩니다: 스트리밍 아키텍처 개선, Tool Calling의 다단계 지원 강화, 그리고 멀티모달 입력 확장입니다.

가장 눈에 띄는 변화는 streamText가 더 이상 Promise를 반환하지 않는다는 점입니다. 3.x에서 const result = await streamText({...})로 쓰던 코드를 const result = streamText({...})로 바꿔야 합니다. 사소해 보이지만, 이 변경이 스트리밍 파이프라인 전체의 성능을 끌어올립니다. 불필요한 비동기 래핑이 사라지면서 첫 바이트 도달 시간(TTFB)이 단축됩니다.

Tool Calling: maxSteps로 다단계 에이전트 구축하기

AI SDK 4.0에서 가장 실용적인 변화는 Tool Calling 시스템입니다. 기존의 maxToolRoundtrips가 maxSteps로 이름이 바뀌었고, 동작 방식도 더 직관적으로 변했습니다. maxSteps: 5로 설정하면 모델이 도구를 호출하고, 결과를 받아 다시 판단하는 과정을 최대 5단계까지 자동으로 반복합니다.

import { generateText, tool } from 'ai';
import { z } from 'zod';

const { text, steps } = await generateText({
  model: yourModel,
  tools: {
    weather: tool({
      description: 'Get weather for a location',
      inputSchema: z.object({
        location: z.string().describe('City name'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
        condition: 'sunny',
      }),
    }),
  },
  maxSteps: 5,
  prompt: '서울과 도쿄의 날씨를 비교해줘',
});

이 코드에서 모델은 서울 날씨 조회 → 도쿄 날씨 조회 → 비교 분석까지 자동으로 진행합니다. steps 배열에서 각 단계의 도구 호출, 결과, 생성 텍스트를 모두 확인할 수 있습니다. 기존 3.x의 roundtrips보다 훨씬 깔끔합니다.

도구 실행 과정을 모니터링하려면 experimental_onToolCallStart와 experimental_onToolCallFinish 콜백을 활용하면 됩니다. 도구 이름, 입력값, 실행 시간, 에러 여부를 실시간으로 추적할 수 있어서 프로덕션 환경의 디버깅에 매우 유용합니다.

streamText + Tool Calling: 실시간 스트리밍의 진화

AI SDK 4.0의 스트리밍은 Server-Sent Events(SSE) 기반으로 표준화되었습니다. keep-alive, 자동 재연결, 캐시 핸들링이 내장되어 있어 프로덕션 배포 시 안정성이 크게 향상됩니다.

import { streamText, tool } from 'ai';
import { z } from 'zod';

const result = streamText({
  model: yourModel,
  tools: {
    searchDocs: tool({
      description: 'Search documentation',
      inputSchema: z.object({ query: z.string() }),
      execute: async ({ query }) => {
        // 문서 검색 로직
        return { results: ['doc1', 'doc2'] };
      },
    }),
  },
  maxSteps: 3,
  prompt: 'AI SDK의 스트리밍 설정 방법을 찾아줘',
});

// UI에서 실시간으로 렌더링
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

주목할 점은 streamText 호출 시 await가 없다는 것입니다. 결과 객체를 바로 받고, textStream을 async iterator로 소비합니다. 도구 호출이 포함된 경우에도 중간 결과가 실시간으로 스트리밍됩니다.

PDF 지원과 Computer Use: 멀티모달의 확장

AI SDK 4.0은 Anthropic, Google Generative AI, Google Vertex AI에서 PDF 파일을 직접 처리할 수 있습니다. 메시지 콘텐츠의 file 타입으로 PDF를 전달하면, 텍스트 추출, 요약, 질의응답이 가능합니다. 기업 환경에서 문서 기반 AI 워크플로우를 구축할 때 큰 도움이 됩니다.

더 흥미로운 건 Computer Use 지원입니다. Anthropic의 Claude Sonnet 3.5와 함께 사용하면, AI가 마우스 이동, 키보드 입력, 스크린샷 캡처, 파일 편집, 터미널 명령 실행까지 수행합니다. maxSteps와 결합하면 복잡한 자동화 시퀀스를 구성할 수 있습니다. 물론 아직 베타이고, 가상 머신 환경에서의 사용이 권장됩니다.

3.x에서 4.0으로: 마이그레이션 실전 가이드

AI SDK 4.0은 꽤 많은 Breaking Change를 포함합니다. 하지만 Vercel이 제공하는 공식 마이그레이션 가이드와 자동 코드모드 도구가 있어서 생각보다 수월합니다.

핵심 변경 사항을 정리합니다:

• streamText/streamObject: await 제거 — Promise를 반환하지 않음
• maxToolRoundtrips → maxSteps: 값은 roundtrips + 1 (예: roundtrips 2 → maxSteps 3)
• baseUrl → baseURL: 모든 프로바이더에서 대문자 URL로 통일
• 프레임워크 패키지 분리: ai/svelte → @ai-sdk/svelte, ai/vue → @ai-sdk/vue
• experimental_ 접두사 제거: experimental_StreamData → StreamData, experimental_addToolResult → addToolResult
• useChat 변경: streamMode → streamProtocol, options → headers + body 분리
• 에러 처리: isXXXError 정적 메서드 → isInstance 인스턴스 메서드

자동 마이그레이션은 한 줄이면 됩니다:

npx @ai-sdk/codemod upgrade
# 또는 4.0 전용 변경만
npx @ai-sdk/codemod v4

코드모드가 대부분의 기계적 변경을 처리하지만, streamText의 await 제거처럼 로직 흐름에 영향을 주는 변경은 수동으로 확인하는 것을 권장합니다.

프로바이더 생태계: Grok, Cohere, 그리고 더 많은 선택지

AI SDK 4.0은 프로바이더 생태계도 크게 확장했습니다. xAI의 Grok이 퍼스트파티 프로바이더로 추가되었고, Cohere는 v2 지원과 함께 Tool Calling이 가능해졌습니다. OpenAI는 predicted output과 프롬프트 캐싱을, Google은 파일 입력, 파인튜닝 모델, 스키마 지원을 추가했습니다. Amazon Bedrock, Groq, LM Studio, Together AI 등도 지원 목록에 포함됩니다.

프로바이더 간 전환이 코드 한 줄 수정으로 가능하다는 것이 AI SDK의 핵심 장점입니다. model 파라미터만 바꾸면 OpenAI에서 Anthropic으로, Google에서 Groq으로 즉시 전환됩니다. LangChain 대비 30ms vs 45ms(p99)의 레이턴시 차이도 프로덕션 환경에서는 무시할 수 없는 수치입니다.

Sean’s Take: 현장에서 느낀 AI SDK 4.0의 진짜 가치

28년간 음악/오디오/테크 업계에서 일하면서, 저는 수많은 프레임워크의 흥망성쇠를 지켜봤습니다. Vercel AI SDK가 특별한 이유는 ‘프론트엔드 개발자가 AI를 쉽게 쓸 수 있게 한다’는 명확한 비전 때문입니다. 실제로 제가 운영하는 블로그 자동화 파이프라인도 AI SDK의 Tool Calling 개념에서 영감을 많이 받았습니다.

4.0의 maxSteps는 특히 에이전트 패턴을 구현할 때 혁신적입니다. 이전에는 도구 호출 결과를 수동으로 다시 모델에 넣는 보일러플레이트가 필요했는데, 이제 프레임워크가 이 루프를 자동으로 처리합니다. 제 파이프라인에서 리서치 → 콘텐츠 생성 → 이미지 처리를 순차적으로 처리하는 것과 본질적으로 같은 패턴입니다.

다만 주의할 점도 있습니다. Breaking Change가 상당히 많아서, 중규모 이상의 프로젝트에서는 마이그레이션에 반나절 이상 잡아야 합니다. 코드모드가 기계적 변경은 처리하지만, 스트리밍 로직이 복잡한 경우 수동 검토가 필수입니다. 그래도 streamText의 await 제거로 인한 성능 개선과 SSE 기반 안정성을 생각하면, 업그레이드를 미룰 이유가 없습니다.

2025년 AI 앱 개발의 선택지는 크게 세 가지입니다: OpenAI SDK로 직접 구현하거나, LangChain으로 복잡한 파이프라인을 설계하거나, Vercel AI SDK로 React/Next.js 생태계에서 빠르게 출시하거나. 만약 여러분의 스택이 TypeScript + React라면, AI SDK 4.0은 현 시점에서 가장 균형 잡힌 선택입니다.

---

---