Vercel AI SDK 리서치 원본 — 2026-07-25

불변 캡처. 절대 편집하지 마라. 가공본은 위키 페이지에.

조사 방법

검색어

"Vercel AI SDK version 2026 latest major version 5" (WebSearch)

열어본 URL (WebFetch, 시각 2026-07-25)

https://ai-sdk.dev/docs/introduction — 개요/패키지 구조
https://www.npmjs.com/package/ai — HTTP 403 (WebFetch 차단). 대신 npm view CLI 로 우회.
https://github.com/vercel/ai/releases — 릴리스 목록 (소형 모델이 monorepo release-please 태그를 오독함, npm 데이터로 교차검증)
https://ai-sdk.dev/docs/foundations/overview — 3개 surface
https://ai-sdk.dev/docs/ai-sdk-core/generating-text — generateText/streamText
https://ai-sdk.dev/docs/agents/overview — Agent 추상화
https://ai-sdk.dev/docs/ai-sdk-ui/chatbot — useChat
https://ai-sdk.dev/docs/ai-sdk-core/embeddings — embed/embedMany
https://ai-sdk.dev/docs/migration-guides/migration-guide-7-0 — v7 breaking changes
https://ai-sdk.dev/docs/ai-sdk-core/generating-structured-data — 구조화 출력
https://ai-sdk.dev/providers/ai-sdk-providers/anthropic — Anthropic 프로바이더
https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling — tool() 헬퍼
https://ai-sdk.dev/docs/ai-sdk-core/provider-management — 프로바이더 교체
https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0 — v6 breaking changes

CLI 우회 (npm registry, 2026-07-25 실행)

npm view ai version / npm view ai dist-tags / npm view ai time
npm view @ai-sdk/{anthropic,openai,google,react,provider,harness,vue} version

확인된 사실 [신뢰도]

버전 (npm registry, 실측)

[HIGH] ai 패키지 최신(latest) = 7.0.37, 발행 2026-07-23T22:31Z. (npm CLI npm view ai version → 7.0.37; time 필드로 날짜 확인) 출처: registry.npmjs.org [HIGH] ai dist-tags 실측:

alpha:   5.0.0-alpha.15
canary:  7.0.0-canary.176
beta:    7.0.0-beta.187
latest:  7.0.37
ai-v6:   6.0.235
ai-v5:   5.0.220

→ v5·v6·v7 세 메이저 라인이 동시에 유지보수 중. v7 이 current stable. v5 latest=5.0.220, v6 latest=6.0.235 (둘 다 2026-07-23 에도 패치 발행됨). 출처: npm dist-tags [HIGH] 현재 메이저는 v7. 공식 docs 사이드바가 "v7 (Latest)" 표기. 출처: ai-sdk.dev/docs/introduction

프로바이더 패키지 버전 (npm, 실측 2026-07-25)

[HIGH] 다음은 모두 메이저 4 라인 (ai 코어 7 과 버전 번호가 다름 — 독립 버저닝):

@ai-sdk/anthropic  4.0.20
@ai-sdk/openai     4.0.20
@ai-sdk/google     4.0.24
@ai-sdk/react      4.0.40
@ai-sdk/vue        4.0.37
@ai-sdk/provider   4.0.3
@ai-sdk/harness    1.0.43   ← harness 계열은 별도 1.x

→ 주의: 코어 ai 는 7.x 인데 프로바이더/react 는 4.x. 버전 번호가 서로 안 맞는다. 출처: npm

패키지/아키텍처 구조 (3개 surface)

[HIGH] AI SDK 는 3개 표면으로 구성: 1. AI SDK Core — "generateText, structured objects, tool calls, agents 를 위한 통합 API". import: 'ai' 2. AI SDK UI — "chat/generative UI 를 위한 framework-agnostic 훅". import: @ai-sdk/react (등 @ai-sdk/vue, svelte, angular) 3. AI SDK Harnesses — "확립된 agent harness 를 HarnessAgent 로 실행하는 균일 API" (v7 신규 surface) 출처: ai-sdk.dev/docs/foundations/overview [HIGH] harness 패키지들 (npm 실측): @ai-sdk/harness, @ai-sdk/harness-opencode, @ai-sdk/harness-codex, @ai-sdk/harness-claude-code, @ai-sdk/workflow-harness, @ai-sdk/sandbox-vercel. → Claude Code / Codex / opencode 같은 기성 에이전트 하네스를 SDK 로 감쌈. 출처: github releases + npm

지원 프로바이더 (공식 목록 24+)

[HIGH] Vercel AI Gateway, OpenAI, Anthropic, Google Generative AI & Vertex AI, xAI Grok, Azure, Amazon Bedrock, Groq, Mistral, DeepSeek, Cohere, Perplexity, Together.ai, Fireworks, Fal AI, Luma AI, DeepInfra, Cerebras, Baseten 등. 출처: ai-sdk.dev/docs/introduction

