Overview

The Sunny Agents SDK is a TypeScript/JavaScript library that enables you to embed AI-powered chat experiences into any web application. Use createSunnyChat to drop in a fully-featured chat widget with automatic authentication and server-driven configuration.

What you can build

The SDK is designed specifically for healthcare applications:

Core capabilities

Partner setup

publicKey and partnerIdentifier are obtained from Sunny Central, the partner portal. Sign in at platform.sunnyhealthai.com (production) or platform.sunnyhealthai-staging.com (staging), then go to Developer Tools to create API keys, view your partner name, and configure authentication (allowed domains and token exchange). See Partner Setup for details.

How it works

createSunnyChat fetches your partner’s auth configuration from the server via the /sdk/config endpoint, activates the chosen authentication mode, and renders a chat widget in your container. The WebSocket connection is established when the user sends their first message.

Getting started

Provide your partner identifier, public key, and auth type — all authentication configuration is handled automatically by the server:

import { createSunnyChat } from "@sunnyhealthai/agents-sdk";
const chat = createSunnyChat({
  container: document.getElementById("chat"),
  partnerIdentifier: "acme-health",
  publicKey: "pk-sunnyagents_abc_xyz",
  authType: "passwordless", // or "tokenExchange"
});
// Access the underlying client for programmatic control
chat.client.on("snapshot", (snapshot) => { /* update your UI */ });
// Clean up when done
chat.destroy();

Authentication modes

The SDK supports two authentication methods. You specify the authType and the SDK handles everything else using server-provided configuration:

Custom Token Exchange

For applications with their own authentication (Auth0, Firebase, custom providers):

const chat = createSunnyChat({
  container: document.getElementById("chat"),
  partnerIdentifier: "acme-health",
  publicKey: "pk-sunnyagents_abc_xyz",
  authType: "tokenExchange",
  idTokenProvider: async () => {
    return localStorage.getItem("id_token");
  },
});

Passwordless Authentication

Email or SMS-based authentication without passwords. The SDK renders a verification UI in the chat automatically:

const chat = createSunnyChat({
  container: document.getElementById("chat"),
  partnerIdentifier: "acme-health",
  publicKey: "pk-sunnyagents_abc_xyz",
  authType: "passwordless",
});

Key features

• Real-time streaming - Messages stream in real-time as they’re generated
• Type-safe - Full TypeScript support with comprehensive type definitions
• Event-driven - Subscribe to events for snapshot updates, streaming deltas, and more
• Artifact support - Parse and render rich content delivered inline in messages
• MCP approvals - Handle tool execution approvals interactively
• File attachments - Send files as base64-encoded attachments
• Automatic reconnection - WebSocket connections automatically reconnect on failure
• Token management - Automatic token refresh and caching

Framework compatibility

The SDK is framework-agnostic and works with:

• React - Mount createSunnyChat in a useEffect hook
• Vue - Mount in onMounted lifecycle
• Angular - Use with Angular services and components
• Vanilla JavaScript - Use directly in any web page

Installation

npm install @sunnyhealthai/agents-sdk
# or
pnpm add @sunnyhealthai/agents-sdk
# or
yarn add @sunnyhealthai/agents-sdk

Getting help