Vercel AI SDK 5 에이전트 빌드 — stopWhen·prepareStep으로 도구 루프 정밀 제어

핵심 요약

Vercel AI SDK 5는 에이전트 루프를 정밀 제어할 수 있는 primitive를 도입했다. stopWhen으로 종료 조건을, prepareStep으로 매 step 직전 컨텍스트·도구·모델을 동적으로 바꾼다. tool-level provider option 덕에 Anthropic 캐시 같은 공급자 특화 기능을 도구 단위로 켤 수 있다.

• 완전한 타입 안전 (도구·메시지·UI 메시지)
• React/Svelte/Vue/Angular 통합 chat UI
• OpenAI·Anthropic·Google 통일 인터페이스
• AI Gateway 연동으로 모델 라우팅·관측성 즉시 이용

1. 가장 단순한 에이전트

import { generateText, tool } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'
import { z } from 'zod'

const result = await generateText({
  model: anthropic('claude-opus-4-7'),
  tools: {
    weather: tool({
      description: '도시의 현재 날씨',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => fetchWeather(city),
    }),
  },
  stopWhen: stepCountIs(10),  // 최대 10 step
  prompt: '서울과 도쿄 날씨를 비교해줘',
})

2. stopWhen — 종료 조건 조합

import { stepCountIs, hasToolCall } from 'ai'

stopWhen: [
  stepCountIs(20),                    // 20 step 넘기면 종료
  hasToolCall('finalAnswer'),         // 도구 호출되면 종료
  ({ steps }) => totalCost(steps) > 0.5,  // $0.5 넘기면 종료
  ({ steps }) => steps.length > 3 &&
    steps.slice(-3).every(s => s.toolCalls.length === 0),  // 3 step 연속 도구 안 쓰면 종료
]

여러 조건을 OR로 결합. 비용 폭주·무한 루프 방어에 필수.

3. prepareStep — 동적 컨텍스트

매 step 직전 호출되는 콜백. 도구 결과에 따라 다음 step의 모델·도구·메시지를 바꾼다.

const result = await generateText({
  model: anthropic('claude-opus-4-7'),
  tools: { search, readFile, runCode },
  prepareStep: async ({ stepNumber, steps }) => {
    // 첫 step: 검색만 허용
    if (stepNumber === 0) return { activeTools: ['search'] }

    // 5 step 이후엔 가벼운 모델로 다운그레이드
    if (stepNumber > 5) return {
      model: anthropic('claude-haiku-4-5'),
    }

    // 컨텍스트가 200K 넘으면 압축
    if (currentTokens(steps) > 200_000) return {
      messages: await summarize(steps),
    }

    return {}
  },
  prompt: userQuery,
})

4. Anthropic 캐시 — tool-level option

도구 정의 자체를 캐시해서 멀티스텝 에이전트 비용 대폭 절감:

tools: {
  searchKnowledgeBase: tool({
    description: '내부 지식베이스 검색 (방대한 도구 설명)',
    inputSchema: z.object({ ... }),
    execute: async (...) => { ... },
    providerOptions: {
      anthropic: { cacheControl: { type: 'ephemeral' } },
    },
  }),
}
// 첫 호출에서만 도구 정의 풀비용, 이후 step은 10%만

10 step 에이전트가 같은 도구 세트 쓰면 비용 60~80% 절감.

5. 스트리밍 + UI 통합

// app/api/chat/route.ts
import { streamText } from 'ai'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    messages,
    tools,
    stopWhen: stepCountIs(15),
  })
  return result.toUIMessageStreamResponse()
}

// app/chat.tsx
'use client'
import { useChat } from '@ai-sdk/react'

export default function Chat() {
  const { messages, sendMessage, status } = useChat()
  return (
    <form onSubmit={(e) => { e.preventDefault(); sendMessage({ text: input }) }}>
      ...
    </form>
  )
}

도구 호출 UI 렌더링

{messages.map(m => (
  m.parts.map((part, i) => {
    if (part.type === 'text') return <p key={i}>{part.text}</p>
    if (part.type === 'tool-call') return (
      <ToolCallBadge key={i} name={part.toolName} args={part.args} />
    )
    if (part.type === 'tool-result') return (
      <ToolResult key={i} result={part.result} />
    )
  })
))}

6. 인간 개입 (HITL)

// 위험한 도구는 클라이언트가 승인 후 실행
tools: {
  deleteFile: tool({
    description: '파일 삭제 (위험)',
    inputSchema: z.object({ path: z.string() }),
    // execute 없음 — 클라이언트가 처리
  }),
}

// 클라이언트
useChat({
  onToolCall: async ({ toolCall }) => {
    if (toolCall.toolName === 'deleteFile') {
      const ok = await confirm('정말 삭제?')
      if (!ok) return { error: 'user_cancelled' }
      return await api.delete(toolCall.args.path)
    }
  },
})

7. AI Gateway 통합

모델 ID만 바꾸면 OpenAI/Anthropic/Google/오픈소스 가는 라우팅:

import { gateway } from '@ai-sdk/gateway'

const model = gateway({
  primary: anthropic('claude-opus-4-7'),
  fallback: openai('gpt-5'),
  costLimit: { perRequest: 1.0 },  // 1USD 넘으면 fallback
})

Vercel 대시보드에서 토큰 사용·비용·지연시간 자동 추적.

8. 다른 SDK와의 비교

특정 공급자 종속 없이 SDK 1개로 끝내고 싶다 → AI SDK 5. Anthropic 깊은 기능 다 쓰고 싶다 → Anthropic SDK 직접.

자주 묻는 질문

v4에서 v5로 마이그레이션 어렵나?

중간 정도. useChat 인터페이스가 message-parts 모델로 바뀌어 렌더링 로직 재작성 필요. 도구 정의는 거의 동일.

Edge runtime에서도 동작?

예. Vercel Edge·Cloudflare Workers·Deno Deploy 모두 지원.

스트리밍 토큰 단가 추적?

onFinish 콜백으로 토큰 수신, AI Gateway 쓰면 자동 기록.