ai-sdk

ai-sdk 스킬 개요

이 ai-sdk 스킬로 할 수 있는 일

ai-sdk 스킬은 Vercel의 AI SDK로 개발하는 사람을 위한 실전형 가이드입니다. 특히 일반적인 LLM 조언이 아니라, 현재 버전 기준으로 정확한 도움을 받아야 할 때 유용합니다. 이 스킬의 핵심 역할은 앱에 chat, streaming, tools, structured generation, embeddings, agents를 붙일 때 올바른 API 형태를 고르고, 최신 문법을 확인하고, 오래된 패턴을 피하도록 돕는 것입니다.

어떤 사람이 ai-sdk 스킬을 설치하면 좋은가

특히 잘 맞는 사용자는 다음과 같습니다.

• ai-sdk for Full-Stack Development를 검토 중인 풀스택 개발자
• 오래된 AI SDK 코드를 최신 API로 마이그레이션해야 하는 팀
• generateText, streamText, tools, ToolLoopAgent, useChat를 사용하는 개발자
• OpenAI, Anthropic, Google, gateway 기반 접근 방식 사이에서 provider 설정을 비교하려는 사람
• 단순한 "AI 코드 써줘" 프롬프트보다 시행착오를 줄이고 싶은 빌더

일반 프롬프트보다 이 ai-sdk 스킬이 더 유용한 이유

이 스킬의 가장 큰 차별점은 AI SDK에 대한 모델 내부 지식이 자주 오래되어 있다는 점을 명시적으로 경고한다는 데 있습니다. 기억에 의존하지 않고, 로컬 패키지 문서, 소스 코드 확인, 그리고 자주 바뀌는 API, gateway 사용법, devtools, type-safe agent 패턴 같은 구체적 레퍼런스를 먼저 보도록 안내합니다. 그래서 이 ai-sdk 스킬은 일반적인 프롬프트보다 설치 판단과 실제 구현 작업에서 더 신뢰할 수 있습니다.

도입 전에 가장 먼저 확인해야 할 것

사용자들이 보통 먼저 궁금해하는 점은 다음과 같습니다.

• 우선 ai만 설치하면 되는지
• provider 패키지는 나중에 어떻게 고르는지, 처음부터 과하게 설치하지 않아도 되는지
• 최근에 어떤 API가 바뀌었는지
• 온라인에서 찾은 useChat 예제가 아직 유효한지
• tool loop와 streamed run을 어떻게 디버깅하는지
• 이 SDK가 server route, React UI, 혹은 둘 다에 맞는지

이런 점이 막히는 지점이라면, 이 페이지가 시간을 많이 아껴줄 것입니다.

ai-sdk 스킬 사용법

최소 ai-sdk 설치 경로부터 시작하기

먼저 가능한 한 가장 작은 설치 단계로 시작하세요.

pnpm add ai

여기서 저장소 가이드가 의도하는 바는 분명합니다. 처음에는 핵심 패키지인 ai만 설치하세요. 실제 사용 사례가 필요해지기 전까지는 @ai-sdk/openai, @ai-sdk/react 같은 provider/client 패키지를 바로 추가하지 않는 것이 좋습니다. 이렇게 하면 잘못된 전제를 줄이고, 현재 문서 기준으로 구현을 맞춰 가기 쉬워집니다.

GitHub 스킬 자체를 agent workflow에 설치하려면 다음을 사용하세요.

npx skills add vercel/ai --skill ai-sdk

코드 요청 전에 로컬 문서를 먼저 확인하기

핵심 사용 패턴은 "기억에 기대어 묻기"가 아닙니다. 순서는 아래와 같습니다.

1. node_modules/ai/docs/가 있는지 확인합니다.
2. node_modules/ai/docs/와 node_modules/ai/src/를 검색합니다.
3. 그다음에만 ai-sdk.dev 또는 저장소 레퍼런스를 참고합니다.

이것이 ai-sdk 가이드에서 가장 중요한 실무 습관입니다. AI SDK API는 빠르게 바뀌고, 공개된 예제는 그 변화를 따라오지 못하는 경우가 많기 때문입니다.

먼저 읽어야 할 파일

빠르게 감을 잡고 싶다면 다음 순서로 보세요.

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

이 순서가 잘 작동하는 이유는 다음과 같습니다.

