ai

1. 프로젝트 개요

AI SDK(vercel/ai)는 Vercel과 Next.js 팀이 만든 제공자에 종속되지 않는 TypeScript 툴킷으로, AI 기반 애플리케이션과 에이전트를 구축하기 위한 것입니다. 개발자에게 수십 개의 모델 제공자와 UI 프레임워크에서 텍스트, 구조화된 데이터, 에이전트 워크플로를 생성할 수 있는 단일 통합 API를 제공합니다.

2. 배경 및 포지셔닝

AI SDK는 AI 애플리케이션 개발의 반복적인 문제점을 해결하기 위해 만들어졌습니다. 모든 모델 제공자(OpenAI, Anthropic, Google 등 수십 개)가 자체 SDK, 요청 형식, 스트리밍 프로토콜을 제공하여, 개발자가 모델을 변경하거나 대체 제공자를 추가할 때마다 통합 코드를 다시 작성해야 했습니다. AI SDK의 핵심 임무는 이러한 차이를 하나의 일관된 인터페이스 뒤로 추상화하는 것입니다. generateText, streamText, generateObject 및 에이전트 기본 요소는 뒤에 어떤 모델이 있든 관계없이 모두 동일한 방식으로 작동합니다.

유사한 프로젝트와 비교하여 AI SDK는 다음과 같은 차별성을 갖습니다:

• 클라이언트 측에서 프레임워크에 종속되지 않으며(Next.js, React, Svelte, Vue, Angular) 서버 측에서는 런타임에 종속되지 않습니다(Node.js, 엣지 런타임, 서버리스 함수).
• 단일 모델 문자열로 16개 이상의 제공자에 걸쳐 100개 이상의 모델에 대한 액세스를 제공하는 기본 제공 게이트웨이(Vercel AI Gateway)를 제공하여, 시작하기 위해 별도의 제공자 패키지가 필요하지 않습니다.
• 채팅 완성을 둘러싼 얇은 래퍼가 아닌 에이전트를 일급 개념(ToolLoopAgent)으로 취급하며, 도구 호출, 내구성이 있는 장기 실행 워크플로, 샌드박스된 코드 실행에 대한 기본 지원을 제공합니다.
• Core(서버/엣지 로직), UI(클라이언트 훅), RSC(스트리밍 React Server Components) 간의 엄격한 분리를 유지하여, 팀이 필요한 계층만 채택할 수 있도록 합니다.

3. 기능 카테고리

• 🤖 모델 제공자(40개 이상 패키지) — 통합 API를 특정 LLM 공급업체 및 추론 플랫폼에 연결하는 어댑터입니다.

  • @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google — 가장 널리 사용되는 세 가지 제공자입니다.
  • @ai-sdk/xai, @ai-sdk/mistral, @ai-sdk/groq, @ai-sdk/cohere — 추가적인 주요 호스팅 모델 제공자입니다.
  • @ai-sdk/amazon-bedrock, @ai-sdk/azure, @ai-sdk/google-vertex — 클라우드 플랫폼 네이티브 모델 액세스입니다.
  • @ai-sdk/openai-compatible — OpenAI 호환 추론 엔드포인트(자체 호스팅 또는 타사)용 일반 어댑터입니다.

• 🎙️ 음성 및 오디오(7개 패키지) — 전사 및 음성 생성용 제공자입니다.

  • @ai-sdk/deepgram, @ai-sdk/assemblyai, @ai-sdk/revai, @ai-sdk/gladia — 음성-텍스트 전사입니다.
  • @ai-sdk/elevenlabs, @ai-sdk/cartesia, @ai-sdk/lmnt, @ai-sdk/hume — 텍스트-음성 및 음성 합성입니다.

• 🎨 이미지 및 비디오 생성(6개 패키지) — 시각적 미디어 생성용 제공자입니다.

  • @ai-sdk/replicate, @ai-sdk/fal, @ai-sdk/black-forest-labs — 이미지 생성 및 호스팅 모델 추론입니다.
  • @ai-sdk/luma, @ai-sdk/klingai, @ai-sdk/minimax — 비디오 및 멀티모달 생성입니다.

• 🖼️ UI 프레임워크 통합(5개 패키지) — 채팅 및 생성형 인터페이스 구축을 위한 클라이언트 측 훅입니다.

  • @ai-sdk/react, @ai-sdk/vue, @ai-sdk/svelte, @ai-sdk/angular — 프레임워크별 채팅/완성 훅입니다.
  • @ai-sdk/rsc — 생성형 UI를 위한 스트리밍 React Server Components 지원입니다.

