Quickstart: Your First AI Assistant

Get a working AI assistant running in under 5 minutes with this step-by-step guide.

Prerequisites

A modern web browser
A Diosc Hub instance URL
An API key for your assistant

Don't have these yet? Contact your Diosc administrator or see the deployment guide to set up your own Diosc Hub instance.

Step 1: Add the Script

The fastest way to get started is using the CDN version. Add this to your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My AI Assistant</title>

  <!-- Load Diosc Assistant Kit from CDN -->
  <script type="module" src="https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js"></script>
</head>
<body>
  <!-- Component will go here -->
</body>
</html>

Step 2: Add the Component

Add the <diosc-chat> component to your page:

<body>
  <diosc-chat
    backend-url="https://your-hub.example.com"
    api-key="your-api-key-here">
  </diosc-chat>
</body>

Replace:

https://your-hub.example.com with your Diosc Hub URL
your-api-key-here with your actual API key

Step 3: See it Work

Open your HTML file in a browser. You should see:

A chat interface appears (usually in the bottom-right corner)
A greeting message from your AI assistant
An input field where you can type messages

Try it out:

Type "Hello!" and press Enter
You'll see the AI respond with a streaming message
The conversation is maintained as you chat

Complete Working Example

Here's the complete HTML file you can save and open immediately:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My AI Assistant</title>
  <script type="module" src="https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js"></script>

  <style>
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      margin: 0;
      padding: 20px;
      background: #f5f5f5;
    }
    h1 {
      color: #333;
    }
  </style>
</head>
<body>
  <h1>Welcome to My App</h1>
  <p>This is your application with an AI assistant embedded.</p>

  <!-- The AI assistant chat interface -->
  <diosc-chat
    backend-url="https://your-hub.example.com"
    api-key="your-api-key-here">
  </diosc-chat>
</body>
</html>

What Just Happened?

Let's break down what the assistant-kit did automatically:

Loaded the web component - The script tag loaded all necessary code
Initialized the core - Created a centralized state management system
Connected to your Hub - Established a WebSocket connection for real-time streaming
Fetched assistant config - Retrieved your assistant's name, avatar, and styling
Rendered the UI - Displayed a fully-functional chat interface

All of this happened with just two tags: <script> and <diosc-chat>.

Next Steps

Customize the Appearance

Add CSS custom properties to change colors and styling:

<style>
  diosc-chat {
    --primary-color: #0891b2;
    --background-color: #ffffff;
    --text-color: #000000;
    --border-radius: 12px;
    --font-family: 'Inter', sans-serif;
  }
</style>

Add Authentication

If your APIs require authentication, set up the auth provider:

<script type="module">
  import { diosc } from 'https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js';

  // Configure authentication
  diosc('auth', async () => ({
    headers: {
      'Authorization': 'Bearer ' + getUserToken()
    },
    userId: getCurrentUserId()
  }));

  function getUserToken() {
    // Your logic to get the user's auth token
    return localStorage.getItem('access_token') || 'demo-token';
  }

  function getCurrentUserId() {
    // Your logic to get the current user ID
    return 'user-123';
  }
</script>

See the Authentication Guide for complete patterns.

Use the Core API

Instead of just the component, you can control the assistant programmatically:

<script type="module">
  import { diosc } from 'https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js';

  // Configure
  diosc('config', {
    backendUrl: 'https://your-hub.example.com',
    apiKey: 'your-api-key',
    autoConnect: true,
    verbose: true  // Enable debug logging
  });

  // Listen for messages
  diosc('on', 'message', (message) => {
    console.log('AI said:', message.content);
  });

  // Send a message programmatically
  async function askAI(question) {
    const response = await diosc('invoke', question);
    console.log('Response:', response.content);
  }

  // Try it
  askAI('What can you help me with?');
</script>

Connect to Your APIs

The real power comes from connecting the AI to your backend APIs via MCP (Model Context Protocol):

Set up an MCP server - A simple HTTP server that exposes tools (API endpoints)
Configure it in Diosc Hub - Tell the Hub which tools are available
The AI uses your tools - The assistant automatically calls your APIs when needed

See the MCP Integration Guide for details.

Troubleshooting

Component doesn't appear

Check the browser console for errors:

// Open browser DevTools (F12) and check the Console tab

Common issues:

CORS errors: Your Hub needs to allow requests from your domain
Invalid API key: Double-check the API key is correct
Wrong backend URL: Ensure the URL is accessible from your browser

Connection fails

Enable verbose logging to see what's happening:

<script type="module">
  import { diosc } from 'https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js';

  diosc('config', { verbose: true });

  diosc('on', 'error', (error) => {
    console.error('Diosc error:', error);
  });

  diosc('on', 'connected', () => {
    console.log('Successfully connected!');
  });
</script>

Authentication errors

If you see 401 or 403 errors, check your auth provider:

diosc('on', 'auth_failed', (error) => {
  console.error('Auth failed:', error);
  // Maybe redirect to login?
  window.location.href = '/login';
});

Framework-Specific Setup

React

import { useEffect } from 'react';
import { diosc } from '@diosc-ai/assistant-kit';

function App() {
  useEffect(() => {
    diosc('config', {
      backendUrl: process.env.REACT_APP_HUB_URL,
      apiKey: process.env.REACT_APP_API_KEY
    });
  }, []);

  return (
    <div>
      <h1>My React App</h1>
      <diosc-chat />
    </div>
  );
}

Vue

<template>
  <div>
    <h1>My Vue App</h1>
    <diosc-chat />
  </div>
</template>

<script setup>
import { onMounted } from 'vue';
import { diosc } from '@diosc-ai/assistant-kit';

onMounted(() => {
  diosc('config', {
    backendUrl: import.meta.env.VITE_HUB_URL,
    apiKey: import.meta.env.VITE_API_KEY
  });
});
</script>

Angular

import { Component, OnInit } from '@angular/core';
import { diosc } from '@diosc-ai/assistant-kit';

@Component({
  selector: 'app-root',
  template: `
    <h1>My Angular App</h1>
    <diosc-chat></diosc-chat>
  `
})
export class AppComponent implements OnInit {
  ngOnInit() {
    diosc('config', {
      backendUrl: environment.hubUrl,
      apiKey: environment.apiKey
    });
  }
}

Complete NPM Setup

For production apps, install via NPM:

npm install @diosc-ai/assistant-kit

Then import in your JavaScript:

import { diosc } from '@diosc-ai/assistant-kit';

diosc('config', {
  backendUrl: 'https://your-hub.example.com',
  apiKey: 'your-api-key',
  autoConnect: true
});

Add the component to your HTML/JSX/Vue template:

<diosc-chat></diosc-chat>

Learn More

Now that you have a working assistant, explore:

Client SDK Reference - Complete API documentation
Authentication Guide - OAuth, JWT, sessions
Styling Guide - Theming and customization
Tool Integration - Connect to your APIs

What's Next?

You've successfully embedded an AI assistant in your app! The assistant can:

✅ Chat with users in real-time
✅ Stream responses token-by-token
✅ Maintain conversation context
✅ Handle errors gracefully

To make it truly powerful, you'll want to:

Connect your APIs - Let the AI interact with your backend
Add authentication - Ensure proper access control
Customize the UI - Match your brand
Register browser tools - Enable client-side actions

Each of these is covered in the documentation. Happy building! 🚀

Prerequisites​

Step 1: Add the Script​

Step 2: Add the Component​

Step 3: See it Work​

Complete Working Example​

What Just Happened?​

Next Steps​

Customize the Appearance​

Add Authentication​

Use the Core API​

Connect to Your APIs​

Troubleshooting​

Component doesn't appear​

Connection fails​

Authentication errors​

Framework-Specific Setup​

React​

Vue​

Angular​

Complete NPM Setup​

Learn More​

What's Next?​