feat: allow disabling the ADK Development UI with adk.web.ui.enabled

Set adk.web.ui.enabled to false, as a system property or in the application config, to leave the Development UI routes unmounted. It stays mounted by default.

PiperOrigin-RevId: 968449879

Author: sherryfox

webserver/src/jvmMain/kotlin/com/google/adk/kt/webserver/AdkWebServer.kt

@@ -30,6 +30,7 @@ import com.google.adk.kt.webserver.loaders.AgentLoader
 import com.google.adk.kt.webserver.models.VersionInfo
 import com.google.adk.kt.webserver.routes.appRoutes
 import com.google.adk.kt.webserver.routes.artifactRoutes
+import com.google.adk.kt.webserver.routes.isWebUiEnabled
 import com.google.adk.kt.webserver.routes.runRoutes
 import com.google.adk.kt.webserver.routes.sessionRoutes
 import com.google.adk.kt.webserver.routes.staticRoutes
@@ -57,9 +58,13 @@ import org.slf4j.event.Level
  * Embedded Ktor server exposing the ADK dev/web API.
  *
  * [start] and [stop] are safe to call from different threads; a [stop] arriving while [start] is
- * still binding aborts it. A failed [start] leaves the engine recorded, so call [stop] before
+ * still binding aborts it, and a failed [start] leaves the engine recorded, so call [stop] before
  * retrying.
  *
+ * Set `adk.web.ui.enabled` to `false`, as a system property or in the application config, to leave
+ * the Development UI unmounted; only `true` and `false` count, and any other value is ignored with
+ * a warning.
+ *
  * @property captureMessageContent When true, the server records prompt/response content into
  *   telemetry spans so the Dev UI trace view can display it. This may capture PII and increase span
  *   size, so it defaults to false; enable it only for local development.
@@ -183,6 +188,8 @@ fun Application.adkModule(
     graphRoutes(agentLoader, sessionService)
     runRoutes(agentLoader, sessionService, artifactService, plugins)
     sessionRoutes(sessionService)
-    staticRoutes(this@adkModule)
+    if (this@adkModule.isWebUiEnabled(default = true)) {
+      staticRoutes(this@adkModule)
+    }
   }
 }

webserver/src/jvmMain/kotlin/com/google/adk/kt/webserver/routes/StaticRoutes.kt

@@ -32,6 +32,29 @@ import org.slf4j.LoggerFactory
 
 private val logger = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass())
 
