Web Interface Guide

The DevOps Agent web interface provides a modern, browser-based way to interact with your agents. This guide covers everything from basic setup to advanced configuration and troubleshooting.

🌐 Overview

The web interface offers:

Modern UI: Responsive design accessible from any browser
Session Persistence: Conversations survive server restarts
Automatic Recovery: Graceful handling of interrupted sessions
Real-time Streaming: Live responses via Server-Sent Events
Artifact Management: Upload, download, and manage files
CORS Support: Cross-origin integration capabilities

🚀 Quick Start

Zero-Setup Web Interface (Recommended)

# No local setup required - uses packaged agents
adk web-packaged --session_db_url "sqlite:///sessions.db"

# Access in browser
open http://localhost:8000

Local Agents Setup

# Start the web interface with local agents
adk web agents/

# Access in browser
open http://localhost:8000

Recommended Setup (Persistent Sessions)

# Use SQLite for session persistence
adk web-packaged --session_db_url "sqlite:///sessions.db"

# Access in browser
open http://localhost:8000

📋 Command Reference

Available Commands

Zero-Setup Command (Recommended)

adk web-packaged [OPTIONS]

Local Agents Command

adk web AGENTS_DIR [OPTIONS]

Common Examples

# Zero-setup with persistent sessions (recommended)
adk web-packaged --session_db_url "sqlite:///sessions.db"

# Local agents with persistent sessions
adk web agents/ --session_db_url "sqlite:///sessions.db"

# Custom port and host (zero-setup)
adk web-packaged --host 0.0.0.0 --port 8080 --session_db_url "sqlite:///sessions.db"

# Production configuration (zero-setup)
adk web-packaged \
  --host 0.0.0.0 \
  --port 8080 \
  --session_db_url "postgresql://user:pass@host:port/db" \
  --artifact_storage_uri "gs://my-bucket" \
  --allow_origins "https://mydomain.com" \
  --trace_to_cloud

# Suppress auto-reload message
adk web-packaged --no-reload --session_db_url "sqlite:///sessions.db"

🔄 Command Comparison

`web-packaged` vs `web`

Feature	`web-packaged`	`web`
Setup Required	None	Local agents directory
Agents Source	Bundled with package	Local filesystem
Use Case	Quick demos, instant start	Development, custom agents
Installation	Works with `uvx` immediately	Requires local agent files
Customization	Limited to packaged agents	Full customization

When to Use Each

Use web-packaged when:

✅ Quick demos or testing
✅ Installing via uvx from git
✅ No local setup desired
✅ Using standard DevOps agent

Use web when:

✅ Developing custom agents
✅ Need to modify agent behavior
✅ Working with local agent files
✅ Building custom workflows

⚙️ Configuration Options

Core Options

Option	Description	Default	Example
`--host`	Binding host	`127.0.0.1`	`--host 0.0.0.0`
`--port`	Server port	`8000`	`--port 8080`
`--reload/--no-reload`	Auto-reload	`True`	`--no-reload`

Session Management

Option	Description	Use Case
No option	In-memory sessions	Quick testing, sessions lost on restart
`--session_db_url "sqlite:///sessions.db"`	SQLite database	Development, local persistence
`--session_db_url "postgresql://..."`	PostgreSQL	Production, shared database
`--session_db_url "agentengine://resource_id"`	Google Cloud	Managed cloud sessions

Advanced Options

Option	Description	Example
`--artifact_storage_uri`	Artifact storage location	`gs://my-bucket`
`--allow_origins`	CORS allowed origins	`https://mydomain.com`
`--trace_to_cloud`	Enable cloud tracing	Flag only
`--log_level`	Logging verbosity	`DEBUG`, `INFO`, `WARNING`

🗄️ Session Management

Session Storage Types

1. In-Memory Sessions (Default)

adk web agents/

Characteristics:

✅ Fast startup
✅ No setup required
❌ Sessions lost on restart
❌ Not suitable for production

Use Cases:

Quick testing
Development experiments
Temporary interactions

2. SQLite Sessions (Recommended for Development)

adk web agents/ --session_db_url "sqlite:///sessions.db"

