About LensOS

AI Agent SDK with server/client architecture for building secure, production-ready conversational AI.

LensOS is the operating system for building AI-powered applications. The @lens-os/sdk provides a server-side Agent Handler and a client-side React Hook — API keys never leave the server.

Architecture Overview

LensOS uses a server/client separation pattern. The server holds all secrets and runs the AI agent loop, while the client communicates through a simple endpoint URL.

Architecture
┌─────────────────────────────────────────────────────────────────┐
│                      Browser (React)                            │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  useLensAgent({ endpoint: '/api/agent/chat' })           │   │
│  │                                                          │   │
│  │  • Sends user message via POST                           │   │
│  │  • Reads SSE stream (text, tool_call, tool_result, ...)  │   │
│  │  • Handles action_request (DOM tools) automatically      │   │
│  │  • POSTs action results back to /api/agent/action-result │   │
│  └────────────┬─────────────────────────────┬───────────────┘   │
│               │ POST /api/agent/chat        │ POST /action-result│
└───────────────┼─────────────────────────────┼───────────────────┘
                │                             │
                ▼                             ▼
┌───────────────────────────────────────────────────────────────────┐
│                      Server (Next.js / Node.js)                   │
│                                                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  createAgentHandler({                                        │ │
│  │    apiKey, openaiKey, model, toolExecutors                   │ │
│  │  })                                                          │ │
│  │                                                              │ │
│  │  • Creates SupervisorAgent per request                       │ │
│  │  • Streams SSE events back to client                         │ │
│  │  • Executes tools server-side                                │ │
│  │  • Sends action_request for DOM tools → waits for result     │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                          │                                        │
│              ┌───────────┼───────────┐                            │
│              ▼           ▼           ▼                            │
│      Lens OS SaaS   OpenAI API   Your API Routes                 │
│      (config/store)  (LLM)       (tool endpoints)                │
└───────────────────────────────────────────────────────────────────┘

Key Design Principles

  • API keys stay on the server — createAgentHandler holds apiKey and openaiKey; the client only knows the endpoint URL.
  • SSE as internal contract — The SSE event format between server handler and client hook is managed by the SDK. You don't need to parse or format SSE yourself.
  • Tool executors receive context — Every tool executor function receives (parameters, context) where context contains userId, sessionId, etc.
  • DOM tools use action requests — When the agent needs to interact with the page (click, scroll), the server sends an action_request via SSE, the client executes the action, and POSTs the result back.

Features

  • Multi-turn Agent Loop — Autonomous LLM orchestration with tool execution
  • Streaming Responses — Real-time text and tool call events via SSE
  • React Hooks — useLensAgent and useChat for easy integration
  • Tool System — 3-tier priority: Manual → Customer → Platform
  • Session Management — Conversation history with automatic session tracking
  • Action Request Protocol — Server-driven DOM interactions (click, scroll, navigate)
  • TypeScript — Full type definitions included

Installation

Terminal
# Using bun
bun add @lens-os/sdk

# Using npm
npm install @lens-os/sdk

Requirements

  • Node.js >= 18
  • React >= 18 (for React hooks)
  • OpenAI API key

Note

LensOS SDK is open source and available under the MIT license.