Vercel AI SDK는 단순한 채팅 라이브러리가 아닙니다. 제대로 사용한다면, 단일 모델 제공업체에 종속되지 않고 UI, streaming (스트리밍), tools (도구), MCP, 구조화된 출력 (structured output), 에이전트 (agents) 및 observability (관측성)를 연결하는 TypeScript 레이어입니다.

Vercel AI SDK는 streaming (스트리밍), chat UI, tool calling (도구 호출), 구조화된 출력 (structured output), 에이전트 (agents) 및 교체 가능한 제공업체를 갖춘 AI 제품을 구축하기 위한 TypeScript 툴킷입니다. 이 SDK의 진정한 가치는 이를 단순한 fetch 래퍼 (wrapper)로 취급하는 것을 넘어, 프론트엔드, 백엔드, tools (도구) 및 observability (관측성) 사이의 계약으로 사용할 때 나타납니다.

TL;DR

주요 키워드는 Vercel AI SDK agentes Next.js입니다. 스페인어권의 검색 의도는 실용적입니다: 토큰을 전송하고, 도구를 호출하며, JSON을 검증하고, MCP와 통합하며, 프로덕션 환경에서 측정 가능한 Next.js 기반의 채팅 또는 에이전트를 구축하는 것입니다.

나의 입장: 만약 당신의 제품이 이미 TypeScript/Next.js 환경에 있고 빠른 반복 (iteration) 속도가 필요하다면 AI SDK는 매우 잘 맞습니다. 이것이 권한 아키텍처, 지속성 (persistence) 또는 평가 (evaluation)를 대체하는 것은 아닙니다. 단지 LLM 부분이 불필요한 접착 코드 (glue code)를 덜 갖도록 만들어 줄 뿐입니다.

Vercel AI SDK란 무엇이며 무엇이 아닌가

Vercel AI SDK는 모델과 통신하고, streams (스트림)를 생성하며, tools (도구)를 정의하고, 입력과 출력을 검증하며, UI에 메시지를 렌더링하고, 제공업체를 연결하기 위한 공통 레이어입니다. 이 SDK의 약속은 모델이 더 잘 추론하게 만드는 것이 아니라, 애플리케이션의 절반을 다시 작성하지 않고도 모델을 변경하고, 도구를 추가하며, 흐름을 운영할 수 있는 안정적인 인터페이스를 제공하는 것입니다.

이것은 데이터베이스가 아니며, 권한 시스템도 아니고, 지속성 큐 (durable queue)도 아닙니다. 만약 에이전트에게 메모리, 감사 (audit), 비즈니스 추적성 또는 긴 작업 (long-running jobs)이 필요하다면, 해당 요소들은 별도로 설계해야 합니다. SDK는 호출과 streams (스트림)를 오케스트레이션할 수 있지만, 제품에 대한 책임은 여전히 당신에게 있습니다.

흔히 하는 실수는 시각적인 채팅부터 시작하는 것입니다. 전문가의 순서는 다릅니다: 유스케이스 (use case), 메시지 계약 (message contract), 허용된 tools (도구), 승인 정책, 비용 제한, 지속성 (persistence), 메트릭 (metrics), 그리고 그 이후에 UI를 구축하는 것입니다.

Vercel AI SDK를 데모에서 제품으로 끌어올리기 위한 최소 아키텍처: 채팅 UI, route handler, 에이전트 (agent), 타입이 지정된 도구 (typed tools), MCP, 데이터 및 메트릭 (metrics).

Next.js에서의 최소 아키텍처

App Router에서의 기본 패턴은 간단합니다: 클라이언트는 useChat을 사용하고, 서버는 route.ts를 노출하며, 핸들러 (handler)는 UI 메시지를 모델 메시지로 변환하고, streamText가 응답을 생성하며, 그 결과가 UI와 호환되는 스트림 (stream)으로 돌아옵니다. 이 체인은 사소해 보일 수 있지만, 프로덕션 수준의 계약 (contract)을 정의합니다.