핵심 Core API

[HIGH] generateText (import 'ai'): const { text } = await generateText({ model, prompt }). 반환: text, content(모든 step), usage, finishReason. [HIGH] streamText (import 'ai'): 즉시 반환. result.textStream(ReadableStream+AsyncIterable), result.stream(전체 이벤트 스트림 — v7 에서 fullStream 이 stream 으로 개명됨), result.text(Promise), result.usage(Promise). 콜백: onEnd, onError, onChunk. 출처: ai-sdk.dev/docs/ai-sdk-core/generating-text

tool() 헬퍼

[HIGH] import { tool } from 'ai'. 필드: - description — 선택. 툴 선택에 영향 - inputSchema — Zod 또는 JSON schema (⚠️ 필드명이 parameters 아니라 inputSchema. 구버전에서 개명됨) - execute — 선택. async 함수, 툴 입력으로 호출 - strict — 선택 boolean, strict tool calling

const weatherTool = tool({
  description: 'Get the weather in a location',
  inputSchema: z.object({
    location: z.string().describe('The location to get the weather for'),
  }),
  execute: async ({ location }) => ({ location, temperature: 72 }),
});

툴은 이름을 key 로 하는 객체로 전달: tools: { weather: weatherTool }. [HIGH] 멀티스텝: stopWhen: isStepCount(5). (v7 에서 stepCountIs() → isStepCount() 개명). 반환에 steps 포함. 출처: ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling

Agent 추상화 (v7)

[HIGH] 메인 클래스 = ToolLoopAgent (v6 에서 Experimental_Agent → ToolLoopAgent 로 개명·안정화).

const agent = new ToolLoopAgent({ model, tools: {...} });
const result = await agent.generate({ prompt: '...' });
// result.text, result.steps

"LLM 이 tool 을 loop 안에서 써서 task 완수". 루프·컨텍스트 관리·정지조건을 자동 처리. [HIGH] 기본 stopWhen 이 v6 에서 step count 1 → 20 으로 변경됨 (Agent 클래스 기준). [HIGH] HarnessAgent — Claude Code 같은 기성 하네스용 별도 추상화. ToolLoopAgent(직접 model+tools 루프)와 구분. 출처: ai-sdk.dev/docs/agents/overview + migration-guide-6-0

UI 훅 useChat

[HIGH] import { useChat } from '@ai-sdk/react'. 반환: messages, sendMessage, status('submitted'|'streaming'|'ready'|'error'), stop, regenerate, error, setMessages. [HIGH] 메시지 parts 모델: 각 메시지는 parts 배열 (type 별 content). message.parts.map(part => part.type === 'text' ? part.text : ...). (v5→v6 breaking change 의 핵심) [HIGH] transport 로 서버 연결:

const { messages, sendMessage, status } = useChat({
  transport: new DefaultChatTransport({ api: '/api/chat' }),
});

서버 route (Next.js):

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();
  const result = streamText({ model, messages: await convertToModelMessages(messages) });
  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  });
}

⚠️ v7 에서 toUIMessageStream() 등은 result 의 메서드가 아니라 stateless 헬퍼 함수로 분리됨. convertToModelMessages 는 async (v6부터). 출처: ai-sdk.dev/docs/ai-sdk-ui/chatbot

프로바이더 교체 (3가지 방법)

[HIGH] (1) 문자열 model ID + AI Gateway (v7 권장 기본): model: "xai/grok-4.5" → "providerId/modelId" 포맷. 전역 프로바이더(기본=gateway)가 라우팅. 예: "openai/gpt-5.1", "google/gemini-2.5-flash", "anthropic/claude-sonnet-4.5". [HIGH] (2) 프로바이더 인스턴스 (기존 방식, 여전히 유효): import { anthropic } from '@ai-sdk/anthropic'; model: anthropic('claude-...'). [HIGH] (3) createProviderRegistry:

import { createProviderRegistry, gateway } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { openai } from '@ai-sdk/openai';
export const registry = createProviderRegistry({ gateway, anthropic, openai });
// registry.languageModel('openai:gpt-5.1')  ← 기본 구분자 ':'

구분자 커스터마이즈: createProviderRegistry({...}, { separator: ' > ' }). [HIGH] customProvider (v7 에서 experimental_customProvider → customProvider 개명): 모델 별칭·설정 프리컨피그:

export const anthropic = customProvider({
  languageModels: {
    opus: gateway('anthropic/claude-opus-4.1'),
    sonnet: gateway('anthropic/claude-sonnet-4.5'),
  },
  fallbackProvider: gateway,
});

출처: ai-sdk.dev/docs/ai-sdk-core/provider-management

