Quick Start

Get up and running with LensOS in just a few minutes.

Select your framework to see the corresponding setup guide:

1. Install the SDK

Terminal
bun add @lens-os/sdk

2. Get Your API Key

You need a LensOS API key and an OpenAI API key. Go to the dashboard to create your LensOS key:

Open API Keys Dashboard →
.env
# Server-side only — never use NEXT_PUBLIC_ prefix
LENS_API_KEY=your-lens-api-key
OPENAI_API_KEY=your-openai-api-key

3. Create Server Route

The agent handler runs on the server. API keys stay here and are never exposed to the client.

src/app/api/agent/chat/route.ts
import { createAgentHandler } from '@lens-os/sdk/server';

export const handler = createAgentHandler({
  apiKey: process.env.LENS_API_KEY!,
  openaiKey: process.env.OPENAI_API_KEY!,
});

export const { POST } = handler;

4. Create Action Result Route

src/app/api/agent/chat/action-result/route.ts
import { createActionResultHandler } from '@lens-os/sdk/server';
import { handler } from '../route';

export const { POST } = createActionResultHandler(handler._pendingActions);

5. Use React Hook

The client only needs the endpoint URL — no API keys required.

src/components/ChatPanel.tsx
'use client';
import { useLensAgent } from '@lens-os/sdk/react';

export default function ChatPanel() {
  const { messages, isLoading, sendMessage } = useLensAgent({
    endpoint: '/api/agent/chat',
  });

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i} className={msg.role}>
          {typeof msg.content === 'string' ? msg.content : ''}
        </div>
      ))}
      <input
        disabled={isLoading}
        onKeyDown={(e) => {
          if (e.key === 'Enter' && e.currentTarget.value.trim()) {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
        placeholder="Ask me anything..."
      />
    </div>
  );
}

Tip

That's it — 3 files to get a working AI agent. API keys stay on the server, the client communicates via the endpoint URL only.

Next Steps

  • Read the SDK Integration guide for deep server & client setup
  • Learn about Widgets to embed AI in your frontend
  • Configure Rules to control agent behavior
  • Add custom Tools to extend agent capabilities
  • Set up a Knowledge Base for domain-specific data