M5 개발 환경 + 외부 서비스 가입 9종

이 모듈에서 세팅하는 환경과 9개의 API 키는 이후 모든 실습의 토대입니다. 여기서 한 번 제대로 정리해두면 M6부터는 코드 작성에만 집중할 수 있습니다.

왜 이 환경 세팅이 중요한가

Production-ready AI Agent 서비스를 만들려면 LLM, 음성, 스토리지, 메일, 모니터링이 유기적으로 연결되어야 합니다. 키 하나가 누락되거나 환경 변수명이 틀리면 강의 후반부에서 디버깅에 시간을 낭비하게 됩니다. .env.local 한 파일로 통합하는 것은 "나중에 정리하자"가 아니라 지금 이 순간 해야 할 일입니다.

Node.js 24 LTS 설치

Node.js는 반드시 LTS(Long Term Support) 버전을 사용합니다. 강의 기준은 Node.js 24 LTS입니다.

Mac

# Homebrew가 없다면 먼저 설치
brew install node@24
node -v  # v24.x.x 확인

Windows 공식 사이트(nodejs.org)에서 .msi 인스톨러를 내려받아 설치합니다. 설치 후 PowerShell에서 node -v로 버전을 확인하세요.

팁: 여러 Node 버전을 함께 쓴다면 fnm(Fast Node Manager)을 추천합니다. nvm보다 속도가 빠르고 Windows도 공식 지원합니다.

패키지 매니저: pnpm

강의 전체에서 pnpm을 사용합니다. npm보다 디스크 효율이 높고, Vercel 배포에서도 자동 감지됩니다.

npm install -g pnpm
pnpm -v  # 설치 확인

에디터: VS Code / Cursor / Claude Code

세 가지 모두 강의에서 사용할 수 있습니다. 권장 우선순위는 다음과 같습니다.

에디터	특징	추천 대상
Claude Code	Anthropic 공식 CLI, 강의 기술 스택과 가장 긴밀하게 통합	이 강의 수강생 기본
Cursor	AI 자동완성 내장, 빠른 코드 생성	코드 생성 속도를 중시할 때
VS Code	가장 넓은 생태계, 검증된 안정성	기존 VS Code 사용자

Git은 모든 플랫폼에서 git --version으로 확인 후, 없으면 git-scm.com에서 설치하세요.

9종 외부 서비스 & 무료 한도

서비스	역할	무료 한도
GitHub	소스 코드 관리	무제한 public repo
Vercel	배포 + Blob 스토리지 KV	Blob 1GB, Hobby 플랜 무료
Anthropic	Claude LLM (Opus/Sonnet/Haiku)	$5 무료 크레딧(신규)
OpenAI	GPT 계열 LLM + 임베딩(text-embedding-3-small)	$5 무료 크레딧(신규)
ElevenLabs	STT(Scribe v2) + TTS(eleven_v3)	월 10,000자 무료
Resend	트랜잭션 이메일 발송	월 3,000건 무료
Brave Search API	웹 검색 도구 (Agent용)	월 2,000건 무료
Vercel AI Gateway	LLM 통합 라우팅 (`provider/model` 문자열)	사용량 기반, 캐싱으로 절감
Sentry	에러 모니터링	월 5,000 이벤트 무료

주의: Anthropic과 OpenAI의 무료 크레딧은 카드 등록 후 지급됩니다. 카드 정보를 입력해도 자동 과금은 되지 않으니 안심하고 등록하세요. 단, 지출 한도(Spending Limit)를 반드시 설정해두세요.

callLLM() 통합 패턴 미리 보기

강의에서는 Anthropic과 OpenAI를 하나의 callLLM() 함수로 통합합니다. Vercel AI Gateway의 provider/model 문자열 규칙을 따릅니다.

// lib/llm.ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: process.env.AI_GATEWAY_URL, // Vercel AI Gateway 엔드포인트
  apiKey: process.env.ANTHROPIC_API_KEY,
});

