Industrial Agent Platform

제조 데이터, 설비 이벤트, MES/ERP/품질/정비 tool을 하나의 MCP-compatible Agent 실행 경계로 묶는 산업 운영 AI 백엔드입니다.

LLM Agent를 단순 질의응답으로 두지 않고, 현장 데이터 연동과 운영 추적이 가능한 제품으로 만들기 위해 다음 문제를 제품 경계로 다룹니다.

• 설비 이벤트가 어떤 source system에서 들어왔는가
• 이벤트가 어떤 asset, work order, lot, material과 연결되는가
• Agent가 어떤 문서를 근거로 판단했는가
• MES/ERP 조회와 품질/정비 쓰기 작업을 어떻게 분리하는가
• 위험 tool call은 어디에서 approval-required 상태로 전환되는가
• 운영자는 incident triage, audit event, scenario run으로 실행을 재구성할 수 있는가

이 제품이 하는 일

한 줄로 정리하면, 제조 이벤트를 받아서 Agent가 근거 문서와 업무 시스템 tool을 함께 사용해 운영 판단을 만들고, 위험한 실행은 승인 대기로 통제하는 백엔드입니다.

대표 흐름은 다음과 같습니다.

설비/QMS/MES 이벤트 적재
-> 산업 운영 summary 계산
-> incident triage
-> 정비/품질/운영 문서 RAG 검색
-> MES/ERP read tool 호출
-> 정비 ticket/lot hold write tool approval-required 전환
-> 운영자 승인 또는 반려
-> audit event, timeline, dashboard 추적

예를 들어 LINE-7-PRESS-02 설비에서 온도 critical 이벤트가 들어오면 이 시스템은 다음을 처리합니다.

• 이벤트를 industrial_event로 저장한다.
• critical 이벤트 수와 영향을 받은 설비를 summary로 보여준다.
• 최근 이벤트를 묶어 원인 후보와 권장 조치를 만든다.
• 정비 기준 문서를 근거로 Agent 답변을 만든다.
• maintenance.ticket.create 요청은 즉시 실행하지 않고 승인 대기로 넘긴다.
• 승인/반려/replay 결과를 audit event로 남긴다.

문서

• 기능 설명과 사용 흐름
• 제품 전략
• 아키텍처
• API 설계
• DB 설계
• 디자인 패턴

10분 사용 흐름

1. 설치와 실행

make install
make dev

기본 주소:

http://127.0.0.1:8000

다른 포트가 필요하면 직접 실행합니다.

. .venv/bin/activate
uvicorn apps.api.main:app --host 127.0.0.1 --port 8014

확인:

curl -sS http://127.0.0.1:8014/health

2. 설비 이벤트 적재

curl -sS -X POST http://127.0.0.1:8014/v1/industrial/events \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "source_system": "opc-ua",
    "asset_id": "LINE-7-PRESS-02",
    "event_type": "temperature.threshold.exceeded",
    "severity": "critical",
    "payload": {
      "temperature_c": 91.4,
      "work_order_id": "WO-DEMO-001"
    }
  }'

3. 운영 요약과 triage 확인

curl -sS 'http://127.0.0.1:8014/v1/industrial/operations/summary?tenant_id=demo'

curl -sS -X POST http://127.0.0.1:8014/v1/industrial/incidents/triage \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "asset_id": "LINE-7-PRESS-02"
  }'

4. 문서 적재

curl -sS -X POST http://127.0.0.1:8014/v1/documents/ingest \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "title": "프레스 라인 정비 기준",
    "content": "LINE-7-PRESS-02 설비는 온도 90도를 초과하면 critical event로 분류한다. critical event가 발생하면 cooling 상태, 부하 상태, 최근 정비 이력을 함께 확인한다.",
    "source_type": "manual",
    "source_uri": "manual://press-line-maintenance",
    "classification": "internal"
  }'

5. Agent 실행과 approval-required 확인

curl -sS -X POST http://127.0.0.1:8014/v1/agents/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "scenario": "production-incident-triage",
    "message": "LINE-7-PRESS-02 설비에 대한 정비 ticket 생성을 처리해줘",
    "actor_scopes": ["industrial:read", "maintenance:write"]
  }'

이 요청은 maintenance.ticket.create write tool로 라우팅되고, 바로 실행되지 않고 approval_required 상태가 됩니다.

승인 대기 조회:

curl -sS 'http://127.0.0.1:8014/v1/approvals/pending?tenant_id=demo'

승인:

curl -sS -X POST http://127.0.0.1:8014/v1/approvals/{approval_id}/approve \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "demo",
    "approved_by": "operator-01"
  }'

6. 한 번에 전체 흐름 검증

make demo

make demo는 sample document ingest, 산업 이벤트 적재, operations summary, incident triage, Agent run, feedback, diagnostics, evidence bundle, replay, approval-required action, scenario run을 한 번에 실행합니다.

제품 경계

Manufacturing Gateway / MCP Client / Dashboard / REST API
        |
        v
FastAPI Router
        |
        v
Application Use Case
        |
        v
Domain Model / Policy
        |
        v
Port Interface
        |
        v
Adapter: Postgres, Vector DB, MES, ERP, QMS, Maintenance, Webhook

핵심 원칙은 제조 도메인 규칙과 외부 시스템 연동을 분리하는 것입니다.
MES, ERP, QMS, 정비 시스템은 바뀔 수 있지만, 이벤트 수집, incident triage, approval, audit, evaluation 모델은 제품의 중심에 남습니다.

