왜 Agent가 실패할까?

"Agent 만들었는데 쓸모가 없어요." 제조 현장에서 가장 많이 듣는 말이다.

대부분 설계 단계에서 실패한다.

---

원칙 1: 하나의 Agent, 하나의 역할

나쁜 설계:

만능 Agent
  - 설비 관리
  - 품질 관리
  - 재고 관리
  - 인사 관리
  - 회계 관리
  → Tool 50개, 프롬프트 3000토큰
  → LLM이 혼란 → 엉뚱한 Tool 호출

좋은 설계:

설비 관리 Agent (Tool 6개)
  - get_equipment_status
  - get_alarm_history
  - search_manual
  - get_maintenance_log
  - get_maintenance_schedule
  - create_work_order

품질 관리 Agent (Tool 5개)
  - get_quality_data
  - get_defect_breakdown
  - get_spc_chart
  - search_quality_standard
  - create_quality_report

"Tool이 10개를 넘으면 LLM이 흔들린다." 역할을 명확히 나누자.

---

원칙 2: Tool 이름이 곧 문서다

LLM은 Tool의 이름과 설명만 보고 선택한다.

나쁜 Tool 이름:

- func1()
- getData()
- process()
- doSomething()

좋은 Tool 이름:

- get_equipment_status()     -> 설비 상태 조회
- check_inventory()          -> 재고 확인
- search_manual()            -> 매뉴얼 검색
- get_alarm_history()        -> 알람 이력 조회
- create_work_order()        -> 작업지시 생성

이름 규칙:

접두사	의미	예시
get_	조회 (읽기)	get_equipment_status
check_	확인/검증	check_inventory
search_	검색	search_manual
create_	생성 (쓰기)	create_work_order
update_	수정	update_maintenance_plan
calculate_	계산	calculate_oee

---

원칙 3: Tool 설명은 상세하게

나쁜 설명:

{
  "name": "get_equipment_status",
  "description": "설비 상태 조회"
}

좋은 설명:

{
  "name": "get_equipment_status",
  "description": "특정 설비의 현재 가동 상태를 조회합니다. 설비 ID를 입력하면 가동/비가동 상태, 현재 가동률, 활성 알람 목록, 마지막 점검일을 반환합니다. 설비 ID는 'CNC-001', 'PRESS-005' 형식입니다. 와일드카드(*)를 사용하면 라인 전체를 조회할 수 있습니다."
}

LLM은 설명이 구체적일수록 정확하게 Tool을 선택한다.

---

원칙 4: 에러 처리는 필수

제조 현장에서 시스템은 자주 불안정하다. 네트워크 끊김, MES 점검, 데이터 누락...

나쁜 에러 처리:

def get_equipment_status(equipment_id):
    result = mes_api.get(equipment_id)  # MES 다운이면?
    return result                        # 크래시!

좋은 에러 처리:

def get_equipment_status(equipment_id: str) -> str:
    try:
        result = mes_api.get(equipment_id)
        if not result:
            return f"설비 {equipment_id}를 찾을 수 없습니다. ID를 확인해주세요."
        return format_status(result)
    except ConnectionError:
        return "MES 시스템에 연결할 수 없습니다. 네트워크 상태를 확인해주세요."
    except TimeoutError:
        return "MES 응답 시간 초과. 잠시 후 다시 시도해주세요."

Tool이 에러를 문자열로 설명하면, LLM이 사용자에게 적절히 안내할 수 있다.

---

원칙 5: 안전 장치를 넣어라

제조 현장의 Agent는 실제 시스템을 건드린다. 잘못된 작업지시가 나가면 생산 라인이 멈춘다.

위험도별 Tool 분류:

[읽기 전용 - 안전]
  get_equipment_status, search_manual, check_inventory
  → 자유롭게 호출 가능

[데이터 수정 - 주의]
  update_maintenance_plan, create_quality_report
  → 로그 기록 필수

[시스템 제어 - 위험]
  create_work_order, emergency_stop, adjust_parameters
  → 반드시 사람 확인 후 실행

# 위험한 Tool에는 확인 단계를 넣는다
def create_work_order(details: str) -> str:
    """작업 지시를 생성합니다. 실행 전 반드시 사용자 확인을 받습니다."""
    # 미리보기만 생성
    preview = format_work_order_preview(details)
    return f"""
작업 지시 미리보기:
{preview}

[주의] 이 작업 지시를 실제로 생성하시겠습니까?
'승인'이라고 입력하면 생성됩니다.
"""

---

5대 원칙 요약

#	원칙	핵심
1	단일 역할	Tool 10개 이내
2	명확한 이름	동사_목적어 형식
3	상세한 설명	입출력, 형식, 예시 포함
4	에러 처리	문자열 반환으로 안내
5	안전 장치	위험 Tool은 확인 단계

"Agent는 코드가 아니라 설계로 성패가 갈린다."