webui.go

Overview

The webui.go file implements a Web UI Launcher as a sublauncher component that integrates an embedded Angular-based web user interface (UI) into the ADK web server. It serves the UI assets statically from within the executable binary at a configurable HTTP path prefix (default /ui/) and dynamically generates runtime configuration data (such as the backend REST API URL) for the UI to consume.

This launcher enables users to interact visually with the ADK REST API backend through a browser without requiring a separately deployed frontend server. It integrates seamlessly with the main HTTP router and the launcher framework, handling command-line flags, HTTP routing, static asset delivery, and user messages.

The file belongs to the broader REST API and Web Launchers system that exposes AI agents via HTTP interfaces, complementing REST API endpoints and other sublaunchers such as A2A.

Key Types

webUIConfig

type webUIConfig struct {
	backendAddress string
	pathPrefix     string
}

• Purpose: Holds configurable parameters for the Web UI launcher.

• Fields:

  • backendAddress (string): The full URL of the ADK REST API server as accessible from the web browser.

  • pathPrefix (string): The HTTP path prefix where the Web UI is served, e.g., /ui/.

webUILauncher

type webUILauncher struct {
	flags  *flag.FlagSet
	config *webUIConfig
}

• Purpose: Implements the weblauncher.Sublauncher interface to launch and serve the ADK Web UI.

• Fields:

  • flags: Command-line flag set to parse Web UI specific flags.

  • config: Configuration parameters encapsulated in webUIConfig.

Functions and Methods

NewLauncher() weblauncher.Sublauncher

• Description: Constructs and returns a new instance of webUILauncher initialized with default configuration and CLI flags.

• Details:

  • Creates a flag.FlagSet named "webui" to parse flags.

  • Defines the api_server_address flag for specifying the backend REST API URL, defaulting to "http://localhost:8080/api".

  • Sets the default pathPrefix to "/ui/".

• Returns: A weblauncher.Sublauncher interface implemented by the newly created webUILauncher.

• Usage:

launcher := NewLauncher()

(w *webUILauncher) CommandLineSyntax() string

• Implements: weblauncher.Sublauncher

• Description: Returns a formatted string describing the command-line syntax and available flags for the Web UI launcher.

• Uses the utility method util.FormatFlagUsage to generate the usage text.

• Returns: A string suitable for display in help messages.

(w *webUILauncher) Keyword() string

• Implements: weblauncher.Sublauncher

• Description: Returns the command keyword "webui" used to identify this sublauncher in the command-line interface.

• Returns: "webui"

(w *webUILauncher) Parse(args []string) ([]string, error)

• Implements: weblauncher.Sublauncher

• Description: Parses command-line arguments relevant to the Web UI launcher.

• Parameters:

  • args []string: Arguments slice to parse.

• Returns:

  • Remaining unparsed arguments ([]string).

  • Error if parsing fails.

• Details: Uses the internal flag.FlagSet to parse flags and returns the leftover arguments.

(w *webUILauncher) SetupSubrouters(router *mux.Router, config *launcher.Config) error

• Implements: weblauncher.Sublauncher

• Description: Adds the Web UI subrouter to the provided main HTTP router.

• Parameters:

  • router *mux.Router: The main HTTP router to augment.

  • config *launcher.Config: Launcher configuration (not used directly here).

• Returns: error (always nil in this implementation).

• Details: Calls AddSubrouter with configured path prefix and backend address to mount the Web UI routes.

(w *webUILauncher) AddSubrouter(router *mux.Router, pathPrefix, backendAddress string)

• Description: Adds a subrouter to serve the embedded ADK Web UI and related endpoints.

• Parameters:

  • router *mux.Router: The parent HTTP router.

  • pathPrefix string: URL path prefix where the UI is served (e.g., /ui/).

  • backendAddress string: Backend REST API server URL to be embedded in runtime config.

• Functionality:

  • Creates a subrouter for HTTP GET requests under pathPrefix.

  • Defines a dynamic endpoint /assets/config/runtime-config.json that returns JSON with the backendUrl field.

  • Registers a redirect handler from / to the pathPrefix.

  • Serves static UI files embedded in the binary from the distr directory via Go's embed filesystem.

