Vercel AI SDK 6의 핵심 변경점을 개발자 관점에서 분석한다. Agent API로 에이전트를 1급 추상화로 쓰는 법, Tool Execution Approval로 인간 승인 루프를 구현하는 법, MCP 서버 연결, DevTools 디버깅, 리랭킹·이미지 편집, 그리고 v5에서 코드 변경 최소화로 마이그레이션하는 방법까지 실전 코드와 함께 정리한다.
한 줄 요약: Vercel AI SDK 6은 에이전트를 1급 추상화로 격상하고, 인간 승인 루프(Tool Execution Approval)·MCP 풀 지원·DevTools·리랭킹·이미지 편집을 한 번에 추가했다. v5에서 마이그레이션은 코드 변경이 최소화된다.
※ 2026년 4월 기준. 출처: vercel.com/blog/ai-sdk-6, ai-sdk.dev 공식 문서
Vercel AI SDK는 지금까지 언어 모델 호출·스트리밍·도구 사용을 TypeScript에서 추상화하는 유틸리티 레이어였다. SDK 6은 여기서 한 단계 더 나아가 에이전트 자체를 1급 추상화로 만든다. 에이전트를 한 번 정의하면 API 라우트·서버 액션·React 컴포넌트 어디서나 동일하게 사용할 수 있다.
주요 변경점을 한눈에 정리하면 다음과 같다.
| 기능 | SDK 5 | SDK 6 |
|---|---|---|
| 에이전트 추상화 | 수동 루프 구현 | Agent API (1급 추상화) |
| 도구 승인 | 없음 | Tool Execution Approval |
| MCP 지원 | 부분 지원 | 풀 지원 (v3 LM Spec) |
| 디버깅 | 콘솔 로그 | DevTools (브라우저 패널) |
| 리랭킹 / 이미지 편집 | 없음 | 내장 지원 |
SDK 6의 핵심은 createAgent 함수다. 모델·시스템 프롬프트·도구·최대 스텝 수를 한 곳에 정의하면, 이 에이전트를 서버와 클라이언트 어디서나 동일하게 호출할 수 있다. 기존에는 에이전틱 루프를 직접 구현해야 했던 generateText + maxSteps 조합이 Agent로 추상화된다.
에이전트는 도구 호출 결과를 자동으로 다음 단계 입력으로 넘기는 루프를 내장한다. 루프가 끝나는 조건은 모델이 도구 없이 최종 텍스트만 반환하거나, maxSteps에 도달했을 때다.
Agent API — 기본 에이전트 정의와 실행import { createAgent } from 'ai'; import { anthropic } from '@ai-sdk/anthropic'; import { tool } from 'ai'; import { z } from 'zod'; // 에이전트를 한 번 정의 const codeReviewAgent = createAgent({ model: anthropic('claude-opus-4-7'), system: 'You are an expert code reviewer. Analyze code for bugs, security issues, and improvements.', tools: { readFile: tool({ description: 'Read a file from the repository', parameters: z.object({ path: z.string().describe('File path to read'), }), execute: async ({ path }) => { // 실제 파일 읽기 로직 return { content: await fs.readFile(path, 'utf-8') }; }, }), }, maxSteps: 10, }); // Next.js API Route에서 사용 export async function POST(req) { const { files } = await req.json(); const result = await codeReviewAgent.generate([ { role: 'user', content: `다음 파일들을 리뷰해줘: ${files.join(', ')}` } ]); return Response.json({ review: result.text }); }
AI 에이전트가 파일 삭제·외부 API 호출·DB 쓰기 같은 파괴적 작업을 수행하기 전에 사람의 승인을 받는 Human-in-the-Loop 패턴이 SDK 6에서 내장 기능으로 들어왔다. experimental_toToolResultContent + onToolCall 훅을 조합해 구현했던 것이 이제 approval 설정 하나로 가능하다.
승인이 필요한 도구는 require로 표시하고, UI에서 승인·거부 인터페이스를 연결하면 된다. 거부 시 에이전트는 대안 방법을 시도하거나 멈춘다.
Tool Execution Approval — 삭제 작업 전 사용자 확인import { createAgent, tool } from 'ai'; import { anthropic } from '@ai-sdk/anthropic'; import { z } from 'zod'; const fileAgent = createAgent({ model: anthropic('claude-opus-4-7'), system: 'You are a file management assistant.', tools: { deleteFile: tool({ description: 'Delete a file from the system', parameters: z.object({ path: z.string(), reason: z.string().describe('Why this file should be deleted'), }), // approval: 'required' — 실행 전 사용자 승인 필요 approval: 'required', execute: async ({ path }) => { await fs.unlink(path); return { deleted: path }; }, }), }, }); // 승인 핸들러 — UI에서 Yes/No를 받아 에이전트에 전달 const result = await fileAgent.generate(messages, { onToolApprovalRequired: async ({ toolName, args }) => { // 실제 구현: 웹소켓이나 SSE로 클라이언트에 승인 요청 전송 const approved = await requestUserApproval({ toolName, args }); return approved ? 'approved' : 'rejected'; }, });
SDK 6은 v3 Language Model Specification을 기반으로 MCP(Model Context Protocol) 풀 지원을 내장한다. experimental_createMCPClient를 통해 MCP 서버에 연결하고, 서버가 제공하는 도구를 에이전트에 직접 주입할 수 있다.
실무에서 MCP 연결이 가장 유용한 상황은 다음과 같다. 사내 데이터베이스 MCP 서버, GitHub MCP 서버, Notion MCP 서버 등 기존 인프라를 에이전트가 자동으로 호출하게 만들 때 개별 도구를 일일이 구현할 필요가 없다.
MCP 서버 연결 — 외부 도구를 에이전트에 주입import { createAgent, experimental_createMCPClient } from 'ai'; import { anthropic } from '@ai-sdk/anthropic'; // MCP 서버 연결 const mcpClient = await experimental_createMCPClient({ transport: { type: 'sse', // Server-Sent Events 방식 url: 'https://your-mcp-server.com/sse', }, }); // MCP 서버의 도구 목록 가져오기 const mcpTools = await mcpClient.tools(); // 에이전트에 MCP 도구 주입 const agent = createAgent({ model: anthropic('claude-opus-4-7'), system: 'You are a helpful assistant with access to company tools.', tools: { ...mcpTools, // MCP 도구 자동 주입 }, maxSteps: 15, }); // 사용 후 연결 해제 process.on('exit', () => mcpClient.close());
AI SDK DevTools는 브라우저 개발자 도구 패널에서 LLM 호출을 실시간으로 확인할 수 있는 기능이다. 에이전트 루프의 각 스텝에서 어떤 도구가 호출됐는지, 모델이 무엇을 생각했는지, 토큰이 얼마나 소비됐는지를 한눈에 볼 수 있다.
DevTools가 특히 유용한 상황은 에이전트가 예상과 다르게 도구를 호출하거나, 루프가 왜 멈췄는지 파악할 때다. 기존에는 console.log를 이곳저곳 심어야 했던 것이 패널 하나로 가능해진다.
DevTools 활성화 — Next.js 앱에 추가하기// app/layout.tsx import { AISDKDevTools } from '@ai-sdk/devtools'; export default function RootLayout({ children }) { return ( <html> <body> {children} {/* 개발 환경에서만 DevTools 활성화 */} {process.env.NODE_ENV === 'development' && <AISDKDevTools />} </body> </html> ); } // next.config.js — DevTools 패키지 허용 const nextConfig = { experimental: { // DevTools 서버 컴포넌트 렌더링 허용 serverActions: { allowedOrigins: ['localhost:3000'] }, }, }; export default nextConfig;
SDK 6은 RAG 파이프라인에 필요한 리랭킹(Reranking)을 내장 지원한다. 벡터 검색으로 가져온 상위 N개 문서를 크로스 인코더로 재정렬해 관련성 높은 컨텍스트만 모델에 전달할 수 있다.
리랭킹 — RAG 검색 결과 재정렬import { rerank } from 'ai'; import { cohere } from '@ai-sdk/cohere'; // 벡터 검색 결과를 리랭킹으로 재정렬 const { results } = await rerank({ model: cohere.rerank('rerank-v3.5'), query: '사용자 질의', documents: vectorSearchResults, // 벡터 DB에서 가져온 상위 20개 topK: 5, // 최종적으로 컨텍스트에 넣을 상위 5개만 선택 }); // 리랭킹된 상위 5개 문서만 LLM에 전달 const context = results.map(r => r.text).join('\n\n'); // 이미지 편집 (인페인팅, 아웃페인팅) import { experimental_generateImage } from 'ai'; import { openai } from '@ai-sdk/openai'; const edited = await experimental_generateImage({ model: openai.image('dall-e-3'), prompt: '배경을 산으로 교체', image: originalImageBase64, // 기존 이미지 입력 operation: 'edit', });
Vercel은 SDK 6을 "major version이지만 코드 변경은 최소화"를 설계 목표로 삼았다. 기존 generateText·streamText·generateObject API는 그대로 동작한다. 마이그레이션 codemods도 제공돼 자동으로 변경 가능한 부분은 스크립트로 처리된다.
실질적으로 변경이 필요한 경우는 v3 Language Model Specification에 의존한 커스텀 프로바이더를 만든 경우와, experimental_toToolResultContent 같은 실험적 API를 직접 사용한 경우다. 그 외 일반적인 사용 패턴은 패키지 버전 업그레이드 후 codemod 한 번으로 끝난다.
v6 마이그레이션 — 패키지 업데이트와 codemod 실행# 1. 패키지 업데이트 npm install ai@6 @ai-sdk/anthropic@latest @ai-sdk/openai@latest # 2. Vercel 공식 codemod 실행 (자동 변환 가능한 부분 처리) npx @ai-sdk/codemod upgrade # 3. 타입 에러 확인 npx tsc --noEmit # 주요 변경사항 요약: # - LanguageModel 인터페이스 → v3 LM Spec으로 업데이트 # - experimental_toToolResultContent 제거 → 내장 Tool Approval로 대체 # - createStreamableUI → useAgent 훅으로 마이그레이션 권장 # - 새 Agent API는 추가 설치 없이 'ai' 패키지에서 임포트
