elastikteams_ag_ui

Real-time AI agent progress tracking UI for web applications. Supports LangGraph, LangChain, and custom AI workflows via Server-Sent Events (SSE).

Installation

npm install elastikteams_ag_ui

Quick Start

import { AgentProgressUI } from 'elastikteams_ag_ui/web';
import 'elastikteams_ag_ui/web/styles.css';

const ui = new AgentProgressUI({
  sessionId: 'your-session-id',
  sseEndpoint: 'http://localhost:3001/api/agent-progress',
  containerId: 'agent-progress-container',
  showProgressBar: true,
  expandable: true,
  onComplete: (agents) => {
    console.log('All agents completed:', agents);
  },
  onError: (error) => {
    console.error('Agent error:', error);
  }
});

// Start listening to SSE events
ui.connect();

// Later, cleanup
ui.destroy();

Features

• Real-time progress tracking via SSE
• Expandable/collapsible step details
• Streaming text display
• Progress bars and spinners
• Light/dark theme support
• Framework agnostic (works with Angular, React, Vue, vanilla JS)
• TypeScript support with full type definitions

Configuration Options

interface AgentUIOptions {
  // Required
  sessionId: string;           // Unique session identifier
  sseEndpoint: string;         // SSE endpoint URL

  // Container
  containerId?: string;        // Render inside this div
  useModal?: boolean;          // Fallback to modal if container not found

  // UI Features
  expandable?: boolean;        // Enable expand/collapse (default: true)
  showSpinner?: boolean;       // Show animated spinners (default: true)
  showProgressBar?: boolean;   // Show progress bars (default: true)
  defaultExpanded?: boolean;   // All steps expanded by default (default: false)
  autoScroll?: boolean;        // Auto-scroll to active step (default: true)

  // Content Control
  showInitializing?: boolean;  // Show "Agent initializing..." message
  showSectionHeaders?: boolean;// Show "Live Agent Output" header
  showStreamText?: boolean;    // Show stream text from agents
  inlineSpinner?: boolean;     // Show spinner inline with names
  hideProcessingText?: boolean;// Hide "Processing..." static text

  // Completion Behavior
  showOnComplete?: boolean;    // Keep UI visible after completion (default: false)

  // Theme
  theme?: AgentUITheme;

  // Callbacks
  onComplete?: (agents: Map<string, AgentState>) => void;
  onError?: (error: Error) => void;
  onStepComplete?: (step: StepState) => void;
  onConnect?: () => void;
  onDisconnect?: () => void;
}

Theme Customization

const ui = new AgentProgressUI({
  sessionId: 'session-123',
  sseEndpoint: '/api/agent-progress',
  theme: {
    mode: 'dark',              // 'light' | 'dark' | 'auto'
    primaryColor: '#3b82f6',
    successColor: '#22c55e',
    errorColor: '#ef4444',
    backgroundColor: '#1f2937',
    textColor: '#f9fafb',
    borderRadius: '8px',
    spacing: 'comfortable'     // 'compact' | 'comfortable' | 'spacious'
  }
});

API Methods

// Connect to SSE endpoint
ui.connect();

// Disconnect from SSE endpoint
ui.disconnect();

// Expand all steps
ui.expandAll();

// Collapse all steps
ui.collapseAll();

// Get current agent states
const agents = ui.getAgents();

// Cleanup and destroy
ui.destroy();

SSE Event Format

The backend should emit events in this format:

// Agent started
{ type: 'agent:start', agentId: string, agentName: string }

// Step started
{ type: 'step:start', agentId: string, stepId: string, stepName: string, stepIndex: number }

// Step progress
{ type: 'step:progress', agentId: string, stepId: string, progress: number, message?: string }

// Streaming text
{ type: 'step:stream', agentId: string, stepId: string, chunk: string }

// Step completed
{ type: 'step:complete', agentId: string, stepId: string, result?: any }

// Agent completed
{ type: 'agent:complete', agentId: string, result?: any }

// Error
{ type: 'agent:error', agentId: string, error: { message: string, code?: string } }

Exports

// Main class
import { AgentProgressUI } from 'elastikteams_ag_ui/web';

// Types
import type {
  AgentUIOptions,
  AgentUITheme,
  AgentState,
  StepState,
  AgentStatus,
  StepStatus,
  StepOutput
} from 'elastikteams_ag_ui/web';

// Advanced: Individual components
import { AgentStore, SSETransport, UIRenderer } from 'elastikteams_ag_ui/web';

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

License

MIT - Elastik Teams India Pvt. Ltd.