Building Custom Agent UIs
For teams that need a fully custom agent experience beyond the embeddable widget, Eloquent provides npm packages that handle all communication, authentication, and state management. Your team builds the UI; the packages handle the platform integration.
When to Use Custom UIs
Use the embedded widget (see Building Agents from Admin UI) when:
- You need a quick chat bubble on an existing website
- Default styling and behavior are sufficient
Build a custom UI when:
- You need full control over layout, branding, and user experience
- You need bilingual or RTL language support
- You need custom features like document viewers, voice I/O, or side panels
- You're embedding the agent deep into an existing portal or application
Available Packages
Install from npm:
npm install @elqnt/chat @elqnt/agents @elqnt/api-client
@elqnt/chat
Core chat SDK for real-time messaging:
| Export | Purpose |
|---|---|
useChat() | React hook for chat — connect, send messages, receive streaming responses |
useChatHistory() | Load and delete past conversations |
useHumanAgentSessions() | Manage human handoff sessions |
createSSETransport() | Browser transport using native EventSource |
createFetchSSETransport() | React Native transport using fetch-based SSE |
createWhatsAppTransport() | WhatsApp Business API transport |
@elqnt/agents
Agent management and background task execution:
| Export | Purpose |
|---|---|
useAgents() | List, create, update, delete agents |
useSkills() | Manage skills assigned to agents |
useWidgets() | Widget configuration management |
useBackgroundAgents() | Trigger and stream long-running agent tasks via SSE |
useAnalytics() | Agent performance metrics (chats, CSAT, outcomes) |
useSchedulerTasks() | One-time background task execution |
useSchedulerSchedules() | Recurring background task scheduling |
@elqnt/api-client
HTTP client with built-in JWT authentication:
| Export | Purpose |
|---|---|
browserApiRequest | Browser-side HTTP calls with automatic token management |
createServerClient | Server-side HTTP calls with JWT generation |
useApiAsync | React hook for async request orchestration |
Additional Packages
| Package | Purpose |
|---|---|
@elqnt/kg | Knowledge Graph SDK — semantic search, document retrieval, graph queries |
@elqnt/docs | Document handling — citations, source tracking |
Integration Pattern
1. Server-Side Configuration
Your Next.js (or similar) server loads configuration from environment variables:
CHAT_SERVER_BASE_URL=https://chat.customer.example.com
API_GATEWAY_URL=https://api.customer.example.com
ORG_ID=<organization-id>
AGENT_NAME=<agent-name>
JWT_SECRET=<jwt-secret>
Server actions generate JWT tokens for authenticated API Gateway calls — secrets never reach the browser.
2. Client-Side Provider
Wrap your UI with a context provider that initializes the chat connection:
- Pass server-resolved config (API URLs, org ID, agent name)
- Initialize
useChat()with SSE transport - Handle message streaming, typing indicators, and tool execution
3. Chat Lifecycle
- Create chat — HTTP POST to create a new session with agent name and metadata
- Connect to SSE — establish a streaming connection for real-time events
- Send messages — HTTP POST for each user message
- Receive responses — streamed via SSE as the agent generates output
- End chat — HTTP POST to close the session
4. Client-Side Tool Execution
Some tools execute on the client side rather than the server. This is useful for:
- Knowledge Graph queries that display results in a custom UI
- Document lookups that show PDF citations with highlighted regions
- Any operation where the UI needs direct access to tool results
The useChat() hook emits tool call events that your code intercepts, executes, and sends results back to the agent.
Customization Capabilities
Layout & Branding
Full React UI control — build any layout. Not limited to a chat bubble. Use your own design system, colors, logos, and animations.
Localization & RTL
Build bilingual interfaces with language switching. Support right-to-left languages (Arabic, Hebrew, etc.) with directional CSS.
Voice I/O
Integrate text-to-speech and speech recognition using cloud services (Azure Speech SDK, Web Speech API, etc.).
Document Viewer
Build side panels that display referenced documents, PDF pages, highlighted citations, and source metadata alongside the chat.
Portal Embedding
Use window.postMessage() to communicate with a parent frame when your agent UI runs inside an iframe in a larger portal application.
Telemetry
Add custom event tracking (Azure Application Insights, Google Analytics, etc.) to monitor agent usage, user behavior, and conversation outcomes.
Transport Options
| Transport | Use Case | Setup |
|---|---|---|
createSSETransport() | Standard web browser | Native EventSource, auto-reconnection |
createFetchSSETransport() | React Native mobile apps | Fetch-based SSE for non-browser environments |
createWhatsAppTransport() | WhatsApp Business API | Webhook-based messaging |
Real-World Example
A government organization deployed a custom agent UI with:
- Bilingual interface — Arabic and English with full RTL support
- Custom Knowledge Graph integration — client-side tool execution queries HR and procurement regulations
- Document citation viewer — side panel showing referenced documents with bounding region highlights
- Voice support — text-to-speech for AI responses, speech recognition for user input
- Azure telemetry — custom event tracking for conversation analytics
- Portal embedding —
postMessageintegration with the organization's internal portal
The entire UI was built using @elqnt/chat and @elqnt/kg packages, with a Next.js application hosted alongside the main Eloquent deployment.