docs: Agent Gateway, API key usage dashboard, agents, and LLM Serving

docs/.vitepress/config.mts

@@ -1,7 +1,7 @@
 import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import defineVersionedConfig from 'vitepress-versioning-plugin'
-import { latestReleasedVersion, visibleVersions } from './versions'
+import { developmentVersion, latestReleasedVersion, visibleVersions } from './versions'
 
 const base = process.env.VITEPRESS_BASE ?? '/docs/'
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -11,6 +11,10 @@ type SidebarItem = {
   link?: string
   collapsed?: boolean
   items?: SidebarItem[]
+  // Restrict this item to specific versions, for pages that only exist in
+  // some version trees (e.g. new unreleased pages under `development`).
+  // Omit for items that exist in every visible version.
+  versions?: string[]
 }
 
 const baseSidebar: SidebarItem[] = [
@@ -35,7 +39,8 @@ const baseSidebar: SidebarItem[] = [
       { text: 'Agent Sandboxes', link: '/agentops/sandboxes.html' },
       { text: 'MCP Servers', link: '/agentops/mcp_servers.html' },
       { text: 'Memory Stores', link: '/agentops/memory_stores.html' },
-      { text: 'Agents', link: '/agentops/agents.html' }
+      { text: 'Agents', link: '/agentops/agents.html' },
+      { text: 'LLM Serving', link: '/agentops/llm_serving.html', versions: [developmentVersion] }
     ]
   },
   {
@@ -63,6 +68,7 @@ const baseSidebar: SidebarItem[] = [
       { text: 'Component Versions', link: '/platform/component_versions.html' },
       { text: 'Observability', link: '/platform/observability.html' },
       { text: 'System Status', link: '/platform/system_status.html' },
+      { text: 'Agent Gateway', link: '/platform/agent_gateway.html', versions: [developmentVersion] },
       { text: 'API Keys', link: '/platform/api_keys.html' }
     ]
   },