클라이언트에서는 messages를 단순 텍스트로 취급하지 마세요. AI SDK는 텍스트, 도구 호출 (tool calls), 승인 (approvals), 오류 (errors), 메타데이터 (metadata)와 같은 파트 (parts) 단위로 작동합니다. 만약 message.content만 렌더링한다면 중요한 상태들을 놓치게 될 것입니다. 실제 애플리케이션에서 UI는 도구가 승인을 기다리고 있는지, 실패했는지, 또는 사용 가능한 출력을 생성했는지 알아야 합니다.

서버에서는 route handler가 중요한 경계입니다. 여기서 모델 (model), 시스템 프롬프트 (system prompt), 도구 (tools), 단계 제한 (step limits), 타임아웃 (timeouts), 중단 신호 (abort signals), 로깅 (logging) 및 비용 태그 (cost tags)를 정의합니다. 만약 이 로직이 컴포넌트, 서버 액션 (server actions), 숨겨진 헬퍼 (helpers) 사이에 분산되어 있다면, 나중에 에이전트가 왜 특정 행동을 했는지 감사 (audit)할 수 없게 됩니다.

app/api/chat/route.ts

import { convertToModelMessages, streamText, stepCountIs, tool } from "ai";
import { z } from "zod";

...

Zod를 사용한 구조화된 출력 (Structured output)

import { generateText, Output } from "ai";
import { z } from "zod";

...

스트리밍 (Streaming): 이득을 보는 지점과 깨지는 지점

도움이 되고 있나요? 매주 한 번씩 전달해 드립니다

개발자를 위한 AI 도구, 에이전트 (agents), MCP, 보안 및 워크플로우 (workflows)에 대한 내용을 5분 분량의 이메일로 요약해 드립니다. 스페인어로, 노이즈 없이 전달합니다.

무료 구독하기

스트리밍 (streaming)은 속도에 대한 인식을 개선하지만, 상태 (states)를 생각하는 방식 또한 변화시킵니다. 클래식한 엔드포인트 (endpoint)는 성공하거나 실패합니다. 반면 스트림 (stream)은 잘 시작되었다가, 도구 (tool)를 호출하고, 승인을 요청하고, 부분적인 텍스트를 출력한 뒤, 도구 실행 중 실패하더라도 여전히 복구 가능한 대화를 남길 수 있습니다.

확인해야 할 사항

내부 지원용 채팅의 경우 텍스트 스트리밍만으로 충분합니다. 하지만 도구를 실행하는 에이전트 (agent)의 경우, 단순히 단어뿐만 아니라 도구의 상태 (tool states)를 보여주어야 합니다. 사용자는 에이전트가 검색 중인지, 권한을 기다리는 중인지, 작업을 실행 중인지, 아니면 결과를 요약 중인지 이해할 수 있어야 합니다.

저의 규칙은 다음과 같습니다: 2초 이상 걸리는 모든 도구는 가시적인 상태를 생성해야 합니다. 데이터를 변경하는 모든 도구는 흔적을 남겨야 합니다. 자동화에 사용되는 모든 출력은 수락하기 전에 스키마 (schema)로 검증되어야 합니다.

도구 (Tools): 작은 계약, 명시적 권한

도구는 에이전트의 보안 경계입니다. AI SDK에서는 inputSchema와, 의미가 있는 경우 outputSchema를 사용하여 도구를 정의합니다. 이는 모델이 무엇을 요청할 수 있는지, 그리고 시스템이 무엇을 반환하는지를 기술하도록 강제합니다. 만약 어떤 도구가 작업을 실행하기 위해 자유로운 string 형식을 허용한다면, 그것은 도구가 아니라 개발자 경험 (DX)만 좋은 보안 구멍입니다.

