pipeline/MULTI_AGENT_ARCHITECTURE.md

PIPELINE 멀티 에이전트 아키텍처 설계서

1. 개요

PIPELINE은 OpenClaw 기반 멀티 에이전트 AI 플랫폼을 빌트인으로 탑재하여, 여러 AI 에이전트가 기존 시스템의 데이터를 활용하여 협업하고 행동하는 구조를 제공합니다.

설계 원칙

에이전트 = 템플릿 (재사용 가능)
커넥터  = 데이터 소스 (동적 연결)
그룹    = 에이전트 + 커넥터 조립 (멀티 에이전트 단위)

• 에이전트는 **역할(시스템 프롬프트)**만 정의하고, 데이터 접근은 커넥터가 담당
• 같은 에이전트가 다른 커넥터를 물고 다른 회사/시스템에서 동작 가능
• 외부 시스템은 멀티 에이전트 그룹 1개만 호출하면 내부에서 자동 분업

---

2. 전체 아키텍처

┌─────────────────────────────────────────────────────────────┐
│                    PIPELINE 플랫폼                           │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           멀티 에이전트 워크스페이스                    │   │
│  │                                                     │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │  [MES 멀티 에이전트]                          │  │   │
│  │  │                                              │  │   │
│  │  │  ① 영업담당 에이전트                          │  │   │
│  │  │     └─ 커넥터: A회사 수주DB                   │  │   │
│  │  │              ↓                               │  │   │
│  │  │  ② 설계담당 에이전트                          │  │   │
│  │  │     └─ 커넥터: CAD REST API + BOM 파일        │  │   │
│  │  │              ↓                               │  │   │
│  │  │  ③ 구매담당 에이전트                          │  │   │
│  │  │     └─ 커넥터: 자재DB + 원자재 시세 크롤러     │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  │                                                     │   │
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │  [SCM 멀티 에이전트]                          │  │   │
│  │  │                                              │  │   │
│  │  │  ① 물류담당 에이전트                          │  │   │
│  │  │     └─ 커넥터: B회사 재고DB + PLC 설비데이터   │  │   │
│  │  │              ↓                               │  │   │
│  │  │  ② 품질담당 에이전트                          │  │   │
│  │  │     └─ 커넥터: 검사성적서 파일 + 불량DB        │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────┐  ┌──────────────────────────────┐    │
│  │  에이전트 관리    │  │  데이터 커넥터 허브            │    │
│  │  (템플릿)        │  │  ┌──────┐ ┌────────┐        │    │
│  │  - 영업담당      │  │  │  DB  │ │REST API│        │    │
│  │  - 설계담당      │  │  └──────┘ └────────┘        │    │
│  │  - 구매담당      │  │  ┌──────┐ ┌────────┐ ┌────┐│    │
│  │  - 물류담당      │  │  │  PLC │ │  File  │ │크롤││    │
│  │  - 품질담당      │  │  └──────┘ └────────┘ └────┘│    │
│  └─────────────────┘  └──────────────────────────────┘    │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  OpenClaw Gateway (내장)                              │  │
│  │  - MCP 도구 동적 주입                                 │  │
│  │  - LLM 프로바이더 (Claude / GPT / Gemini / Ollama)    │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────┬────────────────────────────────────────┘
                     │ API 키 (sk-pipe-xxxxx)
                     │
    ┌────────────────▼────────────────────┐
    │          외부 시스템                  │
    │  MES / ERP / WMS / SCM / 모바일 앱   │
    └─────────────────────────────────────┘

---

3. 핵심 개념

3-1. 에이전트 (Agent) = 재사용 템플릿

에이전트: "영업담당"
├── 모델: Claude Sonnet 4
├── 시스템 프롬프트: "당신은 영업 데이터 분석 전문가입니다..."
└── 커넥터: 없음 (그룹에서 동적 할당)

이 에이전트는 여러 그룹에서 재사용:
  - A회사 MES 그룹 → 커넥터: A회사 수주DB
  - B회사 MES 그룹 → 커넥터: B회사 수주DB
  - C회사 SCM 그룹 → 커넥터: C회사 거래처DB

3-2. 데이터 커넥터 허브 (Data Connector Hub)

커넥터 유형	데이터 소스	에이전트 활용
Database	PostgreSQL, MSSQL, MariaDB, Oracle	SQL 쿼리로 데이터 조회/분석
REST API	외부 시스템 API 호출	JSON 데이터 수집/명령 전달
PLC	장비 데이터 (Modbus, OPC-UA)	실시간 설비 상태 모니터링
File	CSV, Excel, JSON, PDF	문서 분석, 데이터 추출
Crawler	웹 크롤링 (시세, 뉴스, 규격)	외부 정보 수집

3-3. 멀티 에이전트 그룹 = 에이전트 + 커넥터 조립