Anthropic 프로바이더 상세

[HIGH] 설치 pnpm add @ai-sdk/anthropic. import { anthropic } from '@ai-sdk/anthropic' (기본 인스턴스) 또는 { createAnthropic } (커스텀). [HIGH] API 키: 기본 env ANTHROPIC_API_KEY. 또는 createAnthropic({ apiKey }). bearer 는 authToken/ANTHROPIC_AUTH_TOKEN. [HIGH] 모델 생성: anthropic('claude-...'). 별칭 anthropic.languageModel(), anthropic.chat(), anthropic.messages(). [MED] 문서 예시 모델 ID: claude-opus-4-20250514, claude-sonnet-4-5, claude-haiku-4-5. ⚠️ 이건 AI SDK 문서의 예시일 뿐 — 실제 현행 Anthropic 모델은 위키 §7(claude-api 스킬)이 정본. AI SDK 문서 예시가 Anthropic 최신 모델 ID 를 앞서지 못한다. 출처: ai-sdk.dev/providers/ai-sdk-providers/anthropic

임베딩

[HIGH] import { embed, embedMany } from 'ai'. - embed({ model, value }) → { embedding }. 단일 값 (유사도/클러스터링). - embedMany({ model, values: [...] }) → { embeddings }. 배치 (RAG 데이터스토어 준비). [HIGH] 모델 지정: 문자열 'openai/text-embedding-3-small' 또는 프로바이더 메서드 openai.embeddingModel('text-embedding-3-large'), mistral.embeddingModel('mistral-embed'). 출처: ai-sdk.dev/docs/ai-sdk-core/embeddings

구조화 출력 (v7 방식)

[HIGH] v7 권장: generateText/streamText 의 output 프로퍼티 + Output.* 헬퍼 (import { Output } from 'ai'): - Output.object({ schema }) — Zod 스키마 구조화 객체 - Output.array({ element }) — 배열 - Output.choice({ options }) — 문자열 선택지 중 택1 (enum) - Output.json() — 스키마 없는 JSON - Output.text() — 평문

const { output } = await generateText({
  model,
  output: Output.object({ schema: z.object({ name: z.string(), age: z.number().nullable() }) }),
  prompt: 'Generate a lasagna recipe.',
});

[HIGH] 구버전 generateObject/streamObject 는 v6 에서 deprecated (여전히 존재하지만 output 방식 권장). 출처: migration-guide-6-0 + generating-structured-data

마이그레이션 노트 (뭐가 깨졌나)

v6 → v7 breaking changes [HIGH] (migration-guide-7-0)

system 옵션 → instructions (모든 텍스트 생성 함수에서). messages 안 system 메시지는 기본 거부 → instructions 쓰거나 allowSystemInMessages: true.
experimental_ 접두사 대거 제거: experimental_output→output, experimental_prepareStep→prepareStep, experimental_activeTools→activeTools, experimental_telemetry→telemetry, experimental_generateImage→generateImage, experimental_transcribe→transcribe, experimental_generateSpeech→generateSpeech, experimental_customProvider→customProvider.
streamText: result.fullStream→result.stream. toUIMessageStream()/toUIMessageStreamResponse() 가 result 메서드→stateless 헬퍼. includeRawChunks→include.rawChunks. request/response body 기본 제외 (include:{requestBody:true}).
stepCountIs()→isStepCount().
콜백 개명: onFinish→onEnd (deprecated onFinish 는 아직 수용), onStepFinish→onStepEnd, experimental_onToolCallStart→onToolExecutionStart 등.
멀티스텝 누적 변경: top-level content/toolCalls/toolResults/usage 가 이제 모든 step 합산 (전엔 마지막 step 만). 마지막 step 전용 데이터(reasoning, request, response, providerMetadata)는 finalStep 프로퍼티로 이동. totalUsage deprecated.
툴: ToolCallOptions→ToolExecutionOptions. needsApproval→toolApproval 세팅. experimental_context→context, 공유 런타임 데이터는 runtimeContext.
usage 필드: usage.cachedInputTokens→usage.inputTokenDetails.cacheReadTokens, usage.reasoningTokens→usage.outputTokenDetails.reasoningTokens.
telemetry: OpenTelemetry 가 별도 @ai-sdk/otel 패키지로 분리. 시작 시 registerTelemetry() 호출. opt-out 로 전환.
content parts: {type:'media'}→{type:'file-data'}. image part deprecated→file part + mediaType:'image'.
런타임: 최소 Node.js 22 (18/20 미지원). ESM only — CommonJS require() 불가.

v5 → v6 breaking changes [HIGH] (migration-guide-6-0)

