AI 技術架構：Pi Agent Harness 整合方案

架構總覽

以 Pi Agent Harness 為核心嘅 AI 整合架構——雙 Agent、多 Provider、MIT 開源。

2 個

Agent 實例：Copilot + AutoDiag

30+

支援 LLM providers 經 pi-ai 統一介面

MIT

Pi Agent Harness 完全開源，無 IP 風險

Node.js

AI Gateway 為獨立微服務

點解揀 Pi Agent Harness

Pi Agent Harness 提供統一嘅 Multi-Provider API、完整 Agent Runtime 同 MIT 開源許可。

統一 Multi-Provider API

pi-ai 封裝 30+ LLM providers（Claude、GPT、Gemini、Ollama 等），一套 code switch provider 唔使改 workflow。內建 token tracking 同 cost control。

完整 Agent Runtime

pi-agent-core 提供 tool calling、SSE streaming、beforeToolCall/afterToolCall hooks、transformContext（RAG pattern），唔使自己寫 agent loop。

MIT License · 零 IP 風險

完全開源 MIT license，可以商業使用、修改、分發。無 vendor lock-in，隨時可以替換底層 LLM provider。

系統架構

以 Pi Agent Harness 為核心，雙 Agent 架構對接現有平台同數據層。

Portal 前端

現有平台頁面：儀表板、警報中心、投訴頁、工單、設定。AI 結果浮現喺現有頁面。

API Gateway

統一入口：認證、rate limit、路由、audit。

Agent「Copilot」

用戶對話介面，SSE streaming，處理投訴、報修、查詢。

Agent「AutoDiag」

事件驅動，由規則引擎 / ML alert 觸發，自動診斷。

AI Gateway（Node.js 微服務）

Pi Agent Harness 整合層：pi-ai + pi-agent-core、tool registry、prompt management、cost tracking、fallback routing。

Tool: 查詢工單歷史

queryTicketHistory

Tool: 讀取 Sensor 數據

readSensorData

Tool: 開工單 / 派工

createWorkOrder

Tool: 發通知

sendNotification

雲端 LLM（Claude / Gemini / GPT）

主力推理——經 pi-ai 統一介面呼叫。

本地模型（Ollama fallback）

離線 fallback——數據不出境、零成本。

向量庫（RAG 知識檢索）

歷史案例 embedding——經 transformContext 注入。

AI Gateway 用 Node.js 而唔係 Supabase Edge Functions——因為 pi-ai 只支援 Node.js runtime。

Agent Copilot 同 AutoDiag 共享同一個 AI Gateway，但各自有獨立嘅 system prompt 同 tool set。

雙 Agent 架構

兩個 Agent 各司其職——Copilot 服務用戶對話，AutoDiag 處理事件驅動自動診斷。

用戶對話模式

Agent Copilot — 用戶對話介面

觸發方式：用戶在 support page 發送訊息

通訊模式：SSE streaming（逐字回覆）

System Prompt：品牌語氣 + 投訴處理 SOP + 安撫指引

Tool Set：查工單、讀 sensor、開工單、發通知

transformContext：自動注入該租戶嘅工單歷史 + 現場 sensor 數據

人工把關：P1 行動需員工確認先執行

事件驅動模式

Agent AutoDiag — 自動診斷引擎

觸發方式：規則引擎 L1 alert 或 ML 模型 L2 anomaly signal

通訊模式：非 streaming，批次處理

System Prompt：診斷 SOP + 數據分析指引 + 證據鏈要求

Tool Set：讀 sensor 歷史、查工單記錄、讀天氣 API、開工單

transformContext：自動注入異常設備嘅 30 分鐘歷史 + 同類型過往案例

輸出：1–2 個 probable cause + confidence + 行動建議

Tooling 設計

Agent 透過 tool calling 存取平台能力——每個 tool 都有明確嘅輸入輸出同數據源。

