ServiceAgent Quickstart

Start with the right package and get ServiceAgent live fast.

The fastest way to get started is to choose the right package for your stack and copy one of the working examples below.

Package selector

Use @serviceagent/nextjs for Next.js, @serviceagent/react for React or Vite, @serviceagent/sdk for backend API access, @serviceagent/aiva-sdk for custom low-latency voice, and @serviceagent/mcp for Cursor and Claude.

Quick install by stack

Stack	Recommended package	Why
Next.js	@serviceagent/nextjs	Best full-stack fit for UI, webhooks, and server-side integration.
React or Vite	@serviceagent/react	Fastest path for chat, booking, and voice UI.
Node.js backend	@serviceagent/sdk	Typed backend SDK for server-to-server API access.
Custom voice and dialer	@serviceagent/aiva-sdk	Low-level voice control for HD audio, transcripts, summaries, and call intelligence.
Cursor or Claude	@serviceagent/mcp	Lets AI coding assistants provision and configure ServiceAgent directly.

30-second Next.js quickstart

npm

npm install @serviceagent/nextjs

Next.js example

import { ServiceAgentProvider } from '@serviceagent/nextjs';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ServiceAgentProvider>{children}</ServiceAgentProvider>
      </body>
    </html>
  );
}

30-second React quickstart

npm

npm install @serviceagent/react

React example

import { Chat } from '@serviceagent/react';

export default function App() {
  return <Chat />;
}

30-second backend SDK quickstart

npm

npm install @serviceagent/sdk

Server-side example

import { ServiceAgent } from '@serviceagent/sdk';

const sa = new ServiceAgent({
  apiKey: process.env.SERVICEAGENT_API_KEY,
  baseURL: process.env.SERVICEAGENT_API_URL || 'https://process.serviceagent.ai',
});

const results = await sa.searchKnowledgeBase('What are your weekend hours?');

Environment variables

Most frontend installs only need a widget key and API URL to get started. Add the values below and then use the package-specific components.

.env.local

NEXT_PUBLIC_SERVICEAGENT_WIDGET_KEY=wid_xxxxx
NEXT_PUBLIC_SERVICEAGENT_API_URL=https://process.serviceagent.ai
NEXT_PUBLIC_SERVICEAGENT_BOOKING_KEY=your_booking_key
NEXT_PUBLIC_SERVICEAGENT_VOICE_ENDPOINT=wss://process.serviceagent.ai/v1/voice/stream
SERVICEAGENT_API_KEY=your_api_key

Get an API key — no portal sign-in required

You only need a server-side SERVICEAGENT_API_KEY for webhooks, voice, CRM-sync, and any other backend call. Pick the path that matches your environment — all three end with the key written to .env for you.

MCP-aware IDE

Cursor · Claude · Windsurf · Continue

From inside the IDE, ask the assistant to call the claim_workspace tool. It sends the magic link, polls until you click it, then writesSERVICEAGENT_API_KEY to .env.

claim_workspace({
  installToken,
  email: "you@org.com"
})

Plain shell · Lovable · Bolt · v0 · Replit

npx @serviceagent/cli claim

One command. Same outcome — the key lands in .env, the stale install token is stripped automatically.

npx @serviceagent/cli claim \
  --email you@org.com

Already a customer

Dashboard → API Keys

If you already have a ServiceAgent org, manage and rotate keys in the dashboard.

Open API Keys

Fastest install path

Use the CLI

If you want the quickest setup flow without reading deeper docs, run the CLI directly:

CLI

npx @serviceagent/cli add

Using Cursor or Claude?

Start with the prompt builder if you want a copy-ready implementation prompt that already includes the right packages, env vars, and endpoints for your stack.

What happens after install?

Add chat globally or on support pages.
Add booking widgets on sales, consultation, or appointment flows.
Add low-latency AI voice for support, sales, intake, and dialer use cases with transcripts and summaries.
Wire backend APIs and webhooks for production workflows.