프로덕션 레벨 AI Agent 실전 배포 마스터플랜

HANS17 ACADEMY · 강사 전한철(Hans17) · 프레임워크 없는(No-framework) 결정적 통제와 실전 아키텍처 설계 — 이론과 실습을 한 장으로 압축한 마스터 요약.

이 문서는 10시간 13개 모듈 강의 전체를 한 장의 청사진으로 압축한 마스터 요약입니다. 각 절은 강의 모듈(M1~M13)과 직접 연결됩니다.

0. 한 문장 요약

"통제권을 잃지 말고 확장하라. 규모가 방식을 결정한다." — 프레임워크의 블랙박스를 버리고, LLM의 창의성은 통제하되 시스템의 일관성은 코드로 보장하는 프로덕션 AI 에이전트를 설계하고 배포한다.

1. 패러다임 시프트 — 챗봇에서 에이전트로 (M1)

• 단순 챗봇 = 선형 구조: [사용자 입력] → [LLM 1회 호출] → [텍스트 출력]. 한 번 묻고 한 번 답하면 끝난다.
• AI 에이전트 = 무한 루프 구조: [목표 입력] → ① 인지(Perceive) 현재 상태·맥락 파악 → ② 의사결정(Decide) 다음 행동 고르기 → ③ 행동(Act) API 호출·파일 저장 등 도구(Tool) 사용 → ④ 학습(Learn) 결과를 메모리에 갱신 → 목표 달성? YES면 종료, NO면 루프 반복.
• 핵심 명제: "Agent는 대화하는 봇이 아니라, 목표를 위해 스스로 도구를 쓰는 시스템이다."

2. 아키텍처 철학 — 프레임워크의 함정과 Dispatcher 패턴 (M4)

• 블랙박스 프레임워크(LangGraph / AutoGen): 복잡한 분기, 비결정적 흐름, 비용 예측 불가, 디버깅 어려움.
• 명시적 라우팅(No-framework): 완전한 제어권, 하드코딩 분기, 결정성 100%, 보안 격리.
• The Explicit Dispatcher: [사용자 입력] → [Intent Classifier (LLM 1회 호출)] → searchAgent() / reportAgent() / emailAgent() / fallback 으로 명시적으로 분기한다.
• 핵심 명제: "프레임워크가 알아서 해주는 블랙박스를 버려야 프로덕션에서 버틸 수 있다."

3. 에이전트의 두뇌 — 토큰 경제학과 callLLM() 추상화 (M5 / M7)

• 한국어 토큰의 현실: "Hello world" = 2 토큰 vs "안녕하세요" = 5~6 토큰. 한국어는 영어 대비 약 2.5배의 토큰을 소모한다 → 비용·컨텍스트 설계에 직접 영향.
• callLLM() 단일 추상화: anthropic/claude-sonnet-4-5, openai/gpt-4o 등 서로 다른 모델을 하나의 함수로 통합하고 Vercel AI Gateway(Metrics & Routing)를 통과시킨다.
• extractJSON() 강건 파서: 모델 응답에 섞인 마크다운 코드펜스(json 펜스 등)를 정규식으로 벗겨내 순수 JSON만 안전하게 추출한다.
• Prompt Caching: 반복되는 컨텍스트 비용을 최대 90% 절감. JSON 강제: jsonMode + 스키마 주입으로 결정론적 파싱.

4. 기억 — 지식 단절과 환각을 끊어내는 RAG 파이프라인 (M3 / M8)

RAG = Retrieval-Augmented Generation(검색 증강 생성). 모델이 외부 지식을 검색해 근거로 답하게 만드는 기법이다.

• 파이프라인: 임베딩(text-embedding-3-small, 1536차원) → 코사인 유사도 검색(Threshold 0.15~0.2 적용) → 프롬프트 주입(근거 밖 답변 금지) → 답변 생성(출처 인용 강제).
• 환각 차단 4원칙(Anti-Hallucination Shields):
  1. Score 임계값 — 매치 점수 0.15 미만은 과감히 버린다.
  2. 출처 인용 강제 — [출처: {source}] 표기 없이는 생성 불가.
  3. 청크 사이즈 조정 — 300~600 토큰 단위로 문맥을 조율한다.
  4. 모른다의 명시화 — 문서에 없으면 억지로 지어내지 않는다.

5. RAG 스케일링 결단 — 규모가 방식을 결정한다 (M8)

• In-Memory Cosine (강사 Agent에 적용): 1만 청크 미만·고정 데이터. 별도 DB 없이 content/embeddings.json을 로드한 뒤 수학 공식을 직접 계산. 인프라 비용 0, Vercel 최적화로 약 200ms 응답.
• Vector DB (RAG Lab에 적용): 수만~700만 자 이상·사용자 가변 업로드. Supabase pgvector 확장 + HNSW 인덱스 + match_documents RPC. 영속성 보장, 메타데이터(카테고리/태그) 필터링 가능.
• 핵심: 청크 스키마 {content, embedding, metadata}만 동일하게 유지하면, 두 방식 사이의 마이그레이션은 거의 복붙(Copy-Paste)이다.

6. 상태 유지와 대용량 저장소 — Vercel Blob KV & Direct Upload (M9)

• 1GB 파일은 4MB 제한의 Next.js API Route를 우회해야 한다 → 클라이언트가 secure token(@vercel/blob/client)만 받아 Vercel Blob Storage로 직접 업로드(Direct Upload) 한다.
• blob-kv.ts: kvPutText()(JSON 직렬화 저장, addRandomSuffix: false로 덮어쓰기), kvGetJson()(상태 복원), kvDelete()(사용 후 원본 즉시 삭제 — 개인정보 보호).
• Prefix 경로(projects/<id>/...)로 테넌트(사용자)를 격리한다.

