> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifi.life/llms.txt
> Use this file to discover all available pages before exploring further.

# 프로덕션 운영 가이드

> 이 문서는 **[GenAI 개념](/blog/guides/genai-concepts/overview)** 섹션의 일부입니다.

[← AI Agent 아키텍처 개요](overview)

***

## Agent 프로덕션 안전성

Agent를 프로덕션 환경에 배포할 때는 **안전성(Safety)** 이 핵심입니다. LLM의 비결정적 특성 때문에 전통적인 소프트웨어보다 더 철저한 안전장치가 필요합니다.

### 도구 접근 권한 제어

Agent에게 부여하는 도구 권한은 **최소 권한 원칙(Least Privilege)** 을 따라야 합니다.

| 단계                        | 접근 수준         | 예시                            |
| ------------------------- | ------------- | ----------------------------- |
| **1단계: Read-Only**        | 조회만 가능        | SQL Agent가 `SELECT`만 실행 가능    |
| **2단계: Read-Write (제한적)** | 특정 테이블/컬럼만 쓰기 | 고객 메모 필드만 업데이트 가능             |
| **3단계: Read-Write (전체)**  | 모든 쓰기 가능      | `UPDATE`, `DELETE` 포함 — 주의 필요 |

> **참고**
> Databricks에서는 **Unity Catalog 권한** 이 이를 자동으로 강제합니다. Agent의 서비스 프린시펄에 `SELECT` 권한만 부여하면, Agent가 아무리 `DELETE` 쿼리를 생성해도 실행이 거부됩니다.

### Human-in-the-Loop 승인 패턴

고위험 행동(금융 거래, 데이터 삭제, 이메일 발송 등)에는 **사람의 승인** 을 요구해야 합니다.

**Human-in-the-Loop 흐름:**

* Agent: "고객 A에게 환불 120만원을 처리하려고 합니다. 승인하시겠습니까?"
  * **승인**→ 환불 실행
  * **거부**→ "환불이 취소되었습니다. 다른 조치가 필요하신가요?"

Agent가 고위험 행동을 감지하면 실행을 멈추고 사용자에게 확인을 요청하는 방식으로 구현합니다.

### 비용 제어

Agent가 무한 루프에 빠지거나 과도한 리소스를 사용하는 것을 방지합니다.

| 제어 항목                | 설정 예시            | 목적           |
| -------------------- | ---------------- | ------------ |
| **Max Token Budget** | 세션당 최대 50,000 토큰 | LLM 호출 비용 제한 |
| **Max Tool Calls**   | 요청당 최대 10회 도구 호출 | 무한 루프 방지     |
| **Timeout**          | 요청당 최대 60초       | 응답 지연 방지     |

### Guardrails 구현

Agent의 입력과 출력 양쪽에 안전 필터를 적용합니다.

* **Input Guardrails**: 프롬프트 인젝션 차단, 입력에 포함된 PII(개인정보) 감지
* **Output Guardrails**: PII 유출 방지, 유해 콘텐츠 차단, 주제 이탈(off-topic) 응답 필터링

### 위험 수준별 대응 전략

| 위험 수준     | 행동 예시               | 대응 전략                   | Databricks 기능                 |
| --------- | ------------------- | ----------------------- | ----------------------------- |
| **낮음**    | 데이터 조회, 문서 검색       | 자동 실행 허용                | UC 권한 (SELECT only)           |
| **중간**    | 데이터 업데이트, 보고서 생성    | 로깅 + 사후 검토              | MLflow Tracing, AI Guardrails |
| **높음**    | 금융 거래, 데이터 삭제       | Human-in-the-Loop 승인 필수 | Review App, 승인 워크플로우          |
| **매우 높음** | 시스템 설정 변경, 대량 메일 발송 | 자동화 금지, 수동 처리           | Agent 도구에서 제외                 |

***

## Agent 디버깅 가이드

