Session & API

Session management and SDK API reference.

The SDK automatically creates and manages sessions via the Lens OS SaaS API. Each useLensAgent instance generates a unique sessionId on mount.

Session Management

Basic Operations

Session operations

const { sessionId, newSession, clearMessages } = useLensAgent({
  endpoint: '/api/agent/chat',
});

// Current session ID
console.log(sessionId); // "session-1709123456789-abc123def"

// Start a brand new session (clears messages + generates new ID)
newSession();

// Clear messages but keep the same session
clearMessages();

Session History via API Routes

To list and load previous sessions, create API routes that use LensClient:

src/app/api/agent/sessions/route.ts

import { LensClient } from '@lens-os/sdk';

const client = new LensClient({ apiKey: process.env.LENS_API_KEY! });

export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const userId = searchParams.get('userId');
  if (!userId) {
    return Response.json({ error: 'userId required' }, { status: 400 });
  }
  const sessions = await client.listSessions(userId);
  return Response.json(sessions);
}

src/app/api/agent/sessions/[id]/route.ts

import { LensClient } from '@lens-os/sdk';

const client = new LensClient({ apiKey: process.env.LENS_API_KEY! });

export async function GET(req: Request, { params }: { params: { id: string } }) {
  const messages = await client.getMessages(params.id);
  return Response.json(messages);
}

API Reference

Exports

@lens-os/sdk — LensClient, SupervisorAgent, all types (SSEEvent, ToolResult, SessionContext, etc.)
@lens-os/sdk/server — createAgentHandler, createActionResultHandler, PendingActionStore
@lens-os/sdk/react — useLensAgent, useChat

LensClient

Direct API client for Lens OS SaaS. Useful for config, sessions, and knowledge search outside the agent loop.

LensClient

import { LensClient } from '@lens-os/sdk';

const client = new LensClient({
  apiKey: process.env.LENS_API_KEY!,
  baseUrl: 'https://osapi.ask-lens.ai', // optional, this is the default
});

// Tenant config (cached with 60s TTL)
const config = await client.getConfig();

// Sessions
const sessions = await client.listSessions('user-123');
const session = await client.getSession('session-id');
const messages = await client.getMessages('session-id');

// Knowledge search
const results = await client.searchKnowledge('search query', 10);

// Product search
const products = await client.searchProducts('search query', 10);

Key Types

Types

interface Message {
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: string | MessageContent[];
  timestamp?: Date;
}

interface TenantConfig {
  systemPrompt?: string;
  prompts: SitePrompt[];
  skills: Skill[];
  tools: ToolRegistryItem[];
  version: string;
}

interface Skill {
  id: string;
  name: string;
  displayName: string;
  prompt: string;
  description?: string;
  temperature?: number;
  maxTokens?: number;
  enabledTools?: string[];
}

Tip

Use LensClient for server-side operations like listing sessions and searching the knowledge base. Never expose it to client-side code.