Characteristics:

✅ Persistent across restarts
✅ Single file storage
✅ No external dependencies
✅ Automatic database creation
❌ Single-user only

Use Cases:

Local development
Personal projects
Persistent testing

3. PostgreSQL Sessions (Production)

adk web agents/ --session_db_url "postgresql://user:password@host:5432/dbname"

Characteristics:

✅ Multi-user support
✅ High availability
✅ Backup and recovery
✅ Scalable
❌ Requires database setup

Use Cases:

Production deployments
Team environments
Enterprise usage

4. Agent Engine Sessions (Google Cloud)

adk web agents/ --session_db_url "agentengine://your-resource-id"

Characteristics:

✅ Fully managed
✅ Google Cloud integration
✅ Automatic scaling
✅ Built-in monitoring
❌ Requires Google Cloud setup

Use Cases:

Google Cloud environments
Managed deployments
Enterprise Google Cloud usage

🌍 Network Configuration

Local Development

# Default - localhost only
adk web agents/ --session_db_url "sqlite:///sessions.db"
# Access: http://localhost:8000

Network Access

# Allow network access
adk web agents/ --host 0.0.0.0 --port 8080 --session_db_url "sqlite:///sessions.db"
# Access: http://your-ip:8080

CORS Configuration

# Single origin
adk web agents/ --allow_origins "https://mydomain.com"

# Multiple origins
adk web agents/ \
  --allow_origins "https://mydomain.com" \
  --allow_origins "https://app.mydomain.com" \
  --allow_origins "http://localhost:3000"

🔧 Troubleshooting

Common Issues

Session Not Found Errors

Problem: Browser shows “Session not found” errors after server restart.

Solution:

# Use persistent sessions
adk web agents/ --session_db_url "sqlite:///sessions.db"

Explanation: In-memory sessions are lost when the server restarts. The web interface now includes automatic session recovery, but persistent storage is recommended.

Port Already in Use

Problem: Address already in use error.

Solutions:

# Use different port
adk web agents/ --port 8080

# Find and kill existing process
lsof -ti:8000 | xargs kill -9

# Check what's using the port
lsof -i :8000

Static Files Not Loading

Problem: Web interface shows blank page or missing styles.

Solutions:

Restart the server - Files are served automatically
Check browser console for error messages
Clear browser cache and refresh
Verify server logs for any errors

CORS Errors

Problem: Cross-origin requests blocked.

Solution:

# Add your domain to allowed origins
adk web agents/ --allow_origins "https://yourdomain.com"

# For development with multiple origins
adk web agents/ \
  --allow_origins "http://localhost:3000" \
  --allow_origins "https://yourdomain.com"

Auto-reload Warnings

Problem: Seeing “Reload mode is not supported” message.

Solution:

# Suppress the message (normal behavior)
adk web agents/ --no-reload --session_db_url "sqlite:///sessions.db"

Explanation: This is expected behavior. The web interface works correctly without reload mode.

Database Issues

SQLite Permission Errors

# Check directory permissions
ls -la $(dirname sessions.db)

# Ensure write permissions
chmod 755 $(dirname sessions.db)

# Use absolute path
adk web agents/ --session_db_url "sqlite:///$(pwd)/sessions.db"

PostgreSQL Connection Issues

# Test connection
psql "postgresql://user:password@host:5432/dbname" -c "SELECT 1;"

# Check network connectivity
telnet host 5432

# Verify credentials and database exists

Performance Issues

Slow Response Times

Check system resources (CPU, memory)
Monitor database performance for persistent sessions

Enable tracing for detailed analysis:

adk web agents/ --trace_to_cloud --log_level DEBUG

Memory Usage

Use persistent sessions to reduce memory overhead
Monitor session count in production
Implement session cleanup for long-running deployments

🚀 Production Deployment

Basic Production Setup

adk web agents/ \
  --host 0.0.0.0 \
  --port 8000 \
  --session_db_url "postgresql://user:pass@db:5432/sessions" \
  --artifact_storage_uri "gs://production-artifacts" \
  --allow_origins "https://yourapp.com" \
  --trace_to_cloud \
  --no-reload

