Update UI Submodule and Reference Docs (#939)

This PR standardizes UI documentation across the repository by updating installation commands to use npm ci for reproducible builds, adding prominent WebSocket requirement notices for human-in-the-loop workflows (OAuth, interactive prompts), and consolidating all UI setup references to point to the comprehensive launching-ui.md guide. The changes improve the Settings Options documentation with clearer structure matching the current UI implementation and enhance examples/UI/README.md with configuration examples and troubleshooting sections. These updates provide a single source of truth for UI configuration and help users avoid common issues by clearly explaining when WebSocket mode is required versus HTTP requests.
## By Submitting this PR I confirm:
- I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md).
- We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  - Any contribution which contains commits that are not Signed-Off will not be accepted.
- When the PR is ready for review, new or existing tests cover these changes.
- When the PR is ready for review, the documentation is up to date with these changes.



## Summary by CodeRabbit

- Documentation
  - Revamped "Launching the UI" guide: modernized UI features, clearer prerequisites, step-by-step startup, expanded Appearance/API/WebSocket configuration, and detailed HTTP vs streaming endpoint guidance.
  - Emphasized WebSocket requirement for human-in-the-loop, OAuth, and interactive workflows; updated multiple READMEs and workflow docs for consistency.
- Chores
  - Updated UI submodule to a newer revision.

