30초 핵심 요약
- 1SEO/GEO 데이터 분석용 AI Agent를 6주간 구축했습니다
- 2Regex 파싱 → Native Function Calling 전환으로 도구 호출 에러율 0% 달성
- 38개 도구, 4겹 안전장치, SSE 실시간 스트리밍 완성
- 4한영 동의어 처리: Regex 딕셔너리 → LLM Entity Extraction으로 전환
- 5현재 과제: 응답 속도 2초 → 0.3초 최적화 진행 중
- 6핵심 교훈: "AI Agent는 만드는 것보다 안정적으로 운영하는 게 더 어렵다"
AI Agent 구축은 LLM이 데이터베이스 조회와 분석 도구를 스스로 골라 쓰도록 만드는 작업입니다. 이 글은 HaloX가 SEO/GEO 데이터 분석용 AI Agent를 6주 동안 만들며 겪은 시행착오, 선택한 구조, 내부 운영 수치를 정리한 구축기입니다.
Overview - 왜 Agent가 필요했나
HaloX는 SEO와 GEO(Generative Engine Optimization) 데이터를 통합 관리하는 SaaS 플랫폼입니다.
키워드 검색량, SERP 분석, AI 엔진 인용 점수, 경쟁사 비교 등 수십 가지 데이터가 매일 쌓이고 있었습니다. 문제는 데이터는 넘치는데 인사이트를 뽑기가 너무 번거로웠다는 것입니다.
"이 키워드의 검색량이 얼마지?" → Keywords 페이지로 이동 "GEO 점수가 떨어진 이유가 뭐지?" → GEO 대시보드 → 프롬프트 결과 → 인용 분석 페이지를 순회 "경쟁사 대비 우리 콘텐츠는?" → SERP 분석 → 콘텐츠 비교 → 수동 정리
하나의 질문에 답하려면 3–4개 페이지를 돌아다녀야 했습니다. 그래서 결론은 하나였습니다:
질문하면 알아서 찾아주는 AI 비서가 필요하다.
The Challenge - 처음에 부딪힌 벽들
Agent를 만들기로 결정한 뒤, 네 가지 큰 벽에 부딪혔습니다.
벽 1: 질문 유형이 너무 다양하다
사용자 질문은 단순 조회부터 복잡한 분석까지 스펙트럼이 넓었습니다.
| 복잡도 | 예시 질문 | 필요한 처리 |
|---|---|---|
| L1 (단순 조회) | "SEO 키워드 검색량 알려줘" | DB 쿼리 1회 |
| L2 (필터링) | "검색량 1000 이상인 키워드 목록" | DB 쿼리 + 필터 |
| L3 (분석) | "왜 GEO 점수가 떨어졌지?" | 다중 DB 조회 + 비교 + 추론 |
| L4 (크로스 분석) | "경쟁사 대비 콘텐츠 전략은?" | SERP + GEO + 키워드 교차 분석 |
| L5 (전략 제안) | "다음 달 콘텐츠 우선순위는?" | 전체 데이터 종합 + 전략 추론 |
모든 질문을 하나의 프롬프트로 처리하면? LLM 비용이 폭발하고, 단순 질문에도 불필요하게 느린 응답이 나옵니다.
해결: 복잡도 레벨(L1~L5) 분류 체계를 도입했습니다.
Intent Router가 질문을 분석해서 복잡도를 판별하고, L1~L2는 단일 도구로, L3 이상은 ReAct 루프로 라우팅합니다. 질문을 단계적으로 분류하는 방식은 계층형 분류 설계에서 따로 다뤘습니다.
벽 2: LLM이 도구를 불안정하게 호출한다
초기 구현에서는 LLM에게 "이런 포맷으로 도구를 호출해"라고 텍스트로 지시했습니다.
Thought: 사용자가 키워드 검색량을 원합니다
Action: seo.keyword_lookup
Action Input: {"keyword": "AI Agent"}
이 텍스트를 정규식(Regex)으로 파싱해서 도구 이름과 인자를 추출했습니다.
문제는 AI가 항상 같은 포맷으로 텍스트를 생성하지 않는다는 것입니다.
실제로 겪은 파싱 실패 사례들:
// 케이스 1: AI가 따옴표를 빠뜨림
Action Input: {keyword: AI Agent} // JSON 파싱 실패
// 케이스 2: AI가 줄바꿈을 추가함
Action: seo.keyword_lookup
Action Input: {"keyword": "AI Agent"} // 빈 줄 때문에 매칭 실패
// 케이스 3: AI가 중첩 JSON을 생성함
Action Input: {"filters": {"min_volume": 1000}} // 중괄호 매칭 실패
이 문제를 해결하려고 extractBalancedJson이라는 복잡한 유틸리티 함수를 만들었습니다. 중괄호 개수를 세고, 이스케이프된 문자를 처리하고, 여러 줄에 걸친 JSON을 추출하는 코드였습니다.
하지만 예외 케이스가 계속 발견되었고, 파싱 코드가 Agent 로직보다 더 복잡해지는 역설적인 상황이 벌어졌습니다.
벽 3: 응답이 너무 느리다
단순한 키워드 조회 질문에도 2초 이상 걸렸습니다.
| 단계 | 소요 시간 |
|---|---|
| DB에서 Gemini 설정 로드 | ~200ms |
| LLM 인텐트 라우팅 | ~800ms |
| 도구 실행 (DB 쿼리) | ~200ms |
| LLM 최종 답변 생성 | ~800ms |
| 합계 | ~2,087ms |
"검색량 알려줘" 같은 단순 질문에 2초는 사용자 경험상 허용할 수 없는 수준이었습니다.
벽 4: 한국어와 영어가 뒤섞인 질문
SEO/GEO 분야 특성상, 사용자들은 한국어와 영어를 자유롭게 섞어 씁니다.
"검색량 알려줘" → search_volume 필드 조회
"search volume 보여줘" → 같은 search_volume 필드 조회
"KD가 높은 키워드" → keyword_difficulty 필드 조회
"월간 검색 트래픽" → search_volume? monthly_traffic? 모호함
첫 시도: Regex 동의어 딕셔너리
처음에는 한영 동의어를 수동으로 매핑했습니다.
// v1: Regex 기반 동의어 매핑 (금방 한계에 도달) const SYNONYM_MAP: Record<string, string> = { "검색량": "search_volume", "검색 볼륨": "search_volume", "키워드 난이도": "keyword_difficulty", "KD": "keyword_difficulty", "경쟁도": "competition", "CPC": "cpc_max", // ... 수십 개가 계속 늘어남 }; function normalizeQuery(query: string): string { for (const [ko, en] of Object.entries(SYNONYM_MAP)) { query = query.replace(new RegExp(ko, "gi"), en); } return query; }
한계: 동의어가 계속 늘어났습니다. "월간 검색 트래픽", "오가닉 트래픽", "자연 유입" 같은 복합 표현은 매핑이 불가능했고, "KD"처럼 약어는 맥락에 따라 다른 의미를 가질 수 있었습니다. 3주 만에 딕셔너리가 100개를 넘기면서 유지보수가 불가능해졌습니다.
해결: LLM에게 Entity Extraction을 맡기다
결국 동의어 처리도 LLM의 몫이었습니다. Intent Router가 질문을 분류할 때, 동시에 Entity Extraction도 수행하도록 변경했습니다.
// v2: LLM Entity Extraction (현재 방식) // Intent Router의 응답에 extractedEntities 필드를 추가 { "intent": "seo.keyword_lookup", "complexity": "L1", "extractedEntities": { "keyword": "best vpn", "metrics": ["search_volume", "keyword_difficulty"], "language": "en" } } // "검색량"이든 "search volume"이든 "월간 검색 트래픽"이든 // LLM이 문맥을 파악해서 "search_volume"으로 정규화
추가로, 한국어 조사 제거 로직도 넣었습니다. "브레이즈의", "허브스팟에서", "키워드를" 같은 입력에서 12종 이상의 조사(의, 에서, 를, 을, 이, 가, 는, 은, 로, 으로, 좀, 도)를 제거해서 순수한 엔티티만 추출합니다.
The Solution - 우리가 선택한 아키텍처
Agent란?
AI Agent란 LLM(대규모 언어 모델)이 외부 도구를 사용해서 스스로 문제를 해결하는 시스템입니다. 텍스트만 생성하는 챗봇과 달리, 데이터베이스를 조회하고, API를 호출하고, 그 결과를 분석해서 답변합니다.
전체 아키텍처
아래 다이어그램은 Agent의 전체 처리 흐름입니다.
flowchart TD A[User Message] --> B[Input Guardrail] B -->|PII/Injection Filter| C{Intent Router} C -->|18 intents x L1-L5| D{Complexity?} D -->|L1/L2: Simple| E[Single Tool Call] D -->|L3+: Complex| F[ReAct Loop] F --> G[Thought: Plan next step] G --> H[Function Call: Execute tool] H --> I[Observation: Analyze result] I -->|Need more info?| G I -->|Done| J[Synthesize Answer] E --> J J --> K[Output Guardrail] K -->|Length/Citation check| L[SSE Stream Response]
사용자 메시지가 들어오면 먼저 Input Guardrail이 PII(개인정보)와 프롬프트 인젝션을 필터링합니다. 통과하면 Intent Router가 18가지 인텐트 중 하나로 분류하고 복잡도(L1~L5)를 판별합니다. 단순 질문(L1/L2)은 도구 하나로 바로 처리하고, 복잡한 질문(L3+)은 ReAct 루프에서 생각→실행→관찰을 반복합니다. 최종 답변은 Output Guardrail을 거쳐 SSE 스트리밍으로 실시간 전송됩니다.
핵심 컴포넌트 4가지
1. Intent Router - 질문 분류기
사용자 질문을 18가지 인텐트(의도)로 분류하고, 5단계 복잡도를 판별합니다.
사용자: "best vpn 키워드의 검색량은?"
→ Intent: seo.keyword_lookup
→ Complexity: L1 (단순 조회)
→ Routing: 단일 도구 실행
2. Tool Registry - 도구 등록소
8개의 전문 도구가 등록되어 있습니다.
| 카테고리 | 도구 | 기능 |
|---|---|---|
| SEO | keyword_lookup | 키워드 검색량, 난이도 조회 |
| SEO | serp_analysis | SERP 스냅샷 분석 |
| SEO | content_gap | 콘텐츠 갭 분석 |
| GEO | avi_score | AI Visibility Index 조회 |
| GEO | citation_analysis | 인용 분석 |
| GEO | prompt_performance | 프롬프트별 성과 분석 |
| Knowledge | hybrid_search | 하이브리드 검색 (키워드 + 벡터) |
| Cross | cross_analysis | SEO x GEO 교차 분석 |
3. ReAct Loop - 추론 엔진
복잡한 질문(L3+)은 ReAct(Reasoning + Acting) 패턴으로 처리합니다.
Step 1 - Thought: GEO 점수 하락 원인을 찾으려면 최근 점수 변화를 확인해야 합니다
Step 2 - Action: geo.avi_score(keyword="best vpn")
Step 3 - Observation: AVI 70→55로 하락, 인용 수 감소
Step 4 - Thought: 인용이 줄었으니 어떤 소스에서 줄었는지 확인해야 합니다
Step 5 - Action: geo.citation_analysis(keyword="best vpn")
Step 6 - Observation: Reddit 인용 3→0, 공식 문서 인용 유지
Step 7 - Final Answer: Reddit에서의 인용이 사라진 것이 주 원인입니다...
4. 4겹 안전장치
| 레이어 | 기능 | 예시 |
|---|---|---|
| 입력 필터 | 개인정보, 프롬프트 인젝션 차단 | 주민번호 패턴 탐지, "이전 지시를 무시해" 차단 |
| 계획 검증 | 예산 한도, 스텝 제한 | 쿼리당 $0.05, ReAct 최대 5스텝, Gemini 최대 8호출 |
| 도구 검증 | 워크스페이스 격리, 읽기 전용 | 타 워크스페이스 데이터 접근 차단 |
| 출력 필터 | 응답 길이, 인용 검증 | 4,000자 초과 시 축약, RAG 응답 인용 확인 |
Implementation - 단계별 구축 타임라인
Week 1-2: 기초 공사
만든 것: Intent Router + 기본 도구 3개 + SSE 스트리밍
SSE 스트리밍 도입기: "뿅" 에서 "스르륵"으로
처음에는 SSE가 없었습니다. Agent가 답변을 완성할 때까지 사용자에게는 로딩 스피너만 보였습니다.
Before: 2초 동안 빙글빙글 돌다가 → "뿅!" 전체 텍스트가 한꺼번에 나타남
사용자 반응? "멈춘 건가?" "에러 난 건가?" 2초는 짧은 시간 같지만, 아무런 피드백 없이 기다리는 2초는 체감상 10초와 같았습니다.
ChatGPT처럼 글자가 하나씩 나타나는 방법을 찾아보니 SSE(Server-Sent Events)라는 기술이 있었습니다.
// SSE 스트리밍 핵심 패턴 function formatSSE(event: string, data: string): string { return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`; } // Edge Function에서 ReadableStream으로 실시간 전송 const stream = new ReadableStream({ start(controller) { // 상태 업데이트: "분석 중..." controller.enqueue(formatSSE("status", "키워드 데이터를 조회하고 있습니다...")); // 답변 청크 단위 전송 for (const chunk of answerChunks) { controller.enqueue(formatSSE("chunk", chunk)); } // 완료 메타데이터 controller.enqueue(formatSSE("done", { tokens: 150, cost: 0.001 })); controller.close(); } });
After: 0.3초부터 "분석 중..." 상태가 표시되고, 답변이 글자 단위로 실시간 표시됨
실제 응답 시간은 동일한 2초인데, 체감 속도는 2배 이상 향상되었습니다. SSE 스트리밍은 Agent 구축 시 Day 1부터 넣어야 할 필수 요소입니다.
실수: 초기에 도구 호출을 Regex로 구현함 (이후 Week 6에서 전면 교체)
Week 3-4: 추론 엔진
만든 것: ReAct Loop + Hybrid Search + 안전장치
Hybrid Search는 키워드 기반 검색(BM25)과 벡터 기반 의미 검색을 결합한 방식으로, RAG의 검색 단계에 해당합니다. "VPN 추천"으로 검색하면 키워드 매칭뿐 아니라 "가상 사설 네트워크 서비스 비교" 같은 의미적으로 관련된 문서도 찾아줍니다.
실수: 안전장치를 나중에 추가하려다가, 테스트 중 LLM이 무한 루프에 빠지는 사고 발생. 안전장치는 처음부터 넣어야 합니다. 검색 결과에 없는 내용을 지어내지 않게 막는 방법은 RAG 환각 방어 전략에 정리했습니다.
Week 5: 모니터링
만든 것: Agent 모니터링 대시보드 + LLM 비용 추적
모니터링 없이 Agent를 운영하면 어떻게 될까요? 한 달 뒤 LLM 청구서를 보고 놀라게 됩니다. 인텐트별 호출 빈도, 평균 토큰 사용량, 도구 성공률을 실시간으로 추적하는 대시보드를 만들었습니다.
Week 6: 대전환 - Native Function Calling
만든 것: Regex 파싱 전면 제거, Gemini Native Function Calling 전환
이것이 가장 큰 전환점이었습니다.
Step 1: 도구 스키마 변환
먼저 기존 도구 정의를 Gemini의 tools 포맷으로 변환하는 함수를 만들었습니다.
// agent-tools.ts - 도구 스키마를 Gemini 포맷으로 변환 function getGeminiFunctionDeclarations() { return toolRegistry.map(tool => ({ name: tool.name.replace(/\./g, "_"), // 중요! 아래 Step 2 참조 description: tool.description, parameters: { type: "OBJECT", properties: tool.params, required: tool.required } })); }
Step 2: 예상 못한 문제 - 도구 이름 규칙
Gemini에 도구를 등록했더니 즉시 에러가 발생했습니다.
Error: Function name "seo.keyword_lookup" contains invalid characters.
Only [a-zA-Z0-9_] are allowed.
우리 도구 이름은 seo.keyword_lookup처럼 점(.)으로 카테고리를 구분하는 규칙을 쓰고 있었는데, Gemini는 점을 허용하지 않았습니다.
해결: 등록할 때 점을 언더스코어로 변환하고, 응답에서 역변환하는 유틸리티를 추가했습니다.
// 등록 시: seo.keyword_lookup → seo_keyword_lookup const geminiName = toolName.replace(/\./g, "_"); // 응답 수신 시: seo_keyword_lookup → seo.keyword_lookup function resolveGeminiFunctionName(geminiName: string): string { const tool = toolRegistry.find(t => t.name.replace(/\./g, "_") === geminiName ); return tool?.name ?? geminiName; }
사소해 보이지만, 이런 "문서에 안 나오는 제약사항"을 발견하고 우회하는 데만 반나절이 걸렸습니다.
Step 3: Multi-turn 패턴 구현
Native Function Calling의 핵심은 대화 턴 구조입니다. LLM이 함수 호출을 요청하면, 그 결과를 다시 대화에 넣어서 다음 판단을 받는 구조입니다.
// Multi-turn ReAct with Native FC while (canContinueReAct(budget, step)) { const response = await gemini.generateContent({ contents: conversationHistory, tools: [{ functionDeclarations }] }); const part = response.candidates[0].content.parts[0]; if (part.functionCall) { // LLM이 도구 호출을 요청함 const result = await executeTool(part.functionCall); // 결과를 대화 히스토리에 추가 conversationHistory.push( { role: "model", parts: [{ functionCall: part.functionCall }] }, { role: "function", parts: [{ functionResponse: { name: part.functionCall.name, response: { result } }}]} ); step++; } else { // LLM이 최종 답변을 생성함 finalAnswer = part.text; break; } }
이전 방식 (Regex 파싱):
AI가 텍스트로 생성 → Regex로 "Action:" 뒤 추출 → JSON 파싱 시도 → 실패 시 재시도
현재 방식 (Native Function Calling):
AI에게 도구 스키마 제공 → AI가 구조화된 JSON 반환 → 바로 실행
결과: 300줄의 파싱 로직이 사라지고, 도구 호출 성공률이 100%가 되었습니다.
Results - 숫자로 보는 성과
| 지표 | Before (Week 1-5) | After (Week 6+) | 변화 |
|---|---|---|---|
| 도구 호출 성공률 | ~85% (regex) | 100% (Native FC) | +15%p |
| ReAct 루프 코드량 | ~300줄 | ~150줄 | -50% |
| JSON 파싱 에러 | 월 수십 건 | 0건 | -100% |
| 한영 동의어 매핑 | 100+ regex 규칙 | LLM 자동 추출 | 유지보수 0 |
| 지원 인텐트 | 0개 → 18개 | 18개 | - |
| 등록 도구 수 | 0개 → 8개 | 8개 | - |
| 안전장치 레이어 | 0겹 → 4겹 | 4겹 | - |
| 평균 응답 시간 | - | ~2,087ms | 개선 필요 |
| 건당 LLM 비용 | - | ~$0.001 | - |
표의 수치는 HaloX 내부 운영 로그 기준이며, 측정 기간과 질문 구성에 따라 달라질 수 있습니다.
Key Learnings - 다시 한다면 이렇게
교훈 1: Regex 파싱은 절대 하지 마라
LLM의 텍스트 출력을 정규식으로 파싱하는 것은 모래 위에 집을 짓는 것과 같습니다. AI는 동일한 프롬프트에도 매번 다른 포맷으로 응답할 수 있습니다. 처음부터 Function Calling을 지원하는 모델(Gemini, GPT 계열 등)을 선택하세요.
교훈 2: 복잡도 분류가 비용 절감의 핵심
L1~L5 복잡도 분류 체계를 도입한 덕분에:
- L1/L2 질문(전체의 ~70%)은 단일 도구로 빠르게 처리
- L3+ 질문만 비용이 높은 ReAct 루프 사용
- 결과적으로 전체 LLM 비용의 60% 이상을 절감할 수 있었습니다
교훈 3: SSE 스트리밍은 체감 속도를 2배로 만든다
실제 응답 시간이 동일해도, 글자가 실시간으로 나타나는 것만으로 사용자는 "빠르다"고 느낍니다. Agent를 만든다면 SSE 스트리밍은 처음부터 넣는 편이 좋습니다.
처음에 SSE 없이 만들었을 때 "로딩 중... → 뿅!" 방식은 사용자에게 "멈춘 건가?" 하는 불안감을 줬습니다. SSE를 찾아서 적용한 뒤, 같은 2초 응답인데도 "빠르고 자연스럽다"는 피드백으로 바뀌었습니다.
교훈 4: 안전장치는 처음부터 넣어라
"MVP 먼저, 안전장치는 나중에"라는 접근은 위험합니다. 테스트 중 LLM이 도구를 무한 호출하면서 DB에 수천 건의 불필요한 쿼리를 날린 사고가 있었습니다.
우리가 실제로 구현한 안전장치의 구체적 사례:
// PII 탐지: 한국 주민번호, 전화번호 패턴 const PII_PATTERNS = [ /\b\d{6}[-\s]?\d{7}\b/, // 주민번호 (6자리-7자리) /\b0\d{2}[-\s]?\d{3,4}[-\s]?\d{4}\b/, // 전화번호 (0으로 시작) ]; // 프롬프트 인젝션 방어 const INJECTION_PATTERNS = [ /ignore\s+(previous|all)\s+instructions/i, // "이전 지시를 무시해" /you\s+are\s+now/i, // "너는 이제 ~야" /forget\s+everything/i, // "모든 것을 잊어" ]; // 예산 제한: 폭주 방지 const LIMITS = { maxCostPerQuery: 0.05, // 쿼리당 $0.05 maxReActSteps: 5, // ReAct 최대 5스텝 maxGeminiCalls: 8, // Gemini 최대 8회 호출 maxResponseLength: 4000, // 응답 최대 4,000자 };
이런 안전장치가 없었다면 비용 폭탄, 무한 루프, 데이터 유출 사고가 발생할 수 있었습니다. 최대 반복 횟수, 타임아웃, 결과 크기 제한은 Day 1부터 넣으세요.
교훈 5: 모니터링 없으면 비용 폭탄
어떤 인텐트가 가장 많이 호출되는지, 평균 토큰 사용량은 얼마인지 모르면 최적화할 수 없습니다. LLM 비용 추적 대시보드를 만든 뒤에야 "이 인텐트는 프롬프트를 줄이면 50% 절감할 수 있겠다"는 인사이트를 얻었습니다.
교훈 6: 동의어 처리는 LLM에게 맡겨라
한영 혼용 환경에서 Regex 동의어 딕셔너리는 금방 한계에 도달합니다. "검색량", "search volume", "월간 검색 트래픽", "organic traffic" - 같은 개념의 다양한 표현을 수동으로 매핑하는 건 끝이 없는 두더지 잡기입니다. LLM의 Entity Extraction에 맡기면 새로운 표현이 등장해도 코드 수정 없이 자동으로 처리됩니다.
Conclusion + Next Steps
현재 Phase 1(코어 엔진)은 완료되었고, Phase 2(최적화)를 진행 중입니다.
다음 목표:
- 응답 속도 10배 개선: Gemini 설정 캐싱 + L1 질문 fast-path → 2초 → 0.3초
- 프롬프트 캐싱: Gemini Cached Content API로 입력 토큰 60–70% 절감
- 황금 테스트셋: 50개 벤치마크 질문 + 자동 품질 평가(RAGAS)
- 자동 품질 평가: Agent 업데이트마다 회귀 테스트 자동 실행
AI Agent를 구축하면서 깨달은 가장 중요한 교훈:
AI Agent는 만드는 것보다 안정적으로 운영하는 게 더 어렵다.
엔진을 만드는 건 6주면 됩니다. 하지만 속도를 최적화하고, 비용을 관리하고, 품질을 자동으로 평가하는 운영 체계를 만드는 건 그보다 훨씬 오래 걸립니다.
에이전트 작업 흐름을 설계하는 일반 패턴은 에이전틱 워크플로우 패턴에, 계획·실행·검증을 나눈 사례는 PEV 워크플로우 사례에, 콘텐츠 생산에 적용한 구조는 AI 콘텐츠 파이프라인에 정리했습니다.