현재 구현 범위

• FastAPI 기반 REST API
• MCP-compatible JSON-RPC tool boundary
• 산업 이벤트 적재 API
• 설비/asset 기준 이벤트 필터링
• 산업 운영 summary API
• 산업 incident triage API
• 문서 적재, chunking, RAG 검색
• Ontology graph read model
• MES 작업지시 조회 tool
• ERP 재고/대체 자재 조회 tool
• 정비 ticket 생성 tool
• 품질 lot hold 요청 tool
• Tool Schema Registry
• required scope 기반 tool 실행 제어
• read tool 즉시 실행
• write tool approval-required 전환
• 승인/반려/replay API
• Tool Gateway timeout/retry/fallback/circuit breaker
• Agent 실행 trace
• audit event와 request id correlation
• webhook outbox와 dispatcher
• operations summary/SLO/alerts/dashboard
• production incident scenario runbook
• quality lot hold scenario runbook
• evaluation run과 regression gate
• Docker Compose 기반 로컬 인프라
• ruff, mypy, pytest 기반 검증

산업 도메인 API

POST /v1/industrial/events
GET  /v1/industrial/events
GET  /v1/industrial/operations/summary
POST /v1/industrial/incidents/triage

예시 이벤트:

{
  "tenant_id": "default",
  "source_system": "opc-ua",
  "asset_id": "LINE-7-PRESS-02",
  "event_type": "temperature.threshold.exceeded",
  "severity": "critical",
  "payload": {
    "temperature_c": 91.4,
    "work_order_id": "WO-DEMO-001"
  }
}

Incident triage 결과는 다음 정보를 반환합니다.

severity
affected_assets
linked_event_ids
root_cause_hints
recommended_actions
required_agent_scopes

MCP Tool Catalog

Tool	Type	Scope	목적
mes.work-order.lookup	read	industrial:read	MES 작업지시와 설비 생산 상태 조회
erp.inventory.lookup	read	industrial:read	ERP 재고와 대체 자재 가능성 조회
maintenance.ticket.create	write	maintenance:write	설비 이상 정비 ticket 생성 요청
quality.lot-hold.request	write	quality:write	품질 이상 lot hold 요청

쓰기성 tool은 바로 실행하지 않습니다. Agent 실행 중 approval_required 상태로 전환하고, 운영자가 승인하면 replay합니다.

기본 Scenario Runbook

production-incident-triage
quality-lot-hold

각 scenario는 RAG 근거 확인, MCP tool 조회, 승인 필요 tool 실행을 하나의 흐름으로 검증합니다.

기술 스택

영역	선택
API	Python 3.12+, FastAPI
Agent Runtime	Use case orchestration, LangGraph dependency boundary
RAG	query classification, retrieval strategy, citation
MCP	JSON-RPC compatible /mcp endpoint
Vector Search	local keyword adapter, Qdrant adapter
Persistence	in-memory adapter, Postgres adapter
Industrial Data	event ingestion, asset filter, incident triage
Tooling	MES/ERP/QMS/Maintenance tool registry
Governance	PII redaction, policy guard, approval-required action
Reliability	timeout, retry, fallback, circuit breaker
Observability	request id, process time header, trace step, audit event
Integration	webhook subscription, audit event outbox
Quality Gate	ruff, mypy, pytest, regression evaluation

전체 API

GET  /health
GET  /dashboard
GET  /v1/readiness

POST /v1/industrial/events
GET  /v1/industrial/events
GET  /v1/industrial/operations/summary
POST /v1/industrial/incidents/triage

POST /v1/documents/ingest
GET  /v1/documents
POST /v1/knowledge/search

POST /v1/agents/runs
POST /v1/agents/runs/preview
GET  /v1/agents/runs
GET  /v1/agents/runs/{run_id}
GET  /v1/agents/runs/{run_id}/timeline
GET  /v1/agents/runs/{run_id}/diagnostics
GET  /v1/agents/runs/{run_id}/evidence
POST /v1/agents/runs/{run_id}/feedback
POST /v1/agents/runs/{run_id}/replay

GET  /v1/ontology/graph
GET  /v1/audit/events
GET  /v1/audit/export

GET  /v1/operations/summary
GET  /v1/operations/usage
GET  /v1/operations/slo
GET  /v1/operations/incidents/snapshot
GET  /v1/operations/feedback/summary
GET  /v1/operations/alerts
GET  /v1/operations/migrations/status

GET  /v1/scenarios
GET  /v1/scenarios/runs
GET  /v1/scenarios/{scenario_id}
POST /v1/scenarios/{scenario_id}/run

GET  /v1/tools
GET  /v1/tools/gateway/status
POST /mcp

GET  /v1/approvals/pending
POST /v1/approvals/{approval_id}/approve
POST /v1/approvals/{approval_id}/reject

빠른 실행

make install
make dev

Swagger:

http://127.0.0.1:8000/docs

Operator dashboard:

http://127.0.0.1:8000/dashboard

서버 없이 전체 흐름을 검증할 수도 있습니다.

make demo
make verify

로컬 기본 모드

.env 없이 실행하면 다음 모드로 동작합니다.

STORAGE_BACKEND=memory
VECTOR_BACKEND=local

이 모드는 외부 DB 없이 산업 이벤트 적재, RAG, MCP tool, approval, audit, scenario run을 검증하기 위한 모드입니다.

Postgres/Qdrant를 붙이면 같은 port 경계 위에서 저장소와 Vector DB adapter를 교체합니다.