export async function callLLM(
  model: string, // "anthropic/claude-sonnet-4-5" | "openai/gpt-4o" 등
  messages: { role: "user" | "assistant"; content: string }[],
  temperature = 0.7
) {
  const response = await client.messages.create({
    model,
    max_tokens: 2048,
    temperature,
    messages,
  });
  return response.content[0].type === "text" ? response.content[0].text : "";
}

임베딩은 항상 OpenAI text-embedding-3-small(1536차원)을 사용하며, vector DB 없이 코사인 유사도를 직접 계산합니다(M7에서 상세 구현).

// lib/embedding.ts
export function cosineSimilarity(a: number[], b: number[]): number {
  const dot = a.reduce((sum, ai, i) => sum + ai * b[i], 0);
  const magA = Math.sqrt(a.reduce((sum, ai) => sum + ai * ai, 0));
  const magB = Math.sqrt(b.reduce((sum, bi) => sum + bi * bi, 0));
  return dot / (magA * magB);
}

실습 (Lab)

Step 1 — 환경 확인

node -v    # v24.x.x
pnpm -v    # 9.x.x 이상
git --version

Step 2 — 9개 서비스 가입 & API Key 발급

아래 순서대로 진행합니다. 각 서비스에서 API Key를 발급받아 안전한 곳에 임시 보관하세요.

GitHub → github.com → 계정 생성(이미 있으면 건너뜀)
Vercel → vercel.com → GitHub 계정으로 로그인 → Settings > Tokens에서 토큰 생성
Vercel Blob → Vercel 대시보드 > Storage > Create Blob Store (이름: hans17-blob)
Anthropic → console.anthropic.com → API Keys → Create Key
OpenAI → platform.openai.com → API Keys → Create new secret key
ElevenLabs → elevenlabs.io → Profile → API Key
Resend → resend.com → API Keys → Create API Key (도메인 인증은 M9에서)
Brave Search → api.search.brave.com → 가입 → API Keys → Create
Sentry → sentry.io → 프로젝트 생성(Next.js 선택) → DSN 복사

Step 3 — .env.local 통합 작성

프로젝트 루트에 .env.local 파일을 만들고 아래 형식으로 채웁니다.

# .env.local — 절대 Git에 커밋하지 마세요 (.gitignore에 포함 확인)

# LLM
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...

# Vercel AI Gateway
AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/.../vercel

# Storage
BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

# Voice
ELEVENLABS_API_KEY=sk_...

# Email
RESEND_API_KEY=re_...

# Search
BRAVE_SEARCH_API_KEY=BSA...

# Monitoring
SENTRY_DSN=https://...@sentry.io/...
NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

Step 4 — 검증

pnpm dlx tsx -e "console.log(process.env.ANTHROPIC_API_KEY?.slice(0,10))"

sk-ant-api가 출력되면 성공입니다.

보안 체크: cat .gitignore | grep .env.local 로 .env.local이 무시 목록에 있는지 반드시 확인하세요. 키가 GitHub에 올라가면 수 분 내에 악용될 수 있습니다.

핵심 정리

Node.js 24 LTS + pnpm 조합이 강의 전체의 런타임 기준이며, fnm으로 버전을 관리하면 충돌을 예방할 수 있다.
9개 서비스(GitHub/Vercel Blob/Anthropic/OpenAI/ElevenLabs/Resend/Brave/AI Gateway/Sentry)는 모두 무료 티어 안에서 강의 실습이 가능하다.
LLM은 callLLM()으로 통합하고, Vercel AI Gateway의 "anthropic/claude-sonnet-4-5" 같은 provider/model 문자열로 모델을 지정한다.
임베딩은 OpenAI text-embedding-3-small(1536차원), RAG는 별도 vector DB 없이 코사인 유사도를 직접 구현한다.
모든 키는 .env.local 한 파일에 통합하고, .gitignore 등재를 반드시 확인한다.
Anthropic/OpenAI 지출 한도를 미리 설정해두면 예상치 못한 과금 사고를 막을 수 있다.

LAB · 실습

9개 서비스 가입 → 각 API Key 발급 → .env.local 한 파일로 통합