# Minerp Agent — AI runtime & MCP Hub

**Minerp Agent** là lớp AI của nền tảng Minerp: chat nội bộ ERP, knowledge base (RAG), orchestration đa agent, bot đa kênh, và **MCP Hub** (Model Context Protocol) để gắn công cụ đọc-only từ bên trong lẫn bên ngoài.

> Cập nhật: 2026-10-05 · Service: `services/multi-agent` · API: `https://minerp.vn/api/multi-agent`  
> Bản đồ ERP + extension: [minerp-odm-features.md](./minerp-odm-features.md) · Shop AI merchant: [minerp-studio-features.md §9](./minerp-studio-features.md#9-shop-ai-add-on-sku-shop_ai)

---

## 1. Tên sản phẩm vs mã kỹ thuật

| Lớp | Tên |
|-----|-----|
| **Product** | Minerp Agent |
| **Add-on merchant** | Shop AI (`shop_ai`) |
| **Code / API / DB** | `multi-agent`, `/api/multi-agent`, `multi_agent_db` *(không đổi)* |

---

## 2. Platform ERP (`www/platform`)

| Route | Tính năng |
|-------|-----------|
| `/chat` | WebSocket chat — Direct / Team / Handoff, upload file, tool calls |
| `/kb` | Knowledge bases, ingest tài liệu, sync sources |
| `/admin/mcp` | **MCP connections** — catalog, OAuth, health, usage stats, audit |
| `/admin` | Orgs, users, conversations, RBAC |

---

## 3. MCP Hub — AI Connections

Pattern “AI Connections”: admin đăng ký connector → agent chat/bot gọi tool qua hub → audit thống nhất.

### 3.1 Connectors (catalog)

| Connector | Transport | Mô tả |
|-----------|-----------|--------|
| `minerp_internal_ping` | internal | Health ping POC |
| `minerp_internal_shop` | internal | Catalog + đơn hàng shop (readonly, tenant scope) |
| `minerp_internal_kb` | internal | Tìm kiếm RAG trên KB đã cấu hình |
| `minerp_internal_calendar` | internal | Lịch sắp tới (readonly, config) |
| `minerp_internal_email_read` | internal | Email gần đây (readonly preview) |
| `minerp_internal_ads_read` | internal | Metrics marketing/ads (shop proxy) |
| `http_mcp_readonly` | HTTP | Remote MCP server + bearer token |
| `http_mcp_oauth` | HTTP | Remote MCP + **OAuth2 PKCE** |

### 3.2 Admin API

| Endpoint | Mục đích |
|----------|----------|
| `GET/POST/PATCH/DELETE /api/v1/admin/mcp/connections` | CRUD connection (encrypted credentials) |
| `POST .../connections/{id}/test` | Kiểm tra + ghi health |
| `POST .../connections/{id}/oauth/start` | Bắt đầu OAuth (HTTP MCP) |
| `GET /api/v1/mcp-oauth/callback` | Callback browser (public) |
| `GET /admin/mcp/audit` | Tool call audit (`source=mcp`) |
| `GET /admin/mcp/stats` | Usage theo connector (7d) |
| `GET /admin/mcp/templates` | Pack connection sẵn |
| `POST /admin/mcp/templates/{id}/apply` | Apply pack (multi-account prefix) |
| `POST /api/v1/hub/mcp` | JSON-RPC hub cho engine ngoài (`X-API-Key`) |

### 3.3 Agent bridge

- **Single assistant** — MCP tools dynamic trên PydanticAI
- **Team / Handoff** — readonly MCP only; specialist kế thừa context
- **Shop CSKH** — `shop_only` filter; Studio tab **MCP tools** (`/studio/agents/mcp`)
- **Giới hạn** — `AGENT_MAX_TOOL_CALLS_PER_TURN`, `MCP_MAX_TOOL_CALLS_PER_TURN`
- **Bảo mật** — SSRF guard trên HTTP MCP URL; tenant isolation trên shop tools

### 3.4 Lộ trình đã giao (2026)

| Phase | Nội dung |
|-------|----------|
| **0 Quick win** | Tenant-safe tools, audit `tool_calls`, tool allowlist |
| **1 POC** | Catalog, hub, bridge, admin UI, internal shop connector |
| **2 Wave A** | HTTP hub, OAuth MCP, health pool, SSRF, audit API, tool budgets |
| **2 Wave B** | Shop bridge, orchestrator MCP, channel bots, Studio MCP UI |
| **2 Wave C** | KB connector, multi-account label, templates, usage stats, calendar/email/ads connectors |
| **2 Wave D** | `schedule_report`, inbox job results, scheduled MCP digest (Celery) |

Gate checklist: [`services/multi-agent/docs/mcp-poc-gate.md`](../../../../services/multi-agent/docs/mcp-poc-gate.md)

---

## 4. Backend capability map

| Nhóm | Tính năng |
|------|-----------|
| **Orchestration** | Single / multi / handoff, specialist budget |
| **RAG** | Qdrant prod, ingest PDF/TXT/MD, tenant-scoped collections |
| **Channels** | Zalo, Messenger, Telegram, Slack — `ChannelBot` per tenant |
| **CSKH marketplace** | Tools đọc catalog/orders platform |
| **Shop AI** | Widget, FAQ, catalog→RAG, live agent, quality report |
| **MCP Hub** | Catalog, connections, OAuth, bridge, audit, stats |
| **Internal API** | `llm_generate`, `email_generate` (Workflow Builder) |
| **Infra** | Outbox/Kafka, Celery, hybrid RBAC, rate limit |

Tool matrix: [`services/multi-agent/docs/tool-matrix.md`](../../../../services/multi-agent/docs/tool-matrix.md)

---

## 5. Shop AI (add-on Studio)

Merchant SKU `shop_ai` trên `storefront.vn/studio` — cùng runtime Minerp Agent, scope tenant:

- Zalo / Messenger CSKH, Knowledge + FAQ, Conversations inbox
- **MCP tools** — merchant quản lý connection readonly (`minerp_internal_shop`)
- Widget Puck **ShopAssistant** trên storefront

Chi tiết menu Studio: [minerp-studio-features.md §9](./minerp-studio-features.md#9-shop-ai-add-on-sku-shop_ai)

---

## 6. Health & staging

```
https://minerp.vn/api/multi-agent/health/ready
https://storefront.vn/api/v1/health/ready          # BFF Shop AI
```

Deploy MCP: migration `0040`–`0042` trên `multi_agent_db`; env `MCP_OAUTH_*` khi dùng OAuth connector.

---

## Tài liệu kỹ thuật

| Loại | Path |
|------|------|
| Service README | [`services/multi-agent/README.md`](../../../../services/multi-agent/README.md) |
| MCP gate | [`services/multi-agent/docs/mcp-poc-gate.md`](../../../../services/multi-agent/docs/mcp-poc-gate.md) |
| Tool matrix | [`services/multi-agent/docs/tool-matrix.md`](../../../../services/multi-agent/docs/tool-matrix.md) |
| Minerp ODM (full map) | [`minerp-odm-features.md`](./minerp-odm-features.md) |