Tool Name	描述	Used By	Data Source
`queryTicketHistory`	查詢指定站點/設備嘅歷史工單	Copilot + AutoDiag	營運 DB
`readSensorData`	讀取指定位置嘅 sensor 實時/歷史數據	Copilot + AutoDiag	時間序列 DB
`createWorkOrder`	自動建立工單並指派	Copilot + AutoDiag	營運 DB
`sendNotification`	發送通知（email / push / webhook）	Copilot + AutoDiag	Notification Service
`readWeatherData`	讀取外部天氣數據輔助診斷	AutoDiag only	天氣 API
`queryKnowledgeBase`	RAG 檢索知識庫案例	Copilot + AutoDiag	向量庫

投訴流程 x Agent Loop

實例：租戶投訴「冷氣不足」——每一步都對應 Pi agent-core 嘅 Agent loop 概念。

場景設定

租戶：B-12 舖投訴：冷氣不足處理：Agent Copilot 驅動：Pi agent-core

1

收到投訴

用戶提交投訴

用户喺 support page 提交「冷氣不足」→ 觸發 Agent Copilot session。

2

Agent Loop 啟動

pi-agent-core 建立 session

pi-agent-core 建立 session，載入 system prompt + transformContext（租戶 profile + 歷史）。

3

Tool Call: readSensorData

自動讀取 Sensor 數據

Agent 自動調用 readSensorData tool，拉取 B-12 附近 sensor 數據。

4

Tool Call: queryTicketHistory

查詢歷史工單

Agent 調用 queryTicketHistory，查該位置過往冷氣相關工單。

5

LLM 推理

pi-ai 送 context 去 LLM

pi-ai 將 context + tool results 送畀 Claude Sonnet，出 root-cause 評估。

LLM 推理 · Root-cause 評估「根據 B-12 附近 sensor 數據：室溫 27.4°C（設定 24°C）、AHU-12 出風 21°C、濾網壓差 3 日內上升 38%。最可能原因：AHU-12 過濾網阻塞。建議清洗/更換濾網。」

6

Tool Call: createWorkOrder

自動開工單

Agent 自動開工單 WO-4821，指派機電承辦商。

7

SSE Streaming 回覆

逐字回覆客人

Agent 逐字回覆客人：安撫 + 診斷結果 + 工單編號。

Agent Copilot · SSE Streaming「多謝你反映冷氣不足嘅問題。經檢查，B-12 附近嘅 AHU-12 濾網壓差偏高，可能影響冷氣效能。我哋已經建立工單 WO-4821 並指派承辦商處理，預計今日內完成。如有補充歡迎繼續講低。」

8

閉環

工單完工 → 知識庫更新

工單完工 → sensor 驗證修復 → 知識庫更新 → transformContext 豐富。

RAG 同 transformContext

每次 Agent loop 開始前，transformContext 自動拉取相關數據注入 LLM context——呢個係 Pi Agent Harness 嘅核心 RAG pattern。

transformContext — 每次 Agent loop 開始前自動注入

// transformContext — 每次 Agent loop 開始前自動注入
async function buildContext(session) {
  const tenant = await db.getTenant(session.tenantId);
  const recentTickets = await db.queryTickets(tenant.siteId, { limit: 5 });
  const sensorSnapshot = await tsdb.readLatest(tenant.location, { window: '30m' });
  const similarCases = await vectorDB.search(session.initialMessage, { topK: 3 });

  return {
    tenantProfile: tenant,
    recentTickets,
    sensorData: sensorSnapshot,
    similarCases,  // RAG 檢索結果
    currentTime: new Date(),
    weather: await weatherAPI.getCurrent(tenant.city)
  };
}
      

Context 自動注入

每次 Agent loop 開始前，transformContext 自動拉取租戶資料、sensor 數據、歷史工單、相似案例，注入 LLM context window。

RAG 向量檢索

