chpark
37cac72085
- Docker/K8s 배포 설정을 pipeline-backend/pipeline-front로 통일 - 네임스페이스, 서비스, PVC 등 k8s 리소스명 pipeline-* 로 변경 - AI 에이전트 관리 기능 추가 (에이전트, 그룹, 프로바이더, 대화, API 키, 지식베이스) - 장비 연결 관리 기능 추가 (PLC/Modbus/OPC-UA/MQTT) - 배치 스케줄러에 AI agent/device collection/crawling 타입 추가 - 배치 편집 UI 개선 (6가지 실행 방식 지원) - 회사별 페이지(COMPANY_*) 제거 및 AdminPageRenderer 최적화 - 메뉴 재구성: 장비 연결 관리 시스템관리로 이동, 에이전트 오케스트레이션으로 개명 - ai-assistant 디렉토리 제거 (backend-node로 통합) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
374 lines
17 KiB
Markdown
374 lines
17 KiB
Markdown
# 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 확장 |
|