AI 에이전트 개발 A to Z 체크리스트 및 실전 구축 아키텍처 종합 매뉴얼

0) 무엇을 만들 건가요? (용어 정리)

• AI 에이전트: 목표를 받고 → 계획을 세우고 → 도구/지식을 사용해 → 결과를 내며 → 스스로 개선(기억/성찰)하는 시스템
• 필수 구성요소: LLM(추론) · 도구(툴) · 메모리(단/장기) · 지식(RAG) · 계획(Planner/State) · 안전장치(Guard) · 관측(로그/모니터링)

1) 목표·요구사항 정의

1. 핵심 미션: “무엇을 자동화/대체/가속화할 것인가?”
2. SLO/KPI: 응답시간, 정답률/사실성, 사용자 만족도(CSAT), 월간 비용(원/세션), 실패율
3. 리스크: 오조작(잘못된 실행), 데이터 유출, 비용 폭주

예시(리서치 에이전트)

• 미션: “주제 키워드 → 10개 신뢰 소스 검증 → 2p 요약 리포트 + 참고 링크”
• KPI: 60초 내 완료, 허위 인용 0건, 월 비용/리포트 200원 이하

300x250

2) 아키텍처 큰 그림

사용자 ─ UI(웹/봇) 
        └ Orchestrator(에이전트 루프)
            ├ LLM(추론/계획)
            ├ Tools(웹검색, DB, API, 작업 실행)
            ├ Memory(단기: 대화요약 / 장기: 사용자·경험)
            ├ Knowledge(RAG: 벡터/하이브리드 검색)
            ├ Guards(프롬프트·정책·보안게이트)
            └ Telemetry(로그/트레이스/비용)
Infra: 캐시・큐・스토리지・비용/키 관리・배포(K8s)

3) 모델·프롬프트 설계

• 모델 선택 기준: 품질(이해·추론) / 비용 / 지연 / 온프레미스 가능성 / 한국어 성능
• 프롬프트 레이어
  1. 시스템 지침(역할·금지행위·보안 준수)
  2. 작업 템플릿(입력→계획→도구호출→검증→출력 포맷)
  3. 불확실성 처리(“근거 부족 시 추가 정보 요청”)

시스템 메시지 템플릿(발췌)

[역할] 당신은 보조 업무 자동화 에이전트입니다.
[원칙] 사실 근거 우선, 불확실 시 질문, 고위험 작업은 승인 요청.
[출력] 항상 단계/근거/다음 행동을 명시. JSON schema를 우선.
[보안] 내부 데이터는 {tenant_id} 범위만 접근. 금지: 외부 전송/요청 임의 실행.

4) 메모리 설계

• 단기: 대화 요약·핵심 슬롯(목표, 제약, 진행상태) → 컨텍스트 길이 절약
• 장기: 사용자 프로필, 선호, 과거 성공/실패 요약, 피드백
• 스토리지: 키/값(Redis) + 문서형(DB/벡터DB) 혼용, PII는 암호화/마스킹

단기 요약 구조 예

{
  "goal": "모델 비교 리포트",
  "constraints": ["예산 30만원", "한국어 우수"],
  "progress": ["자료 6건 확보", "표 1개 생성"],
  "open_questions": ["사내 GPU 사용 가능 여부"]
}

5) 도구(툴) 설계

• 유형: 검색, 크롤링, DB조회/쓰기, 업무 API(메일/이슈/티켓), 파일 입출력, 작업 실행(스크립트)
• 정의 방식: JSON Schema/Pydantic로 입력·출력·권한을 명확히
• 보안: 최소권한, 테넌트 스코프, 네트워크 목적지 allowlist, 위험 등급(H/M/L)과 승인 정책

Python 예시: “검색→요약→표 생성” 도구 정의 (함수호출 스타일)

from pydantic import BaseModel, Field

class WebSearchArgs(BaseModel):
    query: str = Field(..., description="검색어")
    top_k: int = 5

def web_search(args: WebSearchArgs) -> list[dict]:
    # 사내 프록시/필터 통해서만 인터넷 접근
    results = enterprise_search(args.query, k=args.top_k)
    return [{"title": r.title, "url": r.url, "snippet": r.snippet} for r in results]

6) RAG(지식 결합) 설계