Authors:
  - Eric Evans II (https://github.com/ericevans-nv)

Approvers:
  - Will Killian (https://github.com/willkill07)

URL: #939

Author: ericevans-nv

docs/source/_static/hitl_settings.png

@@ -131,7 +131,7 @@ Adding a Telemetry Exporter <./extend/telemetry-exporters.md>
 API Authentication <./reference/api-authentication.md>
 Interactive Models <./reference/interactive-models.md>
 API Server Endpoints <./reference/api-server-endpoints.md>
-Websockets <./reference/websockets.md>
+WebSockets <./reference/websockets.md>
 Command Line Interface (CLI) <./reference/cli.md>
 Cursor Rules Reference <./reference/cursor-rules-reference.md>
 Evaluation <./reference/evaluate.md>

docs/source/_static/ui_home_page.png

@@ -16,43 +16,54 @@ limitations under the License.
 -->
 
 # Launching the NVIDIA NeMo Agent Toolkit API Server and User Interface
+
 NVIDIA NeMo Agent toolkit provides a user interface for interacting with your running workflow. This guide walks you through starting the API server and launching the web-based user interface to interact with your workflows.
 
 ## User Interface Features
-- Chat history
-- Interact with a workflow via the HTTP API
-- Interact with a workflow via a WebSocket
-- Enable or disable a workflow's intermediate steps
-- Expand all workflow intermediate steps by default
-- Override intermediate steps with the same ID
+
+- Modern and responsive user interface
+- Real-time streaming responses
+- Human-in-the-loop workflow support
+- Chat history and conversation management
+- Light and Dark theme support
+- WebSocket and HTTP API integration
+- Intermediate steps visualization
+- Docker deployment support
 
 ## Walk-through
+
 This walk-through guides you through the steps to set up and configure the NeMo Agent toolkit user interface.
 
 ### Prerequisites
+
 Before starting, ensure you have:
+
 - NeMo Agent toolkit installed and configured
 - Set up the simple calculator workflow by following the instructions in `examples/getting_started/simple_calculator/README.md`
 - Node.js v18+ installed (required for the web interface)
 
-
 The NeMo Agent toolkit UI is located in a Git submodule at `external/nat-ui`. Ensure you have checked out all of the Git submodules by running the following:
+
 ```bash
 git submodule update --init --recursive
 ```
 
 ### Start the NeMo Agent Toolkit Server
+
 You can start the NeMo Agent toolkit server using the `nat serve` command with the appropriate configuration file.
 
 ```bash
 nat serve --config_file=examples/getting_started/simple_calculator/configs/config.yml
 ```
+
 Running this command will produce the expected output as shown below (truncated for brevity):
+
 ```bash
 INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)
 ```
 
 ### Verify the NeMo Agent Toolkit Server is Running
+
 After the server is running, you can make HTTP requests to interact with the workflow. This step confirms that the server is properly configured and can process requests.
 
 ```bash
@@ -66,47 +77,76 @@ curl --request POST \
 ```
 
 Running this command will produce the following expected output:
-> **Note:** The response depends on the current time of day that the command is run.
+:::note
+The response depends on the current time of day that the command is run.
+:::
 ```bash
 {
   "value": "No, 8 is less than the current hour of the day (4)."
 }
 ```
 
 ### Launch the NeMo Agent Toolkit User Interface
+
 After the NeMo Agent toolkit server starts, launch the web user interface. Launching the UI requires that Node.js v18+ is installed. Instructions for downloading and installing Node.js can be found in the official [Node.js documentation](https://nodejs.org/en/download).
 
 For comprehensive information about the NeMo Agent Toolkit UI, including setup instructions, configuration options, and UI components documentation, see:
+
 - [NeMo Agent Toolkit UI README](https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI/blob/main/README.md) - Complete UI documentation and setup guide
 - [UI Components Documentation](https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI/tree/main/docs/ui) - Detailed information about components, features, and interface elements
 
+#### Local Development
+
 ```bash
 cd external/nat-ui
-npm install
+npm ci
 npm run dev
 ```
+
 After the web development server starts, open a web browser and navigate to [`http://localhost:3000/`](http://localhost:3000/).
 Port `3001` is an alternative port if port `3000` (default) is in use.
 
 ![NeMo Agent toolkit Web User Interface](../_static/ui_home_page.png)
 
+:::important
+Workflows requiring human input or interaction (such as human-in-the-loop workflows, OAuth authentication, or interactive prompts) must use WebSocket connections. HTTP requests are the default method of communication, but human-in-the-loop functionality is not supported through HTTP. Ensure that `WebSocket` mode is enabled in the UI by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out.
+:::
+
 ### Connect the User Interface to the NeMo Agent Toolkit Server Using HTTP API
+
 Configure the settings by selecting the *Settings* icon located on the bottom left corner of the home page.
 
 ![NeMo Agent toolkit Web UI Settings](../_static/ui_generate_example_settings.png)
 
 #### Settings Options
-**Note:** It's recommended to select `/chat/stream` for intermediate results streaming.
-- `Theme`: Light or Dark Theme.
-- `HTTP URL for Chat Completion`: REST API enpoint.
-  - /generate
-  - /generate/stream
-  - /chat
-  - /chat/stream
-- `WebSocket URL for Completion`: WebSocket URL to connect to running NeMo Agent toolkit server.
-- `WebSocket Schema`: Workflow schema type over WebSocket connection.
+
+**Appearance:**
+
+- `Theme`: Switch between Light and Dark mode
+
+**API Configuration:**
+
+- `HTTP Endpoint`: Select API endpoint type:
+  - **Chat Completions — Streaming** - Real-time OpenAI Chat Completions compatible API endpoint with streaming responses (recommended for intermediate results)
+  - **Chat Completions — Non-Streaming** - Standard OpenAI Chat Completions compatible API endpoint
+  - **Generate — Streaming** - Text generation with streaming
+  - **Generate — Non-Streaming** - Standard text generation
+- `Optional Generation Parameters`: OpenAI Chat Completions compatible JSON parameters that can be added to the request body (available for chat endpoints)
+
+**WebSocket Configuration:**
+
+- `WebSocket Schema`: Select schema for real-time connections:
+  - **Chat Completions — Streaming** - Streaming chat over WebSocket (recommended for intermediate results)
+  - **Chat Completions — Non-Streaming** - Non-streaming chat over WebSocket
+  - **Generate — Streaming** - Streaming generation over WebSocket
+  - **Generate — Non-Streaming** - Non-streaming generation over WebSocket
+
+:::note
+For intermediate results streaming, use **Chat Completions — Streaming** (`/chat/stream`) or **Generate — Streaming** (`/generate/stream`).
+:::
 
 ### Simple Calculator Example Conversation
+
 Interact with the chat interface by prompting the Agent with the
 message: `Is 4 + 4 greater than the current hour of the day?`
 

docs/source/index.md

@@ -152,9 +152,12 @@ At this point, a consent window is displayed to the user. The user must authoriz
 Subsequent tool calls can be disabled for the default user ID by setting `allow_default_user_id_for_tool_calls` to `false` in the authentication configuration. This is recommended for multi-user workflows to avoid accidental tool calls by unauthorized users.
 
 3. **Start the UI**:
-- Start the UI by following the instructions in the [User Interface](../../quick-start/launching-ui.md) documentation.
-- Connect to  the UI at `http://localhost:3000`
-- Ensure that `WebSocket` mode is enabled by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out.
+- Start the UI by following the instructions in the [Launching the UI](../../quick-start/launching-ui.md) documentation.
+- Connect to the UI at http://localhost:3000
+
+:::important
+Ensure that `WebSocket` mode is enabled by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out. WebSocket connections are required for OAuth authentication workflows.
+:::
 
 4. **Send the input to the workflow via the UI**:
 ```text

docs/source/quick-start/launching-ui.md

@@ -72,7 +72,11 @@ nat serve --config_file examples/MCP/simple_auth_mcp/configs/config-mcp-auth-jir
 ```
 
 2. **Start the UI**:
-Start UI and connect to the URL `http://localhost:3000`. Ensure that `Websocket` mode is enabled by navigating to the top-right corner and selecting the `Websocket` option in the arrow pop-out.
+
+   Start the UI by following the instructions in the [Launching the UI](../../../docs/source/quick-start/launching-ui.md) guide. Connect to the URL http://localhost:3000.
+
+   > [!IMPORTANT]
+   > Ensure that `WebSocket` mode is enabled by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out. WebSocket connections are required for OAuth authentication workflows.
 
 3. **Send the input to the workflow via the UI**:
 ```text

docs/source/workflows/mcp/mcp-auth.md

@@ -26,15 +26,19 @@ This example demonstrates how to integrate and use the web-based user interface
 - **Real-Time Streaming:** Shows how to enable intermediate step streaming for enhanced user experience, allowing users to see agent reasoning and tool execution in real-time.
 - **UI Customization Options:** Supports theme customization, endpoint configuration, and display options to match different deployment environments and user preferences.
 - **Conversation Management:** Includes conversation history, session management, and context preservation across multiple interactions within the same session.
+- **Human-in-the-Loop Support:** Interactive prompts and OAuth consent handling for workflows requiring user input or authentication.
 
 ## What You'll Learn
 
 - **UI setup and configuration**: Launch and configure the Agent toolkit web interface
 - **Interactive workflow management**: Use the UI to interact with agents and view conversation history
 - **Connection management**: Configure HTTP and WebSocket connections for different use cases
 - **Real-time streaming**: Enable intermediate step streaming for enhanced user experience
-- **UI customization**: Customize themes, endpoints, and display options
+- **UI customization**: Customize themes, endpoints, and display options through environment variables
 
 ## Quick Start
 
 For complete setup and usage instructions, refer to the comprehensive guide: [Launching the UI](../../docs/source/quick-start/launching-ui.md).
+
+> [!IMPORTANT]
+> Workflows requiring human input or interaction (such as human-in-the-loop workflows, OAuth authentication, or interactive prompts) must use WebSocket connections. HTTP requests are the default method of communication, but human-in-the-loop functionality is not supported through HTTP. Ensure that `WebSocket` mode is enabled in the UI by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out.

examples/MCP/simple_auth_mcp/README.md

@@ -21,12 +21,14 @@ The profiler agent is a tool that allows you to analyze the performance of NeMo
 
 ## Table of Contents
 
-- [Key Features](#key-features)
-- [Installation and Setup](#installation-and-setup)
-  - [Install this Workflow](#install-this-workflow)
-  - [Set Up API Keys](#set-up-api-keys)
-- [Run the Workflow](#run-the-workflow)
-- [Features](#features)
+- [NeMo Agent Toolkit Profiler Agent](#nemo-agent-toolkit-profiler-agent)
+  - [Table of Contents](#table-of-contents)
+  - [Key Features](#key-features)
+  - [Installation and Setup](#installation-and-setup)
+    - [Install this Workflow:](#install-this-workflow)
+    - [Set Up API Keys](#set-up-api-keys)
+  - [Run the Workflow](#run-the-workflow)
+  - [Features](#features)
 
 ## Key Features
 
@@ -81,7 +83,7 @@ export NVIDIA_API_KEY=<YOUR_API_KEY>
    nat serve --config_file=examples/advanced_agents/profiler_agent/configs/config.yml
    ```
 
-4. Launch the NeMo Agent Toolkit User Interface by using the instructions in the [Launching the User Interface](../../../docs/source/quick-start/launching-ui.md#launch-the-nemo-agent-toolkit-user-interface) guide.
+4. Launch the NeMo Agent Toolkit User Interface by using the instructions in the [Launching the UI](../../../docs/source/quick-start/launching-ui.md) guide.
 
 5. Query the agent with natural language via the UI:
    ```

examples/UI/README.md

@@ -119,8 +119,7 @@ Browse to **`http://localhost:5001/`** – you should see the demo home page. Si
 
 ## Deploy the NeMo Agent Toolkit UI
 
-Follow the instructions at the GitHub repository to deploy the [NeMo Agent Toolkit UI](https://github.com/NVIDIA/NeMo-Agent-Toolkit-UI)
-to deploy the UI that works with the agent in this example. Configure it according to the instructions in the README.
+Follow the instructions in the [Launching the UI](../../../docs/source/quick-start/launching-ui.md) guide to set up and launch the NeMo Agent Toolkit UI.
 
 ## Update Your Environment Variables
 
@@ -144,16 +143,18 @@ handles authentication.
 
 ## Query the Agent
 
-Open the NeMo Agent Toolkit UI in your browser at `http://localhost:3000`. Ensure settings are configured correctly to point to your agent's API endpoint at `http://localhost:8000` and
-the WebSocket URL at `ws://localhost:8000/websocket`.
+Open the NeMo Agent Toolkit UI in your browser at http://localhost:3000.
 
-Close the settings window. In your chat window, ensure that `Websocket` mode is enabled by navigating to the top-right corner and selecting the `Websocket` option in the arrow pop-out.
+By default, the UI is configured to connect to your agent's API endpoint at `http://localhost:8000` and the WebSocket URL at `ws://localhost:8000/websocket`. These default values can be changed using environment variables. See the [Launching the UI](../../../docs/source/quick-start/launching-ui.md) guide for environment variable configuration details.
 
-Once you've successfully connected to the websocket, you can start querying the agent. Asking the agent the following query should initiate the demonstrative authentication flow and then return
-information about the authenticated user:
+> [!IMPORTANT]
+> In your chat window, ensure that `WebSocket` mode is enabled by navigating to the top-right corner and selecting the `WebSocket` option in the arrow pop-out. This is required for the OAuth 2.0 authentication flow to work properly.
+
+Once you've successfully connected to the WebSocket, you can start querying the agent. Asking the agent the following query should initiate the demonstrative authentication flow and then return information about the authenticated user:
 
 ```text
 Who am I logged in as?
 ```
 
-**Tip**: Remember to enable pop-ups in your browser to allow the OAuth 2.0 provider to open a new window for authentication.
+> [!TIP]
+> If you encounter errors, verify that WebSocket mode is enabled. HTTP requests are the default method of communication, but human-in-the-loop functionality (including OAuth authentication) is not supported through HTTP.