[A회사 MES 멀티 에이전트]
  ├── ① 영업담당 + A회사 수주DB          ← 같은 에이전트
  ├── ② 구매담당 + A회사 자재DB + 시세 크롤러
  └── ③ 품질담당 + A회사 검사DB

[B회사 MES 멀티 에이전트]
  ├── ① 영업담당 + B회사 수주DB          ← 같은 에이전트, 다른 커넥터
  ├── ② 구매담당 + B회사 자재DB
  └── ③ 설계담당 + B회사 CAD API + BOM 파일

에이전트 5개 + 그룹 2개 = 6개 조합 (에이전트 따로 만들면 6개 필요)

---

4. 실행 흐름

4-1. 외부 시스템 호출 시

POST /api/ai/v1/groups/a-company-mes
{
  "message": "이번 달 납기 지연 가능한 건 알려줘"
}

┌─ 실행 파이프라인 ──────────────────────────────────────┐
│                                                        │
│  ① 영업담당 에이전트 실행                               │
│     MCP 도구: A회사 수주DB 쿼리 실행                    │
│     → "수주 10건 중 3건 납기 위험 (A-2026-001, ...)"    │
│                    │                                    │
│                    ▼                                    │
│  ② 설계담당 에이전트 실행                               │
│     MCP 도구: CAD API 호출 + BOM 파일 분석              │
│     → "A-2026-001: BOM 분석 결과 부품 2개 미확보"       │
│                    │                                    │
│                    ▼                                    │
│  ③ 구매담당 에이전트 실행                               │
│     MCP 도구: 자재DB 조회 + 원자재 시세 크롤링           │
│     → "부품A: 납품 5일 소요, 긴급 발주 추천"            │
│     → "부품B: 재고 있음 (창고 3번)"                     │
│                    │                                    │
│                    ▼                                    │
│  최종 응답 취합                                         │
│  → 납기 위험 3건, 부품 미확보 2건, 긴급 발주 1건 추천    │
│                                                        │
└────────────────────────────────────────────────────────┘

4-2. 스케줄 실행 (예정)

[매일 오전 9시 자동 실행]
  → SCM 멀티 에이전트 실행
  → 결과를 이메일/슬랙/대시보드에 전송

---

5. DB 스키마

기존 테이블 (활용)

테이블	용도
external_db_connections	DB 커넥션 정보 (호스트, 포트, 계정)
external_rest_api_connections	REST API 커넥션 정보 (URL, 인증)

새로 추가한 테이블

-- AI 에이전트 (템플릿)
ai_agents
  ├── id, agent_id, name, model, system_prompt, status

-- LLM 프로바이더 (API 키)
ai_llm_providers
  ├── id, name(anthropic/openai/google), api_key_encrypted, model_name

-- 멀티 에이전트 그룹
ai_agent_groups
  ├── id, group_id, name, description, status

-- 그룹 멤버 (에이전트 + 커넥터 매핑)
ai_agent_group_members
  ├── group_id → ai_agent_groups
  ├── agent_id → ai_agents
  ├── role_name (이 그룹에서의 역할)
  ├── connectors (JSONB: 동적 커넥터 목록)
  │     [
  │       {"type":"database", "connection_id":3, "name":"A회사 수주DB"},
  │       {"type":"rest_api", "connection_id":5, "name":"CAD API"},
  │       {"type":"crawler", "config_id":2, "name":"원자재 시세"},
  │       {"type":"file", "path":"/uploads/bom.csv", "name":"BOM 파일"},
  │       {"type":"plc", "connection_id":1, "name":"1호기 PLC"}
  │     ]
  └── execution_order (실행 순서)

-- API 키 (외부 서비스용)
ai_agent_api_keys
  ├── key_hash, user_id, rate_limit, monthly_token_limit

-- 사용량 로그
ai_agent_usage_logs
  ├── tokens, cost, response_time

---

6. API 엔드포인트

관리 API (Pipeline JWT 인증)

