AI 에이전트 설계

핵심 철학

에이전트는 마법이 아닙니다. 입력, 출력, 메모리, 도구, 결정 로직을 갖춘 시스템입니다. 프로덕션 소프트웨어와 동일한 엄격함으로 설계하세요. 모든 에이전트는 명확한 목적, 정의된 경계, 명시적인 실패 모드를 가져야 합니다.

에이전트 설계 원칙

1. 행동하기 전에 의도 명확히 하기

에이전트는 사용자의 의도가 모호할 때 실행 불가능한 조치를 취하기 전에 명확한 질문을 해야 합니다. 다음 패턴을 사용하세요:

목표가 명확합니까? 그렇지 않다면, 집중된 질문 하나를 하세요.
제약 조건(범위, 출력 형식, 데이터 소스)이 알려져 있습니까?
성공은 어떤 모습입니까?

2. 코드보다 사양 먼저

에이전트 로직을 작성하기 전에 사양 또는 작업 목록 파일을 생성하세요:

에이전트의 역할과 책임 정의
필요한 모든 도구 목록 작성
입력/출력 계약 정의
실패 모드 및 대체 동작 식별
그런 다음 코드 작성

3. 단일 책임

각 에이전트는 한 가지 일을 잘 해야 합니다. 범용 에이전트 하나보다는 특화된 에이전트 팀을 선호하세요.

오케스트레이션 패턴

패턴	사용 시기	설명
순차(Sequential)	선형 파이프라인	에이전트가 고정된 순서로 연결됨 (초안 → 검토 → 게시)
감독자(Supervisor)	복잡한 다중 모듈 작업	리드 에이전트가 전문 작업자에게 라우팅
ReAct	자율 문제 해결	추론(Thought) + 행동(Tool Use) 결합
그룹 채팅(Group Chat)	협업 작업	인간 감독 하의 다중 에이전트 통신
DAG	상태 저장 워크플로우	순환적, 상태 저장 오케스트레이션을 위한 방향성 비순환 그래프

프레임워크 선택 가이드

프레임워크	최적 용도	상태
LangGraph	복잡한 상태 저장 에이전트, 순환 워크플로우, 다중 에이전트 오케스트레이션, 프로덕션급	✅ 활성 — 2025년 5월 GA
LangChain	간단한 RAG 파이프라인, 선형 워크플로우, 빠른 프로토타입	✅ 활성 — RAG에 사용, 에이전트에는 비권장
CrewAI	역할 기반 다중 에이전트 팀("관리자", "연구원", "작가")	✅ 활성
Microsoft Agent Framework	Azure 생태계의 엔터프라이즈 에이전트 — AutoGen + Semantic Kernel 대체	✅ 활성 — 2025년 10월 공개 미리보기, 2026년 1분기 GA 목표
AutoGen	레거시 — 여전히 작동하지만 새 기능 없음	⚠️ 2025년 10월 이후 유지 관리 모드
Custom (MCP)	개방형 표준을 통한 경량, 이식 가능, 상호 운용 가능한 에이전트 도구	✅ 활성

LangChain vs LangGraph — 무엇을 사용할까

LangChain 팀은 이제 명시적으로 다음과 같은 분할을 권장합니다:

LangGraph → 에이전트: 상태 저장, 순환, 다중 에이전트, 장기 실행 작업
LangChain → RAG 및 선형 파이프라인: 간단한 문서 Q&A, 단계별 변환

LangGraph는 LangChain 위에 구축되었습니다. 둘을 함께 사용할 수 있으며, LangChain으로 시작하여 더 많은 제어가 필요할 때 LangGraph로 전환할 수 있습니다.

RAG 파이프라인 설계

표준 RAG 흐름

사용자 쿼리 → 쿼리 임베딩 → 벡터 검색 → 청크 검색 → 프롬프트 증강 → LLM → 응답

청킹 전략 (2026년 모범 사례)

의미 기반 청킹 사용 — 문자 수가 아닌 의미를 기준으로 분할
청크 크기: 정밀도는 256–512 토큰, 서사 콘텐츠는 1024
항상 메타데이터(출처, 페이지, 섹션, 타임스탬프) 포함

하이브리드 검색 (권장)

최상의 재현율을 위해 밀집 벡터(의미 기반) + 희소 벡터(키워드 기반) 결합:

최종 점수 = α × 밀집 점수 + (1 - α) × 희소 점수

벡터 데이터베이스 선택

DB	최적 용도
pgvector	기존 PostgreSQL 스택, 간단한 사용 사례
Pinecone	관리형, 프로덕션 규모, 최소 운영
Weaviate	다중 모드, 내장 하이브리드 검색
Milvus	고성능, 자체 호스팅, 대규모
Chroma	로컬 개발, 프로토타이핑

에이전트 메모리 아키텍처

유형	설명	구현
컨텍스트 내	현재 대화 창	채팅 기록 배열
외부 단기	세션 범위 메모리	Redis / 인메모리 저장소
외부 장기	세션 간 지속	벡터 DB + 메타데이터
일화적	과거 상호작용 요약	요약 체인 → 벡터 저장소