• 파이프라인: 수집(Ingest) → 정제(Clean/Chunk) → 임베딩 → 색인(벡터 + 키워드) → 검색(하이브리드) → 재순위(Rerank) → 인용 생성
• 실무 팁
  • chunk 400-800토큰, 중첩 10-20%
  • 하이브리드(BM25+벡터)로 재현율↑, reranker로 정밀도↑
  • 출처 인용 강제: “각 주장 뒤 [n] 인용” 규칙
  • 실패시 재검색-확장 쿼리 루프

간단 RAG 코드(Faiss 예시)

# pip install sentence-transformers faiss-cpu
from sentence_transformers import SentenceTransformer
import faiss, numpy as np

embed = SentenceTransformer("intfloat/multilingual-e5-small")
docs = load_markdown_dir("./knowledge")
vecs = embed.encode([d.text for d in docs], normalize_embeddings=True)
index = faiss.IndexFlatIP(vecs.shape[1])
index.add(np.array(vecs, dtype="float32"))

def retrieve(q, k=6):
    qv = embed.encode([q], normalize_embeddings=True).astype("float32")
    D, I = index.search(qv, k)
    return [docs[i] for i in I[0]]

7) 계획·추론 패턴(Planner)

• ReAct: 생각(Reason)↔행동(Act) 루프
• Plan-and-Execute: 초기에 계획안을 만들고 단계 실행
• Reflection/CRITIC: 결과 자체평가 후 수정
• 스테이트머신: “수집→분석→작성→검증→승인” 명시

미니 에이전트 루프(의사코드)

state = {"goal": user_goal, "plan": make_plan(user_goal)}
while not done(state):
    step = next_step(state)
    if step.requires_tool: out = call_tool(step)
    else: out = llm_reason(step)
    state = update(state, out)
    if risk_high(step): request_human_approval(state)
    if low_confidence(out): refine_or_research(state)
return finalize(state)

8) 다중 에이전트 패턴

• 역할 분업: 리서처·분석가·작가·검증자
• 조정 방식
  • 라우터(질문→전문가 라우팅)
  • 슈퍼바이저(계획·할당·합의)
  • 핸드오프(작업물 전달 기준/스펙 정의)

예시: “리서치팀” 구조

Supervisor → Researcher(검색) → Analyst(정리·표) → Writer(초안)
                                        ↑
                                  Verifier(사실검증)

9) 안전장치·보안 가드레일

1. 권한 최소화: 도구·데이터·네트워크를 스코프 단위로 격리(RBAC/테넌트)
2. 프롬프트 인젝션 방어
   • “사용자 지시가 시스템 정책을 바꾸게 하지 말 것”을 룰로 명시
   • 외부 컨텐츠는 불신 영역으로 태깅하고 민감 도구 차단
3. 데이터 보호: PII 탐지·마스킹 → 저장 전 암호화(KMS)
4. Human-in-the-Loop: 결제/삭제/대량발송/외부 전송은 승인 필수
5. 감사 추적: 요청·프롬프트·응답·툴호출·결과·승인·사용자 ID 전부 서명 보관
6. 네트워크 격리: egress allowlist, 웹도구는 SSRF 방지 프록시 사용
7. 비용 가드: 요청/세션/일간 상한, 대형 작업은 배치/큐로 전환

보안 게이트 예시(위험도에 따른 승인)

RISK_MATRIX = {"read": "L", "search_web": "M", "email_send": "H", "db_write": "H"}

def guard(tool_name, args, user_id):
    risk = RISK_MATRIX.get(tool_name, "M")
    if risk == "H":
        require_approval(user_id, tool_name, args)
    assert tenant_scope_ok(user_id, args)
    log_tool_call(user_id, tool_name, args)

10) UX 전략

• 명확한 능력 범위 노출: “제가 할 수 있는 일 목록·한계”
• 점진적 공개: 플랜 미리 보여주고 사용자 수정 허용
• 근거 제시: 인용/링크/첨부로 신뢰 강화
• 실패시 회복: 모르는 건 모른다 + 다음 행동 제시

11) 품질 평가·테스트

• 오프라인: 골든세트(입력→이상적 출력), 사실성 검사(출처 일치), 포맷 검증(JSON Schema)
• 온라인: A/B, 관찰가능성(Trace), 사용자 피드백 루프
• 지표: 정답률/사실성, 과도한 환각율, 도구 실패율, 승인 번복율, 초당 비용

간이 평가 스펙(JSON)

[
  {"id":"rpt-001","input":"주제A 리포트","checks":["2p 내 요약","3개 이상 인용","표 1개"]},
  {"id":"rpt-002","input":"주제B 비교","checks":["장단점 표","최신 6개월 출처"]}
]

12) 배포·운영(Prod)