7. 보안 설계 — 프롬프트 인젝션 심층 방어(Defense in Depth) (M4)

• Ring 1 (Outer · System 분리): System / User 역할을 절대 하나의 문자열로 합치지 않는다.
• Ring 2 (길이 Cap): 사용자 입력을 서버 사이드에서 최대 2,000자로 강제 절사한다.
• Ring 3 (키워드 필터): "ignore previous instructions" 등 알려진 공격 패턴을 정규식으로 차단한다.
• Ring 4 (Inner · 구조적 래핑): 사용자 입력을 <user-input> XML 태그로 감싸고, 태그 밖의 명령은 무시하라고 지시한다.
• Tool Use 시 도구의 args는 반드시 서버 사이드에서 Zod 스키마로 타입 검증해야 API 오염을 막을 수 있다.

8. 응용 1 — 결정론적 조립 · 보고서 생성 에이전트 (M10 / M12)

• Phase 1 · 의미 추출 (LLM, 창의성 통제): 혼돈의 원문(회의록) → LLM(claude-sonnet, temperature 0.2, JSON Schema 강제) → 구조화된 JSON(Highlights, Schedule, Flow).
• Phase 2 · 문서 조립 (순수 TypeScript, 100% 결정적): buildMarkdownReport() 순수 함수 + 하드코딩된 마크다운 템플릿 → 완벽히 일관된 6단 구조 보고서.
• 5회 반복 일관성 테스트 통과: Flow 분산 1 이내, Highlights 개수 분산 0. 창의적인 부분만 LLM에 맡기고, 조립은 코드가 한다.

9. 응용 2 — 풀-루프 음성 파이프라인 · ElevenLabs 통합 (M11)

1. 마이크 입력 (Client, MediaRecorder API)
2. Blob 저장 & 우회 (Vercel Blob URL 생성, cloud_storage_url 패턴으로 서버 타임아웃 방지)
3. 인지 (Scribe v2 STT — diarize: true 화자분리, 단어별 타임스탬프 추출, 완료 후 원본 오디오 즉시 삭제)
4. 의사결정 / 요약 (callLLM, temperature 0.2)
5. 행동 (eleven_v3 TTS — optimize_streaming_latency=3, Voice Cloning으로 내 목소리 오디오 스트림 재생)

• 주의: HTMLAudioElement.play()는 브라우저 정책상 사용자 제스처(클릭) 이후에만 실행될 수 있다.

10. 확산·상호작용 — 메일 발송과 비로그인 Q&A 공유망 (M12)

• 발송: Markdown 보고서를 HTML로 변환해 Resend SDK로 전송.
• 토큰화: crypto.getRandomValues(16) 기반 예측 불가능한 128-bit 공유 토큰을 생성해 Blob KV에 저장.
• 공유 페이지(/share/[token]): 수신자가 로그인 없이 안전하게 URL로 접근.
• 후속 질의(Ask): 공유된 원본 보고서를 컨텍스트로 삼아 Claude에 직접 스트리밍 질의. (이메일 푸터에 "공유하기 / 후속 질문하기" 링크가 박힌다.)

11. 개발 워크플로우 — Claude Code × Next.js 융합 (M5)

• .claude/settings.json 구성:
  • MCP (Model Context Protocol): Vercel · Supabase · ElevenLabs 커넥터를 활성화해 인프라를 직접 조작.
  • Skills: /deploy-check 같은 반복 명령어를 SKILL.md로 박제.
  • Hooks: 파일 수정 후 자동 포맷팅 스크립트를 연결.
• 아키텍처 레이아웃: app/api/route.ts(API 엔드포인트) · lib/llm.ts(공통 추상화 계층) · middleware.ts(최전선 인증 보호 및 라우팅 제어).
• 핵심: 손코딩 대신 프롬프트로 지시하고, 9개 서비스 API 키를 .env.local 단일 파일로 결합한다.

12. 프로덕션 배포 및 시스템 관측 — Observability (M13)

• Deployment CLI: ① vercel link(프로젝트 연결) → ② vercel env pull(환경변수 동기화) → ③ vercel --prod(라이브 배포).
• AI Gateway Metrics: Model Latency(ms), Token Costs($)를 가시화.
• Fallback Routing: "fallback": ["openai/gpt-4o"] — Claude가 429 에러를 낼 때 자동 우회.
• Log Drains: Vercel Logs → Sentry(에러 추적) + Datadog(장기 메트릭).

13. 종합 — Hans17 AI Agent 마스터 아키텍처 조감도

• Frontend: Direct Upload · Client Components(UI / Audio)
• Routing: Middleware → Route Handlers(app/api)
• Brain: Dispatcher(Intent Classifier) → Report / Voice / Email Agent → callLLM()
• Memory / Storage: (A) Vercel Blob KV(State / Files) · Vercel AI Gateway · (B) In-Memory / pgvector RAG
• External APIs: Anthropic / OpenAI · ElevenLabs(STT / TTS) · Resend(Mail)

맺음 — 3가지 설계 원칙

1. 프레임워크의 블랙박스에서 벗어나 결정적 파이프라인을 구축하라.
2. LLM의 창의성은 통제하고, 시스템의 일관성은 코드로 보장하라.
3. 논리와 감성, 과학과 사운드의 경계를 넘나드는 당신만의 에이전트를 설계하라.

HANS17 ACADEMY — AI Agent Master Blueprint Complete.