• SKILL.md는 언제 이 스킬을 써야 하는지와 기본 워크플로를 알려줍니다
• common-errors.md는 API 이름 변경 함정을 초기에 잡아줍니다
• ai-gateway.md는 빠르게 동작하는 모델 연결까지 가는 데 도움이 됩니다
• devtools.md는 코드가 실행된 뒤 디버깅 효율을 높여줍니다
• type-safe-agents.md는 UI와 agent 타입을 맞춰야 할 때 중요합니다

코드 작성 전에 현재 API 변화부터 파악하기

도입을 막는 대표적인 원인 중 하나는 오래된 예제를 그대로 복사하는 것입니다. 레퍼런스에는 ai-sdk 사용에 실질적으로 영향을 주는 변경 사항이 몇 가지 명시되어 있습니다.

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• tool parameters → inputSchema
• 일부 오래된 object generation 패턴 변경
• useChat는 많이 바뀌었으므로 재사용 전에 반드시 검증 필요

처음 스킬에 요청할 때 현재 패키지 버전과 레거시 코드를 함께 주면, 마이그레이션 정확도가 훨씬 좋아집니다.

빠르게 첫 성공을 만들고 싶다면 AI Gateway 사용하기

많은 팀에게 가장 빠른 시작 경로는 gateway 기반 설정입니다. 이 스킬에는 Vercel AI Gateway에 대한 유용한 레퍼런스가 포함되어 있고, 여기서는 아래처럼 문자열로 모델을 선택할 수 있습니다.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

이 방식은 provider SDK 연결 작업 자체보다, 제품 동작을 빠르게 검증하는 것이 더 중요한 상황에서 특히 유용합니다.

어떤 모델 ID든 하드코딩하기 전에 현재 모델 목록을 먼저 조회하세요. 레퍼런스에서도 모델 이름은 기억에 의존하지 말라고 분명히 경고합니다.

ai-sdk 스킬에 어떤 입력을 주어야 하는가

스킬이 적절한 패키지 구성과 API 패턴을 고를 수 있도록 충분한 맥락을 주세요. 좋은 요청에는 보통 다음이 포함됩니다.

• 런타임: Next.js, Node.js, Vercel, edge/serverless 등
• 목표: chat UI, agent, RAG, structured extraction, tool calling
• 현재 패키지 버전
• streaming 필요 여부
• provider 선호 또는 gateway 사용 여부
• React hooks가 필요한지, 서버 전용인지 같은 프런트엔드 요구사항
• 실패한 코드와 정확한 에러 메시지

약한 입력:

• "Help me use AI SDK"

강한 입력:

• "I have a Next.js app router project on AI SDK 6, need streaming chat with tool calling, want to start with gateway, and my old useChat code no longer works. Show the minimal server route and UI shape."

두 번째 프롬프트처럼 주면, 스킬이 관련 문서와 최신 API 이름으로 훨씬 정확하게 범위를 좁힐 수 있습니다.

막연한 목표를 더 좋은 ai-sdk 프롬프트로 바꾸기

좋은 공식은 다음과 같습니다.

• 앱 맥락
• 원하는 사용자 경험
• 현재 구현 상태
• 제약 조건
• 기대하는 출력 형식

예시:

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

이 방식은 단순히 "agent 만들어줘"라고 묻는 것보다 훨씬 낫습니다. 스킬이 일반적인 스캐폴딩으로 흘러가지 않도록 필요한 구조를 미리 제공하기 때문입니다.

흔한 작업별로 맞는 워크플로 선택하기

작업 종류에 따라 스킬을 다르게 쓰세요.

• 첫 설치라면: 최소 패키지 조합과 단일 동작 요청 하나를 요청
• 마이그레이션이라면: 기존 코드를 붙여 넣고 API 이름 변경과 동작 차이를 질문
• tool calling이라면: tool schema 형태와 stop condition을 질문
• 프런트엔드 chat이라면: 현재 기준의 useChat 패턴을 구체적으로 요청
• 디버깅이라면: DevTools로 run을 확인하는 방법과 trace 저장 위치를 질문

이처럼 작업 기준으로 프롬프트를 나누는 지점에서 ai-sdk 스킬은 단순한 저장소 훑기보다 더 큰 가치를 냅니다.

코드가 실행되지만 동작이 이상할 때는 DevTools 사용하기

