feat: add agent-builder helm chart

[the-mentor]

Summary

• Adds a new agent-builder Helm chart under helm/agents/agent-builder/
• The agent is a self-hosted kagent meta-agent that interviews users, discovers live cluster resources (ModelConfigs, RemoteMCPServers, existing Agents), drafts a valid kagent.dev/v1alpha2 Agent manifest, and applies it only after explicit human approval via requireApproval
• Wires the chart into the main helm/kagent chart as an optional dependency (enabled by default), following the same pattern as all other bundled agents
• Adds agent-builder to helm unittest nodeSelector test suite (agent-nodeselector_test.yaml)
• Adds agent-builder to make helm-agents Makefile target so it is version-stamped and packaged at release time

---

⚠️ Human-in-the-Loop: The Agent Cannot Write to the Cluster Without Your Approval

Every cluster write goes through a mandatory human approval gate — the agent cannot bypass it.

k8s_apply_manifest is the only tool that modifies the cluster, and it is declared under requireApproval in the Agent spec:

tools:
  - type: McpServer
    mcpServer:
      name: kagent-tool-server
      toolNames:
        - k8s_apply_manifest
        # ... read-only discovery tools
      requireApproval:
        - k8s_apply_manifest   # ← pauses and waits for explicit human approval

This means:

• The agent interviews the user and shows the full YAML manifest in the chat before doing anything
• It then calls k8s_apply_manifest — which pauses and presents an approval prompt to the user
• Nothing is written to the cluster until the user explicitly approves
• If the user declines, the cluster is left completely untouched

The system prompt reinforces this: the agent is told not to ask for permission conversationally ("should I apply?") — the tool's approval prompt is the single, unavoidable checkpoint. There is no way for the agent to write to the cluster without a human saying yes.

All other tools (k8s_get_resources, k8s_get_resource_yaml, k8s_get_available_api_resources, k8s_describe_resource, k8s_get_events, k8s_get_pod_logs) are read-only and require no approval.

---

Design decisions

• Least-privilege toolset: only read-only K8s discovery tools plus k8s_apply_manifest gated behind requireApproval
• No delete, no patch, no exec: the agent has no tools to remove, patch, or exec into resources
• Self-protection: the system prompt explicitly forbids the agent from modifying or replacing itself (agent-builder)
• Grounding protocol: the agent discovers real cluster state (ModelConfigs, RemoteMCPServers, existing Agents) before drafting, so it never fabricates tool names or resource references
• Drift disclosure: after applying an agent, the agent tells the user the resource will drift from GitOps/Helm and recommends committing the manifest to source control
• Deployment settings: mirrors the deployment block of existing working agents (via the standard agent.deploymentSpec helper and values.yaml nodeSelector) so it schedules correctly on any cluster topology

Test plan

• helm template renders a valid Agent manifest with default values
• helm template with agent-builder.enabled=false omits the Agent
• helm unittest nodeSelector test suite passes (22/22)
• make helm-install-provider on a fresh Kind cluster — agent-builder reaches READY: True, ACCEPTED: True
• A2A message/send reaches the agent and routes correctly — confirmed via JSON-RPC response

Verification results

helm template with defaults (agent-builder.enabled=true)

Rendered a valid kagent.dev/v1alpha2 Agent resource. Key fields confirmed present:

• spec.type: Declarative
• spec.declarative.runtime: go
• spec.declarative.tools[0].mcpServer.requireApproval: [k8s_apply_manifest]
• spec.declarative.deployment.nodeSelector absent (correct — no default nodeSelector set)
• All 7 tool names present under kagent-tool-server

helm template with agent-builder.enabled=false

Zero agent-builder resources rendered — the condition gate works correctly.

helm template with agent-builder.nodeSelector.disktype=ssd

spec.declarative.deployment.nodeSelector.disktype: ssd rendered correctly, confirming the agent.deploymentSpec helper propagates values as expected.

helm unittest (tests/agent-nodeselector_test.yaml)

PASS  test agent nodeSelector configuration
Charts:      1 passed, 1 total
Test Suites: 1 passed, 1 total
Tests:       22 passed, 22 total   ← 20 existing + 2 new agent-builder cases
Time:        328ms

Kind cluster deployment (make helm-install-provider)

NAME            TYPE          RUNTIME   READY   ACCEPTED
agent-builder   Declarative   go        True    True

NAME                              READY   STATUS    RESTARTS   AGE
agent-builder-8fdb9b6ff-t5cnq    1/1     Running   0          2m51s

Agent deployed, pod running, controller accepted and marked Ready on a fresh Kind cluster.

A2A message/send to agent-builder

Sent a message/send JSON-RPC request with prompt "I want to build an agent that watches for pods in CrashLoopBackOff and summarizes the logs". The request was routed correctly to the agent (adk_app_name: kagent__NS__agent_builder), a task and session were created, and the agent reached the LLM call stage. A2A routing, session creation, and tool wiring are all confirmed working end-to-end.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new optional (enabled-by-default) bundled Helm subchart that deploys an agent-builder kagent.dev/v1alpha2 Declarative Agent, wires it into the main helm/kagent chart, and extends Helm unittest coverage for nodeSelector behavior.

Changes:

• Introduces the new helm/agents/agent-builder chart (Agent manifest, values, helpers, chart template).
• Wires agent-builder into helm/kagent as a dependency and adds default values.
• Extends the existing agent-nodeselector_test.yaml suite and includes the chart in make helm-agents packaging.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
Makefile	Packages the new agent chart during make helm-agents.
helm/kagent/values.yaml	Adds default configuration block for the new agent subchart.
helm/kagent/tests/agent-nodeselector_test.yaml	Adds nodeSelector unit tests for the new agent template.
helm/kagent/Chart-template.yaml	Adds agent-builder as an optional dependency of the main chart.
helm/agents/agent-builder/values.yaml	Defines chart values (modelConfigRef, runtime, resources, nodeSelector, etc.).
helm/agents/agent-builder/templates/agent.yaml	Adds the Declarative Agent resource manifest with tool gating via requireApproval.
helm/agents/agent-builder/templates/_helpers.tpl	Adds the standard agent.deploymentSpec helper used by other agent charts.
helm/agents/agent-builder/Chart-template.yaml	Defines the new agent chart metadata (name, version, description).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[the-mentor]

The reason i called this agent agent-builder was to try and not confuse the end user by calling it something like agent-builder-agent

If someone has a better naming for this agent please let me know.

[sagy101]

Re: helm/agents/agent-builder/templates/agent.yaml → systemMessage → section ## What a Declarative Agent Looks Like (schema you must honor)

This prose duplicates the v1alpha2 CRD with nothing keeping it in sync — it's accurate today (I checked it against go/api/v1alpha2/agent_types.go), but the type is v1alpha2, so fields will be added/renamed and nothing here fails when they drift. "schema you must honor" also nudges the model to trust this frozen text over live reality.

The fix is cheap because discovery is already half-built. Retitle to "(rough sketch — verify against the live CRD)" and add to the Grounding Protocol:

Before drafting, k8s_get_resource_yaml a working agent and trust its shape over this list (and, if RBAC allows, the agents.kagent.dev CRD's openAPIV3Schema for the authoritative field set).

k8s_get_resource_yaml is already in the granted toolNames, and the API server always serves the current schema — so this can't go stale.

Nit: Self-validate (step 5) should also check "every requireApproval entry is in toolNames" — that's CEL-enforced on the CRD (McpServerTool XValidation), so a scoped child agent otherwise hits a guaranteed apply-rejection.

[the-mentor]

@sagy101 I applied the fixes you suggested.

Thank you 🙏