---
type: knowledge
domain: architecture
status: active
last-reviewed: 2026-07-27
---

# AI·에이전트 설계

> 한 줄 정의
> 외주·SI에서 AI·에이전트 기능의 설계 결정 목록·판단 기준과, **AI 처리 흐름도·평가 리포트·데이터 명세**로의 납품 연결. 핵심 원칙 둘: **결정적 로직과 LLM 판단을 분리**하고, **정확도 기준을 검수 기준으로 착수 전 합의**한다. 아키텍처·평가의 기술 원리는 [[Agent Architecture]]·[[Agent Evaluation]] 등 01_AI에이전트가 정본.

## 설계 대상과 납품 산출물

| 설계 대상 | 납품 산출물 | 검수에서 판정되는 것 |
|---|---|---|
| 파이프라인 구조(결정적 vs LLM) | **AI 처리 흐름도** | 어느 단계가 LLM 판단인지, 실패 시 어디로 가는지 보이는가 |
| 평가 게이트·정확도 기준 | **평가 리포트** | 사전 합의한 기준·케이스셋으로 측정됐는가 — 검수 서명의 근거 |
| 입력·학습·평가 데이터 | **데이터 명세** | 데이터 출처·범위·보존이 발주사와 합의됐는가 |
| HITL(사람 승인 게이트) | 흐름도 + 화면정의서 승인 화면 | 자동 실행 금지 구간이 지켜지는가 |

기획 측 입력 템플릿: [[01_데이터 계약·품질 규칙]] · [[03_베이스라인·평가 계획]] · [[평가-계획-템플릿]] · [[에이전트-명세-템플릿]].

## 핵심 결정 항목 — 판단 기준

| 결정 | 판단 기준 | 기록 위치 |
|---|---|---|
| 결정적 vs LLM 분리 | 규칙으로 판정 가능한 것(집계·검증·라우팅 조건)은 코드로, LLM은 자연어 이해·생성만 — LLM 단계가 줄수록 검수가 쉬워진다 | AI 처리 흐름도 |
| 에이전트 구조 | 단일 에이전트+내부 라우팅이 기본값, 멀티 에이전트 승격은 근거를 ADR로 ([[Multi Agent Architecture]]·[[Supervisor Pattern]]) | ADR |
| 상태 관리 | 대화·작업 상태의 저장 위치·수명·초기화 조건을 명시 ([[State Management]]) — 상태 누수는 재현 어려운 결함이 된다 | 흐름도·명세 |
| 프롬프트·컨텍스트 관리 | 프롬프트를 버전 관리 대상 산출물로 취급 — 변경이 곧 동작 변경이므로 평가 재실행과 세트 | 소스 저장소 |
| 평가 게이트 | **정확도 기준(예: 분류 90%)을 건수로 환산해 착수 전 검수 기준으로 합의** — 기준 없는 "잘 되네요" 검수는 무한 반복된다. 케이스셋(Ground Truth)은 버전 관리 ([[Ground Truth]]) | 평가 계획·평가 리포트 |
| 무성 실패 금지 | 모든 실패는 기록·통지되거나 사람에게 넘어간다 — 조용히 삼켜진 실패는 발견 시점이 곧 분쟁 시점이다 | 흐름도 실패 경로 |
| HITL 지점 | 외부 발신(메일·결제)·데이터 변경은 사람 승인 게이트 뒤에 ([[Human In the Loop]]·[[보안 원리]] 도구 권한 계층화) — 자동화 범위 자체를 발주사와 합의 | 흐름도·승인 화면 |

## 다른 역할과의 경계

- **백엔드**: LLM 호출도 외부 연동이다 — 타임아웃·재시도·폴백은 [[01_백엔드 설계]]의 연동 규율을 따른다.
- **데이터·DB**: 대화 로그·트레이스의 보존 정책과 평가 데이터 명세는 [[02_데이터·DB 설계]]와 공동 — LLM 로그는 무한 적재가 기본값이 되기 쉽다 ([[데이터 원리]]).
- **인프라**: 폐쇄망의 LLM 게이트웨이 경유·비용 상한 알림은 [[04_인프라 설계]] 소관 — 외부 LLM API 호출 가능 여부가 아키텍처를 결정한다.
- **프론트엔드**: 스트리밍·실행 상태 노출·승인 UI는 [[03_프론트엔드 설계]]와 [[프론트엔드 원리]] AI 응답 UX 절.
- **보안·QA**: 프롬프트 인젝션 방어는 [[05_보안 설계]], 평가 게이트의 독립 판정은 QA — 개발자 자체 평가로 대체하지 않는다.

## 외주 특수 제약 — AI는 검수 기준 분쟁의 신영역

- 확률적 출력은 "100% 정확"이 불가능하다 — **오류 허용치(건수)와 오류 시 처리(사람 폴백)를 계약 언어로** 박아야 검수가 끝난다. 실물 물량 기준 환산이 합의를 쉽게 한다 (예: 하루 100건 처리 기준 90% = 하루 10건 오분류).
- 평가 케이스셋은 발주사 실데이터로 만들고 **발주사 확인 서명**을 받는다 — 수행사 자작 케이스로 통과한 평가는 검수 근거가 못 된다.
- 모델·프롬프트 변경은 동작 변경이다 — 유지보수 단계의 모델 교체·성능 개선 요청은 CR 회부 ([[SI 수주와 범위 관리]]).
- 발주사 데이터의 외부 LLM 전송 가능 여부는 보안 심사 사항 — 착수 전 서면 확인 ([[05_보안 설계]]).

## 안티패턴

- **전부 LLM에 맡기기** — 집계·조회까지 LLM이 하면 느리고 검증 불가. 결정적으로 풀리는 것부터 코드로.
- **평가 없는 데모 검수** — 시연 몇 건으로 "된다"를 합의하면 운영 투입 후 오류율이 그대로 분쟁이 된다.
- **무성 실패** — 실패를 삼키고 빈 응답·묵묵부답으로 넘어가는 설계. 모든 실패에 경로를 그린다.
- **HITL 없는 외부 발신** — 에이전트가 사람 승인 없이 메일·결제를 실행하는 구조. 사고 한 건이 프로젝트 신뢰를 끝낸다.
- **프롬프트 무버전 관리** — 누가 언제 바꿨는지 모르는 프롬프트는 평가 리포트를 무효화한다.

## 관련 문서

- [[00_설계 허브]] · [[00_역할별 설계 지도]] · [[01_백엔드 설계]] · [[02_데이터·DB 설계]] · [[04_인프라 설계]] · [[05_보안 설계]]
- [[Agent Architecture]] · [[Workflow Design]] · [[State Management]] · [[Human In the Loop]] · [[10_지식/01_AI에이전트/13_가드레일/가드레일|가드레일]] · [[Prompt Injection]]
- [[Agent Evaluation]] · [[Ground Truth]] · [[LLM-as-a-Judge]] · [[Tracing]] · [[Cost Monitoring]]
- [[외주 개발 산출물]] · [[SI 수주와 범위 관리]] · [[설계 결정과 리뷰]]