From ecd014502d7fc52344ab9d5942f42ff2def7927c Mon Sep 17 00:00:00 2001 From: Peter Jausovec Date: Tue, 26 May 2026 16:32:08 -0700 Subject: [PATCH 1/4] add agentharness docs Signed-off-by: Peter Jausovec --- public/sitemap.xml | 255 +++++++++--------- src/app/docs/kagent/channels/page.mdx | 17 -- .../docs/kagent/channels/whatsapp/page.mdx | 31 --- .../kagent/concepts/agent-harness/page.mdx | 73 +++++ src/app/docs/kagent/concepts/page.mdx | 1 + .../kagent/examples/agent-harness/page.mdx | 217 +++++++++++++++ src/app/docs/kagent/examples/page.mdx | 1 + .../kagent/introduction/installation/page.mdx | 60 +++++ src/config/navigation.json | 27 +- 9 files changed, 498 insertions(+), 184 deletions(-) delete mode 100644 src/app/docs/kagent/channels/page.mdx delete mode 100644 src/app/docs/kagent/channels/whatsapp/page.mdx create mode 100644 src/app/docs/kagent/concepts/agent-harness/page.mdx create mode 100644 src/app/docs/kagent/examples/agent-harness/page.mdx diff --git a/public/sitemap.xml b/public/sitemap.xml index a17d7a01..f5bf2a95 100644 --- a/public/sitemap.xml +++ b/public/sitemap.xml @@ -2,819 +2,826 @@ https://kagent.dev/agents - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/blog - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/community - 2026-05-07 + 2026-05-26 weekly 0.8 - https://kagent.dev/docs/kagent/channels - 2026-05-07 - weekly - 0.8 - - - - https://kagent.dev/docs/kagent/channels/whatsapp - 2026-05-07 + https://kagent.dev/docs/kagent/concepts/agent-harness + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/concepts/agent-memory - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/concepts/agents - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/concepts/architecture - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/concepts - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/concepts/tools - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-agents - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/a2a-byo - 2026-05-07 + 2026-05-26 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/examples/agent-harness + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/agent-sandbox - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/agents-mcp - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/crewai-byo - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/discord-a2a - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/documentation - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/human-in-the-loop - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/langchain-byo - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/skills - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/slack-a2a - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/examples/telegram-bot - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/first-mcp-tool - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/local-development - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/quickstart - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/getting-started/system-prompts - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/introduction/features - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/introduction/installation - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/introduction - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/introduction/what-is-kagent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/observability/audit-prompts - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/observability/launch-ui - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/observability - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/observability/tracing - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/operations/debug - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/operations/operational-considerations - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/operations - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/operations/uninstall - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/operations/upgrade - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/api-ref - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-add-mcp - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-bug-report - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-build - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-completion - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-dashboard - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-deploy - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-get - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-help - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-init - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-install - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-invoke - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-mcp - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-run - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-uninstall - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli/kagent-version - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/cli - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/faq - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/helm - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/release-notes - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/resources/tools-ecosystem - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/amazon-bedrock - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/anthropic - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/azure-openai - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/byo-openai - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/gemini - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/google-vertexai - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/ollama - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/openai - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers - 2026-05-07 + 2026-05-26 + weekly + 0.8 + + + + https://kagent.dev/docs/kagent/supported-providers/sap-ai-core + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kagent/supported-providers/xai - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/install-controller - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/deploy - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/deploy/server - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/develop/fastmcp-python - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/develop/mcp-go - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/develop - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/introduction - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/quickstart - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/api-ref - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-add-tool - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-build - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-completion - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-deploy - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-help - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-init - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-install - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-run - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference/kmcp-secrets - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/reference - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs/kmcp/secrets - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/docs - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/enterprise - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/page.tsx - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/argo-rollouts-conversion-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/cilium-crd-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/helm-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/istio-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/k8s-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/kgateway-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/observability-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/agents/promql-agent - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/istio - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/kubernetes - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/prometheus - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/documentation - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/helm - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/argo - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/grafana - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/other - 2026-05-07 + 2026-05-26 weekly 0.8 https://kagent.dev/tools/cilium - 2026-05-07 + 2026-05-26 weekly 0.8 diff --git a/src/app/docs/kagent/channels/page.mdx b/src/app/docs/kagent/channels/page.mdx deleted file mode 100644 index da95dd7a..00000000 --- a/src/app/docs/kagent/channels/page.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Channels" -sectionOrder: 3 -description: "Connect kagent agents to the messaging platforms your team already uses." ---- - -export const metadata = { - title: "Channels", - description: "Connect kagent agents to the messaging platforms your team already uses.", - author: "kagent.dev" -}; - -# Channels - -Channels connect your kagent agents to the messaging platforms your team already uses. Instead of switching to a separate UI, your team interacts with agents directly inside Slack threads, Telegram chats, Discord servers, or any MCP-compatible client. - -Every channel uses the [A2A (Agent-to-Agent) protocol](/docs/kagent/examples/a2a-agents) under the hood. This means any agent you build works on any channel — no per-platform agent code required. diff --git a/src/app/docs/kagent/channels/whatsapp/page.mdx b/src/app/docs/kagent/channels/whatsapp/page.mdx deleted file mode 100644 index f932dd3c..00000000 --- a/src/app/docs/kagent/channels/whatsapp/page.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "WhatsApp" -pageOrder: 4 -description: "Connect WhatsApp to your kagent agents for mobile-first cluster operations." ---- - -export const metadata = { - title: "WhatsApp Channel for kagent", - description: "Connect WhatsApp to your kagent agents for mobile-first cluster operations.", - author: "kagent.dev" -}; - -# WhatsApp - -Connect WhatsApp to your kagent agents for mobile-first cluster operations. Manage your Kubernetes resources, ask questions, and receive alerts directly in WhatsApp conversations. - -## Status - -WhatsApp channel support is currently in development. The integration will use the WhatsApp Business API to connect your agents to WhatsApp conversations via the A2A protocol. - -## Planned features - -- **Business API integration** — authenticate using the WhatsApp Business API for reliable message delivery -- **Quick replies** — Human-in-the-Loop approval via WhatsApp quick reply buttons -- **Media support** — send and receive images, documents, and other media types -- **Group chats** — route group messages to the appropriate agent -- **Mobile-first UX** — optimized for on-the-go cluster operations from your phone - -## Get involved - -Want to help build the WhatsApp channel? Check out the [contributing guide](https://github.com/kagent-dev/kagent/blob/main/CONTRIBUTING.md) or open an issue on [GitHub](https://github.com/kagent-dev/kagent/issues). diff --git a/src/app/docs/kagent/concepts/agent-harness/page.mdx b/src/app/docs/kagent/concepts/agent-harness/page.mdx new file mode 100644 index 00000000..78380fde --- /dev/null +++ b/src/app/docs/kagent/concepts/agent-harness/page.mdx @@ -0,0 +1,73 @@ +--- +title: "Agent Harness" +pageOrder: 4 +description: "Understand AgentHarness resources, OpenShell-backed execution environments, and backend-specific channel configuration." +--- + +export const metadata = { + title: "Agent Harness", + description: "Understand AgentHarness resources, OpenShell-backed execution environments, and backend-specific channel configuration.", + author: "kagent.dev" +}; + +# Agent Harness + +An `AgentHarness` is a Kubernetes resource that asks kagent to provision a long-running remote execution environment through an OpenShell gateway. It is useful when you want a managed sandbox that can be attached to, bootstrapped, and connected to messaging channels, but you do not want kagent to package and run a full agent runtime inside the workload. + +`AgentHarness` resources appear alongside agents in kagent APIs and status views, but they are not the same thing as `Agent` or `SandboxAgent`. + +## How it differs from agents + +- `Agent` runs a kagent-managed agent runtime, such as a declarative agent or a bring-your-own container. +- `SandboxAgent` runs an agent runtime inside a restricted sandboxed workload. +- `AgentHarness` provisions the execution environment itself. The selected backend decides what is installed and how the environment is bootstrapped. + +Think of `AgentHarness` as lifecycle management for a remote shell or VM-like sandbox. It gives kagent a Kubernetes-native handle for creating, tracking, deleting, and surfacing that environment. + +## Backend model + +The `spec.backend` field selects the backend implementation. + +| Backend | Purpose | +| --- | --- | +| `openclaw` | Provisions an OpenClaw-compatible sandbox and writes OpenClaw configuration when a `ModelConfig` is referenced. | +| `nemoclaw` | Uses the OpenClaw/NemoClaw backend path while preserving a distinct backend value for NemoClaw-oriented environments. | +| `hermes` | Provisions a Hermes sandbox and writes Hermes configuration plus environment files for supported messaging channels. | + +All backends use the same top-level `AgentHarness` shape: `backend`, `description`, `image`, `env`, `network`, `modelConfigRef`, and `channels`. + +## Lifecycle and status + +When the controller reconciles an `AgentHarness`, it translates the Kubernetes spec into an OpenShell sandbox request. If the sandbox already exists, reconciliation is idempotent and kagent reuses it. + +The resource reports two primary conditions: + +- `Accepted` tells you whether kagent accepted the spec and could hand it to the selected backend. +- `Ready` tells you whether the backend sandbox is available. + +Once the sandbox exists, `.status.backendRef` records the backend and sandbox ID, and `.status.connection.endpoint` contains the connection hint returned by kagent. + +## Models and images + +`spec.modelConfigRef` points at a kagent `ModelConfig`. OpenClaw-compatible backends translate that model configuration into OpenClaw bootstrap config. Hermes uses the referenced model while building its Hermes configuration. + +If `spec.image` is omitted, kagent uses the default base image for the selected backend. Set `spec.image` only when you have a backend-compatible custom image. + +## Network access + +`spec.network.allowedDomains` limits outbound access from the harness when the backend supports network policy. Keep this list focused on the APIs the harness needs, such as model provider endpoints or messaging-provider APIs. + +## Channels + +`spec.channels` declares messaging integrations inside the harness environment. Each channel has a stable `name`, a `type`, and exactly one matching channel spec. + +Slack has backend-specific settings because OpenClaw/NemoClaw and Hermes use Slack differently: + +- OpenClaw and NemoClaw settings live under `slack.openclaw` and configure channel access, allowlisted Slack channels, and interactive replies. +- Hermes settings live under `slack.hermes` and configure allowed Slack users plus the home channel used for scheduled messages. + +The API uses CEL validation to ensure Slack settings match the selected backend. A Hermes harness must use `slack.hermes`; an OpenClaw or NemoClaw harness must use `slack.openclaw`. + +## Next steps + +For OpenShell installation and kagent Helm values, see [Enable AgentHarness support](/docs/kagent/introduction/installation#enable-agentharness-support). For complete YAML examples, including Slack token references and backend-specific Slack settings, see the [Agent Harness example](/docs/kagent/examples/agent-harness). For the generated schema, see the [API reference](/docs/kagent/resources/api-ref#agentharness). diff --git a/src/app/docs/kagent/concepts/page.mdx b/src/app/docs/kagent/concepts/page.mdx index f2e326fb..70c7ed1c 100644 --- a/src/app/docs/kagent/concepts/page.mdx +++ b/src/app/docs/kagent/concepts/page.mdx @@ -24,6 +24,7 @@ import QuickLink from '@/components/quick-link'; + diff --git a/src/app/docs/kagent/examples/agent-harness/page.mdx b/src/app/docs/kagent/examples/agent-harness/page.mdx new file mode 100644 index 00000000..ff190efe --- /dev/null +++ b/src/app/docs/kagent/examples/agent-harness/page.mdx @@ -0,0 +1,217 @@ +--- +title: "Agent Harness" +pageOrder: 8 +description: "Provision OpenClaw, NemoClaw, and Hermes sandboxes with the AgentHarness API." +--- + +import { VERSIONS } from "../../../_constants"; + +export const metadata = { + title: "Agent Harness", + description: "Provision OpenClaw, NemoClaw, and Hermes sandboxes with the AgentHarness API.", + author: "kagent.dev" +}; + +# Agent Harness + +`AgentHarness` creates a long-running remote execution environment through an OpenShell gateway. Unlike an `Agent` or `SandboxAgent`, it does not package a kagent runtime into the workload. The backend provisions a sandbox that operators, tools, or chat integrations can attach to. + +Use `AgentHarness` when you want kagent to manage the lifecycle of an OpenClaw, NemoClaw, or Hermes sandbox and surface it in the kagent API/UI alongside regular agents. + +## Before you begin + +1. Install kagent v{VERSIONS.kagent} or later by following the [quick start](/docs/kagent/getting-started/quickstart) guide. +2. Install and expose an OpenShell gateway that the kagent controller can reach over gRPC. For Helm-based setup instructions, see [Enable AgentHarness support](/docs/kagent/introduction/installation#enable-agentharness-support). +3. Configure the kagent controller with the gateway address. For example, set the controller environment variable `OPENSHELL_GATEWAY_URL` to a gRPC target such as `dns:///openshell.openshell.svc:443`. + +When `OPENSHELL_GATEWAY_URL` is empty, the AgentHarness backends are not registered by the controller. + +## Choose a backend + +`spec.backend` selects the sandbox backend. + +- `openclaw` provisions an OpenClaw-compatible sandbox. When `modelConfigRef` is set, kagent translates the referenced `ModelConfig` and writes OpenClaw configuration into the sandbox. +- `nemoclaw` uses the same kagent backend path as `openclaw`, but lets you label the resource for NemoClaw-oriented usage. +- `hermes` provisions a Hermes sandbox. kagent writes Hermes configuration and environment files into the sandbox and wires supported messaging channels into Hermes environment variables. + +All three backends share the same top-level `AgentHarness` shape: `backend`, optional `description`, optional `image`, optional `env`, optional `network`, optional `modelConfigRef`, and optional `channels`. + +## Create an OpenClaw harness + +The following resource creates an OpenClaw harness and lets it reach the OpenAI and Slack APIs. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: AgentHarness +metadata: + name: openclaw-shell + namespace: kagent +spec: + backend: openclaw + description: "OpenClaw shell for platform experiments" + modelConfigRef: default-model-config + network: + allowedDomains: + - api.openai.com + - slack.com + - api.slack.com + - hooks.slack.com + - wss-primary.slack.com + - wss-backup.slack.com +``` + +Apply the resource and wait for it to become ready. + +```bash +kubectl apply -f openclaw-shell.yaml +kubectl -n kagent get agentharness openclaw-shell +``` + +Example output: + +```txt +NAME BACKEND READY ID AGE +openclaw-shell openclaw True kagent-openclaw-shell 30s +``` + +## Create a Hermes harness + +Hermes uses the same `AgentHarness` API with `spec.backend: hermes`. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: AgentHarness +metadata: + name: hermes-shell + namespace: kagent +spec: + backend: hermes + description: "Hermes shell for scheduled and chat-driven workflows" + modelConfigRef: default-model-config + network: + allowedDomains: + - api.openai.com + - slack.com + - api.slack.com + - wss-primary.slack.com + - wss-backup.slack.com +``` + +If `spec.image` is omitted, kagent uses the backend's default sandbox base image. Set `spec.image` only when you need a custom image that is compatible with the selected backend. + +## Configure Slack + +Slack channels require a bot token and an app-level token. Store them in a Kubernetes `Secret` and reference them from the harness. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: slack-tokens + namespace: kagent +type: Opaque +stringData: + bot-token: xoxb-your-bot-token + app-token: xapp-your-app-token +``` + +Backend-specific Slack settings are nested under the backend name. The API validates this with CEL: + +- `backend: hermes` requires `slack.hermes` and rejects `slack.openclaw`. +- `backend: openclaw` and `backend: nemoclaw` require `slack.openclaw` and reject `slack.hermes`. + +### OpenClaw Slack + +OpenClaw and NemoClaw Slack settings control channel access and interactive replies. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: AgentHarness +metadata: + name: openclaw-slack + namespace: kagent +spec: + backend: openclaw + modelConfigRef: default-model-config + channels: + - name: platform + type: slack + slack: + botToken: + valueFrom: + type: Secret + name: slack-tokens + key: bot-token + appToken: + valueFrom: + type: Secret + name: slack-tokens + key: app-token + openclaw: + channelAccess: allowlist + allowlistChannels: + - C0123456789 + interactiveReplies: true +``` + +Set `channelAccess` to `open`, `allowlist`, or `disabled`. When `channelAccess` is `allowlist`, `allowlistChannels` must include at least one Slack channel ID. + +### Hermes Slack + +Hermes Slack settings control allowed users and the home channel used for scheduled messages. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: AgentHarness +metadata: + name: hermes-slack + namespace: kagent +spec: + backend: hermes + modelConfigRef: default-model-config + channels: + - name: platform + type: slack + slack: + botToken: + valueFrom: + type: Secret + name: slack-tokens + key: bot-token + appToken: + valueFrom: + type: Secret + name: slack-tokens + key: app-token + hermes: + allowedUserIDs: + - U01234567 + - U89ABCDEF + homeChannel: C0123456789 + homeChannelName: platform-alerts +``` + +Use `allowedUserIDsFrom` instead of `allowedUserIDs` when you want to load the Slack member allowlist from a Secret or ConfigMap key. The two fields are mutually exclusive. + +## Check status + +Use `kubectl` to confirm the harness was accepted and is ready. + +```bash +kubectl -n kagent get agentharnesses +kubectl -n kagent describe agentharness hermes-slack +``` + +The `Accepted` condition reports whether kagent accepted the spec. The `Ready` condition reports whether the backend sandbox is ready. Once ready, `.status.backendRef` identifies the sandbox in the OpenShell control plane and `.status.connection.endpoint` shows the connection hint returned by kagent. + +## Troubleshooting + +If the harness is not accepted or ready, check these common causes. + +- The kagent controller was not configured with `OPENSHELL_GATEWAY_URL`, so AgentHarness backends were not registered. +- The OpenShell gateway address is not reachable from the controller pod. +- `modelConfigRef` points to a missing or unsupported `ModelConfig`. +- A Slack channel has the wrong backend settings, such as `slack.hermes` on an OpenClaw harness or `slack.openclaw` on a Hermes harness. +- A Slack credential uses neither `value` nor `valueFrom`, or sets both. + +For the complete generated schema, see the [API reference](/docs/kagent/resources/api-ref#agentharness). diff --git a/src/app/docs/kagent/examples/page.mdx b/src/app/docs/kagent/examples/page.mdx index 1234910e..3d7b93ba 100644 --- a/src/app/docs/kagent/examples/page.mdx +++ b/src/app/docs/kagent/examples/page.mdx @@ -31,5 +31,6 @@ import QuickLink from '@/components/quick-link'; + diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 011a1f3e..7484fc25 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -197,6 +197,66 @@ Another way to install kagent is using Helm. Review the following advanced configuration options that you might want to set up for your kagent installation. +### Enable AgentHarness support + +`AgentHarness` resources require an OpenShell gateway that the kagent controller can reach. To enable the AgentHarness backends, install OpenShell and set `OPENSHELL_GATEWAY_URL` on the kagent controller deployment. + +1. Install OpenShell in your cluster. + + ```bash + kubectl create namespace openshell + kubectl -n openshell create secret generic openshell-ssh-handshake \ + --from-literal=secret="$(openssl rand -hex 32)" + + kubectl apply -f https://raw.githubusercontent.com/NVIDIA/OpenShell/refs/heads/main/deploy/kube/manifests/agent-sandbox.yaml + + helm upgrade --install openshell oci://ghcr.io/nvidia/openshell/helm-chart \ + --version 0.0.49 \ + --namespace openshell \ + --create-namespace \ + --values - <<'EOF' + server: + disableTls: true + auth: + allowUnauthenticatedUsers: true + service: + metricsPort: 0 + EOF + + This example disables TLS and authentication. For production environments, configure TLS and authentication according to your OpenShell requirements. + +2. Configure the kagent controller with the OpenShell gateway URL. + + **Helm values file:** + + ```yaml + controller: + openshell: + enabled: "true" + env: + - name: OPENSHELL_GATEWAY_URL + value: dns:///openshell.openshell.svc:8080 + - name: OPENSHELL_INSECURE + value: "true" + ``` + + **Helm `--set` flags:** + + ```bash + helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --namespace kagent \ + --set controller.openshell.enabled=true \ + --set 'controller.env[0].name=OPENSHELL_GATEWAY_URL' \ + --set-string 'controller.env[0].value=dns:///openshell.openshell.svc:8080' \ + --set 'controller.env[1].name=OPENSHELL_INSECURE' \ + --set-string 'controller.env[1].value=true' + + ``` + + If you already configure `controller.env`, merge the `OPENSHELL_GATEWAY_URL` entry into your existing values. When `OPENSHELL_GATEWAY_URL` is empty, the controller does not register AgentHarness backends. + +For more information about creating harness resources, see [Agent Harness](/docs/kagent/examples/agent-harness). + ### Database configuration For production environments, set up kagent with an external PostgreSQL instance. For more information, see the [Database configuration guide](/operations/operational-considerations/#database-configuration). diff --git a/src/config/navigation.json b/src/config/navigation.json index 1a721689..e2a0fd09 100644 --- a/src/config/navigation.json +++ b/src/config/navigation.json @@ -69,18 +69,6 @@ } ] }, - { - "title": "Channels", - "href": "/docs/kagent/channels", - "description": "Connect kagent agents to the messaging platforms your team already uses.", - "items": [ - { - "title": "WhatsApp", - "href": "/docs/kagent/channels/whatsapp", - "description": "Connect WhatsApp to your kagent agents for mobile-first cluster operations." - } - ] - }, { "title": "Core Concepts", "href": "/docs/kagent/concepts", @@ -101,6 +89,11 @@ "href": "/docs/kagent/concepts/tools", "description": "Understand the different types of tools kagent can use, including built-in, MCP, and HTTP tools, and how tool discovery works." }, + { + "title": "Agent Harness", + "href": "/docs/kagent/concepts/agent-harness", + "description": "Understand AgentHarness resources, OpenShell-backed execution environments, and backend-specific channel configuration." + }, { "title": "Agent Memory", "href": "/docs/kagent/concepts/agent-memory", @@ -157,6 +150,11 @@ "title": "xAI (Grok)", "href": "/docs/kagent/supported-providers/xai", "description": "Learn how to configure xAI Grok models for kagent." + }, + { + "title": "SAP AI Core", + "href": "/docs/kagent/supported-providers/sap-ai-core", + "description": "Learn how to configure SAP AI Core models for kagent." } ] }, @@ -224,6 +222,11 @@ "title": "Human-in-the-Loop", "href": "/docs/kagent/examples/human-in-the-loop", "description": "Build a Kubernetes-native AI agent that pauses and asks for your approval before taking destructive actions." + }, + { + "title": "Agent Harness", + "href": "/docs/kagent/examples/agent-harness", + "description": "Provision OpenClaw, NemoClaw, and Hermes sandboxes with the AgentHarness API." } ] }, From d17461269bfb7109c4df8fdd0e726fde2ff05d02 Mon Sep 17 00:00:00 2001 From: Peter Jausovec Date: Fri, 29 May 2026 11:19:54 -0700 Subject: [PATCH 2/4] Update src/app/docs/kagent/introduction/installation/page.mdx Co-authored-by: Art Signed-off-by: Peter Jausovec --- src/app/docs/kagent/introduction/installation/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/introduction/installation/page.mdx b/src/app/docs/kagent/introduction/installation/page.mdx index 7484fc25..33bfac9a 100644 --- a/src/app/docs/kagent/introduction/installation/page.mdx +++ b/src/app/docs/kagent/introduction/installation/page.mdx @@ -223,7 +223,7 @@ Review the following advanced configuration options that you might want to set u metricsPort: 0 EOF - This example disables TLS and authentication. For production environments, configure TLS and authentication according to your OpenShell requirements. + This example disables TLS and authentication. For production environments, configure TLS and authentication according to your OpenShell requirements. 2. Configure the kagent controller with the OpenShell gateway URL. From bd1c3c52eb48e2a9ab5c2e9cc6d24ef9bf722f4a Mon Sep 17 00:00:00 2001 From: Peter Jausovec Date: Fri, 29 May 2026 11:20:07 -0700 Subject: [PATCH 3/4] Update src/app/docs/kagent/concepts/agent-harness/page.mdx Co-authored-by: Art Signed-off-by: Peter Jausovec --- src/app/docs/kagent/concepts/agent-harness/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/concepts/agent-harness/page.mdx b/src/app/docs/kagent/concepts/agent-harness/page.mdx index 78380fde..38557be2 100644 --- a/src/app/docs/kagent/concepts/agent-harness/page.mdx +++ b/src/app/docs/kagent/concepts/agent-harness/page.mdx @@ -12,7 +12,7 @@ export const metadata = { # Agent Harness -An `AgentHarness` is a Kubernetes resource that asks kagent to provision a long-running remote execution environment through an OpenShell gateway. It is useful when you want a managed sandbox that can be attached to, bootstrapped, and connected to messaging channels, but you do not want kagent to package and run a full agent runtime inside the workload. +An `AgentHarness` is a Kubernetes custom resource that asks kagent to provision a long-running remote execution environment through an [OpenShell](https://github.com/NVIDIA/OpenShell) gateway. It is useful when you want a managed sandbox that can be attached to, bootstrapped, and connected to messaging channels, but you do not want kagent to package and run a full agent runtime inside the workload. `AgentHarness` resources appear alongside agents in kagent APIs and status views, but they are not the same thing as `Agent` or `SandboxAgent`. From b31734097650c0e922bed45adbeea9624e4470f2 Mon Sep 17 00:00:00 2001 From: Peter Jausovec Date: Fri, 29 May 2026 11:20:22 -0700 Subject: [PATCH 4/4] Update src/app/docs/kagent/concepts/agent-harness/page.mdx Co-authored-by: Art Signed-off-by: Peter Jausovec --- src/app/docs/kagent/concepts/agent-harness/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/docs/kagent/concepts/agent-harness/page.mdx b/src/app/docs/kagent/concepts/agent-harness/page.mdx index 38557be2..4e92ec5e 100644 --- a/src/app/docs/kagent/concepts/agent-harness/page.mdx +++ b/src/app/docs/kagent/concepts/agent-harness/page.mdx @@ -59,7 +59,7 @@ If `spec.image` is omitted, kagent uses the default base image for the selected ## Channels -`spec.channels` declares messaging integrations inside the harness environment. Each channel has a stable `name`, a `type`, and exactly one matching channel spec. +`spec.channels` declares the external messaging platform (such as Slack) that you want to integrate with the harness. Each channel has a stable `name`, a `type`, and exactly one matching channel spec. Slack has backend-specific settings because OpenClaw/NemoClaw and Hermes use Slack differently: