설계: Agent 아키텍처 가이드

권장 아키텍처

equipment_agent/
├── main.py              # 진입점, Agent 실행
├── tools/
│   ├── __init__.py
│   ├── equipment.py     # 설비 상태 조회 Tool
│   ├── manual.py        # 매뉴얼 검색 Tool
│   ├── inventory.py     # 재고 확인 Tool
│   └── production.py    # 생산 실적 Tool
├── data/
│   ├── equipment_db.py  # 설비 시뮬레이션 데이터
│   ├── manual_db.py     # 매뉴얼 데이터
│   ├── inventory_db.py  # 재고 데이터
│   └── production_db.py # 생산 데이터
├── core/
│   ├── agent.py         # ReAct Agent 로직
│   ├── cache.py         # 캐싱 시스템
│   └── monitor.py       # 모니터링
├── prompts/
│   └── system.py        # 시스템 프롬프트
└── tests/
    └── test_scenarios.py # 테스트 시나리오

팁: 처음에는 main.py 하나로 시작하고, 동작이 확인되면 파일을 분리하자.

데이터 흐름

사용자 질문
    │
    ▼
┌──────────────────────────────┐
│      ReAct Agent             │
│                              │
│  Thought: 무엇을 조회할까?   │
│      │                       │
│      ▼                       │
│  Tool 선택 & 실행            │
│      │                       │
│  ┌───┼───┬───┬───────┐      │
│  │   │   │   │       │      │
│  ▼   ▼   ▼   ▼       ▼      │
│ 설비 매뉴얼 재고 생산 기타   │
│  │   │   │   │       │      │
│  └───┼───┴───┴───────┘      │
│      │                       │
│      ▼                       │
│  Observation: 결과 분석      │
│      │                       │
│      ▼                       │
│  충분? ──No──> (반복)        │
│      │                       │
│      Yes                     │
│      │                       │
│      ▼                       │
│  최종 응답 생성              │
└──────────────────────────────┘
    │
    ▼
사용자에게 전달

핵심 설계 결정

1. 데이터 소스

소스	구현 방식	이유
MES	시뮬레이션 dict	실제 MES 없이도 동작
매뉴얼	시뮬레이션 dict	이번 주는 도구 설계에 집중하려고 조회를 단순화
ERP	시뮬레이션 dict	실제 ERP 없이도 동작

매뉴얼 조회는 지금 5건짜리 dict 검색이다. RAG는 Week 2·3에서 이미 만들었다. 그때 만든 검색기를 그대로 도구 하나로 감싸면 이 자리를 대체할 수 있다.

@tool
def search_manual(query: str) -> str:
    """알람 코드나 키워드로 장비 매뉴얼을 검색합니다."""
    docs = retriever.invoke(query)          # Week 2·3에서 만든 검색기
    if not docs:
        return f"'{query}'에 대한 매뉴얼을 찾을 수 없습니다."
    return "\n---\n".join(d.page_content for d in docs[:3])

바뀌는 것은 함수 속뿐이고 스키마도 Agent 코드도 그대로다. 도구 뒤를 갈아 끼울 수 있다는 것이 도구로 감싸 두는 이유이고, Week 8의 'RAG + Agent'가 전제하는 것이 바로 이 조합이다. 여유가 있으면 필수 기능을 마친 뒤 이 교체를 해 보라.

2. Agent의 상태는 어디에 있나

지금 설계에서 값을 들고 있는 자리는 넷이다.

자리	사는 범위	무엇을 들고 있나
`messages`	질문 하나가 끝나면 사라짐	시스템 프롬프트, 질문, 도구 호출과 결과
`conversation_history`	세션 전체	지난 질문과 답변
`call_log`	세션 전체	어떤 도구를 언제 불렀나
`cache`	프로세스 전체	도구가 돌려준 문자열

넷을 묶어 부르는 이름이 **에이전트의 상태(state)**다. 지금은 클래스 속성으로 흩어져 있어 "이 실행이 무엇을 알고 있는가"를 한눈에 볼 수 없다. Week 5의 LangGraph는 이 상태를 타입을 붙인 한 덩어리로 선언하고 노드들이 그것을 주고받게 만든다.

지금 단계에서는 각 자리가 언제 비워지는지만 정확히 알아 두면 된다. 특히 conversation_history에 무엇을 넣을지가 뒤에서 문제가 된다(아래 구현 실습의 힌트를 보라).

3. Agent 프레임워크

방식	장점	단점
OpenAI 직접	완전 제어	코드 많음
LangChain	코드 적음, 편리	추상화 (디버깅 어려움)
권장: 둘 다	직접 구현 이해 + LangChain 활용

4. 프롬프트 전략

SYSTEM_PROMPT = """당신은 제조 공장의 설비 관리 AI Agent입니다.

## 역할
공장 엔지니어의 질문에 정확하고 유용한 답변을 제공합니다.

## 사용 가능한 Tool
- get_equipment_status: 설비 상태 조회
- search_manual: 매뉴얼 검색 (알람 코드, SOP)
- check_inventory: 부품 재고 확인
- get_production_data: 생산 실적 조회

## 행동 규칙
1. 항상 실제 데이터를 조회한 후 답변하세요.
2. 추측하지 마세요. 데이터가 없으면 "확인할 수 없습니다"라고 하세요.
3. 문제 설비에 집중하세요. 정상 설비는 건너뛰세요.
4. 알람 발생 시: 설비 상태 -> 매뉴얼 검색 -> 재고 확인 순서로 진행하세요.
5. 응답은 한국어로, 구체적인 조치 방안과 함께 제공하세요.

## 응답 형식
- 현황 요약 (표 형식 권장)
- 문제점 분석
- 구체적 조치 방안 (우선순위 포함)
- 필요 부품/재고 상태 (해당 시)
"""

이 프롬프트를 기반으로 시작하고, 테스트 결과에 따라 반복 개선하세요.

5. 생각해 볼 것: 하나를 셋으로 쪼갠다면

지금은 도구 다섯을 한 Agent가 다 들고 있다. 이것을 설비 / 품질 / 재고 셋으로 나눈다면 무엇이 갈리고 무엇이 남는지 표에 적어 보라. 코드로 만들 필요는 없고 15분이면 된다.

물음	적어 볼 것
무엇이 나뉘나	도구 목록, 시스템 프롬프트, 담당 질문 유형
무엇이 공유되나	원 질문, 이미 조회한 결과, 최종 답을 쓰는 책임
누가 순서를 정하나	"알람 -> 매뉴얼 -> 재고"를 지금은 프롬프트가 정한다. 셋으로 나뉘면 누가 정하나
언제 끝나나	셋 중 하나가 답을 못 찾으면 전체는 끝난 것인가

여기서 답이 막히는 지점이 Week 5의 Supervisor 패턴이 푸는 문제다. 미리 답을 알 필요는 없고, 무엇이 문제인지 손에 쥐고 다음 주로 넘어가면 된다.