Move Visual Builder page under Runtime > Web Interface page (ADK Web) (#1759)

* Move adk web Visual Builder page content into Runtime > adk web page

* Clarify Visual Builder in intro

* Fix casing for consistency

* More casing fixes

* Move Visual Builder page under Web Interface

* Fix link from runtime index page

* Keep Visual Builder file at original path, nest under Web Interface in nav

---------

Co-authored-by: Joe Fernandez <joefernandez@users.noreply.github.com>

Author: koverholt

docs/runtime/index.md

@@ -18,7 +18,7 @@ the method that best fits your development workflow.
     Use `adk web` to launch a browser-based interface for interacting with your
     agents.
 
-    [:octicons-arrow-right-24: Use the Web Interface](web-interface.md)
+    [:octicons-arrow-right-24: Use the Web Interface](web-interface/index.md)
 
 -   :material-console:{ .lg .middle } **Command Line**
 

docs/runtime/web-interface.md docs/runtime/web-interface/index.mddocs/runtime/web-interface.md renamed to docs/runtime/web-interface/index.md

@@ -7,16 +7,27 @@
 The ADK web interface lets you test your agents directly in the browser. This
 tool provides a simple way to interactively develop and debug your agents.
 
-![ADK Web Interface](../assets/adk-web-dev-ui-chat.png)
+![ADK Web Interface](../../assets/adk-web-dev-ui-chat.png)
 
 !!! warning "Caution: ADK Web for development only"
 
-    ADK Web is ***not meant for use in production deployments***. You should
-    use ADK Web for development and debugging purposes only.
+    ADK Web is ***not meant for use in production deployments***. You should use
+    ADK Web for development and debugging purposes only.
+
+Key features of the ADK web interface include:
+
+- **Chat interface**: Send messages to your agents and view responses in
+  real-time
+- **Session management**: Create and switch between sessions
+- **State inspection**: View and modify session state during development
+- **Event history**: Inspect all events generated during agent execution
+- **Visual Builder**: Design agents visually with a drag-and-drop workflow
+  editor and an AI-powered assistant (Python only, [learn
+  more](/visual-builder/))
 
 ## Start the web interface
 
-Use the following command to run your agent in the ADK web interface:
+Use the following command to start the ADK web interface:
 
 === "Python"
 
@@ -43,7 +54,7 @@ Use the following command to run your agent in the ADK web interface:
         With Maven, compile and run the ADK web server:
         ```console
         mvn compile exec:java \
-         -Dexec.args="--adk.agents.source-dir=src/main/java/agents --server.port=8080"
+         -Dexec.args="--adk.agents.source-dir=src/main/java/agents --server.port=8000"
         ```
     === "Gradle"
         With Gradle, the `build.gradle` or `build.gradle.kts` build file should have the following Java plugin in its plugins section:
@@ -61,7 +72,7 @@ Use the following command to run your agent in the ADK web interface:
             dependsOn classes
             classpath = sourceSets.main.runtimeClasspath
             mainClass = 'com.google.adk.web.AdkWebServer'
-            args '--adk.agents.source-dir=src/main/java/agents', '--server.port=8080'
+            args '--adk.agents.source-dir=src/main/java/agents', '--server.port=8000'
         }
         ```
 
@@ -71,9 +82,10 @@ Use the following command to run your agent in the ADK web interface:
         ```
 
 
-    In Java, the Web Interface and the API server are bundled together.
+    In Java, the web interface and the API server are bundled together.
 
-The server starts on `http://localhost:8000` by default:
+Once started, the server prints the access URL to the console. Open it in your
+browser to use the web interface:
 
 ```shell
 +-----------------------------------------------------------------------------+
@@ -83,17 +95,11 @@ The server starts on `http://localhost:8000` by default:
 +-----------------------------------------------------------------------------+
 ```
 
-## Features
-
-Key features of the ADK web interface include:
-
-- **Chat interface**: Send messages to your agents and view responses in real-time
-- **Session management**: Create and switch between sessions
-- **State inspection**: View and modify session state during development
-- **Event history**: Inspect all events generated during agent execution
-
 ## Common options
 
+Here are some commonly used options for the `adk web` command. Run `adk web
+--help` to see all available options.
+
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--port` | Port to run the server on | `8000` |
@@ -102,7 +108,7 @@ Key features of the ADK web interface include:
 | `--artifact_service_uri` | Custom artifact storage URI | Local `.adk/artifacts` |
 | `--reload/--no-reload` | Enable auto-reload on code changes | `true` |
 
-### Example with options
+For example:
 
 ```shell
 adk web --port 3000 --session_service_uri "sqlite:///sessions.db"

docs/visual-builder/index.md

@@ -1,35 +1,36 @@
-# Visual Builder for agents
+# Use the Visual Builder
 
 <div class="language-support-tag">
   <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.18.0</span><span class="lst-preview">Experimental</span>
 </div>
 
-The ADK Visual Builder is a web-based tool that provides a visual workflow
-design environment for creating and managing ADK agents. It allows you to
-design, build, and test your agents in a beginner-friendly graphical interface,
-and includes an AI-powered assistant to help you build agents.
+The ADK Visual Builder is a feature of the ADK web interface that provides a
+visual workflow design environment for creating and managing agents. The Visual
+Builder allows you to design, build, and test agents in a beginner-friendly
+graphical interface, and includes an AI-powered assistant to help you build
+agents.
 
 ![Visual Agent Builder](../assets/visual-builder.png)
 
 !!! example "Experimental"
+
     The Visual Builder feature is an experimental release. We welcome your
     [feedback](https://github.com/google/adk-python/issues/new?template=feature_request.md)!
 
-## Get started
+## Create an agent
 
-The Visual Builder interface is part of the ADK Web tool user interface.
-Make sure you have ADK library
-[installed](/get-started/installation/#python)
-and then run the ADK Web user interface.
+To use the Visual Builder, start the ADK web interface:
 
 ```console