+/** Property that decides whether the Development UI is served at all. */
+internal const val WEB_UI_ENABLED_PROPERTY = "adk.web.ui.enabled"
+
+/**
+ * Whether to mount the Development UI, from the `adk.web.ui.enabled` system property, else the
+ * application config, else [default]. A value that is blank or not a boolean counts as unset, so a
+ * mistyped system property cannot mask a setting in the config.
+ */
+internal fun Application.isWebUiEnabled(default: Boolean): Boolean =
+  webUiSetting(System.getProperty(WEB_UI_ENABLED_PROPERTY))
+    ?: webUiSetting(environment.config.propertyOrNull(WEB_UI_ENABLED_PROPERTY)?.getString())
+    ?: default
+
+/** Parses one configured value, returning null when it is absent, blank or not a boolean. */
+private fun webUiSetting(raw: String?): Boolean? {
+  val value = raw?.trim()?.ifEmpty { null } ?: return null
+  val parsed = value.lowercase().toBooleanStrictOrNull()
+  if (parsed == null) {
+    logger.warn("Ignoring a non-boolean value of {}: {}", WEB_UI_ENABLED_PROPERTY, value)
+  }
+  return parsed
+}
+
 fun Route.staticRoutes(application: Application) {
   var webUiDir =
     System.getProperty("adk.web.ui.dir")

webserver/src/jvmTest/kotlin/com/google/adk/kt/webserver/WebUiToggleTest.kt

@@ -0,0 +1,185 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.kt.webserver
+
+import com.google.adk.kt.webserver.routes.WEB_UI_ENABLED_PROPERTY
+import com.google.adk.kt.webserver.routes.isWebUiEnabled
+import com.google.adk.kt.webserver.telemetry.ApiServerSpanExporter
+import com.google.common.truth.Truth.assertThat
+import io.ktor.client.request.get
+import io.ktor.http.HttpStatusCode
+import io.ktor.server.config.MapApplicationConfig
+import io.ktor.server.testing.ApplicationTestBuilder
+import io.ktor.server.testing.testApplication
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.junit.runners.JUnit4
+
+/**
+ * The `adk.web.ui.enabled` property decides whether the Development UI routes are mounted.
+ *
+ * `/` is the discriminator: `staticRoutes` registers its redirect only when the UI is mounted.
+ */
+@RunWith(JUnit4::class)
+class WebUiToggleTest {
+  private val sessionService = FakeSessionService()
+  private val artifactService = FakeArtifactService()
+  private val agentLoader = FakeAgentLoader()
+
+  @Test
+  fun webUi_unset_isMounted() =
+    withWebUiProperty(null) {
+      testApplication {
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.Found)
+        assertThat(client.get(DEV_UI_INDEX).status).isEqualTo(HttpStatusCode.OK)
+      }
+    }
+
+  @Test
+  fun webUi_disabled_isNotMounted() =
+    withWebUiProperty("false") {
+      testApplication {
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.NotFound)
+        assertThat(client.get(DEV_UI_INDEX).status).isEqualTo(HttpStatusCode.NotFound)
+        // The contract endpoints are untouched by the toggle.
+        assertThat(client.get("/health").status).isEqualTo(HttpStatusCode.OK)
+      }
+    }
+
+  @Test
+  fun webUi_disabledInMixedCase_isNotMounted() =
+    withWebUiProperty("FALSE") {
+      testApplication {
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.NotFound)
+      }
+    }
+
+  @Test
+  fun webUi_nonBooleanValue_fallsBackToDefault() =
+    withWebUiProperty("perhaps") {
+      testApplication {
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.Found)
+      }
+    }
+
+  @Test
+  fun webUi_disabledInConfig_isNotMounted() =
+    withWebUiProperty(null) {
+      testApplication {
+        environment { config = MapApplicationConfig(WEB_UI_ENABLED_PROPERTY to "false") }
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.NotFound)
+      }
+    }
+
+  @Test
+  fun webUi_nonBooleanConfigValue_fallsBackToDefault() =
+    withWebUiProperty(null) {
+      testApplication {
+        environment { config = MapApplicationConfig(WEB_UI_ENABLED_PROPERTY to "perhaps") }
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.Found)
+      }
+    }
+
+  @Test
+  fun webUi_blankProperty_fallsThroughToConfig() =
+    withWebUiProperty(" ") {
+      testApplication {
+        environment { config = MapApplicationConfig(WEB_UI_ENABLED_PROPERTY to "false") }
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.NotFound)
+      }
+    }
+
+  @Test
+  fun webUi_nonBooleanProperty_fallsThroughToConfig() =
+    withWebUiProperty("no") {
+      testApplication {
+        environment { config = MapApplicationConfig(WEB_UI_ENABLED_PROPERTY to "false") }
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.NotFound)
+      }
+    }
+
+  @Test
+  fun webUi_property_winsOverConfig() =
+    withWebUiProperty("true") {
+      testApplication {
+        environment { config = MapApplicationConfig(WEB_UI_ENABLED_PROPERTY to "false") }
+        installAdk()
+
+        assertThat(rootStatus()).isEqualTo(HttpStatusCode.Found)
+      }
+    }
+
+  @Test
+  fun webUi_unsetEverywhere_usesCallerDefault() =
+    withWebUiProperty(null) {
+      testApplication {
+        application {
+          assertThat(isWebUiEnabled(default = false)).isFalse()
+          assertThat(isWebUiEnabled(default = true)).isTrue()
+        }
+        // testApplication builds the Application lazily, so force it.
+        client.get("/")
+      }
+    }
+
+  private fun ApplicationTestBuilder.installAdk() {
+    application { adkModule(sessionService, artifactService, agentLoader, ApiServerSpanExporter()) }
+  }
+
+  /** Status of `/` without following the redirect, so the redirect itself is what is asserted. */
+  private suspend fun ApplicationTestBuilder.rootStatus(): HttpStatusCode =
+    createClient { followRedirects = false }.get("/").status
+
+  /** Runs [body] with `adk.web.ui.enabled` set to [value], or unset when it is null. */
+  private fun withWebUiProperty(value: String?, body: () -> Unit) {
+    val previous: String? = System.getProperty(WEB_UI_ENABLED_PROPERTY)
+    if (value == null) {
+      System.clearProperty(WEB_UI_ENABLED_PROPERTY)
+    } else {
+      System.setProperty(WEB_UI_ENABLED_PROPERTY, value)
+    }
+    try {
+      body()
+    } finally {
+      if (previous == null) {
+        System.clearProperty(WEB_UI_ENABLED_PROPERTY)
+      } else {
+        System.setProperty(WEB_UI_ENABLED_PROPERTY, previous)
+      }
+    }
+  }
+
+  private companion object {
+    const val DEV_UI_INDEX = "/dev-ui/index.html"
+  }
+}