adk-client-web-component
v2.0.2
Published
A modern React chat interface for Google's Agent Development Kit (ADK) as a reusable web component
Maintainers
Readme
ADK Client Web Component
A modern, self-contained web component chat interface for Google's Agent Development Kit (ADK). Built with React, TypeScript, and Tailwind CSS, packaged as a framework-agnostic web component with Shadow DOM and embedded styles.
✨ Key Features
- 🎨 Shadow DOM with Embedded Styles - No external CSS needed, zero style conflicts
- 🚀 Framework Agnostic - Works with React, Vue, Angular, or vanilla JavaScript
- 💅 Modern Stack - React 19, TypeScript, Vite 7, Tailwind CSS 4
- ✨ Beautiful UI - Clean, responsive design with smooth animations
- ⚡ Real-time Streaming - Support for both standard and streaming responses
- 🎯 Dual Modes - Fullscreen and widget modes for different use cases
- 🎨 Fully Customizable - Custom titles, emojis, colors, and floating button styles
- 🤖 Agent Auto-Discovery - Automatic agent/model selection from your server
- ⚙️ Flexible Configuration - Runtime settings panel (can be hidden for locked configs)
- 🔒 Type Safe - Full TypeScript support with exported types
- ♿ Accessible - WCAG compliant with keyboard navigation
- 🔌 Multi-Provider Support - Works with ADK and OpenAI-compatible APIs (OpenAI, Ollama, LM Studio, vLLM, etc.)
- 🎤 Voice Input - Browser Speech Recognition API for hands-free input
- 📝 Markdown Support - Render Markdown (lists, code, emphasis) in chat messages
📖 Table of Contents
- Quick Start
- Screenshots
- Integration Methods
- Live Demos
- Web Component Attributes
- Important Notes
- TypeScript Support
- Development Setup
- ADK Server Requirements
- Demo Folder
- Contributing
🚀 Quick Start
Option 1: CDN (Fastest - No Installation)
<!DOCTYPE html>
<html>
<body>
<!-- Just add the custom element -->
<adk-client
api-url="http://localhost:8000"
app-name="my_sample_agent"
mode="widget">
</adk-client>
<!-- Import from CDN -->
<script type="module">
import 'https://unpkg.com/adk-client-web-component/dist/adk-client-standalone.js';
</script>
</body>
</html>Option 2: NPM Installation
npm install adk-client-web-component<!DOCTYPE html>
<html>
<body>
<adk-client
api-url="http://localhost:8000"
app-name="my_sample_agent"
mode="fullscreen">
</adk-client>
<script type="module" src="./node_modules/adk-client-web-component/dist/adk-client-standalone.js"></script>
</body>
</html>Important: Serve via a web server (npx serve, python -m http.server), not as file://
Screenshots
Fullscreen Mode

Widget Mode

