ai-assistant: docs/holmes: Add Holmes integration guide#884
Open
illume wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page describing how the AI Assistant plugin integrates with a HolmesGPT agent running in-cluster, including setup steps and developer-facing API usage patterns.
Changes:
- Adds an architecture overview for HolmesGPT ↔ AI Assistant communication via AG-UI + Kubernetes service proxy.
- Documents installation/config steps for deploying HolmesGPT and enabling the AG-UI server.
- Provides “Programmatic Usage” examples (health check, HolmesAgent usage) plus troubleshooting and references.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| The HolmesGPT integration helps teams troubleshoot Kubernetes by turning cluster signals into clear explanations. It helps you understand what is happening and what to do next while you stay focused on the workload you are investigating. | ||
|
|
||
| This works well because the AI Assistant is context aware. It can use the cluster context you are already viewing to provide more relevant diagnostics. |
Comment on lines
+21
to
+25
| 1. **`HolmesAgent`** (`@headlamp-k8s/ai-common/agent/holmesClient`) — wraps `@ag-ui/client`'s `HttpAgent` to communicate with the Holmes AG-UI server via SSE. Manages conversation threads, message history, and event subscriptions. | ||
|
|
||
| 2. **Kubernetes Service proxy** — requests are routed through the Kubernetes API server's service proxy (`/api/v1/namespaces/{ns}/services/{svc}:{port}/proxy`). The `getHolmesServiceProxyPath()` function builds this path. | ||
|
|
||
| 3. **Injectable `ClusterRequestFn`** — the cluster request function is injected by the host application (e.g. headlamp-plugin's `clusterRequest`), keeping `ai-common` free of platform-specific dependencies. |
|
|
||
| ## Programmatic Usage | ||
|
|
||
| The `holmesClient` module in `@headlamp-k8s/ai-common` provides the building blocks for integrating with HolmesGPT programmatically. |
| Use `checkHolmesAgentHealth()` to verify the Holmes agent is reachable: | ||
|
|
||
| ```typescript | ||
| import { checkHolmesAgentHealth } from '@headlamp-k8s/ai-common/agent/holmesClient'; |
| ```typescript | ||
| import { checkHolmesAgentHealth } from '@headlamp-k8s/ai-common/agent/holmesClient'; | ||
|
|
||
| // Inject your platform's cluster request function |
Comment on lines
+181
to
+188
| | Prop | Type | Description | | ||
| |---|---|---| | ||
| | `config` | `any \| null` | Current plugin config object | | ||
| | `onConfigChange` | `(patch) => void` | Callback when a field changes | | ||
| | `SectionWrapper` | `React.ComponentType` | Optional layout wrapper (defaults to simple Box) | | ||
| | `defaultNamespace` | `string` | Override default namespace (`default`) | | ||
| | `defaultServiceName` | `string` | Override default service name (`holmesgpt-holmes`) | | ||
| | `defaultPort` | `number` | Override default port (`80`) | |
Comment on lines
+192
to
+201
| ### Injectable ClusterRequestFn | ||
|
|
||
| The `ClusterRequestFn` interface allows platform-specific cluster request implementations to be injected: | ||
|
|
||
| ```typescript | ||
| type ClusterRequestFn = ( | ||
| path: string, | ||
| options: { cluster: string; isJSON: boolean; timeout: number } | ||
| ) => Promise<any>; | ||
| ``` |
Comment on lines
+206
to
+209
| import { clusterRequest } from '@kinvolk/headlamp-plugin/lib/ApiProxy'; | ||
| import { checkHolmesAgentHealth } from '@headlamp-k8s/ai-common/agent/holmesClient'; | ||
|
|
||
| const isHealthy = await checkHolmesAgentHealth(clusterRequest, cluster); |
Comment on lines
+28
to
+29
| AI Assistant → ClusterRequestFn → K8s API Server → Service Proxy → Holmes Pod | ||
| (injected) (proxy path) (ag-ui/chat) |
| }); | ||
| ``` | ||
|
|
||
| The health check probes the root path (`/`) of the Holmes service via the Kubernetes service proxy. A non-503 response means the pod is reachable (even 404/405 from the Holmes server itself indicates successful proxy forwarding). |
illume
force-pushed
the
docs/ai-assistant-holmes-integration
branch
2 times, most recently
from
01ea908 to
683ac15
Compare
Documents the HolmesGPT integration. HolmesGPT runs as an agent in the user's cluster. The AI Assistant connects to it via the AG-UI protocol through the Kubernetes API server proxy. The guide covers: - Why HolmesGPT complements the AI Assistant: it adds reasoning across logs, events, and resource state to move from symptoms to likely causes. - The `HolmesAgent` client in `ai-common/src/agent/holmesClient.ts`: AG-UI thread management, `subscribe`/`addMessage`/`runAgent` interface, and the K8s service proxy path construction. - `MockHolmesAgent`: a deterministic stub for offline testing that replays canned AG-UI event sequences without a live cluster. - Configuration: `holmesServiceUrl` setting in the AI Assistant settings page. Signed-off-by: René Dudfield <renedudfield@microsoft.com> Co-authored-by: Ashu Ghildiyal <aghildiyal@microsoft.com> Signed-off-by: Ashu Ghildiyal <aghildiyal@microsoft.com>
illume
force-pushed
the
docs/ai-assistant-holmes-integration
branch
from
683ac15 to
1ffe1a5
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
docs/holmes/holmes-integration.mdexplaining how the AI assistant integrates with HolmesGPT: the subscribe/addMessage/runAgent interface,MockHolmesAgentfor testing, and how the Holmes agent fits into the provider model.Assisted by Copilot.
Part of the ai-assistant Holmes documentation series.