# 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, 인증) | ### 새로 추가한 테이블 ```sql -- 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 테이블 ```sql 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 확장 |