Agent 디버깅은 전통적인 소프트웨어 디버깅과 근본적으로 다릅니다. Agent는 **비결정적**(같은 입력에 다른 출력), **다단계**(여러 도구 호출 연쇄), **도구 의존적**(외부 시스템 상태에 따라 결과 변동)이기 때문입니다.

### MLflow Tracing으로 Agent 추적

MLflow Tracing은 Agent 실행의 모든 단계를 기록합니다.

```
Trace (전체 요청)
├── Span: LLM 호출 #1 (사용자 의도 분석)
│   ├── Input: 사용자 메시지 + System Prompt
│   ├── Output: Tool Call 결정 (search_documents)
│   └── Duration: 1.2s
├── Span: Tool 실행 #1 (search_documents)
│   ├── Input: {"query": "분기 매출"}
│   ├── Output: [문서 3건]
│   └── Duration: 0.8s
├── Span: LLM 호출 #2 (결과 분석 + 추가 행동 결정)
│   ├── Input: 이전 컨텍스트 + 도구 결과
│   ├── Output: Tool Call 결정 (execute_sql)
│   └── Duration: 1.5s
└── Span: LLM 호출 #3 (최종 응답 생성)
    ├── Input: 모든 수집된 정보
    ├── Output: 최종 분석 보고서
    └── Duration: 0.9s
```

Trace 계층 구조:

* **Span**: 개별 작업 단위 (LLM 호출 1회, 도구 실행 1회 등)
* **Trace**: 하나의 요청에 대한 전체 Span 모음
* **Run**: 여러 Trace를 포함하는 실험 단위

### 흔한 Agent 실패 패턴과 해결법

| 실패 패턴           | 원인                   | 해결법                                           |
| --------------- | -------------------- | --------------------------------------------- |
| **잘못된 도구 선택**   | Tool description이 모호 | 도구 설명을 더 명확하고 구체적으로 수정                        |
| **무한 루프**       | 종료 조건 불명확            | `max_iterations` 설정, System Prompt에 명확한 종료 지시 |
| **도구 호출 실패 무시** | 에러 핸들링 부재            | 도구 실패 시 대안 행동을 System Prompt에 지시              |
| **환각 기반 행동**    | 컨텍스트 부족              | RAG로 관련 정보 제공, 도구 결과에 기반하여 답변하도록 지시           |
| **과도한 도구 호출**   | 비용이 높은 추론            | System Prompt에 효율적 행동 지시, 도구 통합               |

> **주의**
> **디버깅 팁**: Agent가 예상과 다르게 동작할 때, MLflow Tracing에서 **LLM이 무엇을 "생각"했는지**(Thought), **어떤 도구를 선택했는지**(Action), **어떤 결과를 받았는지**(Observation)를 순서대로 확인하세요. 대부분의 문제는 도구 설명의 모호함이나 System Prompt의 불완전함에서 비롯됩니다.

***

## Agent 설계 안티패턴

프로덕션 Agent를 수십 개 구축하면서 반복적으로 목격한 설계 실수들입니다. 이 안티패턴을 미리 알고 피하면 개발 기간과 운영 비용을 크게 줄일 수 있습니다.

### 1. God Agent (전능한 Agent)

**증상**: 하나의 Agent에 모든 도구(20개 이상)와 모든 역할을 몰아넣음.

**왜 문제인가**: LLM의 Context Window에 도구 설명만으로 수천 토큰이 소비되고, 도구 선택 정확도가 50% 이하로 급락합니다. System Prompt도 비대해져서 LLM이 핵심 지시를 놓칩니다.

**해결**: 역할 분리. "이 Agent는 무엇을 하지 않는가?"를 먼저 정의하세요. 하나의 Agent는 하나의 역할(데이터 조회, 문서 검색, 보고서 생성 등)에 집중해야 합니다.

### 2. Chatty Agent (수다스러운 Agent)

**증상**: 매 단계마다 "이렇게 해도 될까요?", "다음으로 진행할까요?"라며 사용자에게 확인을 요청.

**왜 문제인가**: 사용자가 "매출 보고서 만들어줘"라고 했는데 5번이나 확인을 요구하면 Agent를 쓰는 의미가 없습니다. UX가 최악이 됩니다.

