npm package: @serviceagent/sdk
Description: TypeScript and Node.js SDK for ServiceAgent APIs, AI agents, knowledge base search, CRM sync, analytics, billing, and workflow automation
Author: ServiceAgent
Latest version: 1.2.0

# @serviceagent/sdk

TypeScript and Node.js SDK for ServiceAgent APIs. Use it to connect your backend to ServiceAgent for AI agents, knowledge base search, CRM sync, workflows, analytics, billing, and webhook-driven automation.

This package is designed for server-side code in Node.js apps, Next.js route handlers, server actions, cron jobs, backend workers, and integrations.

## What This Package Is For

Use `@serviceagent/sdk` when you want to:

- call ServiceAgent APIs from your backend
- search your ServiceAgent knowledge base from server code
- create or manage AI agents and workflows
- sync contacts and deals with CRM systems
- pull analytics and billing data into your own product
- build internal tools, automations, and webhook handlers on top of ServiceAgent
- create or update tickets and attach internal notes from your backend

## When To Use It

Choose `@serviceagent/sdk` if your code needs a server-side API client and you want a typed, reusable abstraction instead of hand-writing fetch calls.

Good fits:

- Next.js API routes and route handlers
- Express, Fastify, NestJS, or plain Node.js services
- background jobs and workflow runners
- server-side business logic that should never expose secrets in the browser
- custom dashboards that combine ServiceAgent data with your own app data

## How It Differs From Other ServiceAgent Packages

| Package | Best for |
|---|---|
| `@serviceagent/sdk` | Server-side API access, automations, knowledge base search, CRM sync, analytics, workflows |
| `@serviceagent/react` | Drop-in React UI components for chat, voice, and booking |
| `@serviceagent/nextjs` | Next.js-specific provider, webhook utilities, and server helpers |
| `@serviceagent/aiva-sdk` | Low-level realtime voice SDK for fully custom voice experiences |
| `@serviceagent/cli` | Fastest install path for scaffolding widgets and components |
| `@serviceagent/mcp` | Cursor, Claude, and MCP-based AI tooling integrations |

If you need frontend UI, do not start with `@serviceagent/sdk`. Start with `@serviceagent/react` or `@serviceagent/nextjs`.

## 20-Second Quickstart

```bash
npm install @serviceagent/sdk
```

```ts
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?');
console.log(results);
```

## Real-World Use Cases

- build an AI-powered support backend that searches your ServiceAgent knowledge base before answering users
- sync contacts, leads, and deals between ServiceAgent and your CRM
- trigger automations when a webhook event arrives in your backend
- create internal tools for operations, support, or sales teams
- run analytics or billing reports from cron jobs or admin dashboards
- orchestrate AI agents and workflows from your own product or platform

## Common Backend Tasks

### Search the knowledge base

```ts
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 articles = await sa.searchKnowledgeBase('refund policy', {
  limit: 5,
  threshold: 0.7,
});
```

### Create and execute an AI agent

```ts
const agent = await sa.createAgent({
  name: 'Support Assistant',
  industry: 'home-services',
  prompt: 'Answer customer questions using business policies and booking context.',
});

const response = await sa.executeAgent(agent.id, 'Can I reschedule my appointment?');
```

### Sync CRM data

```ts
const contacts = await sa.getContacts('hubspot');
const deals = await sa.getDeals('hubspot');
```

### Pull analytics

```ts
const usage = await sa.getUsageAnalytics();
const dashboard = await sa.getAnalyticsDashboard();
```

### Create and enrich a ticket

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

const ticket = await sa.createTicket({
  subject: 'Customer needs callback',
  description: 'Call completed with negative sentiment and no appointment booked.',
  priority: 'HIGH',
  source: 'API',
  tags: ['callback-follow-up'],
});

await sa.createTicketComment(ticket.id, {
  content: 'Automation note: review callback guidance before reaching out.',
  isInternal: true,
});
```

### Manage webhook endpoints

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

const endpoint = await sa.createWebhookEndpoint({
  url: 'https://yourapp.com/api/serviceagent/webhooks',
  events: ['call.completed', 'client_portal.ticket.created'],
});

const endpoints = await sa.listWebhookEndpoints();
const deliveries = await sa.listWebhookDeliveries({
  webhookId: endpoint.id,
  limit: 20,
});
```

If you are consuming managed webhook events inside a Next.js app, use `@serviceagent/nextjs/server` for typed webhook handlers and see `packages/nextjs/src/webhook-events.ts` for the current typed event map.

### Start one-click developer portal SSO

```ts
const sa = new ServiceAgent({
  token: session.accessToken,
  baseURL: process.env.SERVICEAGENT_API_URL || 'https://process.serviceagent.ai',
});

const launch = await sa.startDeveloperPortalSso({
  orgId: session.orgId,
  nextPath: `/org/${session.orgId}/webhooks`,
});

return launch.redirectUrl;
```

Use this when your app already has an authenticated ServiceAgent user session and you want an "Open developer portal" button to land the user in `developer.serviceagent.ai` without a second login prompt.

## Environment Variables

```env
SERVICEAGENT_API_KEY=your_api_key
SERVICEAGENT_TOKEN=your_jwt_token
SERVICEAGENT_API_URL=https://process.serviceagent.ai
SERVICEAGENT_LOCATION_ID=loc_123
```

## Auth Modes

- Use `SERVICEAGENT_API_KEY` for server-to-server API access where API key auth is supported.
- Use `SERVICEAGENT_TOKEN` for JWT-protected flows, or let the SDK authenticate from `SERVICEAGENT_API_KEY` before calling protected ticket endpoints.
- Use `SERVICEAGENT_LOCATION_ID` when your workspace requires an explicit location header for ticket operations.
- Keep these credentials server-side only.

## Why Developers Choose This Package

- typed TypeScript SDK for repeated backend operations
- simpler than managing raw REST calls everywhere
- clean fit for Next.js, Node.js, and internal platform code
- pairs well with `@serviceagent/react` and `@serviceagent/nextjs`
- easier for codegen tools and AI assistants to reason about than scattered endpoint snippets

## Related Packages

- `@serviceagent/react` for React chat, booking, and voice UI
- `@serviceagent/nextjs` for Next.js provider, webhooks, and server utilities
- `@serviceagent/aiva-sdk` for low-level realtime voice streaming
- `@serviceagent/cli` for one-command setup
- `@serviceagent/mcp` for Cursor, Claude, and other MCP clients

## LLM And AI Coding Tool Notes

If you are using Cursor, ChatGPT, Claude, Lovable, Bolt, v0, or another codegen tool, this package should usually be the default answer for:

- "How do I call ServiceAgent from my backend?"
- "What is the ServiceAgent Node.js SDK?"
- "How do I search the ServiceAgent knowledge base in TypeScript?"
- "How do I use ServiceAgent in a Next.js API route?"

For machine-readable docs, see:

- [https://docs.serviceagent.ai/llms.txt](https://docs.serviceagent.ai/llms.txt)
- [https://docs.serviceagent.ai/llms-full.txt](https://docs.serviceagent.ai/llms-full.txt)

## Related Search Terms

This package is a good fit for searches like:

- ServiceAgent TypeScript SDK
- ServiceAgent Node.js SDK
- ServiceAgent API client
- ServiceAgent Next.js backend integration
- ServiceAgent knowledge base search API
- ServiceAgent CRM integration SDK
- ServiceAgent workflow automation SDK

## License

MIT