@@ -77,6 +83,7 @@ const baseSidebar: SidebarItem[] = [
       { text: 'Network Policies', link: '/admin/network_policies.html' },
       { text: 'Application Networking', link: '/admin/application_networking.html' },
       { text: 'Application Authentication', link: '/admin/application_authentication.html' },
+      { text: 'External Models', link: '/admin/external_models.html', versions: [developmentVersion] },
       { text: 'Storage', link: '/admin/storage.html' },
       { text: 'GPU Administration', link: '/admin/gpu.html' },
       { text: 'Backup and Restore', link: '/admin/backup_restore.html' },
@@ -89,10 +96,12 @@ const baseSidebar: SidebarItem[] = [
 function sidebarFor(version: string): SidebarItem[] {
   return baseSidebar.map((section) => ({
     ...section,
-    items: section.items?.map((item) => ({
-      ...item,
-      link: item.link ? `/${version}${item.link}` : item.link
-    }))
+    items: section.items
+      ?.filter((item) => !item.versions || item.versions.includes(version))
+      .map((item) => ({
+        ...item,
+        link: item.link ? `/${version}${item.link}` : item.link
+      }))
   }))
 }
 

docs/versions/development/admin/external_models.md

@@ -0,0 +1,83 @@
+# External Models
+
+The **AI Gateway** admin page connects centrally managed model providers to prokube. Administrators can add provider credentials once, register models from those providers, and grant specific workspaces access to specific models.
+
+Use this workflow when you need to:
+
+- offer Mistral AI, Azure OpenAI, GitHub Models, or a custom OpenAI-compatible endpoint;
+- share a centrally managed provider credential without copying it into workspace Secrets;
+- control which workspaces can use each external model.
+
+For OpenAI, Anthropic, or Gemini, workspace users can instead create their own Model Configuration backed by a workspace Kubernetes Secret. See [Agents](../agentops/agents.html#_2-choose-or-create-a-model-configuration).
+
+![AI Gateway page with provider catalog and platform-wide usage summary](../../../_static/screenshots/admin/external-models/ai-gateway-overview.png)
+
+## Provider Options
+
+The admin-managed provider catalog supports:
+
+- Anthropic;
+- OpenAI;
+- Mistral AI;
+- Azure OpenAI;
+- GitHub Models;
+- custom OpenAI-compatible endpoints.
+
+Anthropic uses its native protocol. The other provider types use an OpenAI-compatible protocol. Custom and Azure OpenAI providers require an upstream host and path prefix.
+
+## Connect a Provider
+
+Open **AI Gateway** under **Admin**, then select **Add Provider**. Configure:
+
+- **Provider**: select an entry from the provider catalog.
+- **Provider name**: unique name for the provider connection.
+- **Provider API key**: credential stored centrally by prokube.
+- **Upstream host** and **Path prefix**: required for custom and Azure OpenAI providers.
+- **Models**: optional comma- or newline-separated model IDs to add immediately.
+
+Provider API keys are write-only. To rotate one later, edit the provider and enter a **Replacement API key**.
+
+## Add Models
+
+Open a provider and switch to its **Models** tab. Models can be added in two ways:
+
+- **Discover models** queries the provider and lets you select one or more returned model IDs.
+- **Add manually** registers a model ID directly.
+
+The main **Models** table shows each model's provider, API protocol, workspace-access count, and base URL. A model cannot be deleted while a workspace grant still references it. Revoke those grants first.
+
+## Grant Workspace Access
+
+Select **Grant Workspace Access**, then choose:
+
+- **Workspace**: the workspace that should receive the model.
+- **Route ID / ModelConfig name**: the name shown in that workspace's Model Configurations.
+- **Resource**: the provider model to grant.
+
+The grant creates a Model Configuration in the target workspace. It appears automatically on the workspace's **Agents** page, tagged **AI Gateway** as its origin. Users can select it when creating an agent without creating their own provider Secret.
+
+![Workspace Access table with an external model grant](../../../_static/screenshots/admin/external-models/grant-workspace-access.png)
+
+![Granted external model shown as an AI Gateway Model Configuration](../../../_static/screenshots/admin/external-models/grant-workspace-access-agents-tab.png)
+
+The central provider credential is not exposed to the workspace. Revoke the grant from **Workspace Access** when the workspace should no longer use the model.
+
+An admin-granted model is consumed by kagent agents through its generated Model Configuration. It is not selectable as a workload when creating a user API key on the **API Keys** page.
+
+## Usage and Cost
+
+The **Usage and Cost** panel shows authenticated Agent Gateway traffic across all workspaces. Select Last hour, Last 24 hours, Last 7 days, or Last 30 days to view:
+
+- total, successful, and failed requests;
+- request trends;
+- LLM input and output tokens;
+- estimated LLM cost.
+
+These figures are observability estimates, not billing records. Use the workspace [API Key Usage Dashboard](../platform/api_keys.html#usage-dashboard) to inspect usage attributed to visible keys in one workspace.
+
+## Related Pages
+
+- [Agents](../agentops/agents.html)
+- [Agent Gateway](../agentops/agent_gateway.html)
+- [API Keys](../platform/api_keys.html)
+- [LLM Serving](../agentops/llm_serving.html)

docs/versions/development/admin/index.md

@@ -22,6 +22,7 @@ Use these pages when you operate a prokube deployment, connect it to organizatio
 | [Network Policies](./network_policies.html) | Defining reusable egress profiles and assigning outbound network restrictions to workspaces. |
 | [Application Networking](./application_networking.html) | Exposing custom applications through prokube gateways and Istio routing. |
 | [Application Authentication](./application_authentication.html) | Choosing gateway authentication or direct OIDC for custom applications. |
+| [External Models](./external_models.html) | Connecting centrally managed model providers and granting individual models to workspaces. |
 | [Storage](./storage.html) | Understanding StorageClasses, local storage, replicated storage, and PVC troubleshooting. |
 | [GPU Administration](./gpu.html) | Operating GPU nodes, NVIDIA GPU Operator, timeslicing, MIG, and GPU monitoring. |
 | [Backup and Restore](./backup_restore.html) | Disaster-recovery scope, backup storage, restore expectations, and validation. |

docs/versions/development/agentops/agent_gateway.md

@@ -1,29 +1,55 @@
 # Agent Gateway
 
-::: info Documentation in progress
-This page is an early outline. Full Agent Gateway documentation is still being written and will be added here.
-:::
+Agent Gateway is prokube's shared routing and policy layer for external API traffic, the same layer that fronts classic model-serving endpoints and Knative services in MLOps. See [Agent Gateway](../platform/agent_gateway.html) in Foundation for the platform-wide routing model: path families, public vs. internal traffic, API keys, and the upstream [agentgateway](https://agentgateway.dev/) project it's built on.
 
-Agent Gateway provides the external API access layer for AgentOps and selected MLOps workflows.
+This page covers the AgentOps-specific angle: how Agent Gateway moves traffic between agents, tools, and models, and how agents reach external LLM providers.
 
-It is not only an agent feature. The same gateway model can protect sandbox APIs, MCP servers, agent endpoints, and classic model-serving endpoints.
+## How Agent Gateway Moves Agent Traffic
 
-## What It Does
+![Diagram: external callers reach Agent Gateway, which routes to kagent agents, MCP servers, models, and Agent Sandboxes. Agents, tools, and models inside the same workspace call each other directly over mesh identity instead.](../../../_static/diagrams/agentops/agent-gateway-flow.svg)
 
-- Exposes public API path families such as `/sandbox`, `/mcp`, `/a2a`, `/ai`, and `/serving`.
-- Enforces scoped API-key access.
-- Routes requests to workspace-scoped backends.
-- Keeps public API access separate from browser-based UI login.
+An external caller (an SDK, a CI job, or another agent outside the workspace) authenticates with an API key scoped to one of the `/a2a`, `/mcp`, `/ai`, or `/sandbox` paths. Agent Gateway checks the key's scope and workspace, then forwards the request to:
 
-## Common Use Cases
+- a **kagent agent**, over agent-to-agent (A2A);
+- an **MCP server or memory store**, for tool and retrieval access;
+- a **model**, self-hosted through [LLM Serving](llm_serving.html) or granted through [External Models](../admin/external_models.html);
+- an **Agent Sandbox**, for isolated code execution.
 
-- Calling model-serving endpoints from external applications.
-- Giving an agent access to a sandbox API without giving it browser credentials.
-- Exposing MCP servers to external agent clients.
-- Separating workspace and route scopes for automation clients.
+Inside the same workspace, none of this needs an API key: an agent calling another agent, an MCP tool, or a model authenticates automatically over Kubernetes/mesh identity. You only reach for Agent Gateway, and an API key, when the caller is outside the workspace.
 
-## API Keys
+## When to Use Agent Gateway for Agents
 
-API keys are managed through pkui. The current Python and TypeScript SDKs send API keys as `x-api-key`. Bearer-style keys are not the SDK default right now.
+- Reach kagent agents through agent-to-agent (A2A) calls from outside the cluster.
+- Expose MCP servers or memory stores to external agent clients.
+- Give an agent access to a sandbox API without handing it browser credentials.
+- Call a self-hosted or externally granted model from an external application, script, or CI job.
 
-Do not store API keys in source code, notebooks, screenshots, tickets, or chat messages.
+For interactive work in the prokube UI, use your normal user session instead. Agent Gateway is for programmatic clients. For the general routing/API-key mechanics behind all of this, see [Agent Gateway](../platform/agent_gateway.html) in Foundation.
+
+## External Models
+
+Agents can use external models through two different paths:
+
+| | User-created Model Configuration | Admin-managed external model |
+|---|---|---|
+| Providers | OpenAI, Anthropic, Gemini | Anthropic, OpenAI, Mistral AI, Azure OpenAI, GitHub Models, or a custom OpenAI-compatible endpoint |
+| Credential | API key stored in a workspace Kubernetes Secret | Provider credential managed centrally by an administrator |
+| Availability | Available only through that workspace's Model Configuration | Granted to selected workspaces and shown there as an **AI Gateway** Model Configuration |
+| Routing | Agent connects to the provider through the Model Configuration | Model traffic is routed through Agent Gateway |
+
+Use a user-created Model Configuration for a workspace-specific provider credential. Use the admin-managed path when credentials should be shared centrally, when workspaces need explicit model grants, or when the provider is not available in the self-service list.
+
+Workspace users select either type from the same Model Configurations list when creating an agent. Administrators configure providers, models, and workspace grants under [External Models](../admin/external_models.html).
+
+## Related Pages
+
+- [Agent Gateway](../platform/agent_gateway.html) (Foundation: path families, API keys, public vs. internal traffic)
+- [API Keys](../platform/api_keys.html)
+- [Agents](agents.html)
+- [LLM Serving](llm_serving.html)
+- [Agent Sandboxes](sandboxes.html)
+- [MCP Servers](mcp_servers.html)
+- [Memory Stores](memory_stores.html)
+- [External Models](../admin/external_models.html)
+- [Model Serving](../mlops/model_serving.html)
+- [Serverless](../mlops/knative.html)