Web UI Launcher

Purpose

The Web UI Launcher subtopic addresses the need for an interactive, user-friendly web interface within the broader scope of the REST API and web launchers framework. While the parent topic focuses on implementing REST API servers and HTTP handlers for agent interactions, the Web UI Launcher specifically provides an embedded Angular-based frontend launcher that serves static assets and configuration via HTTP. This enables users to interact with the Agent Development Kit (ADK) through a rich graphical interface rather than solely via REST endpoints or CLI commands.

This subtopic ensures that the web UI is seamlessly integrated and served alongside the REST API, simplifying deployment by embedding static resources directly into the executable. It also dynamically supplies runtime configuration (such as backend API URLs) to the UI, enabling flexible backend connectivity without manual configuration file management.

Functionality

The Web UI Launcher handles the following key workflows and responsibilities:

• Embedding and Serving Static Web Assets:
  The Angular-based web UI distribution files are embedded into the executable binary using Go's embed package. This eliminates the need for separate web server configuration or static file hosting setups. The launcher serves these assets over HTTP under a configurable path prefix (default /ui/).

• Dynamic Runtime Configuration Endpoint:
  To decouple build-time settings from runtime environment details, the launcher provides a special HTTP endpoint /ui/assets/config/runtime-config.json that returns JSON configuration data. This includes the backend REST API server address as seen from the browser, allowing the UI to interact correctly with the backend regardless of deployment specifics.

• HTTP Routing and Subrouter Setup:
  The launcher integrates with the main HTTP router (using gorilla/mux) by creating a subrouter mounted at the configured path prefix. It handles:

  • Redirecting root / requests to the UI path prefix.

  • Serving embedded static files for all UI resources.

  • Serving the dynamic runtime configuration JSON.

• Command-Line Interface for Configuration:
  The launcher exposes CLI flags to customize parameters such as the backend API server address. This enables flexible launching scenarios and integration with other sublaunchers within the web server launcher framework.

• User Messaging for Launcher Info:
  Upon launching, it prints out a user-friendly message with the URL where the UI can be accessed, aiding discoverability.

Example Interaction Flow

When a user accesses the web UI URL:

1. The HTTP request hits the subrouter configured at /ui/.

2. Requests for static files (HTML, JS, CSS) are served from the embedded Angular build assets.

3. The UI app fetches /ui/assets/config/runtime-config.json to obtain runtime configuration, primarily the backend API server address.

4. The UI uses this backend address to communicate with the ADK REST API for agent interactions.

5. Any requests to the root / path are redirected to /ui/ for UI access.

This workflow ensures the UI is self-contained, configurable at runtime, and tightly integrated with the backend services.

Integration

The Web UI Launcher integrates tightly with the parent topic [REST API and Web Launchers](80564) by acting as a sublauncher within the overall web server launcher. It complements other sublaunchers such as REST API controllers and A2A protocol sublaunchers by providing a visual interface for users to interact with the agents managed by the REST API.

• It depends on the HTTP routing infrastructure defined in the Router Setup subtopic to register its routes and subrouter.

• It serves static assets embedded at build time under cmd/launcher/web/webui/distr/, which is unique to this subtopic and not covered by other launchers.

• The dynamic runtime-config JSON endpoint integrates with the REST API server address, which may be provided or proxied by the Web Server Launcher or configured through CLI arguments.

• User messages and command-line parsing align with the launcher framework's conventions for sublaunchers, enabling consistent configuration and user experience.

Code Illustration

Key functions illustrating the core behavior:

• Embedding and Serving Web UI Files:

//go:embed distr/*
var content embed.FS

func (w *webUILauncher) AddSubrouter(router *mux.Router, pathPrefix, backendAddress string) {
	rUI := router.Methods("GET").PathPrefix(pathPrefix).Subrouter()

	// Dynamic runtime config endpoint
	rUI.Methods("GET").Path("/assets/config/runtime-config.json").HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		config := struct{ BackendUrl string }{BackendUrl: backendAddress}
		controllers.EncodeJSONResponse(config, http.StatusOK, w)
	})

	// Redirect root to UI path
	router.Methods("GET").Path("/").HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		http.Redirect(w, r, pathPrefix, http.StatusFound)
	})

	// Serve embedded UI files
	ui, err := fs.Sub(content, "distr")
	if err != nil {
		log.Fatalf("cannot prepare ADK Web UI files: %v", err)
	}
	rUI.Methods("GET").Handler(http.StripPrefix(pathPrefix, http.FileServer(http.FS(ui))))
}

• Launcher Creation and CLI Parsing:

func NewLauncher() weblauncher.Sublauncher {
	config := &webUIConfig{}
	fs := flag.NewFlagSet("webui", flag.ContinueOnError)
	fs.StringVar(&config.backendAddress, "api_server_address", "http://localhost:8080/api", "ADK REST API server address as seen from the user browser.")
	config.pathPrefix = "/ui/"

	return &webUILauncher{
		config: config,
		flags:  fs,
	}
}

This code shows the encapsulation of configuration, embedding of assets, HTTP route setup, and integration with CLI flags.

Diagram

flowchart TD
User[User Browser] -->|HTTP GET / or /ui/| Router[HTTP Router]
Router -->|Redirect / to /ui/| Redirect[Redirect Handler]
Router -->|Serve /ui/assets/config/runtime-config.json| ConfigEndpoint[Runtime Config Endpoint]
Router -->|Serve static assets| StaticServer[Embedded UI File Server]
ConfigEndpoint --> UIApp[Angular UI]
StaticServer --> UIApp
UIApp -->|REST API calls| BackendAPI[ADK REST API Server]

This flowchart visualizes the HTTP request routing for the Web UI Launcher, showing how user requests are routed, redirected, served with static assets, and configured dynamically to interact with the backend API.