feat: add built-in prompts and prompt templates for agents (#1401)

[EItanya]

Add Go text/template support to the Agent CRD's systemMessage field, enabling composable prompt fragments and variable interpolation. Templates are resolved at reconciliation time by the controller.

• Add PromptSource type using inlined TypedLocalReference for extensibility
• Add promptSources field to DeclarativeAgentSpec
• Implement template resolution with {{include "source/key"}} syntax and agent context variables (AgentName, AgentNamespace, Description, ToolNames, SkillNames)
• Add ConfigMap watch to agent controller for automatic re-reconciliation
• Ship kagent-builtin-prompts Helm ConfigMap with 5 built-in templates (skills-usage, tool-usage-best-practices, safety-guardrails, kubernetes-context, a2a-communication)
• Add GetConfigMapData/GetSecretData utility functions
• Add architecture documentation in docs/architecture/prompt-templates.md

[Copilot]

Pull request overview

Adds a prompt-templating system for Agent declarative systemMessage, enabling composition from ConfigMap/Secret fragments via {{include "source/key"}} and interpolation of agent context variables at reconciliation time.

Changes:

• Extends the Agent CRD with promptSources (PromptSource) and documents template behavior for systemMessage / systemMessageFrom.
• Implements template resolution (include + variable context) in the Go controller translator, with unit tests.
• Ships a Helm-installed kagent-builtin-prompts ConfigMap plus controller watch logic and utility helpers for fetching ConfigMap/Secret data.

Reviewed changes

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

Show a summary per file

File	Description
helm/kagent/templates/builtin-prompts-configmap.yaml	Adds Helm ConfigMap containing built-in prompt fragments.
go/internal/utils/secret.go	Adds helper to fetch all Secret data as strings.
go/internal/utils/config_map.go	Adds helper to fetch all ConfigMap data.
go/internal/controller/translator/agent/template.go	Implements prompt source resolution, template context building, and template execution.
go/internal/controller/translator/agent/template_test.go	Adds unit tests for include and interpolation behavior.
go/internal/controller/translator/agent/adk_api_translator.go	Integrates template resolution into system message translation.
go/internal/controller/agent_controller.go	Adds ConfigMap watch to re-reconcile affected agents.
go/api/v1alpha2/agent_types.go	Adds PromptSource type and promptSources to the declarative spec.
go/api/v1alpha2/zz_generated.deepcopy.go	Updates generated deepcopy logic for the new API fields/types.
docs/architecture/prompt-templates.md	Adds architecture/design documentation for prompt templates.

Comments suppressed due to low confidence (1)

go/api/v1alpha2/agent_types.go:187

• PromptSource inlines TypedLocalReference, which includes an optional namespace field. Unless cross-namespace prompt sourcing is an explicit, access-controlled feature, this should be constrained (e.g., disallow setting namespace or require it to match the Agent namespace via XValidation). Otherwise, users can point agents at ConfigMaps/Secrets in other namespaces, and the controller’s broad RBAC will allow those reads.

	Context *ContextConfig `json:"context,omitempty"`
}

// ContextConfig configures context management for an agent.
type ContextConfig struct {
	// Compaction configures event history compaction.
	// When enabled, older events in the conversation are compacted (compressed/summarized)
	// to reduce context size while preserving key information.
	// +optional
	Compaction *ContextCompressionConfig `json:"compaction,omitempty"`
}

// ContextCompressionConfig configures event history compaction/compression.
type ContextCompressionConfig struct {
	// The number of *new* user-initiated invocations that, once fully represented in the session's events, will trigger a compaction.

---

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

[supreme-gg-gg]

Tried this out very cool

[supreme-gg-gg]

This does not seem to be used anywhere?

[supreme-gg-gg]

nit: since we only support configmaps kind, should we validate the PromptSource.Kind and give an error if the user tries to provide a secret?