Docker Deployment

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install google-adk
EXPOSE 8000
CMD ["adk", "web", "agents/", "--host", "0.0.0.0", "--session_db_url", "postgresql://..."]

Environment Variables

# Set in production environment
export GOOGLE_API_KEY=your_api_key
export GOOGLE_CLOUD_PROJECT=your_project
export DATABASE_URL=postgresql://...
export ARTIFACT_STORAGE_URI=gs://...

# Use in command
adk web agents/ \
  --session_db_url "$DATABASE_URL" \
  --artifact_storage_uri "$ARTIFACT_STORAGE_URI"

Health Checks

# Basic health check
curl http://localhost:8000/list-apps

# Detailed health check with session creation
curl -X POST http://localhost:8000/apps/devops/users/health/sessions \
  -H "Content-Type: application/json" \
  -d '{}'

🔍 Monitoring and Debugging

Enable Debug Logging

adk web agents/ \
  --log_level DEBUG \
  --trace_to_cloud \
  --session_db_url "sqlite:///sessions.db"

Log Analysis

Key log messages to monitor:

Session {id} not found, creating new session - Automatic recovery
INFO: Reload mode is not supported - Expected behavior
Started server process - Successful startup
Database connection messages - Session storage health

Performance Monitoring

Response times for /run and /run_sse endpoints
Session creation/retrieval times
Database query performance
Memory usage trends

📚 API Reference

The web interface exposes these key endpoints:

Session Management

GET /apps/{app}/users/{user}/sessions - List sessions
POST /apps/{app}/users/{user}/sessions - Create session
GET /apps/{app}/users/{user}/sessions/{id} - Get session

Agent Interaction

POST /run - Execute agent (non-streaming)
POST /run_sse - Execute agent (streaming)

Utility

GET /list-apps - List available agents
GET / - Redirect to web UI
GET /dev-ui/ - Web interface

🎯 Best Practices

Development

Use persistent sessions: --session_db_url "sqlite:///sessions.db"
Enable debug logging: --log_level DEBUG
Use custom ports: Avoid conflicts with other services
Regular database cleanup: Monitor SQLite file size

Production

Use PostgreSQL: For multi-user environments
Configure CORS: Restrict to known domains
Enable tracing: For monitoring and debugging
Use environment variables: For sensitive configuration
Implement health checks: Monitor service availability
Regular backups: For session databases

Security

Restrict host binding: Use 127.0.0.1 for local-only access
Configure CORS carefully: Only allow necessary origins
Use HTTPS: In production environments
Secure database connections: Use encrypted connections
Monitor access logs: Track usage patterns

The web interface provides a powerful, modern way to interact with your DevOps agents. With proper session management and configuration, it offers a reliable, scalable solution for both development and production use cases.

Web Interface Guide

🌐 Overview

🚀 Quick Start

Zero-Setup Web Interface (Recommended)

Local Agents Setup

Recommended Setup (Persistent Sessions)

📋 Command Reference

Available Commands

Zero-Setup Command (Recommended)

Local Agents Command

Common Examples

🔄 Command Comparison

web-packaged vs web

When to Use Each

⚙️ Configuration Options

Core Options

Session Management

Advanced Options

🗄️ Session Management

Session Storage Types

1. In-Memory Sessions (Default)

2. SQLite Sessions (Recommended for Development)

3. PostgreSQL Sessions (Production)

4. Agent Engine Sessions (Google Cloud)

🌍 Network Configuration

Local Development

Network Access

CORS Configuration

🔧 Troubleshooting

Common Issues

Session Not Found Errors

Port Already in Use

Static Files Not Loading

CORS Errors

Auto-reload Warnings

Database Issues

SQLite Permission Errors

PostgreSQL Connection Issues

Performance Issues

Slow Response Times

Memory Usage

🚀 Production Deployment

Basic Production Setup

Docker Deployment

Environment Variables

Health Checks

🔍 Monitoring and Debugging

Enable Debug Logging

Log Analysis

Performance Monitoring

📚 API Reference

Session Management

Agent Interaction

Utility

🎯 Best Practices

Development

Production

Security

`web-packaged` vs `web`