Agent: Experimental_Agent → ToolLoopAgent. system→instructions. 기본 stopWhen step count 1→20.
메시지 타입: CoreMessage 완전 제거. convertToCoreMessages→convertToModelMessages (async — Tool.toModelOutput() async 지원).
구조화 출력: generateObject/streamObject deprecated → generateText/streamText output 세팅으로.
툴 정의: 툴이 더 이상 name 프로퍼티 안 받음 (객체 key 로만). toModelOutput() 가 { output } 받음.
UI 헬퍼 개명: isToolUIPart→isStaticToolUIPart, isToolOrDynamicToolUIPart→isToolUIPart 등 (static vs dynamic 명확화).
프로바이더별: OpenAI strictJsonSchema 기본 true. Azure 기본 Responses API. Google Vertex providerMetadata key google→vertex.
(검색 스니펫 [MED]) "useChat message-parts 모델, tool-call 스트리밍 lifecycle, provider-adapter 계약, 스트리밍 wire format" 4개 축 동시 breaking. → parts 모델이 useChat 의 v6 핵심 변화.

엇갈리거나 미확인

[불일치 해소됨] WebSearch 스니펫이 "v4→v6→v7", 일부는 "AI SDK 7 (2026-06-25)" 주장. npm registry 실측이 정본: latest=7.0.37 (2026-07-23), v5/v6 라인도 유지보수 중. current major = v7 확정.
[미확인] v7 정식 GA 날짜. GitHub releases WebFetch 가 monorepo release-please 태그를 오독(harness 패키지, 2025 날짜 등) — 신뢰 불가. v7 릴리스 날짜는 확정 못 함. (npm time 로 7.0.x 는 2026-07 초에 이미 존재 확인)
[미확인] generateObject/streamObject 가 v7 에서 완전 제거됐는지 vs 여전히 deprecated 로 남아있는지. v6 에서 deprecated 확인. v7 migration 문서엔 완전 제거 언급 없어 — 아직 export 되나 deprecated 로 추정([MED]).
[미확인] @ai-sdk/anthropic 등 프로바이더가 왜 4.x 인데 코어는 7.x 인지 정확한 버저닝 정책. 관찰된 사실만 기록.
[MED, AI SDK 문서 예시일 뿐] AI SDK Anthropic 문서의 모델 ID 예시(claude-opus-4-20250514 등)는 위키 §7 정본과 다르며 구식. 위키 페이지엔 §7 을 쓰고 AI SDK 예시 ID 는 인용하지 말 것.
[주의] AI Gateway 문자열 model ID 예시들(xai/grok-4.5, openai/gpt-5.1, anthropic/claude-opus-4.1, google/gemini-2.5-flash)은 docs 예시에서 나온 것 — 실제 각 프로바이더 현행 모델명은 별도 검증 필요.

⛔ DO-NOT-CITE (저신뢰·검증불가 2차 블로그)

WebSearch 에서 나온 아래 2차 소스는 버전·날짜가 npm 정본과 어긋나거나 SEO 스팸성. 위키에 인용 금지: - dev.to/bean_bean "Ultimate Guide ... 2026" — "v4+" 주장 (구식/부정확) - digitalapplied.com "v5 to v6 Migration Playbook 2026" — 미검증 - developersdigest.tech "AI SDK 7: Production Agent Upgrade" — "2026-06-25 ship" 날짜 미검증 - releasebot.io / releases.sh — aggregator, 미검증

이들 대신 ai-sdk.dev 공식 docs + npm registry 실측만 인용할 것.

원문 발췌 (검증된 코드, 공식 docs verbatim)

generateText 최소형 (foundations/overview):

import { generateText } from "ai";
const { text } = await generateText({
  model: "xai/grok-4.5",
  prompt: "What is love?",
});

ToolLoopAgent (agents/overview):

const weatherAgent = new ToolLoopAgent({ model: "xai/grok-4.5", tools: {...} });
const result = await weatherAgent.generate({ prompt: 'What is the weather in SF?' });

embed / embedMany (ai-sdk-core/embeddings):

import { embed, embedMany } from 'ai';
const { embedding } = await embed({ model: 'openai/text-embedding-3-small', value: 'sunny day' });
const { embeddings } = await embedMany({ model: 'openai/text-embedding-3-small', values: ['a','b'] });

Anthropic 프로바이더 (providers/anthropic):

import { anthropic } from '@ai-sdk/anthropic';
import { generateText } from 'ai';
const { text } = await generateText({
  model: anthropic('claude-haiku-4-5'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.'
});

npm dist-tags 실측 (2026-07-25):

latest: 7.0.37   ai-v6: 6.0.235   ai-v5: 5.0.220
beta: 7.0.0-beta.187   canary: 7.0.0-canary.176
@ai-sdk/anthropic 4.0.20  @ai-sdk/openai 4.0.20  @ai-sdk/react 4.0.40  @ai-sdk/google 4.0.24