코드는 컴파일되는데 모델 동작이 예상과 다르다면, DevTools 레퍼런스의 가치가 높습니다. SDK 호출, step, tool interaction을 아래 파일에 기록해 확인할 수 있습니다.

.devtools/generations.json

특히 다음 같은 문제에 유용합니다.

• 겉으로 드러나지 않는 tool-call loop
• 잘못된 structured output
• prompt와 tool의 불일치
• 이해하기 어려운 streamed 동작
• agent run 중 token과 step 점검

도입 판단 관점에서도 이것은 중요합니다. 초기 설치 이후의 디버깅 비용을 낮춰주기 때문입니다.

UI 렌더링이 중요하다면 type-safe agent 패턴 사용하기

agent 기반 UI를 만들고 있다면, type-safe agent 레퍼런스는 이 스킬이 단순한 예제 수준을 넘는다는 강한 신호입니다. 이 레퍼런스는 agent 정의에서 추론된 UIMessage 타입을 export하는 패턴을 보여주며, 그 결과 useChat 렌더링의 안정성이 높아집니다.

이는 특히 ai-sdk for Full-Stack Development에 중요합니다. 백엔드 agent 설정과 프런트엔드 메시지 렌더링이 서로 어긋나지 않아야 하기 때문입니다.

잘 맞지 않는 경우

주로 아래가 필요하다면 이 스킬은 선택하지 않는 편이 낫습니다.

• ai 패키지와 무관한 provider 전용 SDK 문서
• 구현 작업 없이 일반적인 프롬프트 엔지니어링 조언
• Python 중심 AI 애플리케이션 가이드
• 프레임워크와 무관한 LLM 이론

이 스킬은 JavaScript/TypeScript 스택에서 AI SDK를 구현하거나 디버깅하는 질문일 때 가장 잘 맞습니다.

ai-sdk 스킬 FAQ

초보자에게도 ai-sdk 스킬이 괜찮은가요?

네, 기본적인 JavaScript나 TypeScript에 익숙하다면 괜찮습니다. 이 스킬은 첫 단계를 좁혀준다는 의미에서 초보자 친화적이지만, 프로젝트 파일 수정, 패키지 설치, 프레임워크 관례 이해 정도는 할 수 있다고 가정합니다.

ai-sdk 스킬이 문서 읽기를 대신하나요?

아니요. 이 스킬은 어디를 봐야 하고 어떤 최신 패턴을 믿어야 하는지 안내하는 라우팅 레이어로 쓰는 것이 가장 좋습니다. 핵심 가치는 원문 문서를 대체하는 데 있는 것이 아니라, 잘못된 방향으로 새는 시간을 줄이는 데 있습니다.

ai-sdk 설치 전에 가장 크게 주의할 점은 무엇인가요?

AI SDK 문법에 대해 오래된 예제나 모델의 기억을 믿지 마세요. 저장소는 설치된 문서와 소스를 먼저 확인하라고 반복해서 강조합니다. 이것은 사소한 주의사항이 아니라, 올바른 ai-sdk install과 구현의 핵심 전제입니다.

provider 패키지를 처음부터 전부 설치해야 하나요?

대개는 아닙니다. ai부터 시작하고, 실제 사용 사례가 생길 때만 provider나 client 패키지를 추가하세요. 그래야 의존성 선택에 의도가 생기고, 오래된 가정을 그대로 설정에 끌고 들어오는 일을 줄일 수 있습니다.

이건 주로 chat 앱용인가요?

아니요. chat이 대표적인 사용 사례이긴 하지만, 이 스킬은 structured generation, tool calling, agents, embeddings, gateway 기반 모델 접근, streamed server response에도 잘 맞습니다.

그냥 LLM에게 AI SDK 코드를 써 달라고 하는 것과 무엇이 다른가요?

일반 프롬프트는 이미 폐기된 API를 그럴듯하게 만들어낼 수 있습니다. 이 스킬이 더 나은 이유는 검증 워크플로를 강제하기 때문입니다. 즉, 로컬 문서, 최신 레퍼런스, 알려진 마이그레이션 함정, 필요한 파일 우선 읽기까지 포함합니다. 그 결과 신뢰도는 올라가고 재작업은 줄어듭니다.

React와 useChat에도 도움이 되나요?

