2026년 모든 SaaS에 필요한 5가지 AI 플러밍 (코드 포함)

2026년에는 모든 SaaS가 AI 기능을 추가하고 있습니다. 대부분의 팀은 실제 제품과는 무관한 동일한 5가지 플러밍 (plumbing) 요소에 처음 2주를 허비합니다. Next.js 15에서 작동하는 TypeScript 코드와 함께 각 요소를 소개합니다.

1. 스트리밍 엔드포인트 (차단형이 아닌 방식)

사용자는 20초 동안 스피너(spinner)를 바라보며 기다리지 않을 것입니다. 서버 전송 이벤트 (Server-Sent Events, SSE)를 사용하여 토큰이 생성되는 대로 스트리밍하세요:

// app/api/chat/route.ts
const runner = anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
...

2. 타입이 지정된 도구 핸들러 (Typed tool handlers)

챗봇과 제품의 차이는 도구 (tools)에 있습니다. 즉, 모델이 당신의 데이터에 따라 동작하게 하는 것입니다. Zod를 사용하여 한 번만 정의하면, SDK의 도구 러너 (tool runner)가 실행 루프를 처리합니다:

export const searchOrders = betaZodTool({
  name: "search_orders",
  description: "고객의 주문을 조회합니다. 사용자가 주문 상태에 대해 물을 때 호출합니다.",
...

수동적인 에이전트 루프 (agentic loop)도, 직접 작성하는 JSON 스키마 (JSON schema)도 필요 없으며, 입력값은 엔드 투 엔드 (end-to-end)로 타입이 지정됩니다.

3. 사용량 측정 (Usage metering, 그렇지 않으면 사용자가 당신을 파산시킬 것입니다)

월 10파운드 요금제를 사용하는 열성적인 사용자 한 명이 200파운드의 API 비용을 발생시킬 수 있습니다. 모든 요청을 측정하고 출력 토큰 (output tokens)에 가중치를 두세요 (출력 토큰은 입력 토큰보다 약 5배 더 비쌉니다):

export function billableUnits(u: Usage): number {
  return u.input_tokens + (u.cache_read_input_tokens ?? 0) / 10 + u.output_tokens * 5;
}
...

4. 실제로 캐싱되는 프롬프트 캐싱 (Prompt caching)

프롬프트 캐싱 (Prompt caching)은 입력 비용을 약 90%까지 절감할 수 있지만, 이는 접두사 일치 (prefix match) 방식입니다. 시스템 프롬프트 (system prompt)에 보간된 타임스탬프(interpolated timestamp)가 하나라도 포함되면 모든 요청에 대해 전체 비용을 지불하게 됩니다. 규칙은 다음과 같습니다:

• 시스템 프롬프트는 고정된 상수 (constant)여야 합니다. 날짜, 사용자 이름, 기능 플래그 (feature flags) 등을 포함하지 마세요.
• 동적 컨텍스트 (dynamic context)는 캐시 중단점 (cache breakpoint) 이후인 사용자 메시지에 넣으세요.
• 대화 중간에 도구 목록을 변경하지 마세요. 도구는 접두사의 0번 위치에서 렌더링됩니다.

export const SYSTEM_PROMPT = [{
  type: "text" as const,
  text: STABLE_INSTRUCTIONS,          // 여기에 절대 보간하지 마세요
...

작동 여부를 확인하려면: 두 번째 요청부터 usage.cache_read_input_tokens 값이 0이 아니어야 합니다.

5. 스트림을 적절하게 처리하는 채팅 컴포넌트 (A chat component that handles streams properly)

청크 경계(chunk boundaries)를 가로질러 SSE 버퍼를 파싱하세요 — 매 청크마다 단순히 split을 사용하는 방식은 토큰을 누락시킵니다:

let buffer = "";
while (true) {
  const { done, value } = await reader.read();
...

나머지를 직접 작성하고 싶지 않으신가요?

위의 다섯 가지 요소는 모두 agentship-lite에 오픈 소스 (MIT 라이선스)로 공개되어 있습니다 — 어떤 Next.js 앱에든 복사해서 사용하세요.

만약 이를 둘러싼 전체 SaaS 환경 — Stripe 구독, 인증 (auth), Postgres 스키마 (schema), 사용량 측정 (metering)과 연동된 요금제 제한 (plan gating) — 이 필요하다면, 현재 얼리 액세스 가격이 £49인 AgentShip이 있습니다.