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>
182 lines
5.8 KiB
Markdown
182 lines
5.8 KiB
Markdown
# OpenClaw 멀티 에이전트 AI 통합
|
|
|
|
## 개요
|
|
|
|
Pipeline 프로젝트에 OpenClaw 멀티 에이전트 AI 플랫폼을 빌트인으로 통합했습니다.
|
|
Pipeline UI에서 에이전트 생성/관리, API 키 발급, 대화 모니터링, 사용량 추적이 가능하며,
|
|
외부 서비스에서 Pipeline이 발급한 API 키로 에이전트를 사용할 수 있습니다.
|
|
|
|
## 아키텍처
|
|
|
|
```
|
|
외부 서비스 (ERP, MES, 물류 등)
|
|
│ POST /api/ai/v1/chat/completions
|
|
│ Authorization: Bearer sk-pipe-xxxxx
|
|
▼
|
|
Pipeline Backend (:8080)
|
|
├── 인증 (JWT 또는 API Key)
|
|
├── Rate Limit 체크
|
|
├── 프록시 → OpenClaw Gateway (:18789)
|
|
├── 응답 로깅 (토큰, 비용)
|
|
└── DB 저장 (PostgreSQL)
|
|
▼
|
|
OpenClaw Gateway (내장 프로세스)
|
|
├── Agent A (데이터 분석)
|
|
├── Agent B (보고서 작성)
|
|
├── Agent C (모니터링)
|
|
└── LLM: Claude / GPT / Ollama
|
|
```
|
|
|
|
## DB 테이블
|
|
|
|
| 테이블 | 용도 |
|
|
|--------|------|
|
|
| `ai_agents` | 에이전트 정의 (이름, 모델, 시스템프롬프트, 도구, 상태) |
|
|
| `ai_agent_api_keys` | 외부 서비스용 API 키 (해시 저장, 사용량 제한) |
|
|
| `ai_agent_conversations` | 대화 세션 |
|
|
| `ai_agent_messages` | 대화 메시지 |
|
|
| `ai_agent_usage_logs` | 토큰 사용량, 비용, 응답시간 로그 |
|
|
| `ai_llm_providers` | LLM API 키 관리 (암호화 저장) |
|
|
|
|
## API 엔드포인트
|
|
|
|
### 에이전트 관리 (Pipeline JWT 인증)
|
|
|
|
```
|
|
GET /api/ai-agents 에이전트 목록
|
|
GET /api/ai-agents/:id 에이전트 상세
|
|
POST /api/ai-agents 에이전트 생성
|
|
PUT /api/ai-agents/:id 에이전트 수정
|
|
DELETE /api/ai-agents/:id 에이전트 삭제
|
|
```
|
|
|
|
### API 키 관리 (Pipeline JWT 인증)
|
|
|
|
```
|
|
GET /api/ai-agents/keys/list 키 목록
|
|
POST /api/ai-agents/keys 키 발급 (sk-pipe-xxx 형태, 한 번만 노출)
|
|
DELETE /api/ai-agents/keys/:id 키 폐기
|
|
```
|
|
|
|
### LLM 프로바이더 관리 (Pipeline JWT 인증)
|
|
|
|
```
|
|
GET /api/ai-agents/providers/list 프로바이더 목록
|
|
POST /api/ai-agents/providers 프로바이더 추가 (API 키 암호화 저장)
|
|
PUT /api/ai-agents/providers/:id 프로바이더 수정
|
|
DELETE /api/ai-agents/providers/:id 프로바이더 삭제
|
|
```
|
|
|
|
### 대화 모니터링 (Pipeline JWT 인증)
|
|
|
|
```
|
|
GET /api/ai-agents/conversations/list 대화 목록 (페이징)
|
|
GET /api/ai-agents/conversations/:id 대화 + 메시지 상세
|
|
```
|
|
|
|
### 사용량 (Pipeline JWT 인증)
|
|
|
|
```
|
|
GET /api/ai-agents/usage/summary 요약 (오늘/이번달 토큰, 비용)
|
|
GET /api/ai-agents/usage/logs 상세 로그 (페이징)
|
|
GET /api/ai-agents/usage/daily 일별 차트 데이터
|
|
```
|
|
|
|
### 외부 서비스용 프록시 (API Key 인증)
|
|
|
|
```
|
|
POST /api/ai/v1/chat/completions OpenAI 호환 채팅 (스트리밍 지원)
|
|
GET /api/ai/v1/models 사용 가능 모델 목록
|
|
GET /api/ai/v1/health Gateway 상태
|
|
```
|
|
|
|
## 외부 서비스에서 사용하기
|
|
|
|
### 1. API 키 발급
|
|
|
|
Pipeline 관리자 화면 > AI 에이전트 > API 키 관리에서 키를 발급합니다.
|
|
`sk-pipe-xxxxxxxx` 형태의 키가 생성되며, 최초 1회만 노출됩니다.
|
|
|
|
### 2. 채팅 API 호출
|
|
|
|
```bash
|
|
curl -X POST https://pipeline.example.com/api/ai/v1/chat/completions \
|
|
-H "Authorization: Bearer sk-pipe-xxxxx" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"model": "claude-sonnet-4-20250514",
|
|
"messages": [
|
|
{"role": "user", "content": "매출 데이터를 분석해줘"}
|
|
]
|
|
}'
|
|
```
|
|
|
|
### 3. 응답 형태 (OpenAI 호환)
|
|
|
|
```json
|
|
{
|
|
"id": "chatcmpl-xxx",
|
|
"object": "chat.completion",
|
|
"model": "claude-sonnet-4-20250514",
|
|
"choices": [{
|
|
"index": 0,
|
|
"message": { "role": "assistant", "content": "매출 데이터 분석 결과..." },
|
|
"finish_reason": "stop"
|
|
}],
|
|
"usage": {
|
|
"prompt_tokens": 15,
|
|
"completion_tokens": 200,
|
|
"total_tokens": 215
|
|
}
|
|
}
|
|
```
|
|
|
|
## 프론트엔드 관리 화면
|
|
|
|
| 경로 | 기능 |
|
|
|------|------|
|
|
| `/admin/aiAssistant/agents` | 에이전트 CRUD (카드형 목록) |
|
|
| `/admin/aiAssistant/providers` | LLM API 키 등록/관리 |
|
|
| `/admin/aiAssistant/conversations` | 대화 모니터링 (메시지 열람) |
|
|
| `/admin/aiAssistant/api-keys` | 외부 서비스용 API 키 발급 |
|
|
| `/admin/aiAssistant/usage` | 사용량 대시보드 |
|
|
|
|
## 환경 변수
|
|
|
|
```env
|
|
# OpenClaw Gateway 포트 (기본: 18789)
|
|
OPENCLAW_GATEWAY_PORT=18789
|
|
|
|
# OpenClaw 활성화 여부 (기본: true)
|
|
OPENCLAW_ENABLED=true
|
|
```
|
|
|
|
## 파일 구조
|
|
|
|
```
|
|
backend-node/src/
|
|
├── controllers/aiAgentController.ts # 에이전트/키/프로바이더/대화/사용량 컨트롤러
|
|
├── services/
|
|
│ ├── aiAgentService.ts # 에이전트 CRUD
|
|
│ ├── aiAgentApiKeyService.ts # API 키 발급/검증
|
|
│ ├── aiAgentProviderService.ts # LLM 프로바이더 관리
|
|
│ ├── aiAgentConversationService.ts # 대화 로깅
|
|
│ └── aiAgentUsageService.ts # 사용량 추적
|
|
├── routes/
|
|
│ ├── aiAgentRoutes.ts # 관리 API 라우트
|
|
│ └── openClawProxyRoutes.ts # 외부 서비스 프록시
|
|
├── middleware/
|
|
│ └── aiApiKeyAuthMiddleware.ts # API 키 인증
|
|
├── utils/startOpenClaw.ts # Gateway 프로세스 관리
|
|
├── types/aiAgent.ts # TypeScript 타입
|
|
└── db/migrations/
|
|
└── 300_create_openclaw_tables.sql # 마이그레이션
|
|
|
|
frontend/
|
|
├── lib/api/aiAgent.ts # API 클라이언트
|
|
└── app/(main)/admin/aiAssistant/
|
|
├── agents/page.tsx # 에이전트 관리
|
|
├── providers/page.tsx # 프로바이더 관리
|
|
└── conversations/page.tsx # 대화 모니터링
|
|
```
|