npm package: @skippr/live-agent-sdk
Description: [![Website](https://img.shields.io/badge/Website-skippr.ai-blue)](https://skippr.ai) [![NPM Version](https://img.shields.io/npm/v/%40skippr%2Flive-agent-sdk?color=red)](https://www.npmjs.com/package/@skippr/live-agent-sdk)
Latest version: 0.21.0

# @skippr/live-agent-sdk

[![Website](https://img.shields.io/badge/Website-skippr.ai-blue)](https://skippr.ai) [![NPM Version](https://img.shields.io/npm/v/%40skippr%2Flive-agent-sdk?color=red)](https://www.npmjs.com/package/@skippr/live-agent-sdk)

A live agent with visual and voice skills, embedded into your app with a single React component.

## Installation

```bash
npm install @skippr/live-agent-sdk
```

## Quick Start

```tsx
import { LiveAgent } from '@skippr/live-agent-sdk';
import '@skippr/live-agent-sdk/styles';

function App() {
  return (
    <LiveAgent
      agentId="your_agent_id"
      appKey="pk_live_your_key"
    />
  );
}


## Custom Components

Any component rendered inside `<LiveAgent>` can use the `useLiveAgent` hook to access session state and controls:

```tsx
import { LiveAgent, useLiveAgent } from '@skippr/live-agent-sdk';

function ConnectionStatus() {
  const { isConnected } = useLiveAgent();

  if (isConnected) return <p>Agent connected</p>;
  return <p>Agent disconnected</p>;
}

function App() {
  return (
    <LiveAgent agentId="your_agent_id" appKey="pk_live_your_key">
      <ConnectionStatus />
    </LiveAgent>
  );
}
```

## API Reference

### `<LiveAgent>`

Self-contained widget component. Renders a floating button that opens a sidebar panel for real-time agent interaction.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `agentId` | `string` | *required* | Agent ID provided by Skippr |
| `appKey` | `string` | — | Publishable App Key from the admin dashboard |
| `authToken` | `string` | — | Bearer token for authenticated users |
| `userToken` | `string` | — | Signed JWT for secret mode identity verification |
| `defaultOpen` | `boolean` | `false` | Whether the panel starts open |

---

### `useLiveAgent()`

Hook for accessing session state and panel controls. Must be called within `<LiveAgent>`.

#### State

| Field | Type | Description |
|-------|------|-------------|
| `isConnected` | `boolean` | Whether the agent is connected |
| `isPanelOpen` | `boolean` | Whether the panel is currently open |
| `isStarting` | `boolean` | Whether a session is being created |
| `error` | `string` | Error message, if any |

#### Methods

| Method | Type | Description |
|--------|------|-------------|
| `startSession` | `() => Promise<void>` | Start a new agent session |
| `disconnect` | `() => Promise<void>` | End the current session |
| `openPanel` | `() => void` | Open the panel |
| `closePanel` | `() => void` | Close the panel |
| `togglePanel` | `() => void` | Toggle the panel open/closed |

### Global API

| Method | Description |
|--------|-------------|
| `Skippr.initialize(config)` | Mount the widget |
| `Skippr.logout()` | Clear auth token, show login form (direct auth mode) |
| `Skippr.destroy()` | Remove widget and clear auth tokens |

## Authentication Modes

The SDK supports two identity modes configured per App Key:

**Direct Auth** (default) — Users log in via email OTP inside the widget. No backend integration needed.

**Secret** — Your backend signs a JWT with the App Key's identity secret and passes it as `userToken`. The SDK skips the login form and verifies the user server-side.

## Support

For questions, technical support, or feedback:

* **Email**: contact@skippr.ai
* **Website**: [https://skippr.ai](https://skippr.ai)

---

© 2026 Skippr