**해결**: **자율성 수준을 3단계로 설정** 하세요.

* **자율 실행**: 읽기 작업 (데이터 조회, 문서 검색) → 확인 없이 바로 실행
* **사후 보고**: 쓰기 작업 (데이터 업데이트, 파일 생성) → 실행 후 결과 보고
* **사전 승인**: 고위험 작업 (삭제, 금융 거래, 외부 발송) → 실행 전 반드시 확인

### 3. Blind Agent (맹목적 Agent)

**증상**: 도구 호출 결과를 검증하지 않고 그대로 사용. SQL 결과가 비정상적이어도 그대로 보고서에 포함.

**왜 문제인가**: 도구가 에러를 반환하거나 비정상적인 결과를 줘도 Agent가 무비판적으로 수용하면, 잘못된 정보가 사용자에게 전달됩니다. 이것이 "할루시네이션"보다 위험한 이유는, 실제 데이터에 기반한 것처럼 보이기 때문입니다.

**해결**: System Prompt에 **결과 검증 규칙** 을 추가하세요.

```
도구 결과를 사용하기 전에 다음을 확인하세요:
- 숫자가 상식적인 범위인가? (매출이 음수이면 비정상)
- 결과 건수가 예상 범위인가? (0건이면 검색 조건 재검토)
- 데이터 형식이 올바른가? (날짜, 통화 등)
비정상적인 결과가 의심되면 사용자에게 알리세요.
```

### 4. Amnesia Agent (건망증 Agent)

**증상**: 이전 대화에서 이미 조회한 데이터를 다시 조회하고, 사용자가 알려준 정보를 기억하지 못함.

**왜 문제인가**: 같은 SQL을 반복 실행하면 비용이 낭비되고, 사용자 경험이 나빠집니다. "방금 알려줬잖아요"라는 불만이 나옵니다.

**해결**:

* **단기**: Working Memory(Agent State)에 이번 세션의 주요 결과를 저장
* **장기**: Long-term Memory(Vector Search, Lakebase)로 세션 간 기억 유지
* **최소한의 구현**: System Prompt에 "이전 도구 호출 결과를 재활용하라" 지시 추가

### 5. Over-engineered Agent (과잉 설계 Agent)

**증상**: FAQ 봇에 Supervisor + 3개 Worker Agent + Plan-and-Execute + Long-term Memory를 구현.

**왜 문제인가**: 간단한 작업에 복잡한 아키텍처를 적용하면 지연 시간 증가, 비용 폭발, 디버깅 불가능이 됩니다. 사용자 질문 1개에 내부적으로 LLM 호출이 10회 발생하면 응답에 20초 이상 걸립니다.

**해결**: **"Single Agent First" 원칙** 을 따르세요.

1. 먼저 Single Agent + ReAct로 구현
2. 성능 평가(Agent Evaluation) 실행
3. 정확도가 부족한 부분만 식별
4. 해당 부분에 한정하여 도구 추가 또는 Agent 분리
5. 다시 평가 → 반복

> **주의**
> **가장 흔한 실수**: "우리 시스템은 복잡하니까 처음부터 Multi-Agent로 가야 한다"는 생각. 실제로는 **도구 설명의 품질을 높이는 것** 만으로도 Single Agent의 성능이 극적으로 개선되는 경우가 대부분입니다.

***

## Agent 프로젝트 시작 가이드

처음 Agent를 구축하는 팀을 위한 실전 가이드입니다. 수많은 PoC를 진행하면서 정립된 순서입니다.

### PoC 설계 체크리스트

Agent PoC를 시작하기 전에 아래 항목을 반드시 정리하세요. 이것이 없으면 PoC가 "기술 데모"에 그치고 비즈니스 가치를 입증하지 못합니다.

