/__BR_TAG__/g' "src/app/docs/kagent/resources/api-ref/page.mdx" - - # Convert remaining angle brackets to HTML entities - sed -i 's//\>/g' "src/app/docs/kagent/resources/api-ref/page.mdx" - - # Restore legitimate HTML tags - sed -i 's/__BR_TAG__/
/g' "src/app/docs/kagent/resources/api-ref/page.mdx" - # Verify the output file was created - if [ ! -f "src/app/docs/kagent/resources/api-ref/page.mdx" ]; then + if [ ! -f "$KAGENT_API_PAGE" ]; then echo "Error: Failed to create API docs page" exit 1 fi @@ -158,7 +162,7 @@ jobs: echo "Error: crd-ref-docs-config.yaml not found in scripts directory" exit 1 fi - + envsubst < scripts/crd-ref-docs-config.yaml > crd-ref-docs-config.yaml echo "Changed to docs repository: $PWD" @@ -181,41 +185,30 @@ jobs: # Remove the temporary config file so it is not included in the PR rm -f crd-ref-docs-config.yaml - # Create index file with frontmatter - echo '---' > src/app/docs/kmcp/reference/api-ref/page.mdx - echo 'title: "API docs"' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo 'pageOrder: 5' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo 'description: "kmcp API reference documentation"' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo '---' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo '' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo 'export const metadata = {' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo ' title: "API docs",' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo ' description: "kmcp API reference documentation",' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo ' author: "kagent.dev"' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo '};' >> src/app/docs/kmcp/reference/api-ref/page.mdx - echo '' >> src/app/docs/kmcp/reference/api-ref/page.mdx - cat "./out.md" >> src/app/docs/kmcp/reference/api-ref/page.mdx - - # Remove temporary file + # Fix problematic angle brackets (see the kagent step for rationale). + echo "Fixing problematic angle brackets in generated markdown..." + sed -i 's/
/__BR_TAG__/g' "./out.md" + sed -i 's//\>/g' "./out.md" + sed -i 's/__BR_TAG__/
/g' "./out.md" + + # Write the Hugo page: plain YAML frontmatter + generated body. + mkdir -p "$(dirname "$KMCP_API_PAGE")" + cat > "$KMCP_API_PAGE" <<'EOF' + --- + title: API Reference + linkTitle: API docs + description: kmcp API reference documentation + weight: 5 + author: kagent.dev + --- + + EOF + cat "./out.md" >> "$KMCP_API_PAGE" rm -f "./out.md" - # Fix problematic angle brackets in the generated MDX file - # Convert literal angle brackets to HTML entities to prevent MDX parsing errors - # But preserve legitimate HTML tags like
,
/__BR_TAG__/g' "src/app/docs/kmcp/reference/api-ref/page.mdx" - - # Convert remaining angle brackets to HTML entities - sed -i 's//\>/g' "src/app/docs/kmcp/reference/api-ref/page.mdx" - - # Restore legitimate HTML tags - sed -i 's/__BR_TAG__/
/g' "src/app/docs/kmcp/reference/api-ref/page.mdx" - # Verify the output file was created - if [ ! -f "src/app/docs/kmcp/reference/api-ref/page.mdx" ]; then + if [ ! -f "$KMCP_API_PAGE" ]; then echo "Error: Failed to create KMCP API docs page" exit 1 fi @@ -226,133 +219,95 @@ jobs: run: | echo "Looking for Helm directory:" ls -la "$GITHUB_WORKSPACE/kagent/helm" || echo "Helm directory not found!" - + # Update docs repository cd "$GITHUB_WORKSPACE/website" echo "Changed to docs repository: $PWD" - # Create directory for Helm docs - mkdir -p src/app/docs/kagent/resources/helm/ - # Generate Helm Docs for kagent chart if [ ! -d "$GITHUB_WORKSPACE/kagent/helm/kagent" ]; then echo "Error: kagent Helm chart directory not found" exit 1 fi - + echo "Processing kagent Helm chart..." - + echo "Chart directory contents:" ls -la "$GITHUB_WORKSPACE/kagent/helm/kagent/" - + # Generate Chart.yaml from template for helm-docs to work echo "Generating Chart.yaml from template..." cd "$GITHUB_WORKSPACE/kagent/helm/kagent" - + # Get the version from git or use a default VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "0.5.5") echo "Using version: $VERSION" - + # Copy template and substitute version cp Chart-template.yaml Chart.yaml sed -i "s/\${VERSION}/$VERSION/g" Chart.yaml - + echo "Generated Chart.yaml contents:" cat Chart.yaml - + # Go back to website directory cd "$GITHUB_WORKSPACE/website" - + echo "Chart.yaml contents:" cat "$GITHUB_WORKSPACE/kagent/helm/kagent/Chart.yaml" || echo "Chart.yaml not found!" - + echo "Values.yaml contents (first 20 lines):" head -20 "$GITHUB_WORKSPACE/kagent/helm/kagent/values.yaml" || echo "values.yaml not found!" - + # Generate the helm documentation echo "Running helm-docs..." - - # Debug: Show all available paths - echo "Available paths:" - echo "GITHUB_WORKSPACE: $GITHUB_WORKSPACE" - echo "Current directory: $PWD" - echo "kagent repo path: $GITHUB_WORKSPACE/kagent" - echo "kagent helm path: $GITHUB_WORKSPACE/kagent/helm" - echo "kagent chart path: $GITHUB_WORKSPACE/kagent/helm/kagent" - - # List all helm directories to see what's available - echo "All helm directories:" find "$GITHUB_WORKSPACE/kagent/helm" -name "Chart.yaml" -type f 2>/dev/null | head -10 - - # Check if the specific chart directory exists and what's in it - echo "Checking chart directory:" - if [ -d "$GITHUB_WORKSPACE/kagent/helm/kagent" ]; then - echo "Chart directory exists" - ls -la "$GITHUB_WORKSPACE/kagent/helm/kagent/" - echo "Chart.yaml exists: $([ -f "$GITHUB_WORKSPACE/kagent/helm/kagent/Chart.yaml" ] && echo "YES" || echo "NO")" - echo "Values.yaml exists: $([ -f "$GITHUB_WORKSPACE/kagent/helm/kagent/values.yaml" ] && echo "YES" || echo "NO")" - else - echo "Chart directory does NOT exist" - fi - - # Generate the helm documentation + go run github.com/norwoodj/helm-docs/cmd/helm-docs@v1.14.2 \ --chart-search-root "$GITHUB_WORKSPACE/kagent/helm/kagent" \ - --dry-run > "src/app/docs/kagent/resources/helm/temp.mdx" - - # Go back to website directory - cd "$GITHUB_WORKSPACE/website" + --dry-run > "helm-temp.md" echo "Generated helm-docs output (first 50 lines):" - head -50 "src/app/docs/kagent/resources/helm/temp.mdx" - - echo "Generated helm-docs output (last 50 lines):" - tail -50 "src/app/docs/kagent/resources/helm/temp.mdx" - + head -50 "helm-temp.md" echo "Total lines generated:" - wc -l "src/app/docs/kagent/resources/helm/temp.mdx" + wc -l "helm-temp.md" + + # Remove the badge line and following empty line + # (might be replaced by a helm-docs template in the future). + sed -i '/!\[Version:/,/^$/d' "helm-temp.md" - # Remove badge line and following empty line - # (might be replaced by helm docs template in the future) - sed -i '/!\[Version:/,/^$/d' "src/app/docs/kagent/resources/helm/temp.mdx" + # Drop the leading `#
wrapper, so there's no margin-top from + the next element. Using padding-bottom avoids doubling up with + margin collapsing when a proper
does follow. */ +/* Space between headings and following content. Needed because reuse + shortcode output often has no
wrapper, leaving bare text/links + with no margin-top to create a gap after the heading. */ +.content :is(h1, h2, h3, h4, h5, h6) { + margin-bottom: 0.75rem !important; +} + +/* Space between text and code blocks inside list items and after bare text */ +.content li > .hextra-code-block, +.content li > pre { + margin-top: 0.75rem; +} + +/* Sidebar child indent border - dark mode */ +.dark .sidebar-container ul[style*="border-left"] { + border-left-color: #374151 !important; +} + + + +/* ── Print styles ─────────────────────────────────────────────────────── */ +@media print { + @page { margin: 1.5cm 2cm; } + + /* Hide UI chrome — sidebar/TOC already have hx:print:hidden from hextra */ + .copy-md-wrapper, + .navbar, + .desktop-navbar, + .mobile-nav-bar, + .mobile-nav, + .hextra-nav-container, + footer, + .hextra-component-issue, + [class*="pager"], + [class*="page-feedback"], + [class*="last-updated"], + [class*="comments"], + #chatbot-widget { display: none !important; } + + /* Let article fill the printable area */ + body, html { overflow: visible !important; } + article { + display: block !important; + width: 100% !important; + max-width: 100% !important; + padding-right: 0 !important; + min-height: 0 !important; + } + article > main { + max-width: 100% !important; + padding-left: 0 !important; + padding-right: 0 !important; + } + + /* Fix the main cause: code blocks clip at the paper edge on screen overflow */ + pre, code { + white-space: pre-wrap !important; + overflow: visible !important; + word-break: break-word !important; + max-width: 100% !important; + } + + /* Chroma lntable: the general pre/code rules above collapse the line-number + column at page breaks, causing two-digit numbers to split across lines. + Undo word-break and max-width constraints for that column only. */ + .lntable { width: 100%; } + .lntable .lntd:first-child pre, + .lntable .lntd:first-child code { + white-space: pre !important; + word-break: normal !important; + overflow-wrap: normal !important; + max-width: none !important; + min-width: 2.5em; + } + + /* Avoid breaking inside short blocks; don't force headings to next page */ + blockquote, figure, img { break-inside: avoid; } +} + + +/* ── Top-nav dropdown popover (Docs → kagent/kmcp) ───────────────────── + The Docs menu item has child entries, so Hextra renders it as a dropdown + whose popover is
- . Hextra styles that
+ popover with hx: utility classes for the background, border, radius, and
+ shadow, but in this extras/Tailwind build the border/shadow rely on runtime
+ --tw-* vars that do not materialize here, so the box renders invisibly (white
+ on the white page). Style it explicitly — same values as agw-oss'
+ .navbar-dropdown-content — so the popover reads as a distinct card. */
+.hextra-nav-menu-items {
+ padding: 0.5rem;
+ background-color: white;
+ border: 1px solid rgba(0, 0, 0, 0.1);
+ border-radius: 0.5rem;
+ box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+}
+:where(.dark, .dark *) .hextra-nav-menu-items {
+ background-color: rgb(17, 24, 39); /* gray-900 */
+ border-color: rgba(255, 255, 255, 0.1);
+}
+
+/* Dropdown item spacing lives here, NOT in hx: utility classes: ad-hoc hx:
+ spacing values (gap-3, px-4, py-2.5, …) that Hextra core doesn't already use
+ are not generated in this Tailwind build, so they silently no-op. */
+.hextra-nav-menu-items a {
+ display: flex;
+ align-items: center;
+ gap: 0.75rem;
+ padding: 0.5rem 1rem;
+ border-radius: 0.375rem;
+}
+
+/* Product icons in the Docs dropdown (assets/icons/nav-*.svg, inlined by
+ navbar-link.html). Fixed-width, right-aligned icon column so (a) the labels
+ line up and (b) the gap to each label is uniform even though the marks differ
+ in aspect ratio (kagent is wide, kmcp square). Icons inherit currentColor. */
+.nav-menu-icon {
+ width: 1.4rem;
+ flex: none;
+ justify-content: flex-end;
+}
+.nav-menu-icon svg {
+ height: 1rem;
+ width: auto;
+ max-width: 100%;
+ display: block;
+}
+
+/* ── Navbar logo light/dark switch ────────────────────────────────────────
+ The two logo
A2A↔ACP bridge (ACP client)"] + subgraph actor["Substrate actor"] + shim["acp-shim (WS ↔ stdio)"] + backend["openclaw acp / hermes acp"] + shim --> backend + end + client -->|"A2A (JSON-RPC over HTTP/SSE)"| controller + controller -->|"ACP over WebSocket (Substrate ingress)"| shim + client:::external + controller:::internal + shim:::internal + backend:::internal + classDef internal stroke:#a78bfa,fill:transparent + classDef external stroke:#fb923c,fill:transparent + style actor stroke:#2962FF,fill:transparent +``` + +This means you can open a harness in the kagent UI and chat with it like any other agent — see streamed tool activity and answer tool-approval prompts — without any backend-specific UI. Tool approvals from the harness map onto kagent's human-in-the-loop flow. + +## 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 sandbox base image for the selected backend. Set `spec.image` only when you have a backend-compatible custom image. + +## Channels + +`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 and Hermes use Slack differently: + +- OpenClaw 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 harness must use `slack.openclaw`. + +## Next steps + +For enabling Agent Substrate so the controller can provision harnesses, 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/docs-site/content/kagent/concepts/agent-memory.md b/docs-site/content/kagent/concepts/agent-memory.md new file mode 100644 index 00000000..3e85e470 --- /dev/null +++ b/docs-site/content/kagent/concepts/agent-memory.md @@ -0,0 +1,188 @@ +--- +title: Agent Memory +description: Enable vector-backed long-term memory for agents to learn from past interactions. +weight: 6 +author: kagent.dev +--- + +With agent memory, your agents can automatically save and retrieve relevant context across conversations using vector similarity search. Memory is built on top of the Google ADK memory implementation. + +## Overview + +Agent memory provides the following capabilities. + +- **Vector-backed.** A basic vector store uses embedding models to encode memories as 768-dimensional vectors. +- **Searchable.** Agents retrieve relevant memories via cosine similarity. +- **Automatic.** Agents extract and save user intent, key learnings, and preferences without explicit user action. +- **Time-bounded.** Memories expire after a configurable time to live (TTL), which defaults to 15 days. +- **Metadata.** Memories include timestamps and source session references. +- **Shared storage.** Memory uses the kagent database (PostgreSQL), not a separate database. + +## Configure memory + +### Install kagent with Postgres + +To use memory, you must install kagent with a Postgres database that has the `pgvector` extension installed and vector enabled. For more information, see the [Database configuration](/docs/kagent/operations/operational-considerations#database-configuration) section. + +Example Helm configuration for your own external Postgres: + +```yaml +database: + postgres: + urlFile: /var/secrets/db-url + vectorEnabled: true + bundled: + enabled: false +controller: + volumes: + - name: db-secret + secret: + secretName: my-postgres-url-secret + volumeMounts: + - name: db-secret + mountPath: /var/secrets + readOnly: true +``` + +### Enable memory on an agent + +To enable memory, set the `memory` field on the declarative agent spec, as shown in the following YAML example. The `modelConfig` field references a `ModelConfig` object whose embedding provider generates memory vectors. + +You can also configure memory in the kagent UI when you create or edit an agent. In the UI, select an embedding model and set the memory TTL. + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: Agent +metadata: + name: memory-agent + namespace: kagent +spec: + type: Declarative + declarative: + modelConfig: default-model-config + systemMessage: "You are a helpful assistant with long-term memory." + memory: + modelConfig: default-model-config # References the embedding provider +``` + +The embedding `ModelConfig` does not have to use the same provider as the agent's main LLM. kagent supports several embedding providers, including Amazon Bedrock as shown in the following section. + +### ModelConfig example: Amazon Bedrock + +To use [Amazon Bedrock Titan embedding models](https://docs.aws.amazon.com/bedrock/latest/userguide/titan-embedding-models.html), create a `ModelConfig` with `provider: Bedrock`. + +The Bedrock provider uses the standard AWS credential chain, so no API key secret is required. The agent's pod must have AWS credentials with the `bedrock:InvokeModel` permission for the chosen model. On Kubernetes, the recommended setup is [EKS IRSA on the agent ServiceAccount](/docs/kagent/supported-providers/amazon-bedrock#step-3-configure-the-agent-to-use-an-iam-role). + +```yaml +apiVersion: kagent.dev/v1alpha2 +kind: ModelConfig +metadata: + name: bedrock-embed + namespace: kagent +spec: + provider: Bedrock + model: amazon.titan-embed-text-v2:0 + bedrock: + region: us-east-1 +``` + +| Setting | Description | +| --- | --- | +| `provider` | Set to `Bedrock`. | +| `model` | The Bedrock embedding model ID, such as `amazon.titan-embed-text-v2:0` or `amazon.titan-embed-text-v1`. Note that Titan v1 produces 1536-dimensional vectors and Titan v2 produces 1024-dimensional vectors. kagent truncates and L2-normalizes both to the 768-dimensional vector store, so no model-specific dimension setting is required. | +| `bedrock.region` | The AWS region where the model is available, for example `us-east-1`. | + +Reference the embedding `ModelConfig` from the agent's `memory.modelConfig` field: + +```yaml +spec: + declarative: + memory: + modelConfig: bedrock-embed +``` + +### Optional: Custom TTL + +To change the default memory retention period of 15 days, set the `ttlDays` field. + +```yaml +memory: + modelConfig: default-model-config + ttlDays: 30 # Memories expire after 30 days instead of the default 15 +``` + +## Work with memories + +Review the following sections to understand what your agents can do with memory. + +### Automatic save cycle + +1. The agent processes user messages normally. +2. Every 5th user message, the agent automatically extracts key information such as user intent, key learnings, and preferences. +3. The agent summarizes extracted memories and encodes them as embedding vectors. +4. The agent stores the vectors in the database with metadata and timestamps. + +### Memory retrieval (prefetch) + +Before generating a response, the agent performs the following steps. + +1. Encodes the current user message as an embedding vector. +2. Searches stored memories by cosine similarity. +3. Injects the most relevant memories into the agent's context. + +### Memory tools + +When you enable memory, the agent receives three additional tools. + +| Tool | Description | +|------|-------------| +| `save_memory` | Explicitly save a piece of information. | +| `load_memory` | Search for relevant memories by query. | +| `prefetch_memory` | Automatically run before the agent generates a response to retrieve relevant memories. | + +You can also instruct the agent to use `save_memory` or `load_memory` explicitly during a conversation. + +### View memories in the UI + +In the kagent UI, you can view the memories that an agent has saved. With saved memories, you can inspect what the agent has learned and retained from past interactions. + +### Manage memories via API + +The following API endpoints let you manage memories programmatically. + +Add a memory: + +``` +POST /api/memories/sessions +``` + +Add memories in batch: + +``` +POST /api/memories/sessions/batch +``` + +Search memories by cosine similarity: + +``` +POST /api/memories/search +``` + +List memories: + +``` +GET /api/memories?agent_name=X&user_id=Y +``` + +Delete all memories for an agent: + +``` +DELETE /api/memories?agent_name=X&user_id=Y +``` + +## Known limitations + +- **No per-memory deletion.** You can delete all memories for an agent, but you cannot delete individual memory entries. +- **No cross-agent memory sharing.** Each agent has its own isolated memory store. You cannot share memories across agents. +- **Not pluggable.** Memory is built on the Google ADK memory implementation and cannot be swapped for an alternative memory solution (such as Cognee). However, if an alternative memory solution exposes an [MCP server](/docs/kagent/concepts/tools#mcp-tools), you can add it as a tool and instruct the agent to use it instead of the built-in memory. + diff --git a/docs-site/content/kagent/concepts/agent-substrate.md b/docs-site/content/kagent/concepts/agent-substrate.md new file mode 100644 index 00000000..85e7ff20 --- /dev/null +++ b/docs-site/content/kagent/concepts/agent-substrate.md @@ -0,0 +1,76 @@ +--- +title: Agent Substrate +description: Run declarative agents on Agent Substrate — a Kubernetes-native runtime that delivers fast startup, efficient resource usage, and secure sandboxed execution. +weight: 5 +author: kagent.dev +--- + +Agent Substrate is a Kubernetes-native runtime for running AI agents and other stateful workloads efficiently. Instead of dedicating one pod per agent — which wastes capacity while agents sit idle — Substrate decouples an agent's lifecycle from pod infrastructure. Idle agents are snapshotted to object storage and rehydrated on demand, so a small pool of pre-warmed workers can host far more agents than there are pods. + +kagent can run workloads on Agent Substrate in two ways: + +- **Declarative agents** — A declarative `Agent` describes its model, instructions, and tools (see [Agents](/docs/kagent/concepts/agents)). Its sandboxed variant, the [`SandboxAgent`](/docs/kagent/resources/api-ref) CRD, lets you run a (Go) declarative agent on Agent Substrate. +- **AgentHarness** — The [`AgentHarness`](/docs/kagent/concepts/agent-harness) CRD provisions a long-running execution environment for a coding agent (OpenClaw or Hermes). It always runs on Agent Substrate: kagent generates a per-harness `ActorTemplate` and creates an `Actor` from it on demand, referencing a `WorkerPool` for capacity. + +## Why Agent Substrate + +- **Fast startup** — Agents cold-start by restoring a compressed snapshot rather than booting a fresh pod, so they resume in a fraction of the time. +- **Efficient resource usage** — A pool of pre-warmed workers multiplexes many actors across far fewer pods, persisting idle actors to object storage instead of holding a pod each. +- **Secure execution** — Each workload runs inside a gVisor sandbox, isolating untrusted agent code from the host and from other actors. +- **Declarative management** — WorkerPools and ActorTemplates are Kubernetes CRDs, so the runtime is configured and versioned with the same GitOps workflow as the rest of your platform. + +## Core concepts + +| Term | Definition | +| --- | --- | +| **Actor** | An individual agent instance with isolated state, managed by Substrate. | +| **WorkerPool** | A CRD declaring the pool of pre-warmed gVisor worker pods that host actors. | +| **ActorTemplate** | A CRD defining an actor's configuration and lifecycle behavior. kagent generates one per `AgentHarness`. | +| **Snapshot** | A compressed (Zstd) checkpoint of actor state in object storage that enables suspension and fast restoration. | +| **Session** | The execution context that tracks an actor's activity and checkpoints. | + +## How it works + +When an agent is invoked, Substrate restores its actor onto an available worker from the WorkerPool — rehydrating from a snapshot if the actor was idle. The agent runs inside a gVisor sandbox for the duration of the session. When the actor goes idle, its state is checkpointed back to object storage and the worker is freed to host another actor. This snapshot-and-restore cycle is what lets a single worker pool serve many more agents than a pod-per-agent model. + +## Architecture + +Agent Substrate is composed of a control plane, a data plane, and snapshot storage: + +**Control plane** + +- `ateapi` — gRPC API and workflow engine, backed by Redis. +- `atecontroller` — the Kubernetes reconciler for `WorkerPool` and `ActorTemplate` resources. + +**Data plane** + +- `atenet` — an L7 proxy and DNS routing layer that directs traffic to actors. +- `atelet` — a DaemonSet that manages snapshot uploads and downloads on each node. +- `ateom` — the worker-pod supervisor that communicates with the gVisor runtime. + +**Storage** + +- Zstd-compressed checkpoint snapshots stored in object storage (GCS or S3). + +## Using Agent Substrate with AgentHarness and Declarative agents + +### Declarative agents + +Run a (Go) declarative agent on Agent Substrate by creating a `SandboxAgent` resource. It carries the same spec as a regular `Agent`, but the kagent controller runs it as a sandboxed workload on the runtime instead of a plain Deployment. + +### AgentHarness + +An `AgentHarness` always runs on Agent Substrate; `spec.substrate` is required. The key fields are: + +- `workerPoolRef` — references an existing WorkerPool in the harness namespace. When unset, the controller uses its configured default WorkerPool. +- `snapshotsConfig` — configures where actor memory snapshots are stored. Defaults to `gs://ate-snapshots/
(agentgateway-system ns)
• auth / authz
• rate limiting
• audit logging
• observability"] + end + kagentPods --> agentGateway + agentGateway --> ollama["Ollama
(host)"] + kagentPods:::internal + agentGateway:::internal + ollama:::external + classDef cluster stroke:#818cf8,fill:transparent + classDef internal stroke:#a78bfa,fill:transparent + classDef external stroke:#fb923c,fill:transparent + style kagentPods stroke:#a78bfa,fill:transparent + style agentGateway fill:transparent,stroke:#AA00FF + style ollama fill:transparent,stroke:#00C853 + style KindCluster stroke:#2962FF,fill:transparent +``` + +## Configure kagent to use agentgateway + +With agentgateway installed, point kagent at the agentgateway proxy instead of directly at Ollama. + +1. If you installed kagent without agentgateway, upgrade your installation to route through the proxy. + + ```shell + helm upgrade kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --reuse-values \ + --namespace kagent \ + --set providers.default=ollama \ + --set providers.ollama.baseUrl=http://agentgateway-proxy.agentgateway-system.svc.cluster.local/v1 \ + --set providers.ollama.apiKey=dummy + ``` + +2. Create a `ModelConfig` that points to Ollama via the agentgateway proxy. + + ```yaml + kubectl apply -f- <
+
+---
+
+## Steps
+
+### Step 1: Create Your Telegram Bot
+
+1. Open Telegram, search for **@BotFather**.
+2. Send `/newbot`, pick a name and username.
+3. Copy the **bot token** it gives you.
+
+---
+
+### Step 2: Deploy a kagent Agent
+
+> **Prerequisite:** kagent running in your cluster with `kmcp` CRDs installed. If not, hit the [quickstart](https://kagent.dev/docs/kagent/getting-started/quickstart) first.
+
+This agent has Kubernetes tools, Helm tools, and Prometheus — and it's exposed over A2A so any client (our Telegram bot, or anything else) can talk to it. Feel free to make changes as you please:
+
+```shell
+kubectl apply -f - <
+
+
+Deploy the bot:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: telegram-bot
+ namespace: kagent
+ labels:
+ app: telegram-bot
+spec:
+ replicas: 1
+ strategy:
+ type: Recreate
+ selector:
+ matchLabels:
+ app: telegram-bot
+ template:
+ metadata:
+ labels:
+ app: telegram-bot
+ spec:
+ containers:
+ - name: bot
+ image: your-registry/telegram-kagent-bot:latest
+ env:
+ - name: TELEGRAM_BOT_TOKEN
+ valueFrom:
+ secretKeyRef:
+ name: telegram-bot-token
+ key: TELEGRAM_BOT_TOKEN
+ - name: KAGENT_A2A_URL
+ value: "http://kagent-controller.kagent.svc.cluster.local:8083/api/a2a/kagent/telegram-k8s-agent/"
+ livenessProbe:
+ exec:
+ command: ["cat", "/tmp/bot-healthy"]
+ initialDelaySeconds: 10
+ periodSeconds: 30
+ resources:
+ requests:
+ cpu: 50m
+ memory: 64Mi
+ limits:
+ cpu: 200m
+ memory: 128Mi
+```
+
+The strategy is `Recreate` on purpose — Telegram polling doesn't support multiple consumers. Two pods polling the same bot token means duplicate or missed messages.
+
+```shell
+kubectl apply -f deployment.yaml
+```
+
+---
+
+### Take It Further
+
+The interesting part isn't the Telegram bot — it's the pattern. The bot is just a transport layer. A2A is the interface. That means:
+
+- **Multiple agents, one bot.** Add Telegram commands like `/k8s`, `/istio`, `/security` that route to different kagent agents.
+- **Any chat platform.** Swap `python-telegram-bot` for `discord.py` or `slack-bolt`. Everything else stays the same.
+- **Multi-modal.** kagent supports image parts — screenshot a Grafana dashboard and ask "what's wrong here?"
+- **AgentGateway.** Put [AgentGateway](https://agentgateway.dev) in front of the A2A endpoint for rate limiting, auth, and observability.
+
+Questions? Come find us on [Discord](https://discord.gg/Fu3k65f2k3).
diff --git a/docs-site/content/kagent/getting-started/_index.md b/docs-site/content/kagent/getting-started/_index.md
new file mode 100644
index 00000000..ce5b3877
--- /dev/null
+++ b/docs-site/content/kagent/getting-started/_index.md
@@ -0,0 +1,9 @@
+---
+title: Getting Started
+description: Guides to help you get started with kagent, from quick setup to your first agent and tool.
+weight: 2
+author: kagent.dev
+---
+
+Guides to help you get started with kagent, from quick setup to your first agent and tool.
+
diff --git a/docs-site/content/kagent/getting-started/first-agent.md b/docs-site/content/kagent/getting-started/first-agent.md
new file mode 100644
index 00000000..1302e4d3
--- /dev/null
+++ b/docs-site/content/kagent/getting-started/first-agent.md
@@ -0,0 +1,94 @@
+---
+title: Creating your first agent
+linkTitle: Your First Agent
+description: Learn how to create your first AI agent using the kagent dashboard.
+weight: 2
+author: kagent.dev
+---
+
+In this guide, you'll learn how to create your first AI agent using the kagent dashboard.
+
+## Prerequisites
+
+Before you begin make sure you have a Kubernetes cluster with kagent installed. If you haven't done this yet, check out the [installation guide](/docs/kagent/introduction/installation) or the [quickstart guide](/docs/kagent/getting-started/quickstart).
+
+We'll be working in the kagent dashboard, so use the kagent CLI to open the dashboard:
+
+```bash
+$ kagent dashboard
+```
+
+
+
+## Creating the agent
+
+Let's create an agent that can use Kubernetes tools to interact with the cluster.
+
+1. From the top menu bar, click **+ Create > New Agent**. The **Create New Agent** form opens.
+
+2. For the **Agent Name**, enter `k8sagent`.
+
+3. For the **Agent Namespace**, select the namespace that you installed kagent in, `kagent`.
+
+4. Although optional, enter a description for the agent. The description can help you remember what the agent does and why you created it.
+
+ ```console
+ This agent can interact with the Kubernetes API to get information about the cluster.
+ ```
+
+5. Fill out the **Agent Instructions**. Together with tools, agent instructions are what agent uses to interact with the user. They play an important role in instructing and guiding the agent on how and when to use tools, how to interact with the user, and what to do in certain scenarios. Think of these instructions as if you'd be giving them to a colleague who's new to the job.
+
+ >Note that the way you structure your instructions is up to you. You can add more details, or simplify them as needed. It's important to make sure the instructions are clear and easy to follow.
+
+ ```md
+ You're a friendly and helpful agent that uses Kubernetes tools to answer users questions about the cluster.
+
+ # Instructions
+
+ - If user question is unclear, ask for clarification before running any tools
+ - Always be helpful and friendly
+ - If you don't know how to answer the question DO NOT make things up
+ respond with "Sorry, I don't know how to answer that" and ask the user to further clarify the question
+
+ # Response format
+ - ALWAYS format your response as Markdown
+ - Your response will include a summary of actions you took and an explanation of the result
+ ```
+
+6. For the **Model**, select the default `gpt-4.1-mini` default model.
+
+
+
+## Adding tools
+
+Tools are an essential building block of the agent. They are the commands that the agent can run to interact with the environment. As LLMs don't have the ability to run commands, tools are the way to bridge the gap between the agent and the environment. kagent provides a set of built-in tools that you can use to interact with Kubernetes, Istio, Prometheus and projects. You can also [build your own tools](https://kagent.dev/tools)!
+
+1. Click **Add Tools & Agents**. The selection panel opens.
+2. In the search bar, enter `k8s` to filter the available tools.
+3. Scroll through the list and select some tools, such as the following:
+
+ * `k8s_get_available_api_resources`: Let the agent list the available API resources in the cluster.
+ * `k8s_get_resources`: Let the agent list the resources running in the cluster.
+
+4. Click **Save Selection** to add the tools to the agent.
+
+ 
+
+## Testing the agent
+
+Now that you set up all the details for your agent, you're ready to finish creating and trying it out.
+
+1. Click **Create Agent** to create the agent.
+
+2. From the kagent UI landing page, find your `kagent/k8sagent` agent. You might have to refresh the page.
+
+ 
+
+3. Click your agent, then enter a message such as "What API resources are running in my cluster?", and click **Send**. The agent uses the available tools as shown in the to help answer the question.
+
+ 
+
+## Next Steps
+
+- Learn more about [Core Concepts](/docs/kagent/concepts)
+- Join our [Community](https://discord.gg/Fu3k65f2k3)
diff --git a/docs-site/content/kagent/getting-started/first-mcp-tool.md b/docs-site/content/kagent/getting-started/first-mcp-tool.md
new file mode 100644
index 00000000..40e4c890
--- /dev/null
+++ b/docs-site/content/kagent/getting-started/first-mcp-tool.md
@@ -0,0 +1,181 @@
+---
+title: Adding MCP Tools to Your First kagent Agent
+linkTitle: Your First MCP tool
+description: Learn how to add an MCP (Model Context Protocol) tool to your kagent agent.
+weight: 3
+author: kagent.dev
+---
+
+[MCP (Model Context Protocol)](https://modelcontextprotocol.io/introduction) tools extend the agent's abilities by calling external services to perform tasks that require logic or access outside the cluster.
+
+In this guide, you'll learn how to add an MCP tool to your first AI agent using the kagent resources.
+
+## Prerequisites
+
+1. Install kagent in a Kubernetes cluster. If you haven't done this yet, check out the [installation guide](/docs/kagent/introduction/installation) or the [quickstart guide](/docs/kagent/getting-started/quickstart).
+
+2. Make sure that you have the kagent custom resources in your cluster.
+
+ ```shell
+ kubectl get crd | grep kagent.dev
+ ```
+
+## Creating an agent
+
+To create an agent, follow the [Your First Agent guide](/docs/kagent/getting-started/first-agent).
+
+Take a look at the Agent custom resource for your first agent, such as with the following command.
+
+```shell
+kubectl get agent my-first-k8s-agent -n kagent -o yaml
+```
+
+Example output: Pay attention to the following details:
+
+* The `type` field is set to `Declarative`. This means that the agent is using a declarative model configuration and system message, as opposed to `BYO` where you can bring your own agent configuration separately.
+* The `declarative` field contains the model configuration and system message.
+* The `systemMessage` field contains the system message that the agent will use. Note that the way you structure your instructions is up to you. You can add more details, or simplify them as needed. It's important to make sure the instructions are clear and easy to follow.
+* The `tools` field contains the tools that the agent can run to interact with the environment. The tools refer to a RemoteMCPServer, because these tools are built in to kagent. However, you can also create your own MCPServer or regular Kubernetes Service and designate the Service as for MCP use.
+* The `status` shows that the agent is accepted and ready.
+
+```yaml
+apiVersion: kagent.dev/v1alpha2
+kind: Agent
+metadata:
+ creationTimestamp: "2025-08-13T18:05:07Z"
+ generation: 1
+ name: my-first-k8s-agent
+ namespace: kagent
+spec:
+ description: This agent can interact with the Kubernetes API to get information
+ about the cluster.
+ type: Declarative
+ declarative:
+ modelConfig: default-model-config
+ systemMessage: |-
+ You're a friendly and helpful agent that uses Kubernetes tools to answer users questions about the cluster.
+
+ # Instructions
+ - If user question is unclear, ask for clarification before running any tools
+ - Always be helpful and friendly
+ - If you don't know how to answer the question DO NOT make things up
+ respond with "Sorry, I don't know how to answer that" and ask the user to further clarify the question
+ If you are unable to help, or something goes wrong, refer the user to https://kagent.dev for more information or support.
+
+ # Response format
+ - ALWAYS format your response as Markdown
+ - Your response will include a summary of actions you took and an explanation of the result
+ tools:
+ - mcpServer:
+ apiGroup: kagent.dev
+ kind: RemoteMCPServer
+ name: kagent-tool-server
+ toolNames:
+ - k8s_get_available_api_resources
+ type: McpServer
+ - mcpServer:
+ apiGroup: kagent.dev
+ kind: RemoteMCPServer
+ name: kagent-tool-server
+ toolNames:
+ - k8s_get_resources
+ type: McpServer
+status:
+ conditions:
+ - lastTransitionTime: "2025-08-13T18:05:07Z"
+ message: ""
+ reason: AgentReconciled
+ status: "True"
+ type: Accepted
+ - lastTransitionTime: "2025-08-13T18:05:23Z"
+ message: Deployment is ready
+ reason: DeploymentReady
+ status: "True"
+ type: Ready
+ configHash: 297ryAv8Xqp/ib2XUWNeDphuiqwA1wk7DAxt+E1vQhQ=
+ observedGeneration: 1
+```
+
+## Configuring MCP tools
+
+Now that you've reviewed an existing agent that uses MCP tools, let's create our own from scratch.
+
+The following example creates an agent that can retrieve information from a website. You create a [simple MCP example server](https://modelcontextprotocol.io/examples) that only has one tool, the fetch tool. The fetch tool takes a URL as input and returns the contents of the page.
+
+1. Create an MCPServer resource with kmcp for the fetch tool.
+
+ ```yaml
+ kubectl apply -f - <Using External Secrets Operator instead?
+ +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: telegram-bot-token + namespace: kagent +spec: + refreshInterval: "1h" + secretStoreRef: + name: vault-backend + kind: ClusterSecretStore + target: + name: telegram-bot-token + creationPolicy: Owner + data: + - secretKey: TELEGRAM_BOT_TOKEN + remoteRef: + key: telegram + property: api_key +``` + +| + +#### Agent + +Agent is the Schema for the agents API. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `Agent` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[AgentSpec](#agentspec)_ | | | | +| `status` _[AgentStatus](#agentstatus)_ | | | | + +#### AgentHarness + +AgentHarness is a generic remote execution environment provisioned by a +backend (OpenClaw or Hermes) running on Agent Substrate. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `AgentHarness` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[AgentHarnessSpec](#agentharnessspec)_ | | | | +| `status` _[AgentHarnessStatus](#agentharnessstatus)_ | | | | + +#### AgentHarnessBackendType + +_Underlying type:_ _string_ + +AgentHarnessBackendType selects which sandbox control plane provisions the +environment. Additional backends may be added in the future. + +_Validation:_ +- Enum: [openclaw hermes] + +_Appears in:_ +- [AgentHarnessSpec](#agentharnessspec) +- [AgentHarnessStatusRef](#agentharnessstatusref) + +| Field | Description | +| --- | --- | +| `openclaw` | | +| `hermes` | | + +#### AgentHarnessChannel + +AgentHarnessChannel declares one messenger binding inside a harness VM. + +_Appears in:_ +- [AgentHarnessSpec](#agentharnessspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is a stable id for this binding (OpenClaw channels.*.accounts key). | | MinLength: 1
| +| `type` _[AgentHarnessChannelType](#agentharnesschanneltype)_ | | | Enum: [telegram slack]
| +| `telegram` _[AgentHarnessTelegramChannelSpec](#agentharnesstelegramchannelspec)_ | | | | +| `slack` _[AgentHarnessSlackChannelSpec](#agentharnessslackchannelspec)_ | Slack configures Slack when type is Slack. | | | + +#### AgentHarnessChannelAccess + +_Underlying type:_ _string_ + +AgentHarnessChannelAccess controls whether the bot listens broadly or only on an allowlist. + +_Validation:_ +- Enum: [allowlist open disabled] + +_Appears in:_ +- [AgentHarnessOpenClawSlackOptions](#agentharnessopenclawslackoptions) + +| Field | Description | +| --- | --- | +| `allowlist` | | +| `open` | | +| `disabled` | | + +#### AgentHarnessChannelCredential + +AgentHarnessChannelCredential supplies a token from an inline value or a Secret/ConfigMap key. + +_Appears in:_ +- [AgentHarnessSlackChannelSpec](#agentharnessslackchannelspec) +- [AgentHarnessTelegramChannelSpec](#agentharnesstelegramchannelspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `value` _string_ | | | MaxLength: 8192
| +| `valueFrom` _[ValueSource](#valuesource)_ | | | | + +#### AgentHarnessChannelType + +_Underlying type:_ _string_ + +AgentHarnessChannelType selects a messenger integration for OpenClaw harness VMs. + +_Validation:_ +- Enum: [telegram slack] + +_Appears in:_ +- [AgentHarnessChannel](#agentharnesschannel) + +| Field | Description | +| --- | --- | +| `telegram` | | +| `slack` | | + +#### AgentHarnessConnection + +AgentHarnessConnection describes how clients reach the provisioned harness VM. + +_Appears in:_ +- [AgentHarnessStatus](#agentharnessstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `endpoint` _string_ | Endpoint is the backend-specific address (gRPC target, SSH host:port,
...) clients should use to reach the harness. | | | + +#### AgentHarnessHermesSlackOptions + +AgentHarnessHermesSlackOptions configures Hermes-specific Slack settings (env vars in the sandbox). + +_Appears in:_ +- [AgentHarnessSlackChannelSpec](#agentharnessslackchannelspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `allowedUserIDs` _string array_ | AllowedUserIDs restricts which Slack member IDs may interact with the bot (SLACK_ALLOWED_USERS). | | MaxItems: 1024
| +| `allowedUserIDsFrom` _[ValueSource](#valuesource)_ | | | | +| `homeChannel` _string_ | HomeChannel is the default Slack channel ID for cron/scheduled messages (SLACK_HOME_CHANNEL). | | | +| `homeChannelName` _string_ | HomeChannelName is a human-readable label for HomeChannel (SLACK_HOME_CHANNEL_NAME). | | | + +#### AgentHarnessOpenClawSlackOptions + +AgentHarnessOpenClawSlackOptions configures OpenClaw-specific Slack routing. + +_Appears in:_ +- [AgentHarnessSlackChannelSpec](#agentharnessslackchannelspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `channelAccess` _[AgentHarnessChannelAccess](#agentharnesschannelaccess)_ | | | Enum: [allowlist open disabled]
| +| `allowlistChannels` _string array_ | AllowlistChannels is required when channelAccess is allowlist. | | MaxItems: 1024
| +| `interactiveReplies` _boolean_ | | true | | + +#### AgentHarnessSlackChannelSpec + +AgentHarnessSlackChannelSpec configures Slack when AgentHarnessChannel.type is Slack. +Backend-specific settings live under the matching backend key; AgentHarnessSpec validation +requires the key to match spec.backend. + +_Appears in:_ +- [AgentHarnessChannel](#agentharnesschannel) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `botToken` _[AgentHarnessChannelCredential](#agentharnesschannelcredential)_ | | | | +| `appToken` _[AgentHarnessChannelCredential](#agentharnesschannelcredential)_ | | | | +| `openclaw` _[AgentHarnessOpenClawSlackOptions](#agentharnessopenclawslackoptions)_ | OpenClaw configures OpenClaw-specific Slack routing. | | | +| `hermes` _[AgentHarnessHermesSlackOptions](#agentharnesshermesslackoptions)_ | Hermes configures Hermes-specific Slack settings. | | | + +#### AgentHarnessSpec + +AgentHarnessSpec describes a generic remote execution environment that agents +(or human operators) can attach to via exec or SSH. + +An AgentHarness is distinct from a SandboxAgent: it has no agent runtime baked +in. The backend is responsible for provisioning an environment that stays +ready to accept incoming commands. + +_Appears in:_ +- [AgentHarness](#agentharness) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `backend` _[AgentHarnessBackendType](#agentharnessbackendtype)_ | Backend selects the control plane to use. Required. | | Enum: [openclaw hermes]
| +| `substrate` _[AgentHarnessSubstrateSpec](#agentharnesssubstratespec)_ | Substrate configures the Agent Substrate provisioning stack. Required. | | | +| `description` _string_ | Description is a short human-readable summary shown in the UI (e.g. agents list). | | | +| `image` _string_ | Image is the container image to run in the harness VM, if the backend
supports per-resource images. Backend openclaw pins the image
to the OpenClaw sandbox base when this field is empty; backend hermes pins
to the Hermes sandbox base image when empty. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Env is a list of environment variables injected into the harness workload.
Values use the Kubernetes EnvVar shape; ValueFrom references are
resolved server-side where supported. | | | +| `modelConfigRef` _string_ | ModelConfigRef is the reference to the ModelConfig used to configure the harness.
The controller registers the gateway provider and, after the harness is Ready,
writes OpenClaw config inside the VM (~/.openclaw/openclaw.json) and starts the gateway. | | | +| `channels` _[AgentHarnessChannel](#agentharnesschannel) array_ | Channels configures Telegram and Slack integrations for OpenClaw inside the harness VM. | | MaxItems: 1024
| + +#### AgentHarnessStatus + +AgentHarnessStatus is the observed state of an AgentHarness. + +_Appears in:_ +- [AgentHarness](#agentharness) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | | | | +| `backendRef` _[AgentHarnessStatusRef](#agentharnessstatusref)_ | BackendRef points at the harness instance on the backend control
plane, once Ensure has succeeded at least once. | | | +| `connection` _[AgentHarnessConnection](#agentharnessconnection)_ | Connection is populated by the controller when the harness is ready. | | | + +#### AgentHarnessStatusRef + +AgentHarnessStatusRef identifies a harness instance on an external control plane. + +_Appears in:_ +- [AgentHarnessStatus](#agentharnessstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `backend` _[AgentHarnessBackendType](#agentharnessbackendtype)_ | | | Enum: [openclaw hermes]
| +| `id` _string_ | | | | + +#### AgentHarnessSubstrateSnapshotsConfig + +AgentHarnessSubstrateSnapshotsConfig points at a GCS prefix for actor memory snapshots. +Substrate currently expects a gs:// location (see Agent Substrate SnapshotsConfig). + +_Appears in:_ +- [AgentHarnessSubstrateSpec](#agentharnesssubstratespec) +- [SandboxSubstrateSpec](#sandboxsubstratespec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `location` _string_ | Location is the GCS URI prefix for golden and incremental snapshots.
Example: gs://ate-snapshots/kagent/my-namespace/my-harness/ | | Pattern: `^gs://`
| + +#### AgentHarnessSubstrateSpec + +AgentHarnessSubstrateSpec configures Agent Substrate (WorkerPool + ActorTemplate + Actor). + +kagent generates a per-harness ActorTemplate and creates an Actor from it. WorkerPool +capacity is referenced from workerPoolRef or the controller default; it is not +created or deleted by the AgentHarness controller. + +_Appears in:_ +- [AgentHarnessSpec](#agentharnessspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `workerPoolRef` _[TypedLocalReference](#typedlocalreference)_ | WorkerPoolRef references an existing ate.dev WorkerPool in the harness namespace.
When unset, the controller uses its configured default WorkerPool. | | | +| `snapshotsConfig` _[AgentHarnessSubstrateSnapshotsConfig](#agentharnesssubstratesnapshotsconfig)_ | SnapshotsConfig configures actor memory snapshots. Defaults to
gs://ate-snapshots/<namespace>/<agentharnessname> when unset. | | | +| `workloadImage` _string_ | WorkloadImage overrides the default openclaw sandbox image in the ActorTemplate. | | | + +#### AgentHarnessTelegramChannelSpec + +AgentHarnessTelegramChannelSpec configures Telegram when AgentHarnessChannel.type is Telegram. + +_Appears in:_ +- [AgentHarnessChannel](#agentharnesschannel) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `botToken` _[AgentHarnessChannelCredential](#agentharnesschannelcredential)_ | | | | +| `allowedUserIDs` _string array_ | | | MaxItems: 1024
| +| `allowedUserIDsFrom` _[ValueSource](#valuesource)_ | | | | + +#### AgentProvider + +AgentProvider identifies the organization responsible for an agent on its A2A AgentCard. + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `organization` _string_ | Organization is the name of the agent provider's organization. | | MinLength: 1
| +| `url` _string_ | URL is a URL for the agent provider's website or relevant documentation. | | Format: uri
| + +#### AgentSkill + +AgentSkill describes a specific capability or function of the agent. + +_Appears in:_ +- [A2AConfig](#a2aconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `id` _string_ | ID is the unique identifier for the skill. | | | +| `name` _string_ | Name is the human-readable name of the skill. | | MinLength: 1
| +| `description` _string_ | Description is an optional detailed description of the skill. | | | +| `tags` _string array_ | Tags are optional tags for categorization. | | MaxItems: 20
| +| `examples` _string array_ | Examples are optional usage examples. | | MaxItems: 20
| +| `inputModes` _string array_ | InputModes are the supported input MIME types for this skill, overriding the agent's defaults. | | | +| `outputModes` _string array_ | OutputModes are the supported output MIME types for this skill, overriding the agent's defaults. | | | + +#### AgentSpec + +AgentSpec defines the desired state of Agent. + +_Appears in:_ +- [Agent](#agent) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[AgentType](#agenttype)_ | | Declarative | Enum: [Declarative BYO]
| +| `byo` _[BYOAgentSpec](#byoagentspec)_ | BYO configures a "bring your own" agent backed by a user-provided
container image. Kagent deploys the image and expects it to serve the
agent over the A2A protocol on port 8080.
Required if type is BYO. | | | +| `declarative` _[DeclarativeAgentSpec](#declarativeagentspec)_ | Declarative configures an agent that is fully described by this resource
(model, instructions, tools) and runs on one of kagent's built-in runtimes.
Required if type is Declarative. | | | +| `description` _string_ | | | | +| `iconUrl` _string_ | IconURL is a URL to an icon representing the agent. It is surfaced on the
agent's A2A AgentCard. | | Format: uri
| +| `documentationUrl` _string_ | DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard. | | Format: uri
| +| `version` _string_ | Version is the agent's version string, surfaced on the A2A AgentCard. | | | +| `provider` _[AgentProvider](#agentprovider)_ | Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard. | | | +| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from the specified container images.
and made available to the agent under the `/skills` folder. | | | +| `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.
This is intended for sandboxed declarative execution today, and can also
be consumed by BYO agents. | | | +| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | + +#### AgentStatus + +AgentStatus defines the observed state of Agent. + +_Appears in:_ +- [Agent](#agent) +- [SandboxAgent](#sandboxagent) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | | | | + +#### AgentType + +_Underlying type:_ _string_ + +AgentType represents the agent type + +_Validation:_ +- Enum: [Declarative BYO] + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | +| --- | --- | +| `Declarative` | | +| `BYO` | | + +#### AllowedNamespaces + +AllowedNamespaces defines which namespaces are allowed to reference this resource. +This mechanism provides a bidirectional handshake for cross-namespace references, +following the pattern used by Gateway API for cross-namespace route attachments. + +By default (when not specified), only references from the same namespace are allowed. + +_Appears in:_ +- [AgentSpec](#agentspec) +- [RemoteMCPServerSpec](#remotemcpserverspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `from` _[FromNamespaces](#fromnamespaces)_ | From indicates where references to this resource can originate.
Possible values are:
* All: References from all namespaces are allowed.
* Same: Only references from the same namespace are allowed (default).
* Selector: References from namespaces matching the selector are allowed. | Same | Enum: [All Same Selector]
| +| `selector` _[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta)_ | Selector is a label selector for namespaces that are allowed to reference this resource.
Only used when From is set to "Selector". | | | + +#### AnthropicConfig + +AnthropicConfig contains Anthropic-specific configuration options + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `baseUrl` _string_ | Base URL for the Anthropic API (overrides default) | | | +| `maxTokens` _integer_ | Maximum tokens to generate | | | +| `temperature` _string_ | Temperature for sampling | | | +| `topP` _string_ | Top-p sampling parameter | | | +| `topK` _integer_ | Top-k sampling parameter | | | + +#### AnthropicVertexAIConfig + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `projectID` _string_ | The project ID | | | +| `location` _string_ | The project location | | | +| `temperature` _string_ | Temperature | | | +| `topP` _string_ | Top-p sampling parameter | | | +| `topK` _string_ | Top-k sampling parameter | | | +| `stopSequences` _string array_ | Stop sequences | | | +| `maxTokens` _integer_ | Maximum tokens to generate | | | + +#### AzureOpenAIConfig + +AzureOpenAIConfig contains Azure OpenAI-specific configuration options + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `azureEndpoint` _string_ | Endpoint for the Azure OpenAI API | | | +| `apiVersion` _string_ | API version for the Azure OpenAI API | | | +| `azureDeployment` _string_ | Deployment name for the Azure OpenAI API | | | +| `azureAdToken` _string_ | Azure AD token for authentication | | | +| `temperature` _string_ | Temperature for sampling | | | +| `maxTokens` _integer_ | Maximum tokens to generate | | | +| `topP` _string_ | Top-p sampling parameter | | | + +#### BYOAgentSpec + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `deployment` _[ByoDeploymentSpec](#byodeploymentspec)_ | Deployment configures the Kubernetes Deployment created for the BYO agent container. | | | + +#### BaseVertexAIConfig + +_Appears in:_ +- [AnthropicVertexAIConfig](#anthropicvertexaiconfig) +- [GeminiVertexAIConfig](#geminivertexaiconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `projectID` _string_ | The project ID | | | +| `location` _string_ | The project location | | | +| `temperature` _string_ | Temperature | | | +| `topP` _string_ | Top-p sampling parameter | | | +| `topK` _string_ | Top-k sampling parameter | | | +| `stopSequences` _string array_ | Stop sequences | | | + +#### BedrockConfig + +BedrockConfig contains AWS Bedrock-specific configuration options. + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `region` _string_ | AWS region where the Bedrock model is available (e.g., us-east-1, us-west-2) | | | +| `additionalModelRequestFields` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#json-v1-apiextensions-k8s-io)_ | AdditionalModelRequestFields passes model-specific parameters to Bedrock's
additionalModelRequestFields in the Converse API. Use this for provider-specific
options that are not part of the standard InferenceConfiguration block, such as
Claude extended thinking or top_k. Values are forwarded as-is to the API.
Example: \{"top_k": 5, "thinking": \{"type": "enabled", "budget_tokens": 16000\}\} | | | +| `promptCaching` _boolean_ | PromptCaching enables Bedrock prompt caching by appending a CachePoint
block at the end of the Converse request's `system` content array and
the end of the `toolConfig.tools` array. Bedrock will cache the prefix up to and
including those cache points across requests in the same region for
roughly 5 minutes after first use, billing the cached portion at a
reduced rate on cache hits.
Recommended for tool-using agents that make many Converse calls per
task with a stable system prompt and tool set — the per-call input
token count can drop by 70-90% on hit. Has no effect on models that
don't support caching; the marker is ignored by Bedrock for those.
See https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html
for the current list of supported models and minimum prefix sizes. | false | | +| `cacheTTL` _string_ | CacheTTL controls how long Bedrock retains a cached prefix when
PromptCaching is enabled. Only meaningful when PromptCaching is true.
- "5m" (default): Bedrock's standard 5-minute sliding cache. Each cache
hit refreshes the window. Supported by all prompt-caching models.
- "1h": extended-TTL caching, useful for tasks whose Converse calls are
spaced more than 5 minutes apart.
NOTE: "1h" is NOT strictly better than "5m". Extended-TTL cache writes are
billed at a higher per-token rate than 5-minute writes, and 1h is supported
on a narrower set of models. Only choose "1h" when calls are spaced far
enough apart that a 5-minute cache would expire between them; otherwise the
higher write cost is wasted. See the AWS prompt-caching docs above. | 5m | Enum: [5m 1h]
| + +#### ByoDeploymentSpec + +_Appears in:_ +- [BYOAgentSpec](#byoagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `image` _string_ | Image is the container image of the BYO agent.
The image is expected to serve the agent over the A2A protocol on port 8080. | | MinLength: 1
| +| `cmd` _string_ | Cmd overrides the container entrypoint (the container's command). | | | +| `args` _string array_ | Args are the arguments passed to the container entrypoint. | | | +| `workingDir` _string_ | workingDir sets the container working directory. Defaults to the image WORKDIR when omitted. | | | +| `replicas` _integer_ | Replicas is the number of desired agent pods. Defaults to 1. | | | +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image. | | | +| `volumes` _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volume-v1-core) array_ | Volumes are additional volumes added to the agent pod. | | | +| `volumeMounts` _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volumemount-v1-core) array_ | VolumeMounts are additional volume mounts added to the agent container. | | | +| `labels` _object (keys:string, values:string)_ | Labels are additional labels added to the agent pods. | | | +| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations added to the agent pods. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Env are additional environment variables set on the agent container. | | | +| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#pullpolicy-v1-core)_ | | | | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | | | | +| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#toleration-v1-core) array_ | Tolerations applied to the agent pods. | | | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#affinity-v1-core)_ | | | | +| `nodeSelector` _object (keys:string, values:string)_ | NodeSelector restricts the nodes the agent pods can be scheduled on. | | | +| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#securitycontext-v1-core)_ | | | | +| `podSecurityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#podsecuritycontext-v1-core)_ | | | | +| `serviceAccountName` _string_ | ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig. | | | +| `serviceAccountConfig` _[ServiceAccountConfig](#serviceaccountconfig)_ | ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it. | | | +| `extraContainers` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents. | | | + +#### ContextCompressionConfig + +ContextCompressionConfig configures event history compaction/compression. + +_Appears in:_ +- [ContextConfig](#contextconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `compactionInterval` _integer_ | The number of *new* user-initiated invocations that, once fully represented in the session's events, will trigger a compaction. | 5 | Minimum: 1
| +| `overlapSize` _integer_ | The number of preceding invocations to include from the end of the last compacted range. This creates an overlap between consecutive compacted summaries, maintaining context. | 2 | Minimum: 0
| +| `summarizer` _[ContextSummarizerConfig](#contextsummarizerconfig)_ | Summarizer configures an LLM-based summarizer for event compaction.
If not specified, compacted events are dropped from the context without summarization. | | | +| `tokenThreshold` _integer_ | Post-invocation token threshold trigger. If set, ADK will attempt a post-invocation compaction when the most recently
observed prompt token count meets or exceeds this threshold. | | | +| `eventRetentionSize` _integer_ | EventRetentionSize is the number of most recent events to always retain. | | | + +#### ContextConfig + +ContextConfig configures context management for an agent. + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `compaction` _[ContextCompressionConfig](#contextcompressionconfig)_ | Compaction configures event history compaction.
When enabled, older events in the conversation are compacted (compressed/summarized)
to reduce context size while preserving key information. | | | + +#### ContextSummarizerConfig + +ContextSummarizerConfig configures the LLM-based event summarizer. + +_Appears in:_ +- [ContextCompressionConfig](#contextcompressionconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `modelConfig` _string_ | ModelConfig is the name of a ModelConfig resource to use for summarization.
Must be in the same namespace as the Agent.
If not specified, uses the agent's own model. | | | +| `promptTemplate` _string_ | PromptTemplate is a custom prompt template for the summarizer.
See the ADK LlmEventSummarizer for template details:
https://github.com/google/adk-python/blob/main/src/google/adk/apps/llm_event_summarizer.py | | | + +#### DeclarativeAgentSpec + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `runtime` _[DeclarativeRuntime](#declarativeruntime)_ | Runtime specifies which ADK implementation to use for this agent.
- "go": Uses the Go ADK (default, faster startup, most features supported)
- "python": Uses the Python ADK (slower startup, full feature set)
The runtime determines both the container image and readiness probe configuration. | go | Enum: [python go]
| +| `systemMessage` _string_ | SystemMessage is a string specifying the system message for the agent.
When PromptTemplate is set, this field is treated as a Go text/template
with access to an include("source/key") function and agent context variables
such as .AgentName, .AgentNamespace, .Description, .ToolNames, and .SkillNames. | | | +| `systemMessageFrom` _[ValueSource](#valuesource)_ | SystemMessageFrom is a reference to a ConfigMap or Secret containing the system message.
When PromptTemplate is set, the resolved value is treated as a Go text/template. | | | +| `promptTemplate` _[PromptTemplateSpec](#prompttemplatespec)_ | PromptTemplate enables Go text/template processing on the systemMessage field.
When set, systemMessage is treated as a Go template with access to the include function
and agent context variables. | | | +| `modelConfig` _string_ | The name of the model config to use.
If not specified, the default value is "default-model-config".
Must be in the same namespace as the Agent. | | | +| `stream` _boolean_ | Whether to stream the response from the model.
If not specified, the default value is false. | | | +| `tools` _[Tool](#tool) array_ | | | MaxItems: 20
| +| `a2aConfig` _[A2AConfig](#a2aconfig)_ | A2AConfig instantiates an A2A server for this agent,
served on the HTTP port of the kagent kubernetes
controller (default 8083).
The A2A server URL will be served at
<kagent-controller-ip>:8083/api/a2a/<agent-namespace>/<agent-name>
Read more about the A2A protocol here: https://github.com/a2aproject/A2A | | | +| `deployment` _[DeclarativeDeploymentSpec](#declarativedeploymentspec)_ | | | | +| `executeCodeBlocks` _boolean_ | Allow code execution for python code blocks with this agent.
If true, the agent will automatically execute python code blocks in the LLM responses.
Code will be executed in a sandboxed environment.
due to a bug in adk (https://github.com/google/adk-python/issues/3921 ), this field is ignored for now. | | | +| `memory` _[MemorySpec](#memoryspec)_ | Memory configuration for the agent. | | | +| `shareTools` _boolean_ | ShareTools enables the built-in share link tools for this agent.
When true, the agent gains create_share_link, list_share_links, and delete_share_link tools
that allow it to manage share tokens for the current session. | | | +| `context` _[ContextConfig](#contextconfig)_ | Context configures context management for this agent.
This includes event compaction (compression) and context caching. | | | + +#### DeclarativeDeploymentSpec + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `imageRegistry` _string_ | | | | +| `replicas` _integer_ | Replicas is the number of desired agent pods. Defaults to 1. | | | +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image. | | | +| `volumes` _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volume-v1-core) array_ | Volumes are additional volumes added to the agent pod. | | | +| `volumeMounts` _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volumemount-v1-core) array_ | VolumeMounts are additional volume mounts added to the agent container. | | | +| `labels` _object (keys:string, values:string)_ | Labels are additional labels added to the agent pods. | | | +| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations added to the agent pods. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Env are additional environment variables set on the agent container. | | | +| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#pullpolicy-v1-core)_ | | | | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | | | | +| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#toleration-v1-core) array_ | Tolerations applied to the agent pods. | | | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#affinity-v1-core)_ | | | | +| `nodeSelector` _object (keys:string, values:string)_ | NodeSelector restricts the nodes the agent pods can be scheduled on. | | | +| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#securitycontext-v1-core)_ | | | | +| `podSecurityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#podsecuritycontext-v1-core)_ | | | | +| `serviceAccountName` _string_ | ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig. | | | +| `serviceAccountConfig` _[ServiceAccountConfig](#serviceaccountconfig)_ | ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it. | | | +| `extraContainers` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents. | | | + +#### DeclarativeRuntime + +_Underlying type:_ _string_ + +DeclarativeRuntime represents the runtime implementation for declarative agents + +_Validation:_ +- Enum: [python go] + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | +| --- | --- | +| `python` | | +| `go` | | + +#### FromNamespaces + +_Underlying type:_ _string_ + +FromNamespaces specifies namespace from which references to this resource are allowed. +This follows the same pattern as Gateway API's cross-namespace route attachment. +See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment + +_Validation:_ +- Enum: [All Same Selector] + +_Appears in:_ +- [AllowedNamespaces](#allowednamespaces) + +| Field | Description | +| --- | --- | +| `All` | NamespacesFromAll allows references from all namespaces.
| +| `Same` | NamespacesFromSame only allows references from the same namespace as the target resource (default).
| +| `Selector` | NamespacesFromSelector allows references from namespaces matching the selector.
| + +#### GDCHServiceAccountConfig + +GDCHServiceAccountConfig holds GDCH-specific token exchange parameters. + +_Appears in:_ +- [TokenExchangeConfig](#tokenexchangeconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `audience` _string_ | Audience is the token exchange audience URL (the GDC inference gateway base URL) | | | + +#### GeminiConfig + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +#### GeminiVertexAIConfig + +GeminiVertexAIConfig contains Gemini Vertex AI-specific configuration options + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `projectID` _string_ | The project ID | | | +| `location` _string_ | The project location | | | +| `temperature` _string_ | Temperature | | | +| `topP` _string_ | Top-p sampling parameter | | | +| `topK` _string_ | Top-k sampling parameter | | | +| `stopSequences` _string array_ | Stop sequences | | | +| `maxOutputTokens` _integer_ | Maximum output tokens | | | +| `candidateCount` _integer_ | Candidate count | | | +| `responseMimeType` _string_ | Response mime type | | | + +#### GitRepo + +GitRepo specifies a single Git repository to fetch skills from. + +_Appears in:_ +- [SkillForAgent](#skillforagent) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `url` _string_ | URL of the git repository (HTTPS or SSH). | | | +| `ref` _string_ | Git reference: branch name, tag, or commit SHA. | main | | +| `path` _string_ | Subdirectory within the repo to use as the skill root. The API validates
this input path, but treats repository contents as trusted: symlinks under
this path are dereferenced when materializing the skill. | | | +| `name` _string_ | Name for the skill directory under /skills. If omitted, defaults to the last
segment of Path when Path is set; otherwise defaults to the repo name (last
URL path segment, without .git). | | | + +#### MCPTool + +_Appears in:_ +- [RemoteMCPServerStatus](#remotemcpserverstatus) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | | | | +| `description` _string_ | | | | + +#### McpServerTool + +_Appears in:_ +- [Tool](#tool) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | | | | +| `apiGroup` _string_ | | | | +| `name` _string_ | | | | +| `namespace` _string_ | | | | +| `toolNames` _string array_ | The names of the tools to be provided by the ToolServer
For a list of all the tools provided by the server,
the client can query the status of the ToolServer object after it has been created | | MaxItems: 50
| +| `requireApproval` _string array_ | RequireApproval lists tool names that require human approval before
execution. Each name must also appear in ToolNames. When a tool in
this list is invoked by the agent, execution pauses and the user is
prompted to approve or reject the call. | | MaxItems: 50
| +| `allowedHeaders` _string array_ | AllowedHeaders specifies which headers from the A2A request should be
propagated to MCP tool calls. Header names are case-insensitive.
Authorization header behavior:
- Authorization headers CAN be propagated if explicitly listed in allowedHeaders
- When STS token propagation is enabled, STS-generated Authorization headers
will take precedence and replace any Authorization header from the A2A request
- This is a security measure to prevent request headers from overwriting
authentication tokens generated by the STS integration
Example: ["x-user-email", "x-tenant-id"] | | | + +#### MemorySpec + +MemorySpec enables long-term memory for an agent. + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `modelConfig` _string_ | ModelConfig is the name of the ModelConfig object whose embedding
provider will be used to generate memory vectors. | | | +| `ttlDays` _integer_ | TTLDays controls how many days a stored memory entry remains valid before
it is eligible for pruning. Defaults to 15 days when unset or zero. | | Minimum: 1
| + +#### ModelConfig + +ModelConfig is the Schema for the modelconfigs API. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `ModelConfig` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[ModelConfigSpec](#modelconfigspec)_ | | | | +| `status` _[ModelConfigStatus](#modelconfigstatus)_ | | | | + +#### ModelConfigSpec + +ModelConfigSpec defines the desired state of ModelConfig. + +_Appears in:_ +- [ModelConfig](#modelconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `model` _string_ | | | | +| `apiKeySecret` _string_ | The name of the secret that contains the API key. Must be a reference to the name of a secret in the same namespace as the referencing ModelConfig.
For the SAPAICore provider, the secret must contain two keys: "client_id" and "client_secret"
(the OAuth2 client credentials for SAP AI Core). The apiKeySecretKey field is not used for SAPAICore. | | | +| `apiKeySecretKey` _string_ | The key in the secret that contains the API key.
Not used for the SAPAICore provider (which always reads "client_id" and "client_secret" from the secret). | | | +| `apiKeyPassthrough` _boolean_ | APIKeyPassthrough enables forwarding the Bearer token from incoming A2A requests
directly to the LLM provider as the API key. This is useful for organizations
with federated identity that want to avoid separate secret management.
Mutually exclusive with apiKeySecret. | | | +| `defaultHeaders` _object (keys:string, values:string)_ | | | | +| `provider` _[ModelProvider](#modelprovider)_ | The provider of the model | OpenAI | Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore]
| +| `openAI` _[OpenAIConfig](#openaiconfig)_ | OpenAI-specific configuration | | | +| `anthropic` _[AnthropicConfig](#anthropicconfig)_ | Anthropic-specific configuration | | | +| `azureOpenAI` _[AzureOpenAIConfig](#azureopenaiconfig)_ | Azure OpenAI-specific configuration | | | +| `ollama` _[OllamaConfig](#ollamaconfig)_ | Ollama-specific configuration | | | +| `gemini` _[GeminiConfig](#geminiconfig)_ | Gemini-specific configuration | | | +| `geminiVertexAI` _[GeminiVertexAIConfig](#geminivertexaiconfig)_ | Gemini Vertex AI-specific configuration | | | +| `anthropicVertexAI` _[AnthropicVertexAIConfig](#anthropicvertexaiconfig)_ | Anthropic-specific configuration | | | +| `bedrock` _[BedrockConfig](#bedrockconfig)_ | AWS Bedrock-specific configuration | | | +| `sapAICore` _[SAPAICoreConfig](#sapaicoreconfig)_ | SAP AI Core-specific configuration | | | +| `tls` _[TLSConfig](#tlsconfig)_ | TLS configuration for provider connections.
Enables agents to connect to internal LiteLLM gateways or other providers
that use self-signed certificates or custom certificate authorities. | | | + +#### ModelConfigStatus + +ModelConfigStatus defines the observed state of ModelConfig. + +_Appears in:_ +- [ModelConfig](#modelconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | | | | +| `observedGeneration` _integer_ | | | | +| `secretHash` _string_ | The secret hash stores a hash of any secrets required by the model config (i.e. api key, tls cert) to ensure agents referencing this model config detect changes to these secrets and restart if necessary. | | | + +#### ModelProvider + +_Underlying type:_ _string_ + +ModelProvider represents the model provider type + +_Validation:_ +- Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore] + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) +- [ModelProviderConfigSpec](#modelproviderconfigspec) + +| Field | Description | +| --- | --- | +| `Anthropic` | | +| `AzureOpenAI` | | +| `OpenAI` | | +| `Ollama` | | +| `Gemini` | | +| `GeminiVertexAI` | | +| `AnthropicVertexAI` | | +| `Bedrock` | | +| `SAPAICore` | | + +#### ModelProviderConfig + +ModelProviderConfig is the Schema for the modelproviderconfigs API. +It represents a model provider configuration with automatic model discovery. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `ModelProviderConfig` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[ModelProviderConfigSpec](#modelproviderconfigspec)_ | | | | +| `status` _[ModelProviderConfigStatus](#modelproviderconfigstatus)_ | | | | + +#### ModelProviderConfigSpec + +ModelProviderConfigSpec defines the desired state of ModelProviderConfig. + +_Appears in:_ +- [ModelProviderConfig](#modelproviderconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[ModelProvider](#modelprovider)_ | Type is the model provider type (OpenAI, Anthropic, etc.) | | Enum: [Anthropic OpenAI AzureOpenAI Ollama Gemini GeminiVertexAI AnthropicVertexAI Bedrock SAPAICore]
| +| `endpoint` _string_ | Endpoint is the API endpoint URL for the provider.
If not specified, the default endpoint for the provider type will be used. | | Pattern: `^https?://.*`
| +| `secretRef` _[SecretReference](#secretreference)_ | SecretRef references the Kubernetes Secret containing the API key.
Optional for providers that don't require authentication (e.g., local Ollama). | | | + +#### ModelProviderConfigStatus + +ModelProviderConfigStatus defines the observed state of ModelProviderConfig. + +_Appears in:_ +- [ModelProviderConfig](#modelproviderconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | ObservedGeneration reflects the generation of the most recently observed ModelProviderConfig spec | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions represent the latest available observations of the ModelProviderConfig's state | | | +| `discoveredModels` _string array_ | DiscoveredModels is the cached list of model IDs available from this model provider | | | +| `modelCount` _integer_ | ModelCount is the number of discovered models (for kubectl display) | | | +| `lastDiscoveryTime` _[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#time-v1-meta)_ | LastDiscoveryTime is the timestamp of the last successful model discovery | | | +| `secretHash` _string_ | SecretHash is a hash of the referenced secret data, used to detect secret changes | | | + +#### NetworkConfig + +NetworkConfig configures outbound network access for sandboxed execution paths. + +_Appears in:_ +- [SandboxConfig](#sandboxconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `allowedDomains` _string array_ | AllowedDomains lists the domains that sandboxed execution may contact.
Wildcards such as *.example.com are supported by the sandbox runtime. | | | + +#### OllamaConfig + +OllamaConfig contains Ollama-specific configuration options + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `host` _string_ | Host for the Ollama API | | | +| `options` _object (keys:string, values:string)_ | Options for the Ollama API | | | + +#### OpenAIConfig + +OpenAIConfig contains OpenAI-specific configuration options + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `baseUrl` _string_ | Base URL for the OpenAI API (overrides default) | | | +| `organization` _string_ | Organization ID for the OpenAI API | | | +| `temperature` _string_ | Temperature for sampling | | | +| `maxTokens` _integer_ | Maximum tokens to generate | | | +| `topP` _string_ | Top-p sampling parameter | | | +| `frequencyPenalty` _string_ | Frequency penalty | | | +| `presencePenalty` _string_ | Presence penalty | | | +| `seed` _integer_ | Seed value | | | +| `n` _integer_ | N value | | | +| `timeout` _integer_ | Timeout | | | +| `reasoningEffort` _[OpenAIReasoningEffort](#openaireasoningeffort)_ | Reasoning effort | | Enum: [minimal low medium high]
| +| `tokenExchange` _[TokenExchangeConfig](#tokenexchangeconfig)_ | TokenExchange configures dynamic bearer token acquisition via credential exchange.
Requires apiKeySecret (used as the service account secret) and is mutually exclusive with apiKeyPassthrough. | | | + +#### OpenAIReasoningEffort + +_Underlying type:_ _string_ + +OpenAIReasoningEffort represents how many reasoning tokens the model generates before producing a response. + +_Validation:_ +- Enum: [minimal low medium high] + +_Appears in:_ +- [OpenAIConfig](#openaiconfig) + +#### PromptSource + +PromptSource references a ConfigMap whose keys are available as prompt fragments. +In systemMessage templates, use include("alias/key") (or include("name/key") if no alias is set) +to insert the value of a specific key from this source. + +_Appears in:_ +- [PromptTemplateSpec](#prompttemplatespec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | | | | +| `apiGroup` _string_ | | | | +| `name` _string_ | | | | +| `alias` _string_ | Alias is an optional short identifier for use in include directives.
If set, use include("alias/key") instead of include("name/key"). | | | + +#### PromptTemplateSpec + +PromptTemplateSpec configures prompt template processing for an agent's system message. + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `dataSources` _[PromptSource](#promptsource) array_ | DataSources defines the ConfigMaps whose keys can be included in the systemMessage
using Go template syntax, e.g. include("alias/key") or include("name/key"). | | MaxItems: 20
| + +#### RemoteMCPServer + +RemoteMCPServer is the Schema for the RemoteMCPServers API. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `RemoteMCPServer` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[RemoteMCPServerSpec](#remotemcpserverspec)_ | | | | +| `status` _[RemoteMCPServerStatus](#remotemcpserverstatus)_ | | | | + +#### RemoteMCPServerProtocol + +_Underlying type:_ _string_ + +_Validation:_ +- Enum: [SSE STREAMABLE_HTTP] + +_Appears in:_ +- [RemoteMCPServerSpec](#remotemcpserverspec) + +| Field | Description | +| --- | --- | +| `SSE` | | +| `STREAMABLE_HTTP` | | + +#### RemoteMCPServerSpec + +RemoteMCPServerSpec defines the desired state of RemoteMCPServer. + +_Appears in:_ +- [RemoteMCPServer](#remotemcpserver) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `description` _string_ | | | | +| `protocol` _[RemoteMCPServerProtocol](#remotemcpserverprotocol)_ | | STREAMABLE_HTTP | Enum: [SSE STREAMABLE_HTTP]
| +| `url` _string_ | | | MinLength: 1
| +| `headersFrom` _[ValueRef](#valueref) array_ | | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | | 30s | | +| `sseReadTimeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | | | | +| `terminateOnClose` _boolean_ | | true | | +| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this RemoteMCPServer.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this RemoteMCPServer.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment
A cross-namespace-permitting value (from: All or from: Selector) is
mutually exclusive with spec.tls.caCertSecretRef (enforced by a spec-level
XValidation rule): a pinned CA Secret is mounted onto the consuming agent's
pod by bare name and Kubernetes resolves it in the agent's namespace, not
this RemoteMCPServer's, so a CA-pinning RemoteMCPServer cannot be referenced
cross-namespace. from: Same (the default) is always allowed. | | | +| `tls` _[TLSConfig](#tlsconfig)_ | TLS configuration for the upstream MCP server connection.
Use this for HTTPS upstreams that present a certificate the agent's
system trust store does not include (corporate CA, self-signed cert
on a test fixture, internal MCP gateway). Reuses the same TLSConfig
type as ModelConfig.spec.tls — disableVerify turns off certificate
validation entirely, caCertSecretRef + caCertSecretKey point at a
PEM bundle Secret in the same namespace, and disableSystemCAs
trusts only the named bundle.
Note one asymmetry with ModelConfig: a spec-level XValidation rule
on RemoteMCPServer rejects spec.tls when spec.url has the http://
scheme (a TLS opinion contradicts a plaintext URL). ModelConfig has
no equivalent rule, so a TLS block can sit alongside any baseUrl. | | | + +#### RemoteMCPServerStatus + +RemoteMCPServerStatus defines the observed state of RemoteMCPServer. + +_Appears in:_ +- [RemoteMCPServer](#remotemcpserver) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `observedGeneration` _integer_ | INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
Important: Run "make" to regenerate code after modifying this file | | | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | | | | +| `discoveredTools` _[MCPTool](#mcptool) array_ | | | | +| `secretHash` _string_ | SecretHash stores a hash of the TLS Secret referenced by spec.tls so
agents that consume this RemoteMCPServer can detect cert rotation and
roll on the next reconcile. Empty when spec.tls.caCertSecretRef is unset. | | | + +#### SAPAICoreConfig + +SAPAICoreConfig contains SAP AI Core-specific configuration options. + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `baseUrl` _string_ | Base URL for the SAP AI Core API (e.g., https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com) | | | +| `resourceGroup` _string_ | Resource group in SAP AI Core | default | | +| `authUrl` _string_ | OAuth2 token endpoint URL (e.g., https://tenant.authentication.eu10.hana.ondemand.com) | | | + +#### SandboxAgent + +SandboxAgent declares an agent that runs in an isolated sandbox on Agent Substrate. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha2` | | | +| `kind` _string_ | `SandboxAgent` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[SandboxAgentSpec](#sandboxagentspec)_ | | | | +| `status` _[AgentStatus](#agentstatus)_ | | | | + +#### SandboxAgentSpec + +_Appears in:_ +- [SandboxAgent](#sandboxagent) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[AgentType](#agenttype)_ | | Declarative | Enum: [Declarative BYO]
| +| `byo` _[BYOAgentSpec](#byoagentspec)_ | BYO configures a "bring your own" agent backed by a user-provided
container image. Kagent deploys the image and expects it to serve the
agent over the A2A protocol on port 8080.
Required if type is BYO. | | | +| `declarative` _[DeclarativeAgentSpec](#declarativeagentspec)_ | Declarative configures an agent that is fully described by this resource
(model, instructions, tools) and runs on one of kagent's built-in runtimes.
Required if type is Declarative. | | | +| `description` _string_ | | | | +| `iconUrl` _string_ | IconURL is a URL to an icon representing the agent. It is surfaced on the
agent's A2A AgentCard. | | Format: uri
| +| `documentationUrl` _string_ | DocumentationURL is a URL to human-readable documentation for the agent. It
is surfaced on the agent's A2A AgentCard. | | Format: uri
| +| `version` _string_ | Version is the agent's version string, surfaced on the A2A AgentCard. | | | +| `provider` _[AgentProvider](#agentprovider)_ | Provider identifies the organization responsible for the agent. It is
surfaced on the agent's A2A AgentCard. | | | +| `skills` _[SkillForAgent](#skillforagent)_ | Skills to load into the agent. They will be pulled from the specified container images.
and made available to the agent under the `/skills` folder. | | | +| `sandbox` _[SandboxConfig](#sandboxconfig)_ | Sandbox configures sandboxed execution behavior shared across runtimes.
This is intended for sandboxed declarative execution today, and can also
be consumed by BYO agents. | | | +| `allowedNamespaces` _[AllowedNamespaces](#allowednamespaces)_ | AllowedNamespaces defines which namespaces are allowed to reference this Agent as a tool.
This follows the Gateway API pattern for cross-namespace route attachments.
If not specified, only Agents in the same namespace can reference this Agent as a tool.
This field only applies when this Agent is used as a tool by another Agent.
See: https://gateway-api.sigs.k8s.io/guides/multiple-ns/#cross-namespace-route-attachment | | | +| `substrate` _[SandboxSubstrateSpec](#sandboxsubstratespec)_ | Substrate is optional Agent Substrate-specific settings. | | | + +#### SandboxConfig + +SandboxConfig configures sandboxed execution behavior. + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `network` _[NetworkConfig](#networkconfig)_ | Network configures outbound network access for sandboxed execution paths.
When unset or when allowedDomains is empty, outbound access is denied by default. | | | + +#### SandboxSubstrateSpec + +SandboxSubstrateSpec configures Agent Substrate for a SandboxAgent. +WorkerPool capacity is referenced from workerPoolRef or the controller default. + +_Appears in:_ +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `workerPoolRef` _[TypedLocalReference](#typedlocalreference)_ | WorkerPoolRef references an existing ate.dev WorkerPool. | | | +| `snapshotsConfig` _[AgentHarnessSubstrateSnapshotsConfig](#agentharnesssubstratesnapshotsconfig)_ | SnapshotsConfig configures actor memory snapshots.
Defaults to gs://ate-snapshots/<namespace>/<agentname> when unset. | | | + +#### SecretReference + +SecretReference references a Kubernetes Secret that must contain exactly one data key +holding the API key or credential. + +_Appears in:_ +- [ModelProviderConfigSpec](#modelproviderconfigspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | Name is the name of the secret in the same namespace as the ModelProviderConfig. | | | + +#### ServiceAccountConfig + +_Appears in:_ +- [ByoDeploymentSpec](#byodeploymentspec) +- [DeclarativeDeploymentSpec](#declarativedeploymentspec) +- [SharedDeploymentSpec](#shareddeploymentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `labels` _object (keys:string, values:string)_ | Labels are additional labels added to the created ServiceAccount. | | | +| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations added to the created ServiceAccount. | | | + +#### SharedDeploymentSpec + +_Appears in:_ +- [ByoDeploymentSpec](#byodeploymentspec) +- [DeclarativeDeploymentSpec](#declarativedeploymentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `replicas` _integer_ | Replicas is the number of desired agent pods. Defaults to 1. | | | +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets are references to secrets in the agent's namespace
used for pulling the agent container image. | | | +| `volumes` _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volume-v1-core) array_ | Volumes are additional volumes added to the agent pod. | | | +| `volumeMounts` _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volumemount-v1-core) array_ | VolumeMounts are additional volume mounts added to the agent container. | | | +| `labels` _object (keys:string, values:string)_ | Labels are additional labels added to the agent pods. | | | +| `annotations` _object (keys:string, values:string)_ | Annotations are additional annotations added to the agent pods. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Env are additional environment variables set on the agent container. | | | +| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#pullpolicy-v1-core)_ | | | | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | | | | +| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#toleration-v1-core) array_ | Tolerations applied to the agent pods. | | | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#affinity-v1-core)_ | | | | +| `nodeSelector` _object (keys:string, values:string)_ | NodeSelector restricts the nodes the agent pods can be scheduled on. | | | +| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#securitycontext-v1-core)_ | | | | +| `podSecurityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#podsecuritycontext-v1-core)_ | | | | +| `serviceAccountName` _string_ | ServiceAccountName specifies the name of an existing ServiceAccount to use.
If this field is set, the Agent controller will not create a ServiceAccount for the agent.
This field is mutually exclusive with ServiceAccountConfig. | | | +| `serviceAccountConfig` _[ServiceAccountConfig](#serviceaccountconfig)_ | ServiceAccountConfig configures the ServiceAccount created by the Agent controller.
This field can only be used when ServiceAccountName is not set.
If ServiceAccountName is not set, a default ServiceAccount (named after the agent)
is created, and this config will be applied to it. | | | +| `extraContainers` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | ExtraContainers is a list of additional containers to run alongside the main agent container.
Useful for sidecars such as token proxies, log shippers, or security agents. | | | + +#### SkillForAgent + +_Appears in:_ +- [AgentSpec](#agentspec) +- [SandboxAgentSpec](#sandboxagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `insecureSkipVerify` _boolean_ | Fetch images insecurely from registries (allowing HTTP and skipping TLS verification).
Meant for development and testing purposes only. | | | +| `refs` _string array_ | The list of skill images to fetch. | | MaxItems: 20
MinItems: 1
| +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets is a list of references to secrets in the same namespace to use for
pulling skill images from private registries. Each referenced secret must be of type
kubernetes.io/dockerconfigjson. The credentials from all secrets are merged and made
available to the skills-init container at /.kagent/.docker/config.json; krane will
use them automatically when pulling images. | | MaxItems: 20
| +| `gitAuthSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core)_ | Reference to a Secret containing git credentials.
Applied to all gitRefs entries.
The secret should contain a `token` key for HTTPS auth,
or `ssh-privatekey` for SSH auth. | | | +| `gitRefs` _[GitRepo](#gitrepo) array_ | Git repositories to fetch skills from. | | MaxItems: 20
MinItems: 1
| +| `initContainer` _[SkillsInitContainer](#skillsinitcontainer)_ | Configuration for the skills-init init container. | | | + +#### SkillsInitContainer + +SkillsInitContainer configures the skills-init init container. + +_Appears in:_ +- [SkillForAgent](#skillforagent) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | Resource requirements for the skills-init init container. | | | +| `env` _[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#envvar-v1-core) array_ | Additional environment variables for the skills-init init container. | | | + +#### TLSConfig + +TLSConfig contains TLS/SSL configuration options for outbound HTTPS +connections from the agent (model provider, RemoteMCPServer). The +XValidation rules below apply at admission to every CRD field that +uses TLSConfig, so callers don't need to re-declare them per spec. + +_Appears in:_ +- [ModelConfigSpec](#modelconfigspec) +- [RemoteMCPServerSpec](#remotemcpserverspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `disableVerify` _boolean_ | DisableVerify disables SSL certificate verification entirely.
When false (default), SSL certificates are verified.
When true, SSL certificate verification is disabled.
WARNING: This should ONLY be used in development/testing environments.
Production deployments MUST use proper certificates. | false | | +| `caCertSecretRef` _string_ | CACertSecretRef is a reference to a Kubernetes Secret containing
CA certificate(s) in PEM format. The Secret must be in the same
namespace as the resource referencing it (ModelConfig,
RemoteMCPServer, or any future consumer of TLSConfig).
When set, the certificate will be used to verify the upstream's
SSL certificate. | | | +| `caCertSecretKey` _string_ | CACertSecretKey is the key within the Secret that contains the
CA certificate data (PEM-encoded). Required when CACertSecretRef
is set — admission rejects ref-without-key regardless of
DisableVerify (see the TLSConfig-level XValidation rules). | | | +| `disableSystemCAs` _boolean_ | DisableSystemCAs disables the use of system CA certificates.
When false (default), system CA certificates are used for verification (safe behavior).
When true, only the custom CA from CACertSecretRef is trusted.
This allows strict security policies where only corporate CAs should be trusted. | false | | + +#### TokenExchangeConfig + +TokenExchangeConfig configures dynamic bearer token acquisition before model calls. + +_Appears in:_ +- [OpenAIConfig](#openaiconfig) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[TokenExchangeType](#tokenexchangetype)_ | | | Enum: [GDCHServiceAccount]
| +| `gdchServiceAccount` _[GDCHServiceAccountConfig](#gdchserviceaccountconfig)_ | | | | + +#### TokenExchangeType + +_Underlying type:_ _string_ + +TokenExchangeType identifies the token exchange mechanism + +_Validation:_ +- Enum: [GDCHServiceAccount] + +_Appears in:_ +- [TokenExchangeConfig](#tokenexchangeconfig) + +| Field | Description | +| --- | --- | +| `GDCHServiceAccount` | | + +#### Tool + +_Appears in:_ +- [DeclarativeAgentSpec](#declarativeagentspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[ToolProviderType](#toolprovidertype)_ | | | Enum: [McpServer Agent]
| +| `mcpServer` _[McpServerTool](#mcpservertool)_ | | | | +| `agent` _[TypedReference](#typedreference)_ | | | | +| `headersFrom` _[ValueRef](#valueref) array_ | HeadersFrom specifies a list of configuration values to be added as
headers to requests sent to the Tool from this agent. The value of
each header is resolved from either a Secret or ConfigMap in the same
namespace as the Agent. Headers specified here will override any
headers of the same name/key specified on the tool. | | | + +#### ToolProviderType + +_Underlying type:_ _string_ + +ToolProviderType represents the tool provider type + +_Validation:_ +- Enum: [McpServer Agent] + +_Appears in:_ +- [Tool](#tool) + +| Field | Description | +| --- | --- | +| `McpServer` | | +| `Agent` | | + +#### TypedLocalReference + +_Appears in:_ +- [AgentHarnessSubstrateSpec](#agentharnesssubstratespec) +- [PromptSource](#promptsource) +- [SandboxSubstrateSpec](#sandboxsubstratespec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | | | | +| `apiGroup` _string_ | | | | +| `name` _string_ | | | | + +#### TypedReference + +_Appears in:_ +- [McpServerTool](#mcpservertool) +- [Tool](#tool) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `kind` _string_ | | | | +| `apiGroup` _string_ | | | | +| `name` _string_ | | | | +| `namespace` _string_ | | | | + +#### ValueRef + +ValueRef represents a configuration value + +_Appears in:_ +- [RemoteMCPServerSpec](#remotemcpserverspec) +- [Tool](#tool) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `name` _string_ | | | | +| `value` _string_ | | | | +| `valueFrom` _[ValueSource](#valuesource)_ | | | | + +#### ValueSource + +ValueSource defines a source for configuration values from a Secret or ConfigMap + +_Appears in:_ +- [AgentHarnessChannelCredential](#agentharnesschannelcredential) +- [AgentHarnessHermesSlackOptions](#agentharnesshermesslackoptions) +- [AgentHarnessTelegramChannelSpec](#agentharnesstelegramchannelspec) +- [DeclarativeAgentSpec](#declarativeagentspec) +- [ValueRef](#valueref) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `type` _[ValueSourceType](#valuesourcetype)_ | | | Enum: [ConfigMap Secret]
| +| `name` _string_ | The name of the ConfigMap or Secret. | | MaxLength: 253
| +| `key` _string_ | The key of the ConfigMap or Secret. | | MaxLength: 253
| + +#### ValueSourceType + +_Underlying type:_ _string_ + +_Appears in:_ +- [ValueSource](#valuesource) + +| Field | Description | +| --- | --- | +| `ConfigMap` | | +| `Secret` | | + diff --git a/docs-site/content/kagent/resources/cli/_index.md b/docs-site/content/kagent/resources/cli/_index.md new file mode 100644 index 00000000..aa2b9e24 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/_index.md @@ -0,0 +1,8 @@ +--- +title: CLI docs +description: Complete reference docs for the kagent CLI commands +weight: 1 +--- + +Review the kagent CLI commands and learn how to use them effectively. + diff --git a/docs-site/content/kagent/resources/cli/kagent-add-mcp.md b/docs-site/content/kagent/resources/cli/kagent-add-mcp.md new file mode 100644 index 00000000..563e80c2 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-add-mcp.md @@ -0,0 +1,57 @@ +--- +title: kagent add-mcp +description: kagent add-mcp command +weight: 10 +--- + +Add an MCP server entry to `kagent.yaml`. + +```bash +kagent add-mcp [name] [args...] [flags] +``` + +**Arguments:** +- `name` - Name of the MCP server +- `args` - Command arguments (optional) + +**Flags:** +- `--arg` - Command argument (repeatable) +- `--build` - Construct image specification (e.g., `docker build`) +- `--command` - Command to run MCP server (e.g., `npx`, `uvx`, `kmcp`) +- `--env` - Environment variable in KEY=VALUE format (repeatable) +- `--header` - HTTP header for remote MCP in KEY=VALUE format (repeatable, supports `${VAR}` for env vars) +- `--image` - Container image (optional; mutually exclusive with `--build`) +- `--project-dir` - Project directory (default: current directory) +- `--remote` - Remote MCP server URL (`http://` or `https://`) + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent add-mcp` + +Adds an MCP server entry to your `kagent.yaml` file. Use flags for non-interactive setup or run without flags to open the wizard. + +## Example + +Add a remote MCP server: + +```bash +kagent add-mcp my-mcp-server --remote https://mcp.example.com +``` + +Add an MCP server with a command: + +```bash +kagent add-mcp my-mcp-server --command npx --arg @modelcontextprotocol/server-filesystem +``` + +Add an MCP server with custom environment variables: + +```bash +kagent add-mcp my-mcp-server --command my-server --env API_KEY=secret --env LOG_LEVEL=debug +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-bug-report.md b/docs-site/content/kagent/resources/cli/kagent-bug-report.md new file mode 100644 index 00000000..700e9287 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-bug-report.md @@ -0,0 +1,36 @@ +--- +title: kagent bug-report +description: kagent bug-report command +weight: 10 +--- + +Generate a bug report for troubleshooting. + +```bash +kagent bug-report [flags] +``` + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent bug-report` + +This command generates a comprehensive bug report that includes: +- kagent CLI version +- kagent server version +- Kubernetes cluster information +- Resource status and logs +- Configuration details + +## Example + +Generate a bug report: + +```bash +kagent bug-report +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-build.md b/docs-site/content/kagent/resources/cli/kagent-build.md new file mode 100644 index 00000000..4610e231 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-build.md @@ -0,0 +1,60 @@ +--- +title: kagent build +description: kagent build command +weight: 10 +--- + +Build a Docker image for an agent project. + +```bash +kagent build [project-directory] [flags] +``` + +**Arguments:** +- `project-directory` - The directory containing the agent project with `kagent.yaml` + +**Flags:** +- `--image` - Full image specification (e.g., ghcr.io/myorg/my-agent:v1.0.0) +- `--platform` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) +- `--push` - Push the image to the registry + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent build` + +The `kagent build` command builds Docker images for an agent project created with the `init` command. It looks for a `kagent.yaml` file in the specified project directory and builds Docker images using `docker build`. + +**Image naming:** +- If `--image` is provided, it is used as the full image specification (e.g., `ghcr.io/myorg/my-agent:v1.0.0`) +- Otherwise, defaults to `localhost:5001/{agentName}:latest` where `agentName` is loaded from `kagent.yaml` + +## Example + +Build a Docker image: + +```bash +kagent build ./my-agent +``` + +Build and tag a Docker image: + +```bash +kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 +``` + +Build and push an image to a registry: + +```bash +kagent build ./my-agent --image ghcr.io/myorg/my-agent:v1.0.0 --push +``` + +Build for a specific platform: + +```bash +kagent build ./my-agent --platform linux/amd64 --image ghcr.io/myorg/my-agent:v1.0.0 +``` diff --git a/docs-site/content/kagent/resources/cli/kagent-completion.md b/docs-site/content/kagent/resources/cli/kagent-completion.md new file mode 100644 index 00000000..d6674520 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-completion.md @@ -0,0 +1,23 @@ +--- +title: kagent completion +description: kagent completion command +weight: 40 +--- + +Generate the autocompletion script for kagent for the specified shell. See each sub-command's help for details on how to use the generated script. + +```bash +kagent completion [command] +``` + +**Global Flags:** +- `--config` - config file +- `--kagent-url` - KAgent URL (default "http://localhost:8083") +- `--timeout` - Timeout (default 5m0s) + +**Subcommands:** +- `bash` - Generate the autocompletion script for bash +- `fish` - Generate the autocompletion script for fish +- `powershell` - Generate the autocompletion script for powershell +- `zsh` - Generate the autocompletion script for zsh + diff --git a/docs-site/content/kagent/resources/cli/kagent-dashboard.md b/docs-site/content/kagent/resources/cli/kagent-dashboard.md new file mode 100644 index 00000000..0eacf911 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-dashboard.md @@ -0,0 +1,27 @@ +--- +title: kagent dashboard +description: kagent dashboard command +weight: 10 +--- + +Open the kagent dashboard in your default web browser. + +```bash +kagent dashboard [flags] +``` + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## Example + +Open the dashboard: + +```bash +kagent dashboard +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-deploy.md b/docs-site/content/kagent/resources/cli/kagent-deploy.md new file mode 100644 index 00000000..afb16479 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-deploy.md @@ -0,0 +1,76 @@ +--- +title: kagent deploy +description: kagent deploy command +weight: 10 +--- + +Deploy an agent to Kubernetes. + +```bash +kagent deploy [project-directory] [flags] +``` + +**Arguments:** +- `project-directory` - The directory containing the agent project with `kagent.yaml` + +**Flags:** +- `--api-key` - API key for the model provider (convenience option to create secret) +- `--api-key-secret` - Name of existing secret containing API key (recommended) +- `--dry-run` - Output YAML manifests without applying them to the cluster +- `--image, -i` - Image to use (defaults to `localhost:5001/{agentName}:latest`) +- `--namespace` - Kubernetes namespace to deploy to +- `--platform` - Target platform for Docker build (e.g., linux/amd64, linux/arm64) + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent deploy` + +The `kagent deploy` command deploys an agent to Kubernetes by performing the following steps: + +1. Loads the agent configuration from `kagent.yaml` +2. Either creates a new secret with the provided API key or verifies an existing secret +3. Creates an `Agent` Custom Resource Definition (CRD) with the appropriate configuration + +**API Key Options:** +- `--api-key`: Convenience option to create a new secret with the provided API key +- `--api-key-secret`: Recommended way to reference an existing secret by name + +**Dry-Run Mode:** +Use the `--dry-run` flag to output YAML manifests without applying them to the cluster. This is useful for previewing changes or for use with GitOps workflows. + +## Example + +Deploy using an existing secret: + +```bash +kagent deploy ./my-agent --api-key-secret "my-existing-secret" +``` + +Deploy and create a new secret: + +```bash +kagent deploy ./my-agent --api-key "your-api-key-here" --image "myregistry/myagent:v1.0" +``` + +Deploy to a specific namespace: + +```bash +kagent deploy ./my-agent --api-key-secret "my-secret" --namespace "my-namespace" +``` + +Generate manifests without deploying: + +```bash +kagent deploy ./my-agent --api-key "your-api-key" --dry-run > manifests.yaml +``` + +Deploy with a specific platform for the Docker build: + +```bash +kagent deploy ./my-agent --env-file .env --platform linux/amd64 +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-get.md b/docs-site/content/kagent/resources/cli/kagent-get.md new file mode 100644 index 00000000..ee3c9d53 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-get.md @@ -0,0 +1,56 @@ +--- +title: kagent get +description: kagent get command +weight: 10 +--- + +Get kagent resources. + +```bash +kagent get [resource-type] [resource-name] [flags] +``` + +**Subcommands:** +- `agent [agent_name]` - Get an agent by name or list all agents +- `session [session_id]` - Get a session by ID or list all sessions +- `tool` - List all available tools + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## Example + +List all agents: + +```bash +kagent get agent +``` + +Get a specific agent: + +```bash +kagent get agent k8s-agent +``` + +List all sessions: + +```bash +kagent get session +``` + +Get a specific session: + +```bash +kagent get session abc123 +``` + +List all tools: + +```bash +kagent get tool +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-help.md b/docs-site/content/kagent/resources/cli/kagent-help.md new file mode 100644 index 00000000..43673a48 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-help.md @@ -0,0 +1,17 @@ +--- +title: kagent help +description: kagent help command +weight: 150 +--- + +Help provides help for any command in the `kagent` CLI. + +```bash +kagent help [command] [flags] +``` + +**Global Flags:** +- `--config` - config file +- `--kagent-url` - KAgent URL (default "http://localhost:8083") +- `--timeout` - Timeout (default 5m0s) + diff --git a/docs-site/content/kagent/resources/cli/kagent-init.md b/docs-site/content/kagent/resources/cli/kagent-init.md new file mode 100644 index 00000000..ea12cadd --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-init.md @@ -0,0 +1,62 @@ +--- +title: kagent init +description: kagent init command +weight: 10 +--- + +Initialize a new agent project with the specified framework and language. + +```bash +kagent init [framework] [language] [agent-name] [flags] +``` + +**Arguments:** +- `framework` - The framework to use (currently supports `adk`) +- `language` - The programming language to use (supports `python`) +- `agent-name` - The name of the agent project + +**Flags:** +- `--description` - Description for the agent +- `--instruction-file` - Path to file containing custom instructions for the root agent +- `--model-name` - Model name (e.g., gpt-4, claude-3-5-sonnet, gemini-2.0-flash) (default: "gemini-2.0-flash") +- `--model-provider` - Model provider (OpenAI, Anthropic, Gemini) (default: "Gemini") + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent init` + +The `kagent init` command creates a bootstrap agent project. Select a specific model using the `--model-provider` and `--model-name` flags. You can also customize the root agent instructions by using the `--instruction-file` flag. + +If no custom instruction file is provided, a default dice-rolling instruction is used. If no model is specified, the agent can be configured later. + +Currently supported model providers are the models that are supported in the models configuration: +- OpenAI +- Anthropic +- AzureOpenAI +- Gemini + +## Example + +Create a new agent project: + +```bash +kagent init adk python dice +``` + +Create a new agent project with custom instructions: + +```bash +kagent init adk python dice --instruction-file instructions.md +``` + +Create a new agent project with a specific model: + +```bash +kagent init adk python dice --model-provider Gemini --model-name gemini-2.0-flash +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-install.md b/docs-site/content/kagent/resources/cli/kagent-install.md new file mode 100644 index 00000000..4f724ade --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-install.md @@ -0,0 +1,42 @@ +--- +title: kagent install +description: kagent install command +weight: 10 +--- + +Install kagent in a Kubernetes cluster. + +```bash +kagent install [flags] +``` + +**Flags:** +- `--profile` - Installation profile (minimal|demo) + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## Example + +Install kagent with the default profile: + +```bash +kagent install +``` + +Install kagent with the minimal profile: + +```bash +kagent install --profile minimal +``` + +Install kagent with the demo profile: + +```bash +kagent install --profile demo +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-invoke.md b/docs-site/content/kagent/resources/cli/kagent-invoke.md new file mode 100644 index 00000000..19d70175 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-invoke.md @@ -0,0 +1,47 @@ +--- +title: kagent invoke +description: kagent invoke command +weight: 10 +--- + +Invoke a kagent agent to perform a task. + +```bash +kagent invoke [flags] +``` + +**Flags:** +- `--agent, -a` - Agent to invoke +- `--file, -f` - File to read the task from +- `--session, -s` - Session +- `--stream, -S` - Stream the response +- `--task, -t` - Task to perform +- `--url-override, -u` - URL override + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## Example + +Invoke an agent with a task: + +```bash +kagent invoke --agent "k8s-agent" --task "Get all the pods in the kagent namespace" +``` + +Invoke with streaming output: + +```bash +kagent invoke --agent "k8s-agent" --task "Get all the pods" --stream +``` + +Invoke from a task file: + +```bash +kagent invoke --agent "k8s-agent" --file task.txt +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-mcp.md b/docs-site/content/kagent/resources/cli/kagent-mcp.md new file mode 100644 index 00000000..1b1a65ff --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-mcp.md @@ -0,0 +1,42 @@ +--- +title: kagent mcp +description: kagent mcp command +weight: 10 +--- + +Model Context Protocol (MCP) server management commands for creating and managing MCP servers with dynamic tool loading. + +```bash +kagent mcp [subcommand] [flags] +``` + +**Subcommands:** +- `init` - Initialize a new MCP server project +- `build` - Build a Docker image for your MCP server +- `deploy` - Deploy your MCP server to a Kubernetes cluster +- `add-tool` - Generate an MCP tool boilerplate +- `run` - Run an MCP server locally +- `secrets` - Manage secrets for MCP server projects + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent mcp` + +The `kagent mcp` command provides a set of subcommands for managing MCP servers. This is useful for creating and managing tools that can be used by kagent agents. + +## Example + +See the kagent mcp documentation for detailed examples of each subcommand: + +- [kagent mcp init](/docs/kmcp/reference/kmcp-init) - Create a scaffold for your MCP server +- [kagent mcp build](/docs/kmcp/reference/kmcp-build) - Build a Docker image +- [kagent mcp deploy](/docs/kmcp/reference/kmcp-deploy) - Deploy to Kubernetes +- [kagent mcp add-tool](/docs/kmcp/reference/kmcp-add-tool) - Generate tool boilerplate +- [kagent mcp run](/docs/kmcp/reference/kmcp-run) - Run locally +- [kagent mcp secrets](/docs/kmcp/reference/kmcp-secrets) - Manage secrets + diff --git a/docs-site/content/kagent/resources/cli/kagent-run.md b/docs-site/content/kagent/resources/cli/kagent-run.md new file mode 100644 index 00000000..71b90a27 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-run.md @@ -0,0 +1,62 @@ +--- +title: kagent run +description: kagent run command +weight: 10 +--- + +Run an agent project locally with docker-compose and launch an interactive chat interface. + +```bash +kagent run [project-directory] [flags] +``` + +**Arguments:** +- `project-directory` - The directory containing the agent project (default: current directory) + +**Flags:** +- `--build` - Rebuild the Docker image before running +- `--project-dir` - Project directory (default: current directory) + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent run` + +The `kagent run` command runs an agent project locally using `docker-compose` and launches an interactive chat session. This way, you can test and interact with your agent before deploying it to a Kubernetes cluster. + +### Rebuilding before running + +Use the `--build` flag to rebuild the Docker image before running the agent. This is useful when you've made changes to your agent code and want to test the updated version without manually running `kagent build` first. + +```bash +kagent run --build +``` + +This command rebuilds the agent image and then starts the interactive chat interface. It's equivalent to running `kagent build` followed by `kagent run`. + +## Example + +Run an agent project from the current directory: + +```bash +kagent run +``` + +Run an agent project from a specific directory: + +```bash +kagent run ./my-agent +``` + +Rebuild the image and run the agent: + +```bash +kagent run --build +``` + +This is useful after making code changes to ensure you're testing the latest version of your agent. + diff --git a/docs-site/content/kagent/resources/cli/kagent-uninstall.md b/docs-site/content/kagent/resources/cli/kagent-uninstall.md new file mode 100644 index 00000000..41f7b8b1 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-uninstall.md @@ -0,0 +1,27 @@ +--- +title: kagent uninstall +description: kagent uninstall command +weight: 10 +--- + +Uninstall kagent from a Kubernetes cluster. + +```bash +kagent uninstall [flags] +``` + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## Example + +Uninstall kagent: + +```bash +kagent uninstall +``` + diff --git a/docs-site/content/kagent/resources/cli/kagent-version.md b/docs-site/content/kagent/resources/cli/kagent-version.md new file mode 100644 index 00000000..094f0628 --- /dev/null +++ b/docs-site/content/kagent/resources/cli/kagent-version.md @@ -0,0 +1,31 @@ +--- +title: kagent version +description: kagent version command +weight: 10 +--- + +Print the kagent version information. + +```bash +kagent version [flags] +``` + +**Global Flags:** +- `--kagent-url` - kagent URL (default: "http://localhost:8083") +- `--namespace, -n` - Namespace (default: "kagent") +- `--output-format, -o` - Output format (default: "table") +- `--timeout` - Timeout duration (default: 300s) +- `--verbose, -v` - Verbose output + +## About `kagent version` + +This command prints the kagent CLI version. The CLI attempts to connect to the kagent server to retrieve server version information. Versions unable to be obtained from the remote kagent server are reported as "unknown". + +## Example + +Print version information: + +```bash +kagent version +``` + diff --git a/docs-site/content/kagent/resources/faq.md b/docs-site/content/kagent/resources/faq.md new file mode 100644 index 00000000..9d554b22 --- /dev/null +++ b/docs-site/content/kagent/resources/faq.md @@ -0,0 +1,27 @@ +--- +title: Frequently Asked Questions +linkTitle: FAQs +description: Find answers to frequently asked questions about kagent. +weight: 5 +author: kagent.dev +--- + +## What's the best way to get started with kagent? + +The best way to get started with kagent is to follow the [quickstart guide](/docs/kagent/getting-started/quickstart). This will give you a basic understanding of how kagent works and how to use it. + +## What differentiates kagent from other LLM frameworks? + +kagent is special for a few core reasons: + +- **Declarative**: kagent is designed from the ground up to be declarative. You define the agents, tools, and instructions and kagent will take care of the rest. Most other frameworks are procedural and require you to write code to tell the LLM what to do. +- **Kubernetes Native**: kagent is designed to be used in a Kubernetes environment, and integrates seamlessly with services already running in the cluster. +- **Easy To Use**: kagent abstracts all of the "hard" parts of building an agent, so you can focus on connecting your business logic to the agent. + +## How do I report bugs or request features? + +The best way to report bugs or request features is to create an issue on the [GitHub repository](https://github.com/kagent-dev/kagent/issues). + +## How do I contribute to the kagent project? + +The best way to contribute is to check out the [contribution guide](https://github.com/kagent-dev/kagent/blob/main/CONTRIBUTING.md) and submit a PR. diff --git a/docs-site/content/kagent/resources/helm.md b/docs-site/content/kagent/resources/helm.md new file mode 100644 index 00000000..e69413f3 --- /dev/null +++ b/docs-site/content/kagent/resources/helm.md @@ -0,0 +1,349 @@ +--- +title: kagent +linkTitle: Helm Chart Configuration +description: kagent Helm chart configuration reference +weight: 2 +author: kagent.dev +--- + +A Helm chart for kagent, built with Google ADK + +## Requirements + +| Repository | Name | Version | +|------------|------|---------| +| `${SUBSTRATE_REPO}` | substrate | `${SUBSTRATE_VERSION}` | +| file://../agents/argo-rollouts | argo-rollouts-agent | | +| file://../agents/cilium-debug | cilium-debug-agent | | +| file://../agents/cilium-manager | cilium-manager-agent | | +| file://../agents/cilium-policy | cilium-policy-agent | | +| file://../agents/helm | helm-agent | | +| file://../agents/istio | istio-agent | | +| file://../agents/k8s | k8s-agent | | +| file://../agents/kgateway | kgateway-agent | | +| file://../agents/observability | observability-agent | | +| file://../agents/promql | promql-agent | | +| file://../tools/grafana-mcp | grafana-mcp | | +| file://../tools/querydoc | querydoc | | +| https://oauth2-proxy.github.io/manifests | oauth2-proxy | ~7.0.0 | +| oci://ghcr.io/kagent-dev/kmcp/helm | kmcp | `${KMCP_VERSION}` | +| oci://ghcr.io/kagent-dev/tools/helm | kagent-tools | 0.2.1 | + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| annotations | object | `{}` | Additional annotations to add to all Kubernetes deployment resources | +| argo-rollouts-agent.enabled | bool | `true` | | +| argo-rollouts-agent.memory.enabled | bool | `false` | | +| argo-rollouts-agent.memory.modelConfigRef | string | `""` | | +| argo-rollouts-agent.memory.ttlDays | int | `15` | | +| argo-rollouts-agent.modelConfigRef | string | `""` | | +| argo-rollouts-agent.resources.limits.memory | string | `"256Mi"` | | +| argo-rollouts-agent.resources.requests.cpu | string | `"50m"` | | +| argo-rollouts-agent.resources.requests.memory | string | `"128Mi"` | | +| cilium-debug-agent.enabled | bool | `true` | | +| cilium-debug-agent.memory.enabled | bool | `false` | | +| cilium-debug-agent.memory.modelConfigRef | string | `""` | | +| cilium-debug-agent.memory.ttlDays | int | `15` | | +| cilium-debug-agent.modelConfigRef | string | `""` | | +| cilium-debug-agent.resources.limits.memory | string | `"256Mi"` | | +| cilium-debug-agent.resources.requests.cpu | string | `"50m"` | | +| cilium-debug-agent.resources.requests.memory | string | `"128Mi"` | | +| cilium-manager-agent.enabled | bool | `true` | | +| cilium-manager-agent.memory.enabled | bool | `false` | | +| cilium-manager-agent.memory.modelConfigRef | string | `""` | | +| cilium-manager-agent.memory.ttlDays | int | `15` | | +| cilium-manager-agent.modelConfigRef | string | `""` | | +| cilium-manager-agent.resources.limits.memory | string | `"256Mi"` | | +| cilium-manager-agent.resources.requests.cpu | string | `"50m"` | | +| cilium-manager-agent.resources.requests.memory | string | `"128Mi"` | | +| cilium-policy-agent.enabled | bool | `true` | | +| cilium-policy-agent.memory.enabled | bool | `false` | | +| cilium-policy-agent.memory.modelConfigRef | string | `""` | | +| cilium-policy-agent.memory.ttlDays | int | `15` | | +| cilium-policy-agent.modelConfigRef | string | `""` | | +| cilium-policy-agent.resources.limits.memory | string | `"256Mi"` | | +| cilium-policy-agent.resources.requests.cpu | string | `"50m"` | | +| cilium-policy-agent.resources.requests.memory | string | `"128Mi"` | | +| controller.a2aBaseUrl | string | `http://
the client certificate (tls.crt), key (tls.key), and optionally
the CA certificate (ca.crt) for mTLS authentication.
The Secret must be in the same namespace as the MCPServer. | | | +| `insecureSkipVerify` _boolean_ | InsecureSkipVerify disables SSL certificate verification.
WARNING: This should ONLY be used in development/testing environments.
Production deployments MUST use proper certificates. | false | | + +#### InitContainerConfig + +InitContainerConfig defines the configuration for the init container. + +_Appears in:_ +- [MCPServerDeployment](#mcpserverdeployment) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `image` _string_ | Image defines the full image reference for the init container.
If specified, this overrides the default transport adapter image.
Example: "myregistry.com/agentgateway/agentgateway:0.9.0-musl" | | | +| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#pullpolicy-v1-core)_ | ImagePullPolicy defines the pull policy for the init container image. | | Enum: [Always Never IfNotPresent]
| +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | Resources defines the compute resource requirements for the init container.
Use this to specify CPU and memory requests and limits for the init container. | | | +| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#securitycontext-v1-core)_ | SecurityContext defines the security context for the init container.
If not specified, the main container's security context will be used. | | | + +#### MCPServer + +MCPServer is the Schema for the mcpservers API. + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `apiVersion` _string_ | `kagent.dev/v1alpha1` | | | +| `kind` _string_ | `MCPServer` | | | +| `kind` _string_ | Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds | | | +| `apiVersion` _string_ | APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources | | | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | | +| `spec` _[MCPServerSpec](#mcpserverspec)_ | | | | +| `status` _[MCPServerStatus](#mcpserverstatus)_ | | | | + +#### MCPServerDeployment + +MCPServerDeployment + +_Appears in:_ +- [MCPServerSpec](#mcpserverspec) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `image` _string_ | Image defines the container image to to deploy the MCP server. | | | +| `imagePullPolicy` _[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#pullpolicy-v1-core)_ | ImagePullPolicy defines the pull policy for the container image. | | Enum: [Always Never IfNotPresent]
| +| `port` _integer_ | Port defines the port on which the MCP server will listen. | 3000 | | +| `cmd` _string_ | Cmd defines the command to run in the container to start the mcp server. | | | +| `args` _string array_ | Args defines the arguments to pass to the command. | | | +| `env` _object (keys:string, values:string)_ | Env defines the environment variables to set in the container. | | | +| `secretRefs` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | SecretRefs defines the list of Kubernetes secrets to reference.
These secrets will be mounted as volumes to the MCP server container. | | | +| `configMapRefs` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ConfigMapRefs defines the list of Kubernetes configmaps to reference.
These configmaps will be mounted as volumes to the MCP server container. | | | +| `volumeMounts` _[VolumeMount](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volumemount-v1-core) array_ | VolumeMounts defines the list of volume mounts for the MCP server container.
This allows for more flexible volume mounting configurations. | | | +| `volumes` _[Volume](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#volume-v1-core) array_ | Volumes defines the list of volumes that can be mounted by containers.
This allows for custom volume configurations beyond just secrets and configmaps. | | | +| `initContainer` _[InitContainerConfig](#initcontainerconfig)_ | InitContainer defines the configuration for the init container that copies
the transport adapter binary. This is used for stdio transport type. | | | +| `serviceAccount` _[ServiceAccountConfig](#serviceaccountconfig)_ | ServiceAccount defines the configuration for the ServiceAccount to be created. | | | +| `serviceAccountName` _string_ | ServiceAccountName is the name of an existing ServiceAccount to use. | | | +| `sidecars` _[Container](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#container-v1-core) array_ | Sidecars defines additional containers to run alongside the MCP server container.
These containers will share the same pod and can share volumes with the main container. | | | +| `labels` _object (keys:string, values:string)_ | Labels defines additional labels to add to the pod template.
These labels will be merged with the default labels. | | | +| `annotations` _object (keys:string, values:string)_ | Annotations defines additional annotations to add to the pod template.
These annotations will be merged with the default annotations. | | | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#resourcerequirements-v1-core)_ | Resources defines the compute resource requirements for the main MCP server container.
Use this to specify CPU and memory requests and limits.
Example:
resources:
requests:
cpu: "100m"
memory: "128Mi"
limits:
cpu: "500m"
memory: "512Mi" | | | +| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#securitycontext-v1-core)_ | SecurityContext defines the security context for the main MCP server container.
Use this to configure container-level security settings such as:
- runAsUser/runAsGroup: Run as specific user/group
- runAsNonRoot: Ensure container doesn't run as root
- readOnlyRootFilesystem: Make root filesystem read-only
- allowPrivilegeEscalation: Prevent privilege escalation
- capabilities: Add or drop Linux capabilities | | | +| `podSecurityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#podsecuritycontext-v1-core)_ | PodSecurityContext defines the security context for the entire pod.
Use this to configure pod-level security settings such as:
- runAsUser/runAsGroup: Default user/group for all containers
- fsGroup: Group ownership of mounted volumes
- seccompProfile: Seccomp profile for the pod
- sysctls: Kernel parameters to set | | | +| `tolerations` _[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#toleration-v1-core) array_ | Tolerations defines the tolerations for the pod.
Use this to schedule pods on nodes with matching taints. | | | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#affinity-v1-core)_ | Affinity defines the affinity rules for the pod.
Use this to control pod placement based on node labels, pod labels,
or other scheduling constraints. | | | +| `nodeSelector` _object (keys:string, values:string)_ | NodeSelector defines the node selector for the pod.
Use this to constrain pods to nodes with specific labels. | | | +| `replicas` _integer_ | Replicas defines the number of desired pod replicas.
Defaults to 1 if not specified. | 1 | | +| `imagePullSecrets` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#localobjectreference-v1-core) array_ | ImagePullSecrets defines the list of secrets to use for pulling container images. | | | + +#### MCPServerSpec + +MCPServerSpec defines the desired state of MCPServer. + +_Appears in:_ +- [MCPServer](#mcpserver) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `deployment` _[MCPServerDeployment](#mcpserverdeployment)_ | Configuration to Deploy the MCP Server using a docker container | | | +| `transportType` _[TransportType](#transporttype)_ | TransportType defines the type of mcp server being run | | Enum: [stdio http]
| +| `stdioTransport` _[StdioTransport](#stdiotransport)_ | StdioTransport defines the configuration for a standard input/output transport. | | | +| `httpTransport` _[HTTPTransport](#httptransport)_ | HTTPTransport defines the configuration for a Streamable HTTP transport. | | | +| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)_ | Timeout defines the default connection timeout for clients connecting
to this MCP server. MCP servers deployed via the MCPServer CRD use a
sidecar gateway that spawns a new stdio process (e.g. via uvx/npx)
for each session. Process startup can take 2-8 seconds depending on
package cache state, which may exceed the default timeout used by some
clients. This value is propagated to the generated RemoteMCPServer
resources when they do not specify an explicit timeout. | 30s | | + +#### MCPServerStatus + +MCPServerStatus defines the observed state of MCPServer. + +_Appears in:_ +- [MCPServer](#mcpserver) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions describe the current conditions of the MCPServer.
Implementations should prefer to express MCPServer conditions
using the `MCPServerConditionType` and `MCPServerConditionReason`
constants so that operators and tools can converge on a common
vocabulary to describe MCPServer state.
Known condition types are:
* "Accepted"
* "ResolvedRefs"
* "Programmed"
* "Ready" | | MaxItems: 8
| +| `observedGeneration` _integer_ | ObservedGeneration is the most recent generation observed for this MCPServer.
It corresponds to the MCPServer's generation, which is updated on mutation by the API Server. | | | + +#### ServiceAccountConfig + +ServiceAccountConfig defines the configuration for the ServiceAccount. + +_Appears in:_ +- [MCPServerDeployment](#mcpserverdeployment) + +| Field | Description | Default | Validation | +| --- | --- | --- | --- | +| `annotations` _object (keys:string, values:string)_ | Annotations to add to the ServiceAccount.
This is useful for configuring AWS IRSA (IAM Roles for Service Accounts)
or other cloud provider integrations.
Example: \{"eks.amazonaws.com/role-arn": "arn:aws:iam::123456789012:role/my-role"\} | | | +| `labels` _object (keys:string, values:string)_ | Labels to add to the ServiceAccount. | | | + +#### StdioTransport + +StdioTransport defines the configuration for a standard input/output transport. + +_Appears in:_ +- [MCPServerSpec](#mcpserverspec) + +#### TransportType + +_Underlying type:_ _string_ + +MCPServerTransportType defines the type of transport for the MCP server. + +_Appears in:_ +- [MCPServerSpec](#mcpserverspec) + +| Field | Description | +| --- | --- | +| `stdio` | TransportTypeStdio indicates that the MCP server uses standard input/output for communication.
| +| `http` | TransportTypeHTTP indicates that the MCP server uses Streamable HTTP for communication.
| + diff --git a/docs-site/content/kmcp/reference/kmcp-add-tool.md b/docs-site/content/kmcp/reference/kmcp-add-tool.md new file mode 100644 index 00000000..8a1a78a5 --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-add-tool.md @@ -0,0 +1,30 @@ +--- +title: kmcp add-tool +description: kmcp add-tool command +weight: 10 +--- + +Create a boilerplate for a sample `echo` tool in the `tools` directory of your MCP project and update all the MCP server dependencies to import that tool. You can use this boilerplate as the base to build your own tool. + +```bash +kmcp add-tool [tool-name] [flags] +``` + +**Flags:** +- `--description, -d` - Tool description +- `--force, -f` - Overwrite existing tool file +- `-h, --help` - Help for the command +- `--interactive, -i` - Interactive tool creation +- `--project-dir` - Project directory (default: current directory) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + +## Example + +The following command creates a `mytool` MCP tool in the `my-mcp-server` MCP project. You can edit the file and adjust the code as needed. + +```sh +kmcp add-tool mytool --project-dir my-mcp-server +``` + diff --git a/docs-site/content/kmcp/reference/kmcp-build.md b/docs-site/content/kmcp/reference/kmcp-build.md new file mode 100644 index 00000000..216c32bb --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-build.md @@ -0,0 +1,28 @@ +--- +title: kmcp build +description: kmcp build command +weight: 10 +--- + +Build a Docker image for your MCP server. You can later use this image to deploy your MCP server in a Kubernetes environment. + +```bash +kmcp build [flags] +``` + +**Flags:** +- `-h, --help` - Help for the command +- `--kind-load` - Load image onto a kind cluster (requires kind) +- `--kind-load-cluster` - Name of the kind cluster to load the image onto (default: current cluster context) +- `--platform` - Target platform (e.g., linux/amd64, linux/arm64) +- `--project-dir, -d` - Build directory (default: current directory) +- `--push` - Push the Docker image to a container registry +- `--tag, -t` - Docker image tag + +## Example + +The following command creates a Docker image for the `my-mcp-server` project on your local machine and tags the image as latest. The image is then loaded to a kind cluster named `kind`. + +```sh +kmcp build --project-dir my-mcp-server -t my-mcp-server:latest --kind-load-cluster kind +``` \ No newline at end of file diff --git a/docs-site/content/kmcp/reference/kmcp-completion.md b/docs-site/content/kmcp/reference/kmcp-completion.md new file mode 100644 index 00000000..ec13618e --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-completion.md @@ -0,0 +1,18 @@ +--- +title: kmcp completion +description: kmcp completion command +weight: 30 +--- + +Generate the autocompletion script for kmcp for the specified shell. See each sub-command's help for details on how to use the generated script. + +```bash +kmcp completion [flags] +``` + +**Subcommands:** +- `bash` - Generate the autocompletion script for bash +- `fish` - Generate the autocompletion script for fish +- `powershell` - Generate the autocompletion script for powershell +- `zsh` - Generate the autocompletion script for zsh + diff --git a/docs-site/content/kmcp/reference/kmcp-deploy.md b/docs-site/content/kmcp/reference/kmcp-deploy.md new file mode 100644 index 00000000..b1f378c2 --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-deploy.md @@ -0,0 +1,49 @@ +--- +title: kmcp deploy +description: kmcp deploy command +weight: 10 +--- + +Deploy an MCP server to Kubernetes by generating the MCPServer CRDs. The command uses the `kmcp.yaml` file in your MCP project to spin up and deploy the MCP server in the environment that you specified. + +```bash +kmcp deploy [name] [flags] +``` + +**Subcommands**: + +* `package [flags]` - Deploys an MCP server instance from an existing npm package. + +**Package flags**: +- `--args` - Arguments to pass to the package manager, such as package names (required) +- `--deployment-name` - Name of the MCP server deployment +- `--manager` - Package manager to use (`npx` or `uvx`) (required) + +**Flags:** +- `--args` - Command arguments +- `--command` - Command to run (overrides project config) +- `--dry-run` - Generate manifest without applying to cluster +- `--env` - Environment variables (KEY=VALUE) +- `--environment` - Target environment for deployment (e.g., staging, production) (default: "staging") +- `--file, -f` - Path to kmcp.yaml file (default: current directory) +- `--force` - Force deployment even if validation fails +- `-h, --help` - Help for the command +- `--image` - Docker image to deploy (overrides build image) +- `--namespace, -n` - Kubernetes namespace (default: "default") +- `--no-inspector` - Do not start the MCP inspector tool when deploying the MCP server +- `--output, -o` - Output file for the generated YAML +- `--port` - Container port (default: from project config) +- `--target-port` - Target port for HTTP transport +- `--transport` - Transport type (stdio, http) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + +## Example + +The following example spins up an MCP server in the staging environment with the configuration that is defined in the `my-mcp-server/kmcp.yaml` file. To spin up the server, you use the `my-mcp-server:latest` image. The command automatically opens the MCP inspector tool so that you can test your MCP server. + +```sh +kmcp deploy --environment staging --file my-mcp-server/kmcp.yaml --image my-mcp-server:latest +``` + diff --git a/docs-site/content/kmcp/reference/kmcp-help.md b/docs-site/content/kmcp/reference/kmcp-help.md new file mode 100644 index 00000000..29695c2a --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-help.md @@ -0,0 +1,12 @@ +--- +title: kmcp help +description: kmcp help command +weight: 100 +--- + +Help provides help for any command in the `kmcp` CLI. + +```bash +kmcp help [command] [flags] +``` + diff --git a/docs-site/content/kmcp/reference/kmcp-init.md b/docs-site/content/kmcp/reference/kmcp-init.md new file mode 100644 index 00000000..b3e03579 --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-init.md @@ -0,0 +1,43 @@ +--- +title: kmcp init +description: kmcp init command +weight: 10 +--- + +Create a scaffold for a new [FastMCP](https://github.com/jlowin/fastmcp) or [MCP Go](https://github.com/mark3labs/mcp-go) server project. + +```bash +kmcp init [subcommand] [project-name] [flags] +``` + +**Subcommands:** +- `python [project-name]` - Initialize a Python MCP server project using fastmcp-python +- `go [project-name]` - Initialize a Go MCP server project using mcp-go + +**Flags:** +- `--author` - Set project author +- `--description` - Set project description +- `--email` - Set author email +- `--force` - Overwrite existing directory +- `-h, --help` - Help for the command +- `--namespace` - Default namespace for project resources (default: "default") +- `--no-git` - Skip git initialization +- `--non-interactive` - Use defaults without prompts + +**Go-specific Flags:** +- `--go-module-name` - The Go module name for the project (e.g., github.com/my-org/my-project) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + +## Example + +FastMCP: +```sh +kmcp init python my-mcp-server +``` + +MCP Go: +```sh +kmcp init go my-mcp-server --go-module-name my-mcp-server +``` diff --git a/docs-site/content/kmcp/reference/kmcp-install.md b/docs-site/content/kmcp/reference/kmcp-install.md new file mode 100644 index 00000000..e19e8be4 --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-install.md @@ -0,0 +1,29 @@ +--- +title: kmcp install +description: kmcp install command +weight: 10 +--- + +Install the KMCP controller and its required Custom Resource Definitions (CRDs) +on a Kubernetes cluster. The KMCP contoller manages the lifecycle of MCPServer resources. + +The command installs the following resources: +* The MCPServer Custom Resource Definition to define your MCP server. +* The ClusterRole and ClusterRoleBinding to control RBAC permissions for the KMCP controller. +* The KMCP controller deployment that automatically manages the lifecycle of MCPServer resources. + +```bash +kmcp install [flags] +``` + +**Note**: Run this command once for each cluster to set up the necessary infrastructure +for deploying MCP servers. + +**Flags:** +- `-h, --help` - Help for the command +- `--namespace` - Namespace for the KMCP controller (defaults to kmcp-system) +- `--version` - Version of the controller to deploy (defaults to kmcp version) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + diff --git a/docs-site/content/kmcp/reference/kmcp-run.md b/docs-site/content/kmcp/reference/kmcp-run.md new file mode 100644 index 00000000..26d08740 --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-run.md @@ -0,0 +1,32 @@ +--- +title: kmcp run +description: kmcp run command +weight: 10 +--- + +Run an MCP server on your local machine by using the Model Context Protocol inspector tool. + +**Note**: If you do not have the MCP inspector tool installed, run `npm install -g @modelcontextprotocol/inspector`. + +```bash +kmcp run [flags] +``` + +**Flags:** +- `-h, --help` - Help for the command +- `--no-inspector` - Run the server directly without launching the MCP inspector tool +- `--project-dir, -d` - Project directory to use (default: current directory) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + +## Example + +The following command runs the MCP server that is defined in the `my-mcp-server` project on your local machine. +The command automatically builds the Docker image for your MCP server and opens the MCP inspector tool so that you can connect to your server. + +```sh +kmcp run --project-dir my-mcp-server +``` + +To learn how to use the MCP inspector tool to connect to an MCP server, check out the [FastMCP Python](/docs/kmcp/develop/fastmcp-python) or [MCP Go](/docs/kmcp/develop/mcp-go) guide. diff --git a/docs-site/content/kmcp/reference/kmcp-secrets.md b/docs-site/content/kmcp/reference/kmcp-secrets.md new file mode 100644 index 00000000..747579ac --- /dev/null +++ b/docs-site/content/kmcp/reference/kmcp-secrets.md @@ -0,0 +1,34 @@ +--- +title: kmcp secrets +description: kmcp secrets command +weight: 10 +--- + +Manage secrets for MCP server projects and apply them to a Kubernetes cluster. + +```bash +kmcp secrets [subcommand] [flags] +``` + +**Subcommands:** +- `sync [environment]` - Sync secrets to a Kubernetes environment from a local .env file. The environment is defined in the `kmcp.yaml` file. + +**Sync Flags:** +- `--dry-run` - Output the generated secret YAML instead of applying it +- `--from-file` - Source .env file to sync from (default: ".env") +- `-h, --help` - Help for the command +- `--project-dir, -d` - Project directory (default: current directory) + +**Global Flags:** +- `--verbose, -v` - Show detailed output + +## Example + +The following command reads the environment variables that are defined in the `.env.staging` file and puts them into a Kubernetes secret in your cluster. +The name and namespace for the secret are defined in the `staging` environment configuration of the `kmcp.yaml` file. + +```sh +kmcp secrets sync staging --from-file my-mcp-server/.env.staging --project-dir my-mcp-server +``` + +For more information, check out [Manage secrets for MCP servers](/docs/kmcp/secrets). \ No newline at end of file diff --git a/docs-site/content/kmcp/secrets.md b/docs-site/content/kmcp/secrets.md new file mode 100644 index 00000000..8716c55a --- /dev/null +++ b/docs-site/content/kmcp/secrets.md @@ -0,0 +1,143 @@ +--- +title: Manage secrets +description: Configure your MCP server to read additional environment variables from a Kubernetes secret. +weight: 50 +--- + +You can bootstrap your MCP server with additional environment variables that the MCP server needs to run properly. These environment variables are typically defined in an `.env` file. + +You can use the `kmcp secret` command to store these environment variables in a Kubernetes secret and to automatically configure the MCP server to mount that secret during the MCP server deployment. + +The name and namespace of the Kubernetes secret that you want to create is defined in the `kmcp.yaml` file of your project. + +## Prerequisites + +- Create a [FastMCP](/docs/kmcp/develop/fastmcp-python) or [MCP Go](/docs/kmcp/develop/mcp-go) project with a sample MCP server and tool. +- [Install the kmcp controller](/docs/kmcp/deploy/install-controller) in a local kind cluster to manage the lifecycle of MCP servers in your cluster. + +## Store environment variables in a Kubernetes secret + +1. Review the `kmcp.yaml` configuration of your MCP project. The default `kmcp.yaml` file includes a `secrets` section that defines multiple environments, such as `staging`, `production`, and `local`. Each environment defines the name and the namespace of the Kubernetes secret that you want to use. Note that all environments are currently disabled. + ```sh + cat my-mcp-server/kmcp.yaml + ``` + + Example output: + ```yaml + name: my-mcp-server + framework: fastmcp-python + version: 0.1.0 + description: MCP server built with fastmcp-python + secrets: + local: + enabled: false + provider: env + file: .env.local + production: + enabled: false + provider: kubernetes + secretName: my-mcp-server-secrets-production + namespace: default + staging: + enabled: false + provider: kubernetes + secretName: my-mcp-server-secrets-staging + namespace: default + ``` + +2. Enable the staging environment by setting the `secret.staging.enabled` field to `true`. You can optionally change the name and namespace of the Kubernetes secret that you want to use with your MCP server. However, keep in mind that the secret must be in the same namespace where the MCP server is deployed. + ```yaml + ... + secrets: + local: + enabled: false + provider: env + file: .env.local + production: + enabled: false + provider: kubernetes + secretName: my-mcp-server-secrets-production + namespace: default + staging: + enabled: true + provider: kubernetes + secretName: my-mcp-server-secrets-staging + namespace: default + ``` + +3. Create an `.env.staging` file in your MCP project that defines additional environment variables that you want to provide to your MCP server. + ```sh + cat << EOF > my-mcp-server/.env.staging + # .env.staging + API_KEY=your-api-key-here + DATABASE_URL=postgresql://user:pass@host:5432/db + EOF + ``` + +4. Create the Kubernetes secret in your kind cluster by using the secret defintion from the `kmcp.yaml` file and the environment variables from the `.env.staging` file. Note that this step is not required when you plan to run your MCP server locally only. + ```sh + kmcp secrets sync staging --from-file my-mcp-server/.env.staging --project-dir my-mcp-server + ``` + +5. Verify that the Kubernetes secret is created and that you can see the base64-encoded environment variables that you defined earlier. + ```sh + kubectl get secret my-mcp-server-secrets-staging -o yaml + ``` + + Example output: + ```yaml + apiVersion: v1 + data: + API_KEY: eW91ci1hcGkta2V5LWhlcmU= + DATABASE_URL: cG9zdGdyZXNxbDovL3VzZXI6cGFzc0Bob3N0OjU0MzIvZGI= + kind: Secret + metadata: + name: my-mcp-server-secrets-staging + namespace: default + resourceVersion: "10819" + uid: 85... + type: Opaque + ``` + +## Deploy the MCP server with your secret + +1. Build a Docker image for your MCP server and load it to your kind cluster. + ```sh + kmcp build --project-dir my-mcp-server -t my-mcp-server:latest --kind-load-cluster kind + ``` + +2. Deploy your MCP server and bootstrap it with the Kubernetes secret of the staging environment. + ```sh + kmcp deploy --environment staging --file my-mcp-server/kmcp.yaml --no-inspector --image my-mcp-server:latest + ``` + +3. Verify that your server is up and running. + ```sh + kubectl get pods + ``` + +4. Get the details of the `my-mcp-server` deployment. Verify that you see the reference to your Kubernetes secret in the `spec.containers.envFrom` section. + ```sh + kubectl get deployment my-mcp-server -o yaml + ``` + + Example output: + ```sh + ... + template: + metadata: + creationTimestamp: null + labels: + app.kubernetes.io/instance: my-mcp-server + app.kubernetes.io/managed-by: kmcp + app.kubernetes.io/name: my-mcp-server + spec: + containers: + ... + envFrom: + - secretRef: + name: my-mcp-server-secrets-staging + image: my-mcp-server:latest + ... + ``` + diff --git a/docs-site/go.mod b/docs-site/go.mod new file mode 100644 index 00000000..57b96605 --- /dev/null +++ b/docs-site/go.mod @@ -0,0 +1,5 @@ +module github.com/kagent-dev/website-docs + +go 1.21 + +require github.com/solo-io/docs-theme-extras v0.1.18-beta.7 // indirect diff --git a/docs-site/go.sum b/docs-site/go.sum new file mode 100644 index 00000000..9a4f577c --- /dev/null +++ b/docs-site/go.sum @@ -0,0 +1,6 @@ +github.com/solo-io/docs-theme-extras v0.1.18-beta.5 h1:gbCV0I0NB6z/k+qQTy0Dhl1XkswDwsxQPfZiM1Fniaw= +github.com/solo-io/docs-theme-extras v0.1.18-beta.5/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= +github.com/solo-io/docs-theme-extras v0.1.18-beta.6 h1:+E0ZW1rmf8rnL3TaFgaIwW72HtCdJzuw1UEIdY2RPTc= +github.com/solo-io/docs-theme-extras v0.1.18-beta.6/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= +github.com/solo-io/docs-theme-extras v0.1.18-beta.7 h1:Z1WWb9ZCoJymUkh3d1e9akfVX2aGOIUTdPoEH26XvcQ= +github.com/solo-io/docs-theme-extras v0.1.18-beta.7/go.mod h1:jjjYu/QoD+vMu30zgcpfEuTEGuJOJWs5qai/K18kltg= diff --git a/docs-site/hugo.yaml b/docs-site/hugo.yaml new file mode 100644 index 00000000..db1b73f2 --- /dev/null +++ b/docs-site/hugo.yaml @@ -0,0 +1,151 @@ +# The docs are served as a static sub-site under /docs of the kagent.dev origin +# (the Next.js marketing worker owns everything else). A baseURL with the /docs +# path prefix namespaces every emitted URL (pages AND css/js/images/favicons) +# under /docs, so Hugo's output drops cleanly into the worker's public/docs/ +# static assets with no collisions against the marketing site's /images, etc. +# Content lives at content/
+
+
+
+{{- else -}}
+{{- /* Regular menu item without children */ -}}
+{{- /* Same-origin marketing links (Blog/Tools/Agents/…) live at the site ROOT,
+ not under the docs' /docs baseURL. A menu `url: /agents` would be prefixed
+ to /docs/agents, so those entries set `params.localHref` (used verbatim)
+ to keep them root-relative — clicking stays on the current host instead of
+ jumping to production. */ -}}
+{{- $href := $link -}}
+{{- with $item.Params.localHref -}}{{- $href = . -}}{{- end -}}
+
+ {{- if $icon -}}
+
+ {{- partial "utils/icon" (dict "name" $icon "attributes" `height="1em" class="hx:inline-block"`) -}}
+
+ {{- end -}}
+
+ {{- or (T $item.Identifier) $item.Name | safeHTML -}}
+
+
+{{- end -}}
diff --git a/docs-site/layouts/_partials/sidebar.html b/docs-site/layouts/_partials/sidebar.html
new file mode 100644
index 00000000..fd2a0d40
--- /dev/null
+++ b/docs-site/layouts/_partials/sidebar.html
@@ -0,0 +1,88 @@
+{{- /*
+ kagent project sidebar override.
+
+ Why this exists: Hextra v0.12 ships layouts/_partials/sidebar.html, which
+ (per the _partials-shadows-partials precedence rule) wins over docs-theme-
+ extras' layouts/partials/sidebar.html. Hextra's native sidebar roots the tree
+ at the current section, so kagent's nav "drills down" as you navigate deeper
+ instead of showing the whole product tree.
+
+ kagent docs are flat + unversioned but split across two products (kagent + kmcp,
+ each a top-level content section). This override roots the tree at the product
+ section via .FirstSection — the current page's top-level section ancestor — so
+ every page in a product shows that product's full, expandable tree with the
+ active branch auto-expanded. Using .FirstSection (rather than parsing the URL
+ for a /docs/
+
In v0.6, you add certain fields to designate the Service as an MCP server.
In the following configuration file, notice the following settings:
diff --git a/src/app/tools/layout.tsx b/src/app/tools/layout.tsx
deleted file mode 100644
index 9d55450d..00000000
--- a/src/app/tools/layout.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import React from "react";
-import DocsLayoutClient from "../docs/DocsLayoutClient";
-import navigationData from "@/config/navigation.json";
-
-interface NavItem {
- title: string;
- href: string;
- items?: NavItem[];
- external?: boolean;
-}
-
-export default function ToolsLayout({ children }: { children: React.ReactNode }) {
- const navigation: NavItem[] = navigationData as NavItem[];
-
- return (
-
- {children}
-
- );
-}
diff --git a/src/components/navbar.tsx b/src/components/navbar.tsx
index 2e1e01c3..5114ac0f 100644
--- a/src/components/navbar.tsx
+++ b/src/components/navbar.tsx
@@ -2,13 +2,11 @@
import Link from "next/link";
import { GITHUB_LINK } from "@/data/links";
import { useState } from "react";
-import { usePathname } from "next/navigation";
import KagentLogoWithText from "./icons/kagent-logo-text";
import KagentLogo from "./icons/kagent-logo";
import KMCPIcon from "./icons/kmcpicon";
import { ThemeToggle } from "./theme-toggle";
-import { Button } from "./ui/button";
-import { Menu, X, ChevronDown } from "lucide-react";
+import { Menu, X, ChevronDown, Github } from "lucide-react";
import { DocSearch } from "@docsearch/react";
import {
DropdownMenu,
@@ -17,296 +15,153 @@ import {
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
+/*
+ * Marketing navbar — styled to match the Hugo/Hextra docs top nav so switching
+ * between the marketing pages and /docs isn't jarring. Mirrors the docs nav's
+ * layout (logo left; Docs dropdown + marketing links + search + GitHub icon +
+ * theme toggle on the right), uniform gray link styling (no active bold/underline),
+ * height, and light/dark colors. The docs nav is rendered by Hugo
+ * (docs-site/layouts/_partials/navbar-link.html); keep the two visually in sync.
+ */
+
+// Uniform link styling — matches the docs nav (no active-state emphasis, since
+// most links are cross-section and would rarely be "active" anyway).
+const linkCls =
+ "text-sm whitespace-nowrap text-gray-600 transition-colors hover:text-gray-800 dark:text-gray-400 dark:hover:text-gray-200";
+
+const marketingLinks = [
+ { href: "/blog", label: "Blog" },
+ { href: "/tools", label: "Tools" },
+ { href: "/agents", label: "Agents" },
+ { href: "/community", label: "Community" },
+ { href: "/enterprise", label: "Enterprise" },
+];
+
+// Docs products for the dropdown (mirrors the docs nav's kagent/kmcp menu).
+const docsProducts = [
+ { href: "/docs/kagent", label: "kagent", Icon: KagentLogo },
+ { href: "/docs/kmcp", label: "kmcp", Icon: KMCPIcon },
+];
+
export default function Navbar() {
const [isMenuOpen, setIsMenuOpen] = useState(false);
- const pathname = usePathname();
-
- const isActive = (href: string) => {
- if (href === "/") return pathname === "/";
- return pathname.startsWith(href);
- };
return (
-