agentx-chatbot

v1.0.0

Published

2 months ago

Production-ready AI chatbot widget with streaming, feedback, and markdown support. Works with Angular, React, Vue, Next.js, and vanilla HTML.

0High
0Medium
0Low

manoharchoppa

chatbot ai chat widget web-component angular react vue nextjs streaming markdown feedback agentx

AgentX Chatbot Library

A framework-agnostic AI chatbot widget with streaming, markdown, and feedback support. Works with Angular, React, Vue, Next.js, or any JavaScript project with just 1 line of code.

Quick Start

Option 1: NPM Installation (Recommended)

npm install agentx-chatbot

Then add ONE line to your code:

import 'agentx-chatbot';

Or use the programmatic API:

import { AgentXChatbot } from 'agentx-chatbot';

AgentXChatbot.init({ 
  apiUrl: 'http://localhost:8000' 
});

Option 2: CDN (Script Tag)

<script src="https://unpkg.com/agentx-chatbot"></script>
<script>
  AgentXChatbot.init({ apiUrl: 'http://localhost:8000' });
</script>

Option 3: HTML Custom Element

<agentx-chatbot api-url="http://localhost:8000"></agentx-chatbot>

Framework Integration Examples

Angular

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import 'agentx-chatbot';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  // ...
})
export class AppModule { }

// app.component.html
<agentx-chatbot 
  api-url="http://localhost:8000"
  title="Support Chat"
  position="bottom-right">
</agentx-chatbot>

React / Next.js

// App.jsx or page.tsx
import { useEffect } from 'react';
import { AgentXChatbot } from 'agentx-chatbot';

export default function App() {
  useEffect(() => {
    AgentXChatbot.init({
      apiUrl: 'http://localhost:8000',
      title: 'AI Assistant',
      features: {
        streaming: true,
        feedback: true,
      }
    });
    
    return () => AgentXChatbot.destroy();
  }, []);

  return <div>Your App Content</div>;
}

Or use the HTML element directly:

// With React 19+ or proper TypeScript declarations
function App() {
  return (
    <>
      <YourApp />
      <agentx-chatbot api-url="http://localhost:8000" />
    </>
  );
}

Vue.js

<template>
  <div>
    <YourApp />
    <agentx-chatbot 
      api-url="http://localhost:8000"
      title="Help Center"
    />
  </div>
</template>

<script setup>
import 'agentx-chatbot';
</script>

Plain HTML

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to My Website</h1>
  
  <!-- Just add this one line! -->
  <script src="https://unpkg.com/agentx-chatbot"></script>
  <script>
    AgentXChatbot.init({ 
      apiUrl: 'http://localhost:8000',
      welcomeMessage: 'Hi! How can I help you today?'
    });
  </script>
</body>
</html>

Configuration Options

AgentXChatbot.init({
  // Required
  apiUrl: 'http://localhost:8000',
  
  // Optional - User & Session
  userId: 'user123',              // Auto-generated if not provided
  sessionId: 'session456',        // Auto-created if not provided
  apiKey: 'your-api-key',         // For secured deployments
  
  // Optional - Appearance
  position: 'bottom-right',       // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  title: 'AI Assistant',          // Header title
  placeholder: 'Ask anything...', // Input placeholder
  welcomeMessage: 'Hello!',       // Initial welcome message
  autoOpen: false,                // Auto-open on load
  
  // Optional - Theme
  theme: {
    primaryColor: '#3b82f6',      // Primary button color
    backgroundColor: '#ffffff',   // Widget background
    textColor: '#1e293b',         // Text color
    darkMode: false,              // Enable dark mode
    fontFamily: 'Inter, sans-serif',
    borderRadius: '12px',
  },
  
  // Optional - Features
  features: {
    streaming: true,              // Enable streaming responses
    markdown: true,               // Enable markdown rendering
    feedback: true,               // Enable like/dislike buttons
    copyMessage: true,            // Enable copy button
    typingIndicator: true,        // Show typing animation
    reasoning: false,             // Show AI reasoning steps
  },
  
  // Optional - Callbacks
  callbacks: {
    onOpen: () => console.log('Chat opened'),
    onClose: () => console.log('Chat closed'),
    onMessageSent: (msg) => console.log('Sent:', msg),
    onMessageReceived: (msg) => console.log('Received:', msg),
    onFeedback: (traceId, score, comment) => console.log('Feedback:', score),
    onError: (error) => console.error('Error:', error),
    onSessionChange: (sessionId) => console.log('Session:', sessionId),
  },
  
  // Optional - Custom CSS
  customStyles: `
    :host {
      --agentx-primary: #6366f1;
    }
  `,
});

HTML Attributes

When using the HTML custom element, you can set configuration via attributes:

<agentx-chatbot 
  api-url="http://localhost:8000"
  user-id="user123"
  session-id="session456"
  api-key="your-api-key"
  position="bottom-right"
  title="Help Center"
  placeholder="Type your question..."
  welcome-message="How can I assist you?"
  auto-open="true"
  dark-mode="true"
  primary-color="#6366f1"
></agentx-chatbot>

Programmatic API

import { AgentXChatbot } from 'agentx-chatbot';

// Initialize
const chatbot = AgentXChatbot.init({ apiUrl: 'http://localhost:8000' });

// Control the widget
AgentXChatbot.open();
AgentXChatbot.close();
AgentXChatbot.toggle();

// Send a message
await AgentXChatbot.sendMessage('Hello!');

// Get messages
const messages = AgentXChatbot.getMessages();

// Clear history
AgentXChatbot.clearHistory();

// Create new session
const sessionId = await AgentXChatbot.newSession();

// Event listeners
AgentXChatbot.on('message-sent', ({ message }) => {
  console.log('User sent:', message);
});

AgentXChatbot.on('message-received', ({ message }) => {
  console.log('Bot replied:', message.content);
});

AgentXChatbot.on('feedback', ({ traceId, score, comment }) => {
  console.log('User feedback:', score > 0 ? 'positive' : 'negative');
});

// Remove listener
AgentXChatbot.off('message-sent', callback);

// Destroy widget
AgentXChatbot.destroy();

Events

| Event | Description | Data | |-------|-------------|------| | open | Chat window opened | - | | close | Chat window closed | - | | message-sent | User sent a message | { message: string } | | message-received | Bot response received | { message: ChatMessage } | | feedback | User submitted feedback | { traceId, score, comment } | | error | Error occurred | { error: Error } | | session-change | Session changed | { sessionId: string } | | loading-start | Started loading | - | | loading-end | Finished loading | - |

CSS Customization

The widget uses CSS variables for theming. Override them in your custom styles:

agentx-chatbot {
  --agentx-primary: #6366f1;
  --agentx-primary-hover: #4f46e5;
  --agentx-bg: #ffffff;
  --agentx-bg-secondary: #f8fafc;
  --agentx-text: #1e293b;
  --agentx-text-secondary: #64748b;
  --agentx-border: #e2e8f0;
  --agentx-user-msg: #3b82f6;
  --agentx-user-msg-text: #ffffff;
  --agentx-bot-msg: #f1f5f9;
  --agentx-bot-msg-text: #1e293b;
  --agentx-radius: 12px;
  --agentx-shadow: 0 10px 40px -10px rgba(0, 0, 0, 0.2);
  --agentx-font: 'Inter', sans-serif;
}

Vega-Lite Chart Support

The chatbot automatically detects and renders Vega-Lite chart specifications in AI responses. When the AI responds with a Vega-Lite JSON spec (in a code block or raw JSON), the chatbot will:

Extract the Vega-Lite spec from the message
Auto-fix common spec issues (missing schema, types, etc.)
Render an interactive chart with:
- Fullscreen mode
- PNG export
- Dark mode support
- Responsive sizing

Example AI response that will render a chart:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "title": "Sales by Category",
  "data": {
    "values": [
      {"category": "Electronics", "sales": 150000},
      {"category": "Clothing", "sales": 98000}
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": {"field": "category", "type": "nominal"},
    "y": {"field": "sales", "type": "quantitative"}
  }
}

You can also use the Vega chart utilities directly:

import { extractAllVegaSpecs, VegaChartRenderer } from 'agentx-chatbot';

// Extract specs from text
const specs = extractAllVegaSpecs(responseText);

// Render a chart manually
const container = document.getElementById('chart');
const renderer = new VegaChartRenderer(container, false);
await renderer.render(specs[0], 400, 300);

Backend API Requirements

The chatbot expects your backend (app.py) to expose these endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/healthz | GET | Health check | | /api/v2/{userId}/current-session | GET | Get/create current session | | /api/v2/{userId}/new-session | POST | Create new session | | /api/v2/{userId}/sessions | GET | List user sessions | | /api/v2/{userId}/{sessionId} | GET | Get session with messages | | /api/v2/{userId}/{sessionId}/chat | POST | Send message (non-streaming) | | /api/v2/{userId}/{sessionId}/chat/stream | POST | Send message (SSE streaming) | | /api/traces/{traceId}/score-public | POST | Submit feedback |

Browser Support

Chrome 67+
Firefox 63+
Safari 10.1+
Edge 79+

TypeScript Support

Full TypeScript definitions are included:

import { 
  AgentXChatbot,
  AgentXConfig,
  ChatMessage,
  AgentXEvents,
  ThemeConfig,
  FeatureConfig,
} from 'agentx-chatbot';

const config: AgentXConfig = {
  apiUrl: 'http://localhost:8000',
  theme: {
    primaryColor: '#6366f1',
  } as ThemeConfig,
};

AgentXChatbot.init(config);

AgentXChatbot.on('message-received', (data: { message: ChatMessage }) => {
  console.log(data.message.content);
});