읽기 전용 도구부터 시작하세요: 문서 검색, 티켓 조회, 메트릭 (metrics) 회수 등입니다. 그 다음에는 작은 변이 (mutations)를 추가하세요: 초안 생성, 이슈 (issue) 오픈, 패치 (patch) 제안 등입니다. 되돌릴 수 없는 작업은 인간의 승인이나 매우 엄격한 자동화 정책이 필요합니다.

도구는 지루해야 합니다. 좋은 도구는 한 가지 일만 수행하고, 입력을 검증하며, 실제 사용자의 권한을 적용하고, 호출을 기록하며, 제한된 출력을 반환하고, 해석 가능한 오류와 함께 실패합니다. 모델이 대화 문맥 (conversational context)만으로 권한을 결정해서는 안 됩니다.

무분별한 허용이 되지 않는 MCP

AI SDK는 MCP 서버의 도구(tools)를 소비할 수 있으며, 이는 이미 표준화된 커넥터(connectors)를 보유하고 있는 경우 매우 유용합니다. 하지만 MCP가 신뢰(trust) 문제를 해결해 주는 것은 아닙니다. 원격 서버는 수많은 기능(capabilities)을 노출할 수 있으며, 에이전트는 당신이 예상하지 못한 방식으로 이를 조합할 수 있습니다.

프로덕션 환경을 위해서는 도구 허용 목록(allowlists), 환경별 스코프(scopes), 그리고 읽기(read)와 쓰기(write)의 분리를 선호합니다. 문서를 요약하는 에이전트가 풀 리퀘스트(pull requests)를 생성하거나 고객 데이터에 접근하는 에이전트와 동일한 권한 범위를 가질 필요는 없습니다.

좋은 아키텍처는 MCP를 보편적인 권한이 아닌, 기능의 카탈로그(catalogue)로 취급합니다. 도구를 동적으로 발견(discovery)하는 것은 편리하지만, 어떤 도구를 프로덕션에 투입할지 승인하는 것은 여전히 엔지니어링적인 결정입니다.

에이전트: ToolLoopAgent가 잘못된 프로세스를 해결해주지는 않는다

streamText에서 에이전트로 넘어가는 단계는 사고(thinking), 도구 호출(tool calling), 결과 관찰(observing results), 계속할지 여부 결정, 그리고 종료와 같은 여러 단계가 필요할 때 나타납니다. AI SDK에서 에이전트 패턴은 당신이 수동으로 루프(loop)를 작성하는 것을 방지해주지만, 언제 멈춰야 하는지 또는 어떤 행동이 안전한지는 대신 결정해주지 않습니다.

의도를 가지고 stopWhen을 정의하세요. 단계(steps) 제한이 너무 높으면 응답을 개선하지 못한 채 비용과 시간만 소모할 수 있습니다. 반대로 제한이 너무 낮으면 정당한 워크플로(workflows)가 끊길 수 있습니다. 시작할 때는 적은 단계수를 사용하고, 실제 경로(trajectories)를 측정하며, 증거가 있을 때만 단계수를 높이세요.

도구를 사용하는 모든 채팅을 에이전트라고 부르지 마세요. 제품으로서의 에이전트는 목표, 도구, 관찰 가능한 상태(observable state), 에러 정책(error policy), 평가(evaluation), 그리고 소유자(owner)를 가져야 합니다. 이 점들을 설명할 수 없다면, 당신이 가진 것은 미학적인 자율성을 가진 데모(demo)일 뿐입니다.

구조화된 출력(Structured output): JSON을 검증해야 하는 시점

구조화된 출력은 결과물이 다른 시스템의 입력값으로 사용될 때 품질을 가장 빠르게 향상시키는 요소입니다. 모델이 우선순위, 위험도, 작업 필드, 분류 또는 다음 행동을 결정한다면, 마크다운(markdown)을 수락하지 마세요. 스키마(schema)를 통해 검증된 객체(object)를 요청해야 합니다.