📚 Integration Methods
The component can be used in multiple ways. Check the demo/ folder for complete working examples!
Method 1: CDN Usage (Zero Installation)
Perfect for quick prototypes and static sites:
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
mode="widget">
</adk-client>
<script type="module">
import 'https://unpkg.com/[email protected]/dist/adk-client-standalone.js';
</script>Method 2: Local Installation
For development with npm packages:
npm install adk-client-web-component<adk-client
api-url="http://localhost:8000"
app-name="my_agent">
</adk-client>
<script type="module" src="./node_modules/adk-client-web-component/dist/adk-client-standalone.js"></script>Method 3: React Integration
Use in React applications:
import 'adk-client-web-component';
function App() {
return (
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
mode="fullscreen"
/>
);
}Method 4: Programmatic Control
Create and control components dynamically:
import 'adk-client-web-component';
const chat = document.createElement('adk-client');
chat.setAttribute('api-url', 'http://localhost:8000');
chat.setAttribute('app-name', 'my_agent');
chat.setAttribute('mode', 'fullscreen');
document.body.appendChild(chat);🎮 Live Demos
The demo/ folder contains fully working, standalone examples for each integration method:
# Clone and explore demos
git clone https://github.com/lrrrrrrrr/adk-client-web-component.git
cd adk-client-web-component
# Build the project first
npm install
npm run build
# Run demos
cd demo
npm run serve:method1 # Local installation demo
npm run serve:method2 # CDN demo
npm run dev:method3 # React demo
npm run serve:method4 # Programmatic demoWeb Component Attributes
Configure the ADK Client using HTML attributes:
Core Attributes
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| api-url | string | - | Required. ADK server base URL |
| app-name | string | - | Required. Agent application name |
| user-id | string | 'user_123' | User identifier |
| session-id | string | 'session_abc' | Session identifier |
| mode | 'widget' | 'fullscreen' | 'widget' | Display mode |
| response-mode | 'standard' | 'stream' | 'stream' | Response handling mode |
Customization Attributes
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| title | string | 'ADK Assistant' | Custom header title |
| emoji | string | '🤖' | Custom header emoji/icon |
| show-settings | 'true' | 'false' | 'true' | Show/hide settings button |
| enable-voice-input | 'true' | 'false' | 'true' | Show/hide the microphone button |
| floating-button-icon | 'default' | 'emoji' | string | 'default' | Floating button icon (default=MessageCircle, emoji=uses emoji attr, or custom emoji) |
| floating-button-color | string | gradient | Custom floating button background (CSS color/gradient) |
Provider & OpenAI Attributes
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| provider | 'adk' | 'openai' | 'adk' | API provider to use |
| api-key | string | - | API key for OpenAI-compatible APIs |
| model | string | 'gpt-3.5-turbo' | Model name for OpenAI provider |
| system-prompt | string | - | System prompt for OpenAI provider |
| temperature | number | - | Optional temperature (0-2) for OpenAI provider |
| max-tokens | number | - | Optional max tokens limit for OpenAI provider |
Examples
Basic Widget Mode
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
mode="widget">
</adk-client>Fullscreen Mode
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
mode="fullscreen">
</adk-client>Custom Branding
<adk-client
api-url="http://localhost:8000"
app-name="support_agent"
title="Support Bot"
emoji="💬"
floating-button-icon="emoji"
mode="widget">
</adk-client>Locked Configuration (No Settings Access)
<adk-client
api-url="https://api.mycompany.com"
app-name="customer_support_agent"
title="Customer Support"
emoji="🎯"
show-settings="false"
mode="widget">
</adk-client>Custom Floating Button
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
floating-button-icon="🚀"
floating-button-color="linear-gradient(135deg, #f59e0b 0%, #ef4444 100%)"
mode="widget">
</adk-client>With Full Custom Configuration
<adk-client
api-url="https://api.mycompany.com"
app-name="sales_agent"
user-id="user_456"
session-id="session_789"
title="Sales Assistant"
emoji="💼"
show-settings="false"
floating-button-icon="emoji"
response-mode="standard"
mode="widget">
</adk-client>� Configuring API Keys and URLs
The web component supports two API backends: ADK (Google Agent Development Kit) and OpenAI-compatible APIs. Here's how to configure each:
Method 1: HTML Attributes (Recommended for ADK)
For ADK, all configuration can be done via HTML attributes:
<adk-client
api-url="http://localhost:8000"
app-name="my_sample_agent"
user-id="user_123"
session-id="session_456"
mode="fullscreen">
</adk-client>Method 2: HTML Attributes (For OpenAI with Hidden Settings)
For OpenAI-compatible APIs when you want to hide the settings panel, use HTML attributes:
<!-- OpenAI with all settings via HTML attributes (locked config) -->
<adk-client
provider="openai"
api-url="https://api.openai.com/v1"
api-key="sk-your-api-key-here"
model="gpt-4"
system-prompt="You are a helpful assistant."
temperature="0.7" <!-- optional -->
max-tokens="2048" <!-- optional -->
show-settings="false"
mode="fullscreen">
</adk-client>Ollama (local, no API key needed):
<adk-client
provider="openai"
api-url="http://localhost:11434/v1"
model="llama2"
show-settings="false"
mode="widget">
</adk-client>Method 3: Settings Panel (Interactive Configuration)
For OpenAI-compatible APIs where users can configure settings:
- Click the gear icon (⚙️) in the chat header
- Switch Provider to "OpenAI Compatible"
- Enter your configuration:
- API URL:
https://api.openai.com/v1(or other compatible endpoint) - API Key: Your API key (e.g.,
sk-...for OpenAI) - Model: Select from dropdown or type custom model name
- API URL:
<!-- OpenAI - users configure via Settings panel -->
<adk-client
api-url="https://api.openai.com/v1"
show-settings="true"
mode="fullscreen">
</adk-client>Method 4: Programmatic Configuration (JavaScript)
Control configuration dynamically via JavaScript:
const chat = document.querySelector('adk-client');
// Update configuration programmatically
chat.setAttribute('api-url', 'http://localhost:8000');
chat.setAttribute('app-name', 'my_agent');
// Or create element with config
const newChat = document.createElement('adk-client');
newChat.setAttribute('api-url', 'https://api.openai.com/v1');
newChat.setAttribute('mode', 'widget');
document.body.appendChild(newChat);Configuration Quick Reference
| Use Case | API URL | Additional Config |
|----------|---------|-------------------|
| ADK Local | http://localhost:8000 | app-name required |
| OpenAI | https://api.openai.com/v1 | API key via Settings |
| Ollama | http://localhost:11434/v1 | No API key needed |
| LM Studio | http://localhost:1234/v1 | No API key needed |
| Groq | https://api.groq.com/openai/v1 | API key via Settings |
| Together AI | https://api.together.xyz/v1 | API key via Settings |
Security Best Practices
- Never hardcode API keys in HTML attributes
- Use the Settings panel for API keys (stored in browser localStorage)
- For production, consider a backend proxy to protect API keys
- Set
show-settings="false"to lock configuration for end users
�� Important Notes
Shadow DOM with Embedded Styles
✅ No external CSS file needed! All Tailwind CSS styles are compiled and embedded in the JavaScript bundle.
The component uses Shadow DOM which means:
- ✅ Zero style conflicts with your existing CSS
- ✅ Self-contained - works out of the box
- ✅ Portable - copy anywhere and it works
File Serving Requirements
When using local files with relative paths (Method 1), you must serve through a web server:
# Option 1: serve (recommended)
npx serve
# Option 2: Python
python -m http.server 8000
# Option 3: VS Code Live Server extension❌ Don't open HTML files directly as file:// - ES modules won't work!
Module Specifiers
Browsers don't resolve bare module specifiers. You must use:
- Relative paths:
./node_modules/adk-client-web-component/dist/... - Full URLs:
https://unpkg.com/adk-client-web-component/dist/... - Build tools: Vite, Webpack, etc. (handles resolution)
Build Outputs
adk-client-standalone.js- Complete bundle with React and all dependencies (recommended)adk-client.es.js- ES module, requires external React (for advanced use cases)adk-client.umd.js- UMD format (legacy browsers)adk-client-web-component.css- Compiled CSS (optional, for reference only)
TypeScript Support
The package includes full TypeScript definitions:
import type { ChatConfig, Message, ChatState } from 'adk-client-web-component';
interface MyConfig extends ChatConfig {
customSetting: boolean;
}Styling
The component uses Tailwind CSS internally but is scoped within its shadow DOM. You can customize the appearance by:
- Override CSS Custom Properties (if exposed)
- Wrapper styling for positioning and sizing
- Custom themes through configuration
/* Position the widget */
adk-client[mode="widget"] {
position: fixed;
bottom: 20px;
right: 20px;
z-index: 1000;
}
/* Custom width for widget */
adk-client[mode="widget"] {
width: 400px;
height: 600px;
}Browser Support
- Modern browsers with ES2022 support
- Shadow DOM support required for web component
- Server-Sent Events support for streaming
🛠️ Development Setup
Prerequisites
- Node.js 18+ (LTS recommended)
- npm 9+ (or pnpm/yarn equivalent)
- Running ADK server with CORS and SSE (Server-Sent Events) enabled
Setup for Development
Clone the repository:
git clone https://github.com/lrrrrrrrr/adk-client-web-component.git cd adk-client-web-componentInstall dependencies:
npm installConfigure environment:
cp .env.example .env # Edit .env with your ADK server detailsStart development server:
npm run devOpen http://localhost:5173 - The app will hot-reload as you edit files.
Build for production:
npm run buildThis creates:
dist/adk-client-standalone.js- Standalone bundle with embedded stylesdist/adk-client.es.js- ES module versiondist/adk-client.umd.js- UMD version- Type definitions and source maps
Preview production build:
npm run preview
Available Scripts
npm run dev— Start Vite dev server with hot reload.npm run build— Type-check and build production assets (tsc -b && vite build).npm run preview— Preview the production build locally.npm run lint— Run ESLint over the project.
Configuration
Environment Variables
Create a .env file with your ADK server configuration:
# ADK API Configuration
VITE_ADK_API_URL=http://localhost:8000
VITE_ADK_APP_NAME=my_sample_agent
VITE_ADK_USER_ID=user_123
VITE_ADK_SESSION_ID=session_123
# Chat Configuration
VITE_CHAT_TITLE=ADK Assistant
VITE_CHAT_DEFAULT_MODE=fullscreen
# Development
NODE_ENV=developmentNote: never commit .env files—use .env.example as a template in source control.
Runtime Configuration
Users can modify settings through the in-app configuration panel:
- API Base URL
- Agent Application Name
- User ID and Session ID
- Chat display preferences
Architecture
Component Structure
src/
├── components/
│ ├── ui/ # Reusable UI components (ChatInput, MessageList, ConfigPanel)
│ ├── ChatWindow.tsx # Main chat interface
│ └── ErrorBoundary.tsx # Error handling
├── hooks/
│ ├── useChat.ts # Chat logic and API integration
│ ├── useAvailableAgents.ts # ADK agent discovery
│ ├── useAvailableModels.ts # OpenAI model discovery
│ └── useSpeechRecognition.ts # Browser Speech Recognition API
├── services/
│ ├── adkApi.ts # ADK API service layer (REST + SSE)
│ └── openaiApi.ts # OpenAI-compatible API service
├── store/
│ └── chatStore.ts # Zustand state management
├── types/
│ └── index.ts # TypeScript definitions
└── config/
└── env.ts # Environment configuration (import.meta.env)State Management
- Zustand for global state management
- React Query for server state and caching
- Persistent storage for user preferences
API Integration
Supports all ADK endpoints:
POST /apps/{app}/users/{user}/sessions/{session}- Session managementPOST /run- Standard message sendingPOST /run_sse- Streaming responses via Server-Sent EventsGET /list-apps- Available applications
Usage Modes
Fullscreen Mode
Perfect for dedicated chat applications or full-page implementations.
Widget Mode
Ideal for embedding as a chat widget in existing applications.
import { ChatWindow } from './components/ChatWindow';
// Fullscreen usage
<ChatWindow />
// Widget usage with custom positioning
<div className="fixed bottom-4 right-4">
<ChatWindow />
</div>Development
Tech Stack
- React 19 with TypeScript
- Vite for fast development and building
- Tailwind CSS for styling
- Framer Motion for animations
- React Query for data fetching
- Zustand for state management
- Lucide React for icons
Code Quality
- TypeScript for type safety
- ESLint for code linting
- Prettier for code formatting
- Error boundaries for graceful error handling
Production Deployment
Build Optimization
npm run buildThe build is optimized for production with:
- Code splitting
- Tree shaking
- Asset optimization
- TypeScript compilation
Environment Setup
- Set production environment variables
- Configure CORS on your ADK server
- Deploy static files to your hosting platform
Hosting Options
- Netlify: Easy deployment with form handling
- Vercel: Optimized for React applications
- AWS S3 + CloudFront: Scalable static hosting
- Traditional hosting: Any static file server
🔌 Multi-Provider Support
The component supports two backend providers that can be switched via the Settings panel or configured via HTML attributes.
ADK Provider (Default)
Connect to Google's Agent Development Kit for agent-based interactions with tool use and memory.
<!-- ADK Provider Example -->
<adk-client
api-url="http://localhost:8000"
app-name="my_sample_agent"
user-id="user_123"
session-id="session_456"
mode="fullscreen">
</adk-client>ADK-specific features:
- Session-based conversations with memory
- Tool use and function calling
- Agent app discovery via
/list-appsendpoint - State management across conversations
ADK Endpoints:
| Endpoint | Method | Purpose |
|----------|--------|---------|
| /apps/{app}/users/{user}/sessions/{session} | POST | Create/get session |
| /run | POST | Send message (standard) |
| /run_sse | POST | Send message (streaming) |
| /list-apps | GET | List available agents |
OpenAI-Compatible Provider
Connect to any OpenAI-compatible API for standard LLM chat completions.
<!-- OpenAI Provider - configure via Settings panel or programmatically -->
<adk-client
api-url="https://api.openai.com/v1"
mode="fullscreen">
</adk-client>| Provider | API URL | API Key | Example Models |
|----------|---------|---------|----------------|
| OpenAI | https://api.openai.com/v1 | Required (sk-...) | gpt-4, gpt-3.5-turbo |
| Ollama | http://localhost:11434/v1 | Not needed | llama2, mistral, mixtral |
| LM Studio | http://localhost:1234/v1 | Not needed | (loaded model) |
| vLLM | http://localhost:8000/v1 | Optional | (deployed model) |
| Together AI | https://api.together.xyz/v1 | Required | meta-llama/Llama-2-70b |
| Groq | https://api.groq.com/openai/v1 | Required | llama2-70b-4096 |
OpenAI Provider Settings
When using the OpenAI provider, you can configure via the Settings panel:
- API Key - Required for OpenAI, Together AI, Groq; optional for local servers (Ollama, LM Studio)
- Model - Select from available models or enter custom model name
- System Prompt - Instructions for the model's behavior
- Temperature - Optional randomness control (0 = focused, 2 = creative)
- Max Tokens - Optional response length limit
Programmatic API Usage
Both providers implement the IChatApiProvider interface for consistent usage:
import { ADKApiService, OpenAIApiService } from 'adk-client-web-component';
// ADK Provider
const adkService = new ADKApiService('http://localhost:8000');
await adkService.createSession({
appName: 'my_agent',
userId: 'user_123',
sessionId: 'session_456'
});
// OpenAI Provider (with API key)
const openaiService = new OpenAIApiService(
'https://api.openai.com/v1',
'sk-your-api-key-here' // API key (optional for local servers)
);
// Ollama Provider (no API key needed)
const ollamaService = new OpenAIApiService(
'http://localhost:11434/v1'
);
// Send a message (same interface for both providers)
const response = await openaiService.sendMessage({
messages: [{ role: 'user', content: 'Hello!' }],
model: 'gpt-4',
systemPrompt: 'You are a helpful assistant.',
temperature: 0.7 // optional
});API Architecture Comparison
| Feature | ADK API | OpenAI API |
|---------|---------|------------|
| Session Management | Required (server-side) | Not needed (client-side history) |
| Authentication | Optional X-ADK-API-Key header | Authorization: Bearer <key> |
| Streaming | Server-Sent Events via /run_sse | Server-Sent Events via /chat/completions |
| Model Discovery | /list-apps | /models |
| Tool Use | Built-in agent tools | Not supported in this client |
🎤 Voice Input
The component includes built-in voice input using the Browser Speech Recognition API.
Features
- Real-time transcription - See your words appear as you speak
- Interim results - Visual feedback while processing speech
- Error handling - Clear messages for microphone issues
- Accessibility - Full keyboard and screen reader support
Browser Support
Voice input works in modern browsers that support the Web Speech API:
- ✅ Chrome (desktop & mobile)
- ✅ Edge
- ✅ Safari (macOS & iOS)
- ⚠️ Firefox (limited support)
Usage
- Click the microphone button (🎤) next to the send button
- Speak your message
- Click again to stop, or wait for automatic detection
- Edit the transcribed text if needed
- Press Enter to send
Disable voice input if needed:
<adk-client
api-url="http://localhost:8000"
app-name="my_agent"
enable-voice-input="false"
mode="widget">
</adk-client>🔌 ADK Server Requirements
The component requires a running ADK (Agent Development Kit) backend server when using the ADK provider.
Required Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| /apps/{app}/users/{user}/sessions/{session} | POST | Create/get conversation session |
| /run | POST | Send message (standard mode) |
| /run_sse | POST | Send message (streaming mode, SSE) |
| /list-apps | GET | List available agent apps |
CORS Configuration
Your ADK server must enable CORS for your frontend origin.
Development:
# Allow all origins (development only!)
adk api_server --allow_origins="*"Production:
# Specify explicit origins
adk api_server --allow_origins="https://yourdomain.com,https://www.yourdomain.com"Streaming Support
The /run_sse endpoint must:
- Support Server-Sent Events (SSE)
- Flush tokens as they're generated
- Send events in the format:
data: {"token": "..."}\n\n
Quick Start ADK Server
# Install ADK
pip install google-adk
# Start server with permissive CORS for development
adk api_server --allow_origins="*"The server will start on http://localhost:8000 by default.
Troubleshooting
Common Issues
Connection Failed: Check that your ADK server is running on the configured URL. CORS Errors: Ensure your ADK server allows requests from your domain. Build Errors: Verify all environment variables are properly set.
Debug Mode
Set NODE_ENV=development to enable additional error information and logging.
📦 Demo Folder
The demo/ folder contains 4 complete, standalone integration examples:
- Method 1: Local Installation - Using npm with local node_modules
- Method 2: CDN Usage - Zero installation, load from unpkg.com
- Method 3: React Integration - Full React + TypeScript + Vite setup
- Method 4: Programmatic - Dynamic component creation with JavaScript
Each demo is self-contained and can be copied/used independently. See demo/README.md for detailed instructions.
Running Demos
# Build the main project first
npm run build
# Run individual demos
cd demo
npm run serve:method1 # Local installation
npm run serve:method2 # CDN
npm run dev:method3 # React (with hot reload)
npm run serve:method4 # Programmatic
# Or setup all at once
npm run setup:all🤝 Contributing
Contributions are welcome! Here's how:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Test your changes (run demos, check types)
- Commit (
git commit -m 'Add amazing feature') - Push (
git push origin feature/amazing-feature) - Open a Pull Request
Development Guidelines
- Follow existing code style
- Add TypeScript types for new features
- Test changes with all integration methods (demos)
- Update documentation as needed
- Keep Shadow DOM and embedded styles working
📄 License
MIT License - see LICENSE file for details.
🙏 Acknowledgments
Built with:
- React - UI library
- Vite - Build tool
- Tailwind CSS - Styling
- Zustand - State management
- React Query - Data fetching
- Framer Motion - Animations
- Lucide - Icons
💬 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: Check package.json for maintainer contact
Made with ❤️ and good vibes
