關於 LensOS

具備伺服器/客戶端架構的 AI Agent SDK，用於建構安全、可上線的對話式 AI。

LensOS 是用於建構 AI 驅動應用程式的作業系統。@lens-os/sdk 提供伺服器端 Agent Handler 與客戶端 React Hook — API 金鑰永遠不會暴露在前端。

架構概覽

LensOS 採用伺服器/客戶端分離模式。伺服器持有所有密鑰並執行 AI 代理迴圈， 而客戶端僅透過簡單的端點 URL 進行通訊。

架構圖
┌─────────────────────────────────────────────────────────────────┐
│                      瀏覽器 (React)                              │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  useLensAgent({ endpoint: '/api/agent/chat' })           │   │
│  │                                                          │   │
│  │  • 透過 POST 發送用戶訊息                                  │   │
│  │  • 讀取 SSE 串流 (text, tool_call, tool_result, ...)      │   │
│  │  • 自動處理 action_request (DOM 工具)                      │   │
│  │  • 將動作結果 POST 回 /api/agent/action-result             │   │
│  └────────────┬─────────────────────────────┬───────────────┘   │
│               │ POST /api/agent/chat        │ POST /action-result│
└───────────────┼─────────────────────────────┼───────────────────┘
                │                             │
                ▼                             ▼
┌───────────────────────────────────────────────────────────────────┐
│                      伺服器 (Next.js / Node.js)                    │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  createAgentHandler({                                        │ │
│  │    apiKey, openaiKey, model, toolExecutors                   │ │
│  │  })                                                          │ │
│  │                                                              │ │
│  │  • 每個請求建立一個 SupervisorAgent                            │ │
│  │  • 透過 SSE 串流事件回傳給客戶端                                │ │
│  │  • 在伺服器端執行工具                                          │ │
│  │  • 對 DOM 工具發送 action_request → 等待結果                    │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                          │                                        │
│              ┌───────────┼───────────┐                            │
│              ▼           ▼           ▼                            │
│      Lens OS SaaS   OpenAI API   你的 API Routes                  │
│      (設定/儲存)     (LLM)       (工具端點)                        │
└───────────────────────────────────────────────────────────────────┘

核心設計原則

  • API 金鑰留在伺服器 — createAgentHandler 持有 apiKey 和 openaiKey；客戶端只知道端點 URL。
  • SSE 為內部協議 — 伺服器 handler 與客戶端 hook 之間的 SSE 事件格式由 SDK 管理，你不需要自行解析或格式化 SSE。
  • 工具執行器接收 context — 每個工具執行函式都會收到 (parameters, context)，其中 context 包含 userId、sessionId 等資訊。
  • DOM 工具使用 Action Request — 當 Agent 需要與頁面互動（點擊、滾動），伺服器透過 SSE 發送 action_request，客戶端執行動作後 POST 結果回來。

功能特色

  • 多輪次代理迴圈 — 自主 LLM 協調與工具執行
  • 串流回應 — 透過 SSE 即時傳送文字與工具呼叫事件
  • React Hooks — useLensAgent 和 useChat 輕鬆整合
  • 工具系統 — 三層優先級： 手動 → 客戶 → 平台
  • 對話管理 — 含自動 session 追蹤的對話歷史
  • Action Request 協議 — 伺服器驅動的 DOM 互動（點擊、滾動、導航）
  • TypeScript — 完整的型別定義

安裝

Terminal
# 使用 bun
bun add @lens-os/sdk

# 使用 npm
npm install @lens-os/sdk

系統需求

  • Node.js >= 18
  • React >= 18（React hooks 需要）
  • OpenAI API 金鑰

Note

LensOS SDK 為開源專案，採用 MIT 授權。