Claude API 스트리밍 응답을 Next.js App Router Server Action에서 구현하며 겪은 삽질 기록과 최종 코드

// ❌ 이렇게 하면 안 돼요
'use server'

export async function streamClaude(prompt: string) {
  const stream = await anthropic.messages.stream({
    model: 'claude-opus-4-5',
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }],
  })
  
  return stream.toReadableStream() // 💥 직렬화 오류
}

// 🟡 동작하긴 하는데... 조건이 있어요
'use server'

export async function* streamClaude(prompt: string) {
  const stream = anthropic.messages.stream({
    model: 'claude-opus-4-5',
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }],
  })
  
  for await (const chunk of stream) {
    if (chunk.type === 'content_block_delta' && 
        chunk.delta.type === 'text_delta') {
      yield chunk.delta.text
    }
  }
}

// app/api/claude/route.ts
import Anthropic from '@anthropic-ai/sdk'
import { NextRequest } from 'next/server'

export const runtime = 'nodejs' // 반드시 명시해요

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
})

export async function POST(req: NextRequest) {
  const { prompt, systemPrompt } = await req.json()

  const stream = anthropic.messages.stream({
    model: 'claude-opus-4-5',
    max_tokens: 2048,
    system: systemPrompt ?? 'You are a helpful assistant.',
    messages: [{ role: 'user', content: prompt }],
  })

  return new Response(stream.toReadableStream(), {
    headers: {
      'Content-Type': 'text/plain; charset=utf-8',
      'Transfer-Encoding': 'chunked',
      'X-Accel-Buffering': 'no', // Nginx 프록시 버퍼링 방지
    },
  })
}

// app/actions/claude.ts
'use server'

import { z } from 'zod'

const schema = z.object({
  prompt: z.string().min(1).max(4000),
})

export async function prepareClaudeRequest(formData: FormData) {
  const raw = Object.fromEntries(formData)
  const parsed = schema.safeParse(raw)
  
  if (!parsed.success) {
    return { error: '입력값을 확인해 주세요.' }
  }
  
  // 인증, 레이트 리밋, 로깅 등 서버 사이드 로직
  return { prompt: parsed.data.prompt }
}

// app/components/ChatStream.tsx
'use client'

import { useState } from 'react'
import { prepareClaudeRequest } from '@/app/actions/claude'

export default function ChatStream() {
  const [response, setResponse] = useState('')
  const [loading, setLoading] = useState(false)

  async function handleSubmit(formData: FormData) {
    setLoading(true)
    setResponse('')
    
    const result = await prepareClaudeRequest(formData)
    if (result.error) {
      setResponse(result.error)
      setLoading(false)
      return
    }

    const res = await fetch('/api/claude', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ prompt: result.prompt }),
    })

    const reader = res.body?.getReader()
    const decoder = new TextDecoder()
    
    while (reader) {
      const { done, value } = await reader.read()
      if (done) break
      setResponse(prev => prev + decoder.decode(value, { stream: true }))
    }
    
    setLoading(false)
  }

  return (
    <form action={handleSubmit}>
      <textarea name="prompt" placeholder="질문을 입력하세요" />
      <button type="submit" disabled={loading}>
        {loading ? '응답 중...' : '전송'}
      </button>
      {response && <div className="whitespace-pre-wrap">{response}</div>}
    </form>
  )
}

// vercel.json
{
  "functions": {
    "app/api/claude/route.ts": {
      "maxDuration": 60
    }
  }
}