• 🧩 에이전트 인프라(10개 이상 패키지) — 자율적이고 내구성이 있는 에이전트를 위한 빌딩 블록입니다.

  • ai(핵심 ToolLoopAgent) — SDK의 핵심이 되는 도구 호출 에이전트 루프입니다.
  • @ai-sdk/mcp — 도구 상호 운용성을 위한 Model Context Protocol 클라이언트/서버 지원입니다.
  • @ai-sdk/workflow, @ai-sdk/workflow-harness — 내구성이 있는 장기 실행 에이전트 워크플로입니다.
  • @ai-sdk/sandbox-vercel, @ai-sdk/sandbox-just-bash — 에이전트를 위한 샌드박스된 코드 실행 환경입니다.
  • @ai-sdk/harness-claude-code, @ai-sdk/harness-codex, @ai-sdk/harness-opencode — 인기 있는 코딩 에이전트 하네스와의 통합입니다.

• 🛠️ 개발자 도구(6개 패키지) — AI SDK 앱을 구축하고 운영하기 위한 지원 인프라입니다.

  • @ai-sdk/gateway — Vercel AI Gateway로의 통합 라우팅입니다.
  • @ai-sdk/otel — 관측 가능성을 위한 OpenTelemetry 계측입니다.
  • @ai-sdk/devtools, @ai-sdk/tui — 디버깅 및 터미널 UI 유틸리티입니다.
  • @ai-sdk/provider, @ai-sdk/provider-utils — 새로운 제공자 패키지가 구현해야 하는 저수준 계약입니다.

4. 주요 특징

• 통합 모델 API — 단일 문자열을 변경하는 것만으로 OpenAI, Anthropic, Google 및 100개 이상의 다른 모델 간에 전환할 수 있으며, 애플리케이션 로직을 다시 작성할 필요가 없습니다.
• 기본 제공 Vercel AI Gateway — 별도의 제공자 SDK를 설치하지 않고도 주요 제공자에 대한 바로 사용 가능한 액세스를 제공하며, 중앙 집중식 속도 제한 및 대체 라우팅을 지원합니다.
• ToolLoopAgent 기본 요소 — 수동 채팅 완성 루프가 아닌, 추론 제어, 도구 호출 및 런타임 컨텍스트가 있는 일급 에이전트 추상화입니다.
• 구조화된 출력 생성 — generateObject/Output.object는 Zod(또는 Valibot)를 통해 스키마가 검증된 JSON을 생성하여, 취약한 프롬프트 기반 JSON 파싱을 제거합니다.
• 내구성 있는 워크플로 및 샌드박스 — 재시작 후에도 유지되는 장기 실행 에이전트 워크플로와 안전하게 코드를 실행해야 하는 에이전트를 위한 샌드박스된 실행 환경을 제공합니다.
• 프레임워크에 종속되지 않는 스트리밍 UI — 동일한 스트리밍 채팅/생성형 UI 훅이 Next.js, React, Svelte, Vue 및 Angular에서 작동합니다.

5. 역할별 사용 사례

• 일반 개발자 — 기본 모델에 관계없이 일관된 API를 사용하여 Next.js/React/Vue/Svelte 앱에서 챗봇, 코파일럿 및 생성형 UI 기능을 구축합니다.
• DevOps/SRE — 관측 가능성을 위해 @ai-sdk/otel를 사용하고, 모델 제공자 간의 중앙 집중식 속도 제한, 대체 및 비용 추적을 위해 Vercel AI Gateway를 사용합니다.
• 데이터/연구 과학자 — 제공자별 요청 형식을 수동으로 작성할 필요 없이 generateObject 및 ToolLoopAgent로 구조화된 데이터 추출 및 다단계 추론 파이프라인을 프로토타입화합니다.
• 프로젝트 관리자 — 장기적인 유지 관리의 신호로 대규모 기여자 기반, 주간 다운로드 볼륨 및 활발한 릴리스 주기(AI SDK 6/7)를 통해 프로젝트의 성숙도를 평가합니다.

6. 시작하기

필요한 항목 찾기 — 제공자 디렉터리 및 API 참조를 탐색하여 사용 사례에 맞는 제공자 패키지 또는 기본 요소(generateText, streamText, ToolLoopAgent)를 식별합니다.

설치 및 통합

npm install ai
npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'openai/gpt-5.4', // Vercel AI Gateway를 통해 라우팅됨
  prompt: '에이전트란 무엇입니까?',
});

코딩 에이전트 사용자는 npx skills add vercel/ai로 리포지토리에 AI SDK 스킬을 직접 추가할 수도 있습니다.

기여하기 — CONTRIBUTING.md를 읽어보세요. 이 프로젝트는 현재 요청되지 않은 대규모 풀 리퀘스트보다 고품질 이슈(명확한 재현, 실패한 테스트)를 우선시하므로, 본격적인 작업을 시작하기 전에 이슈 트래커를 확인하세요.

7. 프로젝트 구조

ai/
├── packages/              # 게시된 모든 패키지 (core, providers, UI, agents)
│   ├── ai/                 # 핵심 SDK: generateText, streamText, ToolLoopAgent
│   ├── openai/ anthropic/ google/ ...  # 모델 제공자 어댑터
│   ├── react/ vue/ svelte/ angular/ rsc/  # UI 프레임워크 통합
│   ├── mcp/ workflow/ sandbox-vercel/     # 에이전트 인프라
│   └── provider/ provider-utils/          # 새로운 제공자 구축을 위한 계약
├── apps/
│   └── docs/               # ai-sdk.dev 문서 사이트
├── content/                # 문서 소스 콘텐츠
├── examples/               # 실행 가능한 예제 애플리케이션
├── skills/                 # 코딩 에이전트 스킬 정의
├── tools/                  # 내부 빌드/개발 유틸리티
└── CONTRIBUTING.md