컨텍스트 부패 경고: 긴 컨텍스트 창은 시간이 지남에 따라 에이전트 품질을 저하시킵니다. 관련성을 유지하기 위해 N 턴마다 요약 단계를 구현하세요.

도구 사용 및 함수 호출

도구 정의 패턴

모든 도구에는 다음이 필요합니다:

name: 설명적인_도구_이름
description: 이 도구를 사용해야 하는 시기와 기능 (명시적으로 표기)
parameters:
  - name: 매개변수_이름
    type: string
    description: 이 매개변수가 기대하는 값
    required: true

도구 사용 모범 사례

가능하면 도구는 멱등적이어야 합니다.
다음 단계로 전달하기 전에 항상 도구 출력을 검증하세요.
외부 도구 호출에는 타임아웃과 재시도를 구현하세요.
디버깅을 위해 모든 도구 호출을 로깅하세요.

에이전트 통신 패턴

의도 명확화 프로토콜

에이전트가 모호한 요청을 받았을 때:

모호함 식별 — 구체적으로 무엇이 불명확한가?
질문 하나 하기 — 전부가 아니라 가장 중요한 것
기본값 제안 — "별도로 알려주지 않으면 X로 가정하겠습니다"
되돌릴 수 없는 조치 전 확인 — 삭제, 게시, 전송 전에 항상 질문

진행 상황 보고

장기 실행 작업의 경우 에이전트는 다음을 보고해야 합니다:

[1/4 단계] 문서 가져오는 중... ✓
[2/4 단계] 청킹 및 임베딩... ✓
[3/4 단계] 벡터 저장소 쿼리 중...

오류 전달

✗ 도구 실패: [도구_이름]
이유: [구체적인 오류]
대체: [대신 수행 중인 작업]

MCP (모델 컨텍스트 프로토콜)

MCP는 에이전트를 외부 도구 및 데이터 소스에 연결하기 위한 개방형 표준입니다. 이식 가능하고 상호 운용 가능한 에이전트 도구를 구축할 때 사용하세요.

MCP 서버 구조

my-mcp-server/
├── server.py (또는 index.ts)
├── tools/
│   └── my_tool.py
└── README.md

MCP 사용 시기 vs 직접 통합

여러 에이전트/플랫폼에서 재사용 가능한 도구가 필요하면 MCP 사용
프로젝트별, 일회성 도구 구현에는 직접 통합 사용

자세한 MCP 서버 구현 지침은 mcp-builder 스킬을 참조하세요.

보안 및 안전

절대 에이전트가 샌드박싱 없이 임의 코드를 실행하도록 허용하지 마세요.
모든 LLM API 호출에 속도 제한을 구현하세요.
도구에 전달하기 전에 모든 입력을 검증 및 정화하세요.
감사 가능성을 위해 모든 에이전트 결정을 로깅하세요.
토큰 비용 폭주나 재귀 루프를 방지하기 위한 가드레일을 구현하세요.
시스템 프롬프트 주입 보호 사용 — 사용자 입력과 시스템 지시를 명확한 구분자로 분리하세요.

복원력 있는 에이전트 설계(자가 치유)

에이전트는 프로덕션에서 실패합니다. 처음부터 복구를 고려하여 설계하세요.

검증-재시도 루프 (LoopAgent 패턴)

출력 생성 → 출력 검증 → 유효하지 않은 경우: 피드백 + 재생성
최대 반복: 3  ← 무한 루프 방지를 위한 회로 차단기

계획–검증–실행–관찰–재계획

계획:     계획 생성, 실행 전 실현 가능성 확인
실행:     조치 취하기
관찰:     성공했는가? 출력 확인, 테스트 실행
재계획:   관찰 결과 실패 시 → 조정 후 재시도
중단:     최대 재시도 도달 시 → 실패 명확히 보고, 도움 요청

에이전트 대체 계층

기본 접근 방식 실패 → 대체 접근 방식 시도
대체 실패           → 개발자에게 명확화 요청
명확화 없음          → 안전한 기본 작업 또는 정상 중단

제공 전 출력 검증

생성된 코드를 제공하기 전에 테스트/린트 실행
출력 형식이 요구 사항과 일치하는지 확인
별도의 검증기 단계(다른 모델 또는 프롬프트)를 사용하여 생성기 출력 확인
검증되지 않은 출력을 완료된 것으로 제공하지 마세요.

에이전트용 회로 차단기

이탈 동작을 방지하기 위한 하드 리미트 설정:

작업당 최대 도구 호출 반복 횟수 (예: 10)
세션당 최대 토큰 지출
실패 단계당 최대 재시도 횟수 (예: 3)
도구 호출당 타임아웃

전체 복원력 철학 및 코드 패턴은 self-healing-mindset 스킬을 참조하세요.

즐겨 사용하는 AI에게 물어보기

문서