이것이 진실(truth)을 보장하는 것은 아니지만, 형태(form)는 보장합니다. 진실은 데이터, 테스트 또는 검토를 통해 검증됩니다. 형태는 Zod와 타입(types)을 통해 검증됩니다. 이 두 가지를 혼합하는 것은 전형적인 버그의 원인이 됩니다. 유효한 JSON이 잘못된 결정일 수 있기 때문입니다.

내부 계약(internal contracts) 용도로 사용하세요: decision, confidence, citations, next_actions, requires_approval. 만약 객체가 스키마(schema)를 통과하지 못한다면, 앱은 필드를 지어내는 대신 명확한 설명을 요청하거나 기능을 저하시켜야(degrade) 합니다.

관찰 가능성(Observability) 및 비용

AI SDK의 프로덕션 가치는 모델, 토큰(tokens), 지연 시간(latency), 도구 호출(tool calls), 단계(steps), 오류(errors), 종료 사유(finish reason), 사용자, 기능 및 예상 비용과 같은 메트릭(metrics)을 연결할 때 높아집니다. 그렇지 않으면 채팅이 '가끔 느리다'거나 청구서 금액이 올라갔다는 사실만 알게 될 뿐입니다.

만약 이미 Vercel에 배포되어 있다면, Vercel AI Gateway가 라우팅(routing), 가시성 및 제공업체 제어에 도움을 줄 수 있습니다. 멀티 클라우드(multi-cloud) 계층이나 더 강력한 내부 정책이 필요한 경우에는 LiteLLM 또는 자체 게이트웨이가 더 적합합니다. 이 결정은 종교적인 문제가 아닙니다. 측정과 관리(governance)를 가장 잘 할 수 있는 지점을 선택하세요.

비즈니스 메트릭은 응답당 토큰 수가 아닙니다. 허용 가능한 수준의 개입으로 해결된 작업(tasks)입니다. 모든 것을 검토하게 만드는 저렴한 에이전트는 오히려 비용이 많이 들 수 있습니다. 매주 반복되는 한 시간의 업무를 제거해 주는 비싼 에이전트는 수익성이 높을 수 있습니다.

프로덕션 체크리스트

• 각 워크플로우에 대해 내부 기술 키워드를 정의하세요: 지원 (support), 분석 (analysis), 추출 (extraction), 내부 코파일럿 (internal copilot) 또는 운영 에이전트 (operations agent).
• 인간 채팅 (human chat), 구조화된 생성 (structured generation), 액션 실행 (action execution) 경로를 분리하세요.
• 도구 입력 (tool input), 도구 출력 (tool output) 및 다른 시스템이 소비할 객체를 위해 스키마 (schemas)를 사용하세요.
• 프롬프트 외부에서 권한 (permissions)을 적용하세요: 사용자 (user), 테넌트 (tenant), 리소스 (resource) 및 액션 (action).
• 쓰기 (writing), 결제 (payments), 배포 (deployments), 삭제 (deletions) 또는 민감한 데이터 (sensitive data)를 다루는 도구에 대해 승인 (approval) 단계를 추가하세요.
• 모델 (model), 비용 (cost), 지연 시간 (latency), 단계 (steps), 도구 (tools), 오류 (errors) 및 사용자 (user)를 기록하세요.
• 지속성 (Persistence): 가시적인 텍스트뿐만 아니라 메시지와 중요한 이벤트들을 저장하세요.
• 단계 (steps)나 도구 (tools)의 제한을 높이기 전에 실제 대화를 평가하세요.
• 폴백 (fallback)을 문서화하세요: 대체 모델 (alternative model), 읽기 전용 모드 (read-only mode), 부분 응답 (partial response) 또는 인간 에스컬레이션 (human escalation).

OpenAI Agents SDK, LangGraph 또는 Cloudflare Agents SDK 대신 AI SDK를 선택해야 하는 경우

