diff --git a/assets/agw-docs/pages/observability/ui.md b/assets/agw-docs/pages/observability/ui.md index c2b9f579f..3f0480134 100644 --- a/assets/agw-docs/pages/observability/ui.md +++ b/assets/agw-docs/pages/observability/ui.md @@ -2,8 +2,14 @@ The agentgateway UI is a built-in web interface that runs on port 15000 of the `agentgateway-proxy` pod. In Kubernetes mode, the UI is **read-only**. It reflects the configuration that the agentgateway controller pushes to the proxy over xDS, the protocol that the control plane uses to deliver configuration to the proxy. +{{< version include-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} > [!NOTE] -> The UI is read-only in Kubernetes mode. Unlike standalone mode, you cannot use the UI to add features such as models, LLM providers, or MCP servers. The Kubernetes UI also does not currently show the standalone **LLM > Client Setup** generator. Instead, make configuration changes by updating your Kubernetes resources, such as through GitOps, and configure LLM clients with the values from their integration guides. Follow [agentgateway/agentgateway#2989](https://github.com/agentgateway/agentgateway/issues/2989) for the Client Setup enhancement. +> The UI is read-only in Kubernetes mode. Unlike standalone mode, you cannot use the UI to add features such as models, LLM providers, or MCP servers. The Kubernetes UI also does not currently show the standalone **LLM > Client Setup** generator. Instead, make configuration changes by updating your Kubernetes resources, such as through GitOps, and configure LLM clients with the values from their integration guides. +{{< /version >}} +{{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} +> [!NOTE] +> The UI is read-only in Kubernetes mode. Unlike standalone mode, you cannot use the UI to add features such as models, LLM providers, or MCP servers. Instead, make configuration changes by updating your Kubernetes resources, such as through GitOps. To generate settings for LLM clients, use the [Client Setup](#client-setup) page, which does not change any resources. +{{< /version >}} The UI is useful for debugging and verifying the configuration that the proxy received from the controller, such as confirming that a Gateway, HTTPRoute, AgentgatewayBackend, or AgentgatewayPolicy resource took effect. @@ -143,7 +149,7 @@ EOF {{% version exclude-if="1.2.x,1.1.x,1.0.x,2.2.x" %}} ## Explore the read-only views {#explore} -Because configuration is managed by xDS, every page shows a read-only mode banner and editing is disabled. The views reflect the configuration that the proxy currently runs, so use them to verify that the proxy received the configuration that you expect. The navigation menu groups the views into **Gateway**, **Traffic**, and **Tools**. +Because configuration is managed by xDS, every page shows a read-only mode banner and editing is disabled. The views reflect the configuration that the proxy currently runs, so use them to verify that the proxy received the configuration that you expect. The navigation menu groups the views into **Gateway**, {{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,2.2.x" >}}**LLM**, {{< /version >}}**Traffic**, and **Tools**. ### Listeners {#listeners} @@ -168,8 +174,28 @@ The **Policies** page lists the policies that the proxy currently runs, includin ### CEL Playground {#cel-playground} -The **CEL Playground**, under **Tools**, lets you evaluate Common Expression Language (CEL) expressions against sample input. It is the only interactive tool available in Kubernetes mode, and it does not modify any configuration. For more information about where agentgateway uses CEL, see the [CEL expressions reference]({{< link-hextra path="/reference/cel/" >}}). +The **CEL Playground**, under **Tools**, lets you evaluate Common Expression Language (CEL) expressions against sample input. The playground does not modify any configuration. For more information about where agentgateway uses CEL, see the [CEL expressions reference]({{< link-hextra path="/reference/cel/" >}}). {{< reuse-image-light src="img/agentgateway-ui-kube-cel.png" >}} {{< reuse-image-dark srcDark="img/agentgateway-ui-kube-cel-dark.png" >}} {{% /version %}} + +{{% version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,2.2.x" %}} +### Models {#models} + +The **Models** page, under **LLM**, lists the models that the proxy serves from your {{< reuse "agw-docs/snippets/agentgatewaymodel.md" >}} resources. Each row shows the model name, whether the model is concrete or virtual, its visibility, its target, and its listener. The list includes internal models. To view the YAML for a model, click the view (eye) icon in its row. For more information about models, see [About models]({{< link-hextra path="/documentation/llm/models/about/" >}}). +{{% /version %}} + +{{% version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" %}} +## Generate LLM client settings {#client-setup} + +Use the **LLM** > **Client Setup** page to generate connection settings and snippets for LLM clients, such as curl, Claude Code, Codex CLI, Cursor, and the OpenAI SDKs. The page configures the client only and does not create or change Gateway, HTTPRoute, AgentgatewayBackend, AgentgatewayPolicy, or Secret resources. + +1. Open the **LLM** > **Client Setup** page, such as [http://localhost:15000/ui/llm/client-setup](http://localhost:15000/ui/llm/client-setup). +2. Enter the **Gateway base URL** that clients use to reach the proxy, including any route prefix. The field starts empty because the proxy does not know the external address of its Gateway, such as a load balancer hostname. The snippets appear only after you enter a URL. +3. Select a model. The list includes public concrete models and virtual models from the proxy's configuration. Internal models are not listed, because clients cannot request them directly. If the model that you want is not listed, type its name. If you select a wildcard model, such as `gpt-*`, type the rest of the model name that the client requests. +4. Enter the API key that the client sends. The UI keeps the key in the browser and does not read it from a Kubernetes Secret. +5. Select the client from the **Integration** dropdown and copy the generated settings or snippet. + +For client-specific prerequisites, see [LLM clients]({{< link-hextra path="/integrations/llm/clients/" >}}). +{{% /version %}} diff --git a/assets/agw-docs/snippets/llm-client-setup-index-k8s.md b/assets/agw-docs/snippets/llm-client-setup-index-k8s.md index 3f028532e..9556b0115 100644 --- a/assets/agw-docs/snippets/llm-client-setup-index-k8s.md +++ b/assets/agw-docs/snippets/llm-client-setup-index-k8s.md @@ -1,4 +1,9 @@ ## Generate client settings +{{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} +The agentgateway UI includes an **LLM > Client Setup** page that generates the gateway URL, model, and credential values for these clients from the models that the proxy serves. The page does not create or change Kubernetes resources. For more information, see [Generate LLM client settings]({{< link-hextra path="/documentation/observability/ui/#client-setup" >}}). +{{< /version >}} +{{< version include-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} > [!NOTE] -> The Kubernetes UI is read-only and does not currently show the standalone **LLM > Client Setup** generator. Use the client guides in this section to configure the same gateway URL, model, and credential values manually. Follow [agentgateway/agentgateway#2989](https://github.com/agentgateway/agentgateway/issues/2989) for the Client Setup enhancement. +> The Kubernetes UI is read-only and does not currently show the standalone **LLM > Client Setup** generator. Use the client guides in this section to configure the same gateway URL, model, and credential values manually. +{{< /version >}} diff --git a/assets/agw-docs/standalone/setup/ui/gateway.md b/assets/agw-docs/standalone/setup/ui/gateway.md index 2d8c5cb8d..c8c8e4064 100644 --- a/assets/agw-docs/standalone/setup/ui/gateway.md +++ b/assets/agw-docs/standalone/setup/ui/gateway.md @@ -284,6 +284,18 @@ kill $AGW_UI_GW_PID 2>/dev/null || true > [!NOTE] > The UI gateway is an addition, not a replacement. Agentgateway still serves a copy of the UI on the admin interface, which is loopback-only and which you do not need to change. Adding this gateway does not put the admin interface's debugging endpoints on it. For more information, see [The UI and the admin interface are not the same thing]({{< link-hextra path="/documentation/setup/ui/#admin-interface" >}}). +{{% version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" %}} +## Change the UI gateway in the UI {#change-in-ui} + +You can also change the gateway that serves the UI from the UI itself. The UI must be able to save changes, which depends on your storage mode. For more information, see [Save changes from the UI]({{< link-hextra path="/documentation/setup/ui/launch-ui/#save-changes" >}}). + +1. Open the **Settings** > **UI** page, such as [http://localhost:15000/ui/settings/ui](http://localhost:15000/ui/settings/ui). +2. From the **Public gateway** dropdown, select the gateway that you want to serve the UI, or **None** to serve the UI only on the admin interface. +3. Click **Save UI gateway**. If the UI is already served on a gateway, confirm the change in the **Change UI gateway?** dialog. + +If you opened the UI through the gateway that you changed or removed, the page stops loading. Open the UI on the new gateway or on the admin interface. If you chose **None**, the UI also removes the `ui` section from your configuration, including any `ui.policies`. +{{% /version %}} + ## Next steps * [Secure the UI]({{< link-hextra path="/documentation/setup/ui/secure-ui/" >}}) with an OIDC login on the gateway that you created. diff --git a/assets/agw-docs/standalone/setup/ui/launch.md b/assets/agw-docs/standalone/setup/ui/launch.md index caa375889..89ea71049 100644 --- a/assets/agw-docs/standalone/setup/ui/launch.md +++ b/assets/agw-docs/standalone/setup/ui/launch.md @@ -108,8 +108,16 @@ Use the UI to review what agentgateway loaded and to manage the resources that y * [MCP quickstart]({{< link-hextra path="/documentation/quickstart/mcp/" >}}) to connect an MCP server and try tools in the built-in playground. * [LLM quickstart]({{< link-hextra path="/documentation/quickstart/llm/" >}}) to route requests to an LLM provider and see the model in the UI. +## Save changes from the UI {#save-changes} + Whether the UI can save the changes that you make depends on your storage mode. In the binary and Docker installations, the UI writes to your configuration file by default. In the Helm installation, the ConfigMap is read-only and a save fails unless you switch the chart to database mode. For more information, see [Configuration storage]({{< link-hextra path="/documentation/setup/storage/" >}}). +{{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} +The UI checks a change before it writes the configuration file. If the change is not valid, the save fails with an error and the file does not change. + +If you edit the file outside the UI and agentgateway rejects the reload, the UI shows a **Configuration reload failed** banner. Agentgateway keeps running the previous valid configuration. The UI and `/api/config/effective` show the file on disk, including the rejected change. To retry the reload, fix the file and save it again. +{{< /version >}} + ## Generate LLM client settings {#client-setup} For an example of using the UI to set something up, use the **LLM > Client Setup** page. It generates connection settings and snippets for curl, Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, GitHub Copilot, Windsurf, and the OpenAI JavaScript and Python SDKs{{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,2.2.x" >}}. The page also includes a Pi recipe that writes `baseUrl` and `apiKey` values into `~/.pi/agent/models.json`{{< /version >}}. @@ -119,6 +127,10 @@ For an example of using the UI to set something up, use the **LLM > Client Setup 3. Review the **Gateway base URL**, and select a model and virtual API key. 4. Select the client from the **Integration** dropdown, and copy the generated settings or snippet. +{{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} +Client Setup fills in **Gateway base URL** from the gateway that serves LLM traffic. If the same gateway also serves the UI, Client Setup uses the address in your browser instead, so the URL keeps the host, scheme, and port of a reverse proxy in front of agentgateway. Check the URL before you copy a snippet, and change it if clients reach agentgateway through a different address. The snippets appear only when **Gateway base URL** has a value. +{{< /version >}} + Client Setup does not create a route, model, authentication policy, or provider credential. It generates client-side values from the configuration that already exists. For client-specific prerequisites, see [LLM clients]({{< link-hextra path="/integrations/llm/clients/" >}}). The selected model appears only in recipes that accept a model setting. For example, the Claude Desktop recipe outputs a gateway URL and API key, but does not configure a model name in Claude Desktop.