Method	Path	설명
GET/POST	/api/ai-agents	에이전트 CRUD
GET/POST	/api/ai-agents/providers/*	LLM 프로바이더 관리
GET/POST	/api/ai-agents/keys/*	API 키 발급/관리
GET/POST	/api/ai-agent-groups	멀티 에이전트 그룹 CRUD
POST	/api/ai-agent-groups/:id/members	그룹에 에이전트+커넥터 추가
GET	/api/ai-agent-groups/connectors	사용 가능한 커넥터 목록

외부 서비스 API (API Key 인증)

Method	Path	설명
POST	/api/ai/v1/chat/completions	단일 에이전트 채팅
POST	/api/ai/v1/groups/:groupId	멀티 에이전트 실행 (예정)
GET	/api/ai/v1/models	사용 가능 모델 목록

---

7. 관리 화면 (프론트엔드)

메뉴	경로	기능
멀티 에이전트 워크스페이스	/admin/aiAssistant/workspace	그룹 생성, 에이전트+커넥터 조립
에이전트 관리	/admin/aiAssistant/agents	에이전트 템플릿 CRUD
LLM 프로바이더	/admin/aiAssistant/providers	Claude/GPT/Gemini API 키 등록
API 키 발급	/admin/aiAssistant/api-keys-manage	외부 서비스용 키 생성
대화 모니터링	/admin/aiAssistant/conversations	에이전트 대화 내역 열람

---

8. 예측 진화 시스템

이력 누적 → 자동 학습 구조

에이전트는 매번 실행할 때마다:
1. 현재 데이터 조회 (MCP 커넥터)
2. 과거 분석 이력 조회 (ai_analysis_logs)
3. 과거 예측 vs 실제 비교 (accuracy_score)
4. 이 모든 컨텍스트로 분석/예측 수행
5. 결과를 다시 이력에 저장

→ 실행할수록 데이터가 쌓이고, 에이전트가 참고할 이력이 늘어남
→ 별도 학습 없이 LLM의 추론 능력으로 패턴 인식/예측 가능

ai_analysis_logs 테이블

ai_analysis_logs
├── group_id         → 어떤 그룹이 실행했는지
├── input_message    → 질문
├── analysis_result  → 분석 결과 (전체 텍스트)
├── prediction       → 예측 내용 (JSONB)
├── actual_result    → 실제 결과 (나중에 입력)
├── accuracy_score   → 예측 정확도 (0~100)
├── tokens_used, duration_ms
└── created_at       → 시계열 이력

예시: 30일 후 예측 정확도 변화

1일차: 이력 없음 → 예측 정확도: N/A
7일차: 이력 6건 참고 → 예측 정확도: 60%
14일차: 이력 13건 참고 → 예측 정확도: 72%
30일차: 이력 29건 참고 → 패턴 인식 → 예측 정확도: 85%

---

9. 스케줄러 & 알림

정기 실행 구조

[ai_agent_schedules]
├── cron_expression: "0 9 * * *" (매일 오전 9시)
├── group_id → MES 멀티 에이전트
├── input_message: "오늘 납기 지연 위험이 있는 건 알려줘"
├── notification:
│   ├── system_notice: true (시스템 공지)
│   ├── webhook: "https://hooks.slack.com/..." (슬랙)
│   └── email: ["buyer@company.com"] (이메일)
└── is_active: true

알림 흐름

[cron 실행] → [멀티 에이전트 실행] → [결과 분석]
                                        │
              ┌─────────────────────────┤
              ▼                         ▼                    ▼
    [시스템 공지 저장]          [슬랙 웹훅 발송]       [이메일 발송]
    system_notice 테이블       POST webhook URL      SMTP 발송

---

10. 커넥터 유형 (구현 완료)

커넥터	구현 방식	에이전트 활용
Database	기존 external_db_connections 활용	SQL 쿼리로 데이터 조회
REST API	기존 external_rest_api_connections 활용	JSON 데이터 수집
File	파일 시스템 직접 읽기 (CSV/JSON)	문서 분석, 데이터 추출
Crawler	기존 crawl_configs 활용	웹 크롤링 데이터 수집
PLC	AAS 디지털 트윈 REST API → DB 저장	설비 상태 조회/분석

PLC 데이터 흐름

[PLC 장비] → [AAS 디지털 트윈] → REST API
                                    ↓
                            [Pipeline DB 저장]
                            (plc_device_data 등)
                                    ↓
                          [에이전트가 DB 조회]
                          "1호기 온도 추세 분석"

• AAS에서 장비 종류, 벤더 등 마스터 데이터 관리
• Pipeline에서 실제 PLC 통신 스크립트 구현 (Modbus TCP/OPC-UA)
• 수집 데이터를 DB에 저장 → 에이전트가 이력 분석/예측

---

11. 확장 계획

기능	설명	우선순위
워크플로우 편집기	드래그앤드롭으로 파이프라인 구성	중
PLC 통신 모듈	Modbus TCP/OPC-UA 직접 통신	중
실시간 모니터링	WebSocket으로 에이전트 실행 실시간 스트리밍	중
A/B 테스트	다른 모델/프롬프트로 비교 실험	하
에이전트 마켓플레이스	템플릿 공유/배포	하

---

9. 기술 스택

구성요소	기술
멀티 에이전트 엔진	OpenClaw (Node.js, MCP 지원)
백엔드	Express.js + TypeScript
프론트엔드	Next.js 15 + shadcn/ui
데이터베이스	PostgreSQL
LLM	Claude, GPT, Gemini, DeepSeek, Ollama
커넥터	기존 external_db/rest_api + PLC/File/Crawler 확장