---
id: platform-ai-agent-development
title: "AI 에이전트 개발 가이드"
category: "Platform_Engineering"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["AI agent development", "AI 에이전트 개발", "LLM app", "agent architecture", "RAG agent"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.89
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["platform", "ai", "agent", "llm", "guide", "platform-independent"]
raw_sources: ["일반 AI 에이전트 공학 지식", "AstraAI 전체 (실증 사례)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[AI 에이전트 개발 가이드]]

## 🎯 한 줄 통찰 (One-line insight)
AI 에이전트 개발의 핵심은 "**검색(RAG)·기억(Memory)·도구(Tool)·검증(Critic)·오케스트레이션**" 을 자원 제약에 맞게 조합하는 것 — 특히 작은 로컬 모델에선 *결정론 우선·강한 grounding·자기검증* 이 품질을 가른다. AstraAI 전체가 이 가이드의 실증이다.

## 🧠 핵심 개념 (Core concepts)
컨텍스트 조립, RAG, 다계층 메모리, 도구 호출, 자기검증/critic, 프롬프트 엔지니어링, 멀티에이전트 오케스트레이션, 모델 라우팅/폴백.

## 📖 세부 내용 (Details · 12-field)
- **Problem:** LLM(특히 작은 모델)으로 신뢰 가능·근거 있는·행동하는 시스템을 만들기.
- **Recommended Architecture:** 턴 파이프라인(컨텍스트 조립 → 라우팅 → 생성 → 후처리/검증 → 학습) + RAG + 메모리 + 도구 + 검증 레이어. 흐름 골격은 한 곳([[Agent 오케스트레이터 분해]]).
- **Folder Structure:** `src/{retrieval/, memory/, intelligence/(검증), agent/(handlePrompt,llm,actions), providers/, lib/contextBuilders/}` — AstraAI 구조.
- **Core Components:** RAG([[RAG Pattern]]), 메모리([[Memory Pattern]]), 도구 실행([[Tool Calling Pattern]]), 검증([[Critic Pattern]]/[[Reflection Pattern]]), 프롬프트 빌더([[프롬프트 엔지니어링 패턴]]), 프로바이더([[LLM 프로바이더 추상화]]).
- **State Management:** 대화=단기 메모리, 지식=RAG/장기, 작업 상태=세션 store. 컨텍스트는 토큰 예산 내 선별.
- **Error Handling:** 엔진 폴백, 빈 응답 soft failure, JSON 강건 파싱, 환각 가드([[Error Handling Pattern]], [[Intelligence 검증 레이어]]).
- **Testing Strategy:** 순수 함수 단위(토크나이저/스코어/파서), 검색 평가 하니스(recall@k/MRR), 회귀 케이스(정정 재검사), 프롬프트 골든셋.
- **Scaling Strategy:** 인덱스 캐시(mtime), 토큰 예산, 순차/자원 인지 동시성, sleep-time 사전소화, 클라우드 폴백.
- **Common Mistakes:** 에이전트 남발(hop 손실), 임베딩 단독 의존, 매 턴 LLM 검수(비용), JSON 직접 파싱, 모델 출력 무검증 실행, system 없는 호출(작은 모델 거절).
- **Refactoring Patterns:** 5-persona→단일 작성자([[ADR-0003 단일작성자 다중역할 멀티에이전트]]), 동적→정적, 휴리스틱→골든셋 보정, 프롬프트 블록화.
- **Real-world Tradeoffs:** 로컬(프라이버시/비용 ↔ 품질) vs 클라우드, 결정론(가용/설명 ↔ 의미) vs 임베딩, 검증 깊이(정확 ↔ latency), 멀티에이전트(다양성 ↔ 자원/손실).
- **Design Heuristics:** "결정론 우선, 의미는 가산", "작은 모델엔 강한 system+명시 규칙", "근거 없으면 모른다", "검증 비용은 위험에 비례", "에이전트 추가 전 정보 손실 점검", "동시성은 하드웨어가 결정".

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
"더 큰 모델·더 많은 에이전트" 가 답이 아니다 — 자원 제약 하에선 *잘 설계된 RAG+메모리+검증* 이 작은 모델을 크게 끌어올린다. 이 위키 자체가 그 전략(제2뇌)의 산물.

## 🛠️ 적용 사례 (Applied in summary)
AstraAI(Astra) — RAG/메모리/검증/멀티에이전트의 통합 실증. 본 위키 [[AstraAI 아키텍처 개요]] 및 AI_Training 시리즈.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[플랫폼 개발 가이드 인덱스]]
- **관련 개념:** [[RAG Pattern]], [[Memory Pattern]], [[Agent Orchestration Pattern]], [[Critic Pattern]], [[Tool Calling Pattern]], [[Intelligence 검증 레이어]]
- **참조 맥락:** 작은 모델이 *자기 같은* AI 에이전트 시스템을 설계할 때 최상위 가이드로 참조.

## 📚 출처 (Sources)
- [S1] 일반 AI 에이전트/LLM 앱 공학 지식
- [S2] AstraAI 전체 — 실증 사례

## 📝 변경 이력 (Change history)
- 2026-06-13: 플랫폼 독립 AI 에이전트 개발 가이드 초안.