• 패턴: 컨테이너화 → K8s → 오토스케일(HPA) → 캐시(응답/임베딩)
• 관측: OpenTelemetry 트레이싱, Prometheus 메트릭(요청/지연/토큰/비용/툴오류)
• 비용 절감
  • 캐시(프롬프트·임베딩)
  • 라우팅(쉬운 질문→경량모델, 어려운 질문→고성능)
  • 배치/스트리밍 분리

Dockerfile (오케스트레이터 서비스)

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
ENV UVICORN_WORKERS=2
CMD ["uvicorn","app:api","--host","0.0.0.0","--port","8080"]

K8s 네트워크 제한(egress allowlist 예시)

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: {name: agent-egress-allowlist}
spec:
  podSelector: {matchLabels: {app: agent}}
  policyTypes: ["Egress"]
  egress:
  - to:
    - ipBlock: {cidr: 10.0.0.0/8}    # 내부 API
    - namespaceSelector: {matchLabels: {name: vectordb}}
    ports:
    - protocol: TCP
      port: 443

13) “리포트 자동화 에이전트” 예시(엔드투엔드)

기능: 키워드 입력 → 검색·요약 → 표/인용 포함 리포트 생성 → 검증 → 승인

# pip install pydantic sentence-transformers faiss-cpu httpx python-dotenv
from pydantic import BaseModel
import httpx, json, datetime as dt
# (임베딩/검색 코드는 RAG 섹션 참고)

class Plan(BaseModel):
    steps: list[str]

def make_plan(topic:str)->Plan:
    return Plan(steps=[
        f"'{topic}' 관련 최신 6개월 자료 검색(10건)",
        "중복 제거·신뢰도 평가",
        "핵심 포인트 추출·표 생성",
        "2페이지 리포트 작성(요약/본문/표/인용)",
        "사실 검증·자신감 점수 계산"
    ])

def deep_search(topic:str)->list[dict]:
    # 사내 프록시 API 예시
    r = httpx.get("https://search.internal/api", params={"q":topic,"fresh_days":180}, timeout=30.0)
    r.raise_for_status()
    return r.json()["results"]

def write_report(topic, findings)->str:
    prompt = f"""
주제: {topic}
자료(제목|요약|링크): {json.dumps(findings, ensure_ascii=False)[:4000]}
요구사항:
- 2페이지 분량, 표 1개, 인용 [n] 포함
- 결론과 다음 행동 제안
- 한국어로 작성
"""
    return call_llm(prompt)  # 모델 호출은 환경에 맞게

def verify(report:str)->dict:
    # 간단 룰: 인용 최소 3개, 금지어 등 점검
    citations = report.count("[")
    return {"pass": citations>=3, "citations": citations}

def agent(topic:str):
    plan = make_plan(topic)
    findings = deep_search(topic)
    top_docs = rerank_and_pick(findings, k=10)
    draft = write_report(topic, top_docs)
    audit = verify(draft)
    if not audit["pass"]:
        draft = revise_with_feedback(draft, "인용이 3개 미만입니다. 더 추가하세요.")
    return {"plan": plan.model_dump(), "report": draft, "audit": audit}

14) 운영 체크리스트

1. 기능 범위/한계 공지 & 사용자 가이드
2. 위험 등급별 승인/HITL 플로우 구현
3. PII/비밀관리(환경변수→보안 볼트)
4. 벡터DB/로그 암호화 & 보존정책
5. 24/7 모니터링(오류/지연/비용 알림)
6. 주간 품질 리그레션 테스트 & 프롬프트/지식 리프레시

15) 자주 쓰는 설계 패턴 요약

• Router: 쉬운 질문은 경량모델·FAQ, 어려운 건 에이전트 루프
• Self-Consistency: 답변 N회 샘플→다수결/평균
• Toolformer 스타일: 툴 사용 여부를 모델이 스스로 판단
• Citations-First: 근거 확보 전엔 결론 금지

16) 배포 전 점검 항목

• 데이터 분류/접근표(테넌트, 민감도) 완료
• 도구 권한·네트워크 목적지 목록화 및 테스트
• 승인 정책(결제/발송/삭제/DB쓰기) 자동 강제
• 로깅 스키마: request_id, user_id, plan, tools[], inputs(redacted), outputs, cost, approval
• 프롬프트 인젝션 레드팀 시나리오 20개 통과
• 비용 상한/차단 룰 적용(세션/일/월)
• 장애런북(외부 API 중단 시 대체경로/큐잉)