네. 다만 주의가 필요합니다. useChat는 크게 바뀌었기 때문에 오래된 코드 조각은 의심하고 보는 편이 좋습니다. UI 예제를 복사하기 전에 현재 형태를 이 스킬로 먼저 검증하세요.

어떤 경우에는 이 ai-sdk 가이드를 쓰지 말아야 하나요?

문제가 주로 vendor 과금, 모델 평가 전략, 비 JS 플랫폼 연동이라면 굳이 이 가이드를 볼 필요는 없습니다. 현재 AI SDK 구현 디테일이 막히는 지점일 때 사용하는 것이 맞습니다.

ai-sdk 스킬을 더 잘 활용하는 방법

목표만 말하지 말고 버전 정보를 함께 주기

결과 품질을 가장 빨리 높이는 방법은 정확한 버전을 포함하는 것입니다. 특히 ai와 관련 패키지 버전이 중요합니다. 많은 실패가 "AI SDK 코드 알려줘"라고만 하고, 최신 릴리스인지 오래된 코드를 마이그레이션 중인지 밝히지 않아서 발생합니다.

처음에는 최소 동작 단위부터 요청하기

"내 agent 앱 전체를 만들어줘"보다 더 좋은 방식은 다음과 같습니다.

• "show the smallest generateText example"
• "add one tool"
• "then stream it"
• "then wire useChat"

이런 점진적 워크플로는 ai-sdk 가이드를 훨씬 효과적으로 만듭니다. 복잡도가 커지기 전에 각 단계를 현재 문서와 대조해 검증할 수 있기 때문입니다.

에러는 그대로 보여주기

뭔가 깨졌다면 정확한 에러와 관련 코드 조각을 함께 주세요. common-errors.md 레퍼런스가 있는 이유는 많은 문제가 비슷하지만 미묘하게 다른 API 이름에서 생기기 때문입니다. 정확한 에러 하나만 있어도, 오래된 문서를 보고 있는지, 잘못된 패키지 import를 썼는지, 옵션 이름이 낡았는지 빠르게 판단할 수 있습니다.

gateway를 쓸지 direct provider 설정을 쓸지 명확히 말하기

처음부터 아래 중 하나를 지정하면 애매함이 크게 줄어듭니다.

• "Use Vercel AI Gateway first"
• "Use direct OpenAI provider package"
• "Keep provider choice abstract for now"

이 선택에 따라 설치 명령, 모델 선택, 예제 구조가 달라집니다.

런타임과 프레임워크 경계를 분명히 하기

더 정확한 ai-sdk 사용 도움을 받으려면 다음을 밝혀 주세요.

• server-only인지, client + server인지
• Next.js App Router인지 다른 프레임워크인지
• edge 런타임인지 Node 런타임인지
• TypeScript strictness 수준
• tools가 내부 API를 호출하는지 외부 서비스를 호출하는지

이런 정보는 어떤 코드가 "맞는 코드"인지에 직접 영향을 줍니다.

자주 발생하는 실패 패턴 주의하기

품질을 가장 많이 떨어뜨리는 원인은 다음과 같습니다.

• 오래된 useChat 예제에 의존하기
• 폐기된 옵션 이름을 복사하기
• 오래된 모델 ID를 하드코딩하기
• 너무 많은 패키지를 너무 일찍 설치하기
• tools와 stop condition을 정의하지 않은 채 agent 코드를 요청하기
• run trace 대신 console log만으로 디버깅하기

이 함정만 피해도 ai-sdk 스킬의 신뢰도는 훨씬 높아집니다.

두 가지 구현 경로를 비교해 달라고 요청하기

좋은 개선 방법 중 하나는 코드만이 아니라 "판단"을 요청하는 것입니다. 예를 들어:

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

이런 프롬프트는 "문서 보여줘"보다 도입 판단에 훨씬 유용한 답을 끌어냅니다.

첫 답변 뒤에는 근거를 붙여서 다시 질문하기

첫 결과를 받은 뒤에는 아래 중 하나를 덧붙여 품질을 높이세요.

• 현재 파일 트리
• 설치된 패키지 목록
• 정확히 실패하는 요청
• 캡처한 .devtools/generations.json 일부
• node_modules/ai/docs/에서 가져온 로컬 문서 일부

이처럼 근거를 붙여 반복하는 방식이야말로 ai-sdk 스킬을 일반적인 가이드에서 실제 구현 수준의 도움으로 끌어올리는 가장 좋은 방법입니다.