• Error Handling: If embedded UI files cannot be loaded, logs a fatal error terminating the program.

• Usage Example:

w.AddSubrouter(router, "/ui/", "http://localhost:8080/api")

(w *webUILauncher) SimpleDescription() string

• Implements: weblauncher.Sublauncher

• Description: Returns a brief description of the Web UI launcher.

• Returns: "starts ADK Web UI server which provides UI for interacting with ADK REST API"

(w *webUILauncher) UserMessage(webURL string, printer func(v ...any))

• Implements: weblauncher.Sublauncher

• Description: Prints a user-friendly message indicating the URL where the Web UI can be accessed.

• Parameters:

  • webURL string: Base URL of the web server.

  • printer func(v ...any): Function to output messages (e.g., fmt.Println).

• Example Output:

webui:  you can access API using http://localhost:8080/ui/

Embedded Static Assets

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

• The distr/ directory contains the compiled Angular Web UI distribution files.

• These files are embedded at build time into the executable binary using Go 1.16+ embed package.

• The embedded filesystem content is used to serve static assets over HTTP.

Important Implementation Details

• Dynamic Runtime Configuration Endpoint:
  The launcher provides /ui/assets/config/runtime-config.json that returns JSON with the backend REST API URL. This allows the UI to be fully functional without hardcoded backend paths, supporting flexible deployment environments.

• HTTP Redirect:
  Requests to / (root) are redirected (HTTP 302) to the UI path prefix, ensuring users accessing the base URL are directed to the UI.

• Static File Serving:
  Uses http.FileServer wrapped with http.StripPrefix to serve the embedded UI files without exposing the full internal path structure.

• Command-Line Integration:
  The Web UI launcher supports CLI flags independently from other sublaunchers, allowing configuration of backend API address and enabling composition with other launchers.

• Use of gorilla/mux Router:
  The launcher adds its routes as a subrouter under the main router, enabling clean modular HTTP route management and coexistence with other handlers such as REST API.

Interaction with Other System Components

• Web Server Launcher:
  The webUILauncher is designed to be plugged into the broader web server launcher framework (Web Server Launcher), which manages sublaunchers, HTTP server lifecycle, and command-line parsing.

• REST API Backend:
  The UI interacts primarily with the ADK REST API server, whose address is provided via CLI flag and exposed to the frontend through the dynamic runtime-config JSON endpoint.

• HTTP Routing Infrastructure:
  Integrates with the common HTTP routing setup using gorilla/mux (Router Setup), sharing the router instance.

• REST API and Web Launchers Topic:
  As a component of the web launchers system, it complements API launchers and A2A launchers by providing a graphical frontend (REST API and Web Launchers, Web UI Launcher).

• Embedded Assets:
  The static UI files are embedded at build time, allowing deployment of a single binary without external dependencies for the UI.

Usage Example

A typical usage scenario:

1. Create a Web UI launcher instance:

launcher := webui.NewLauncher()

2. Parse command-line arguments (e.g., -api_server_address).

3. Setup HTTP server and add subrouters:

router := mux.NewRouter()
launcher.SetupSubrouters(router, nil)

4. Start HTTP server serving the router.

5. User accesses http://<host>:<port>/ui/ in a browser.

6. The UI loads static assets from embedded files and obtains runtime configuration from /ui/assets/config/runtime-config.json.

7. UI communicates with the backend API at the specified api_server_address.

Visual Diagram: Web UI Launcher HTTP Routing Flow

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

• Explanation:

  • User requests to / are redirected to /ui/.

  • Requests to /ui/assets/config/runtime-config.json provide the UI with backend API URL.

  • Static assets are served from embedded filesystem under /ui/.

  • The Angular UI loaded in the browser uses the backend API address to make REST calls.

References

• REST API and Web Launchers

• Web UI Launcher

• Web Server Launcher

• Router Setup

• gorilla/mux HTTP routing package

• Go embed package for embedding static files