-adk web --port 8000
+adk web
 ```
 
+Then follow the steps below to create an agent.
+
 ??? tip "Tip: Run from a code development directory"
 
     The Visual Builder tool writes project files to new subdirectories located
-    in the directory where you run the ADK Web tool. Make sure you run this
+    in the directory where you run ADK Web. Make sure you run this
     command from a developer directory location where you have write access.
 
 ![Visual Agent Builder start](../assets/visual-builder-start.png)
@@ -41,13 +42,13 @@ To create an agent with Visual Builder:
 1.  Type a name for your agent application and select **Create**.
 1.  Edit your agent by doing any of the following:
     *   In the left panel, edit agent component values.
-    *   In the central panel, add new agent components .
+    *   In the central panel, add new agent components.
     *   In the right panel, use prompts to modify the agent or get help.
 1.  In bottom left corner, select **Save** to save your agent.
 1.  Interact with your new agent to test it.
 1.  In top left of the page, select the pencil icon, as shown in *Figure 1*, to continue editing your agent.
 
-Here are few things to note when using Visual Builder:
+Here are a few things to note when using Visual Builder:
 
 *   **Create agent and save:** When creating an agent, make sure you select
     **Save** before exiting the editing interface, otherwise your new agent may
@@ -57,11 +58,19 @@ Here are few things to note when using Visual Builder:
 *   **Add tools:** When adding existing custom Tools to a Visual Builder
     agent, specify a fully-qualified Python function name.
 
-## Workflow component support
+??? tip "Try this prompt with the Visual Builder assistant"
+
+    ```none
+    Help me add a dice roll tool to my current agent.
+    Use the default model if you need to configure that.
+    ```
 
-The Visual Builder tool provides a drag-and-drop user interface for constructing agents, as
-well as an AI-powered development Assistant that can answer questions and edit your agent workflow.
-The tool supports all the essential components for building an ADK agent workflow, including:
+## Supported components
+
+The Visual Builder tool provides a drag-and-drop user interface for constructing
+agents, as well as an AI-powered development Assistant that can answer questions
+and edit your agent workflow. The tool supports all the essential components for
+building an ADK agent workflow, including:
 
 *   **Agents**
     *   **Root Agent**: The primary controlling agent for a workflow. All other agents in
@@ -85,15 +94,15 @@ The tool supports all the essential components for building an ADK agent workflo
         and end of agent workflow events.
 
 Some advanced ADK features are not supported by Visual Builder due to
-limitations of the Agent Config feature. For more information, see the
-Agent Config [Known limitations](/agents/config/#known-limitations).
+limitations of the Agent Config feature. For more information, see the Agent
+Config [Known limitations](/agents/config/#known-limitations).
 
-## Project code output
+## Generated project structure
 
 The Visual Builder tool generates code in the [Agent Config](/agents/config/)
 format, using `.yaml` configuration files for agents and Python code for custom
 tools. These files are generated in a subfolder of the directory where you ran
-the ADK Web interface. The following listing shows an example layout for a
+the ADK web interface. The following listing shows an example layout for a
 DiceAgent project:
 
 ```none
@@ -110,18 +119,6 @@ DiceAgent/
     You can edit the generated files in your development environment. However,
     some changes may not be compatible with Visual Builder.
 
-## Next steps
-
-Using the Visual Builder development Assistant, try building a new agent using
-this prompt:
-
-```none
-Help me add a dice roll tool to my current agent.
-Use the default model if you need to configure that.
-```
-
-Check out more information on the Agent Config code format used by Visual Builder
-and the available options:
-
-*   [Agent Config](/agents/config/)
-*   [Agent Config YAML schema](/api-reference/agentconfig/)
+For more information on the Agent Config code format used by Visual Builder, see
+[Agent Config](/agents/config/) and [Agent Config YAML
+schema](/api-reference/agentconfig/).

mkdocs.yml

@@ -221,7 +221,6 @@ plugins:
         Build Agents:
         - get-started/*.md
         - tutorials/*.md
-        - visual-builder/*.md
         - agents/*.md
         - workflows/*.md
         - integrations/*.md
@@ -230,6 +229,7 @@ plugins:
         - skills/*.md
         Run Agents:
         - runtime/*.md
+        - visual-builder/*.md
         - deploy/*.md
         - observability/*.md
         - evaluate/*.md
@@ -271,7 +271,6 @@ nav:
         - get-started/streaming/index.md
         - Python: get-started/streaming/quickstart-streaming.md
         - Java: get-started/streaming/quickstart-streaming-java.md
-      - Visual Builder: visual-builder/index.md
       - Coding with AI: tutorials/coding-with-ai.md
       - Advanced setup: get-started/installation.md
     - Agents:
@@ -315,7 +314,9 @@ nav:
   - Run Agents:
     - Agent Runtime:
       - Agent Runtime: runtime/index.md
-      - Web Interface: runtime/web-interface.md
+      - Web Interface:
+          - runtime/web-interface/index.md
+          - Visual Builder: visual-builder/index.md
       - Command Line: runtime/command-line.md
       - API Server: runtime/api-server.md
       - Ambient Agents: runtime/ambient-agents.md