歷史案例經 embedding 存入向量庫，新投訴自動檢索最相似嘅 3 個過往案例，令 LLM 有得參考過往處理方法。

動態 Context 大小

根據 token budget 動態調整注入量，避免超出 model context limit。priority: sensor real-time > recent tickets > similar cases > weather。

Provider Routing 策略

經 pi-ai 統一介面管理多個 LLM provider——按用途、成本同能力分配。

Provider	Model	用途	特點	優先級
Anthropic	Claude Sonnet	Root-cause 推理、複雜診斷	最強推理能力	Primary
Google	Gemini Flash	分類、摘要、簡單回覆	便宜快速	Secondary
OpenRouter	多模型	Backup fallback	聚合多 provider	Backup
Ollama	本地模型	離線 fallback	零成本、數據不出境	Local Fallback

部署架構

AI Gateway 用 Node.js 獨立微服務部署，與現有 Supabase 架構並行。

瀏覽器 / App

用戶端

Supabase Edge Functions

API Gateway（認證、路由）

Node.js 微服務（AI Gateway）

Pi Agent Harness runtime，獨立部署。

Supabase PostgreSQL

營運 DB + 向量庫（pgvector）

Claude API（雲端）

主力推理——經 pi-ai 統一呼叫。

Gemini API（雲端）

輕量任務——分類、摘要、回覆。

Ollama（本地伺服器）

離線 fallback——數據不出境。

AI Gateway 用 Node.js 獨立微服務部署，唔係 Supabase Edge Functions——因為 pi-ai 只支援 Node.js。

Production 建議用 Railway / Fly.io / AWS ECS 部署 AI Gateway，確保穩定性同 auto-scaling。

Task 61–80 對應

AI 整合專項嘅 20 個 task，對應 Pi Agent Harness 整合嘅各個模組。

Task	內容	Agent	優先級
T61	AI Gateway 基礎建設	—	P0
T62	pi-ai + pi-agent-core 整合	—	P0
T63	Provider routing 配置	—	P0
T64	Tool: readSensorData	AutoDiag	P1
T65	Tool: queryTicketHistory	Copilot + AutoDiag	P1
T66	Tool: createWorkOrder	Copilot + AutoDiag	P1
T67	Agent Copilot system prompt	Copilot	P1
T68	Agent AutoDiag system prompt	AutoDiag	P1
T69	transformContext: 租戶 profile	Copilot	P1
T70	transformContext: sensor 數據	AutoDiag	P1
T71	transformContext: 歷史工單	Copilot + AutoDiag	P1
T72	SSE streaming 整合	Copilot	P2
T73	投訴流程端到端	Copilot	P2
T74	自動診斷端到端	AutoDiag	P2
T75	RAG 向量庫建設	—	P2
T76	Cost tracking 儀表板	—	P2
T77	Prompt 版本管理	—	P3
T78	A/B testing framework	—	P3
T79	本地 Ollama fallback	—	P3
T80	跨站點學習 pipeline	AutoDiag	P4

風險同 Spike

整合過程要留意嘅技術風險同驗證 spike——逐個搞掂先上 production。

pi-ai 只支援 Function Calling Models

pi-ai 要求 model 支援 tool calling / function calling。部分便宜模型（如 Gemini Flash 舊版）可能唔支援。Spike: 測試每個 target model 嘅 function calling 相容性。

Node.js Runtime 限制

AI Gateway 必須用 Node.js，唔可以用 Supabase Edge Functions（Deno）。部署多一個 service 增加運維複雜度。Spike: 評估 Railway / Fly.io 部署成本。

Context Window 限制

大量 sensor 數據 + 歷史工單可能超出 model context limit。需要 transformContext 做 smart truncation。Spike: 測試不同 context 大小對診斷質素嘅影響。

成本控制

LLM API 調用成本隨用量上升。需要 cost tracking + budget alert + 自動降級到便宜 model。Pi 內建 token tracking 可以直接用。