packages/ 아래의 각 폴더는 독립적으로 버전이 관리되는 npm 패키지입니다. 제공자 패키지는 packages/provider에 정의된 공유 계약을 구현하므로 동일한 generateText/streamText API에 연결됩니다.

8. 관련 생태계

• Next.js — AI SDK가 함께 구축되고 가장 일반적으로 배포되는 프레임워크입니다.
• Vercel AI Gateway — 제공자별 설정 없이 100개 이상의 모델에 대한 액세스를 제공하는 기본 라우팅 계층입니다.
• Vercel Sandbox — @ai-sdk/sandbox-vercel이 에이전트 코드 실행에 사용하는 안전한 실행 환경입니다.
• Zod / Valibot — 구조화된 출력 생성에 사용되는 스키마 검증 라이브러리입니다.
• Model Context Protocol (MCP) — @ai-sdk/mcp가 에이전트 생태계 전반에 걸쳐 도구 상호 운용성을 위해 구현하는 개방형 프로토콜입니다.
• LangChain / LlamaIndex — 전용 어댑터 패키지를 통해 선택적 오케스트레이션 계층으로 지원됩니다.

9. 라이선스

이 프로젝트는 Apache License 2.0에 따라 배포됩니다.

• ✅ 상업 및 폐쇄형 소스 제품을 포함하여 자유롭게 사용, 수정 및 배포할 수 있습니다.
• ✅ 기여자로부터 명시적인 특허 허여를 포함합니다.
• ❌ 어떠한 보증도 제공하지 않으며, 기여자는 사용으로 인해 발생하는 손해에 대해 책임을 지지 않습니다.
• ℹ️ 수정된 파일에는 변경이 이루어졌음을 명시하는 공지를 포함해야 하며, 배포 시 라이선스/저작권 공지를 유지해야 합니다.

10. FAQ

Q: 모든 모델 제공자에 대해 별도의 API 키가 필요합니까?
A: 아니요 — 기본적으로 AI SDK는 단일 모델 문자열(예: 'anthropic/claude-opus-4.6')을 사용하여 Vercel AI Gateway를 통해 요청을 라우팅하지만, 직접 연결하기 위해 @ai-sdk/anthropic와 같은 특정 제공자 패키지를 설치할 수도 있습니다.

Q: 원시 텍스트 대신 구조화되고 스키마가 검증된 출력을 얻을 수 있습니까?
A: 네 — generateText와 함께 Output.object(또는 generateObject) 및 Zod 스키마를 사용하여 모델로부터 타입이 지정되고 검증된 JSON을 반환받을 수 있습니다.

Q: AI SDK는 어떤 프런트엔드 프레임워크를 지원합니까?
A: Next.js, React, Svelte, Vue 및 Angular 모두 전용 UI 훅 패키지가 있으며, 핵심 스트리밍 기본 요소는 프레임워크에 종속되지 않습니다.

Q: 코드를 실행하거나 도구를 사용할 수 있는 에이전트를 어떻게 구축합니까?
A: 핵심 ai 패키지에서 ToolLoopAgent를 사용하여 도구를 직접 정의하거나 Model Context Protocol 도구 서버를 위해 @ai-sdk/mcp를 통해 정의합니다. 샌드박스된 코드 실행을 위해 @ai-sdk/sandbox-vercel와 페어링하세요.

Q: 기여하는 가장 좋은 방법은 무엇입니까?
A: 먼저 CONTRIBUTING.md를 확인하세요 — 유지 관리자는 현재 요청되지 않은 전체 구현 풀 리퀘스트보다 명확한 버그 보고서, 최소 재현 및 실패한 테스트를 우선시합니다.

11. 빠른 링크

• 리포지토리: https://github.com/vercel/ai
• 공식 문서: https://ai-sdk.dev/docs
• 기여 가이드: https://github.com/vercel/ai/blob/main/CONTRIBUTING.md
• 커뮤니티: https://vercel.community

12. 요약

AI SDK는 TypeScript 개발자에게 주요 LLM을 호출하고, 구조화된 데이터를 생성하며, 도구를 사용하는 에이전트를 구축할 수 있는 일관된 방법을 제공합니다. 이는 대규모 제공자 생태계, 기본 프레임워크 통합 및 Vercel의 게이트웨이/샌드박스 인프라에 의해 지원됩니다. 공급업체 종속을 피하고, 한 줄 변경으로 모델을 교체하며, 툴킷을 전환하지 않고 간단한 챗봇에서 내구성이 있는 샌드박스 에이전트 워크플로로 확장하려는 프로덕션 AI 기능을 구축하는 팀에 가장 적합합니다.