제품이 TypeScript/Next.js 기반이며 UI, 스트리밍 (streaming), 도구 (tools) 및 제공업체 (providers)를 낮은 마찰로 통합하고 싶다면 Vercel AI SDK를 선택하세요. 제품의 프론트엔드 (frontend)와 백엔드 (backend)가 함께 움직여야 할 때 특히 강력합니다.

트레이싱 (tracing), 가드레일 (guardrails) 및 핸드오프 (handoffs)가 매우 긴밀하게 통합된 OpenAI 중심의 스택을 우선시한다면 OpenAI Agents SDK를 선택하세요. Python에서 명시적인 그래프 오케스트레이션 (graph orchestration), 체크포인트 (checkpoints) 및 복잡한 워크플로우 (workflows)가 필요하다면 LangGraph를 선택하세요. 주요 문제가 Durable Objects, WebSockets 및 에지 (edge) 근처의 스케줄링 (scheduling)을 활용한 상태 유지 런타임 (stateful runtime)이라면 Cloudflare Agents SDK를 선택하세요.

솔직한 비교: AI SDK는 TypeScript 웹 제품을 위한 아마도 가장 직접적인 경로일 것입니다. 하지만 지속적인 워크플로우 (durable workflows), 복잡한 상태를 가진 에이전트 (stateful agents), 또는 프론트엔드가 중요하지 않은 환경에서는 반드시 최선의 선택인 것은 아닙니다.

5일 채택 계획

• 1일 차: useChat와 Route Handler를 사용하여 도구(tools) 없이 최소한의 채팅 기능을 구축합니다. 지연 시간(latency)과 오류를 측정합니다.
• 2일 차: inputSchema, 권한 및 로깅을 포함한 단일 읽기 도구(reading tool)를 추가합니다.
• 3일 차: 현재 텍스트에서 파싱하고 있는 결정 사항에 대해 구조화된 출력(structured output)을 도입합니다.
• 4일 차: needsApproval이 포함된 도구를 추가하고 승인 UI를 설계합니다.
• 5일 차: 비용, 단계(steps) 및 오류 메트릭을 연결합니다. MCP, 게이트웨이(gateway) 또는 멀티 스텝(multi-step) 에이전트가 필요한지 결정합니다.

결론

Vercel AI SDK는 문제의 구체적인 한 부분을 해결하기 때문에 주목할 가치가 있습니다. 즉, 각 제공업체마다 서로 다른 접착제 코드(glue code)를 작성할 필요 없이 TypeScript 애플리케이션을 모델, 스트림(streams), 도구(tools) 및 UI와 결합해 줍니다. 이는 매우 큰 장점이지만, 그것이 전부는 아닙니다.

요약하자면 다음과 같습니다. 모델과의 상호작용 계층을 가속화하기 위해 AI SDK를 사용하십시오. 보안, 지속성(persistence), 관측성(observability) 및 평가(evaluation)는 직접 설계해야 합니다. 만약 이 네 가지 요소가 갖춰져 있지 않다면, SDK는 운영하기 어려운 데모 단계에 더 빨리 도달하게 할 뿐입니다.

자주 묻는 질문 (FAQ)

Vercel AI SDK란 무엇인가요?

Vercel AI SDK는 텍스트 생성, 스트리밍(streaming), 채팅 UI, 도구 호출(tool calling), 구조화된 출력(structured output) 및 다양한 모델 제공업체를 지원하며 AI 애플리케이션과 에이전트를 구축하기 위한 TypeScript 툴킷입니다.

Vercel AI SDK는 Next.js에서만 사용할 수 있나요?

아니요. Next.js와 매우 뛰어난 통합성을 제공하지만, 코어(core)는 다른 TypeScript 환경 및 호환 가능한 프레임워크에서도 사용할 수 있습니다.

streamText는 언제 사용하나요?

사용자가 진행 상황을 보거나 채팅 또는 점진적인 응답을 확인해야 하는 대화형 경험, 특히 웹 UI 환경에서 streamText를 사용하십시오.

**구조화된 출력(structured output)은 언제 사용하나요?