| 항목         | 질문                      | 예시 답변                            |
| ---------- | ----------------------- | -------------------------------- |
| **사용 사례**  | Agent가 해결할 구체적인 업무는?    | "영업팀이 고객 문의에 답변하는 시간을 50% 단축"    |
| **대상 사용자** | 누가 이 Agent를 사용하나?       | "영업팀 20명, Slack에서 사용"            |
| **필요 도구**  | Agent가 접근해야 할 시스템/데이터는? | "CRM DB (고객 정보), 제품 카탈로그, 계약 문서" |
| **평가 기준**  | 성공/실패를 어떻게 판단하나?        | "100개 테스트 질문 대비 정확도 80% 이상"      |
| **위험 수준**  | Agent가 데이터를 변경하나?       | "조회만 가능, 쓰기 작업 없음 (Read-Only)"   |
| **기대 효과**  | ROI를 어떻게 측정하나?          | "월 200시간 수동 조회 → 40시간으로 감소"      |

### 첫 Agent 구축 순서

```
1단계: AI Playground에서 프롬프트 테스트
  → System Prompt 초안 작성, 다양한 질문으로 LLM 응답 품질 확인
  → 이 단계에서 LLM이 답할 수 없는 질문 목록 = 필요한 도구 목록

2단계: 도구 1~2개로 Single Agent 구축
  → 가장 핵심적인 도구만 연결 (예: SQL 조회 1개, 문서 검색 1개)
  → MLflow Tracing 활성화

3단계: Agent Evaluation 실행
  → 30~50개 테스트 질문 + 기대 답변 세트 준비
  → MLflow Evaluate로 자동 평가 (정확도, 지연시간, 비용)

4단계: 도구 추가 및 프롬프트 개선
  → 평가 결과 기반으로 부족한 부분에 도구 추가
  → System Prompt에 실패 케이스 대응 규칙 추가

5단계: 필요시 Multi-Agent 전환
  → 도구가 15개를 넘거나 도메인이 분리되면 Agent 분리 검토
  → Supervisor 패턴으로 시작
```

### MVP Agent의 정의

> **성공**
> **MVP Agent의 목표**: "80%의 정확도로 20%의 업무를 자동화하는 것".

100% 자동화를 처음부터 목표하면 반드시 실패합니다. Agent의 가치는 "완벽한 자동화"가 아니라, "반복적인 단순 작업을 줄여서 사람이 고부가가치 작업에 집중할 수 있게 하는 것"입니다.

첫 번째 Agent가 성공하면, 그 경험을 바탕으로 두 번째, 세 번째 Agent를 빠르게 구축할 수 있습니다. 첫 번째 Agent에 6개월을 쏟는 것보다, 2개월 만에 MVP를 출시하고 사용자 피드백으로 개선하는 것이 훨씬 효과적입니다.

***

## 고객이 자주 묻는 질문

**Q: "Agent와 RPA의 차이가 뭔가요?"**

RPA(Robotic Process Automation)는 **규칙 기반(if-then)** 자동화입니다. 사전에 정의된 경로만 따라갑니다. 반면 AI Agent는 **LLM 기반 자율 판단** 으로, 상황에 따라 유연하게 대응합니다. RPA는 "매일 9시에 이 보고서를 다운로드하라"는 고정 작업에 적합하고, Agent는 "이 데이터를 분석하고 이상이 있으면 알려달라"는 판단이 필요한 작업에 적합합니다.

**Q: "Agent가 실수하면 어떻게 하나요?"**

3중 안전장치를 적용합니다:

1. **Human-in-the-Loop**: 고위험 행동에 사람의 승인 요구
2. **Guardrails**: 입출력에 안전 필터 적용
3. **MLflow Tracing**: 모든 실행 과정을 추적하여 실수 원인 분석 및 개선

**Q: "몇 개 Agent가 적당한가요?"**

**Single Agent로 시작** 하세요. 도구가 15개를 넘으면 Agent를 분리하는 것을 검토합니다. 대부분의 실무 시나리오는 **3\~5개 Agent** 면 충분합니다. 불필요하게 많은 Agent는 복잡도와 비용만 증가시킵니다.

***

[← AI Agent 아키텍처 개요로 돌아가기](overview)