Skip to content

Commit ff2f991

Browse files
committed
feat(api): add spec.kagent.compaction to the v1alpha3 Harness
The Go runtime honours context_config.compaction in config.json, but nothing on main produced it: the v1alpha3 API had no field for it, unlike spec.declarative.context on the 0.10 Agent. This adds spec.kagent.compaction to the Harness with the sliding-window and tail-retention settings and an optional summarizer (ModelConfig, promptTemplate), and the kagent compiler applies it to every root agent the Harness runs. Compaction is runtime policy rather than portable agent behaviour: it is specific to the ADK runner, the Claude and Codex harnesses have nothing to apply it to, and a later harness would compact differently. It therefore sits next to spec.kagent.memory, the existing precedent for kagent-specific policy, instead of on the AgentTemplate. Because only the kagent adapter carries the field, no status warning is needed for harnesses that do not apply it. The CRD rejects at admission what the runtime would refuse at startup: no strategy, tokenThreshold without eventRetentionSize (and the reverse), overlapSize without compactionInterval, a promptTemplate without {conversation_history}. A summarizer ModelConfig other than the agent's own is resolved from the Harness namespace like the memory model, so its credentials and egress join the revision and a change to it compiles a new revision; the agent's own model is left implicit because the runtime already summarizes with it by default. Signed-off-by: Timo Derstappen <[email protected]>
1 parent 4614444 commit ff2f991

10 files changed

Lines changed: 542 additions & 3 deletions

File tree

‎docs/architecture/configuration-and-compilation.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ application and readiness. The central entry points are
6363

6464
## Harness-specific output
6565

66-
- **kagent** emits Go ADK configuration, Shared native subagents, and the kagent
67-
HITL extension.
66+
- **kagent** emits Go ADK configuration, the Harness's memory and context
67+
compaction policy, Shared native subagents, and the kagent HITL extension.
6868
- **Codex** emits native App Server configuration, OpenAI or Bedrock model setup,
6969
Streamable HTTP MCP servers, Shared agents, and skills. Approvals are currently
7070
disabled by policy.
@@ -75,3 +75,10 @@ application and readiness. The central entry points are
7575
supplied in the ADK-shaped format when requested.
7676

7777
Dedicated agent bindings are not compiled yet.
78+
79+
`spec.kagent.compaction` on the Harness is runtime policy, like `spec.kagent.memory`:
80+
it belongs to the runner that drives the root agent and is not part of the
81+
portable template. The kagent compiler applies it to every root agent the
82+
Harness runs. A summarizer `ModelConfig` other than the agent's own is resolved
83+
from the Harness namespace like the memory model and joins the revision's
84+
credentials, egress, and provenance.

‎go/api/config/crd/bases/kagent.dev_harnesses.yaml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,81 @@ spec:
166166
kagent:
167167
description: KagentHarness configures the kagent runtime adapter.
168168
properties:
169+
compaction:
170+
description: |-
171+
Compaction summarizes older session events so the prompt stays small as
172+
a conversation grows. Omitted leaves the history uncompacted.
173+
properties:
174+
compactionInterval:
175+
description: |-
176+
CompactionInterval is the number of new user-initiated invocations that,
177+
once fully represented in the session, triggers a sliding-window
178+
compaction of those invocations.
179+
minimum: 1
180+
type: integer
181+
eventRetentionSize:
182+
description: |-
183+
EventRetentionSize is the number of most recent events that tail
184+
retention keeps uncompacted.
185+
minimum: 1
186+
type: integer
187+
overlapSize:
188+
description: |-
189+
OverlapSize is the number of already-compacted invocations pulled back
190+
into the next sliding window so consecutive summaries overlap.
191+
minimum: 0
192+
type: integer
193+
summarizer:
194+
description: |-
195+
Summarizer selects the model and prompt that write the summaries.
196+
Omitted summarizes with the agent's own model and the runtime's default
197+
prompt.
198+
properties:
199+
modelConfigRef:
200+
description: |-
201+
ModelConfigRef references the ModelConfig in the Harness namespace that
202+
writes the summaries. Omitted uses the agent's own model.
203+
properties:
204+
name:
205+
default: ""
206+
description: |-
207+
Name of the referent.
208+
This field is effectively required, but due to backwards compatibility is
209+
allowed to be empty. Instances of this type with an empty value here are
210+
almost certainly wrong.
211+
More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
212+
type: string
213+
type: object
214+
x-kubernetes-map-type: atomic
215+
x-kubernetes-validations:
216+
- message: name must not be empty
217+
rule: has(self.name) && self.name != ''
218+
promptTemplate:
219+
description: |-
220+
PromptTemplate replaces the runtime's default summarization prompt. It
221+
must contain {conversation_history}, which the runtime replaces with the
222+
rendered events.
223+
minLength: 1
224+
type: string
225+
type: object
226+
x-kubernetes-validations:
227+
- message: promptTemplate must contain {conversation_history}
228+
rule: '!has(self.promptTemplate) || self.promptTemplate.contains(''{conversation_history}'')'
229+
tokenThreshold:
230+
description: |-
231+
TokenThreshold is the prompt token count at which tail-retention
232+
compaction summarizes the history before the next model call.
233+
minimum: 1
234+
type: integer
235+
type: object
236+
x-kubernetes-validations:
237+
- message: compactionInterval or tokenThreshold must be specified
238+
rule: has(self.compactionInterval) || has(self.tokenThreshold)
239+
- message: tokenThreshold and eventRetentionSize must be specified
240+
together
241+
rule: has(self.tokenThreshold) == has(self.eventRetentionSize)
242+
- message: overlapSize requires compactionInterval
243+
rule: '!has(self.overlapSize) || has(self.compactionInterval)'
169244
memory:
170245
description: Memory enables long-term memory for agents using
171246
this Harness.

‎go/api/v1alpha3/configuration_crd_cel_test.go‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,48 @@ func TestConfigurationCRDValidation(t *testing.T) {
172172
}}),
173173
wantReject: "kind must be RemoteMCPServer",
174174
},
175+
{
176+
name: "Harness compaction requires a strategy",
177+
object: compactionHarness(namespace, "compaction-no-strategy", KagentHarnessCompaction{
178+
Summarizer: &KagentHarnessSummarizer{PromptTemplate: "Summarize.\n\n{conversation_history}"},
179+
}),
180+
wantReject: "compactionInterval or tokenThreshold must be specified",
181+
},
182+
{
183+
name: "Harness compaction pairs tokenThreshold with eventRetentionSize",
184+
object: compactionHarness(namespace, "compaction-threshold-alone", KagentHarnessCompaction{TokenThreshold: new(50000)}),
185+
wantReject: "tokenThreshold and eventRetentionSize must be specified together",
186+
},
187+
{
188+
name: "Harness compaction overlap requires an interval",
189+
object: compactionHarness(namespace, "compaction-overlap-alone", KagentHarnessCompaction{
190+
TokenThreshold: new(50000), EventRetentionSize: new(10), OverlapSize: new(2),
191+
}),
192+
wantReject: "overlapSize requires compactionInterval",
193+
},
194+
{
195+
name: "Harness summarizer prompt needs the history placeholder",
196+
object: compactionHarness(namespace, "compaction-prompt-without-history", KagentHarnessCompaction{
197+
CompactionInterval: new(5), Summarizer: &KagentHarnessSummarizer{PromptTemplate: "Summarize."},
198+
}),
199+
wantReject: "promptTemplate must contain {conversation_history}",
200+
},
201+
{
202+
name: "Harness rejects empty summarizer ModelConfig reference",
203+
object: compactionHarness(namespace, "compaction-empty-summarizer-model", KagentHarnessCompaction{
204+
CompactionInterval: new(5), Summarizer: &KagentHarnessSummarizer{ModelConfigRef: &corev1.LocalObjectReference{}},
205+
}),
206+
wantReject: "name must not be empty",
207+
},
208+
{
209+
name: "valid Harness compaction",
210+
object: compactionHarness(namespace, "compaction-valid", KagentHarnessCompaction{
211+
CompactionInterval: new(5), OverlapSize: new(2), TokenThreshold: new(50000), EventRetentionSize: new(10),
212+
Summarizer: &KagentHarnessSummarizer{
213+
ModelConfigRef: &corev1.LocalObjectReference{Name: "summarizer"}, PromptTemplate: "Summarize.\n\n{conversation_history}",
214+
},
215+
}),
216+
},
175217
}
176218

177219
for _, tc := range cases {
@@ -208,3 +250,7 @@ func validAgentTemplate(namespace, name string, tools []ToolBinding) *AgentTempl
208250
},
209251
}
210252
}
253+
254+
func compactionHarness(namespace, name string, compaction KagentHarnessCompaction) *Harness {
255+
return validHarness(namespace, name, HarnessSpec{Kagent: &KagentHarness{Compaction: &compaction}})
256+
}

‎go/api/v1alpha3/harness_types.go‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,65 @@ type KagentHarness struct {
2727
// Memory enables long-term memory for agents using this Harness.
2828
// +optional
2929
Memory *KagentHarnessMemory `json:"memory,omitempty"`
30+
31+
// Compaction summarizes older session events so the prompt stays small as
32+
// a conversation grows. Omitted leaves the history uncompacted.
33+
// +optional
34+
Compaction *KagentHarnessCompaction `json:"compaction,omitempty"`
35+
}
36+
37+
// KagentHarnessCompaction selects the compaction strategies and the model that
38+
// writes the summaries. The sliding window (compactionInterval, overlapSize)
39+
// summarizes each group of completed invocations; tail retention
40+
// (tokenThreshold, eventRetentionSize) bounds the prompt by summarizing
41+
// everything but the most recent events once the prompt grows past a token
42+
// count. At least one strategy must be configured.
43+
// +kubebuilder:validation:XValidation:rule="has(self.compactionInterval) || has(self.tokenThreshold)",message="compactionInterval or tokenThreshold must be specified"
44+
// +kubebuilder:validation:XValidation:rule="has(self.tokenThreshold) == has(self.eventRetentionSize)",message="tokenThreshold and eventRetentionSize must be specified together"
45+
// +kubebuilder:validation:XValidation:rule="!has(self.overlapSize) || has(self.compactionInterval)",message="overlapSize requires compactionInterval"
46+
type KagentHarnessCompaction struct {
47+
// CompactionInterval is the number of new user-initiated invocations that,
48+
// once fully represented in the session, triggers a sliding-window
49+
// compaction of those invocations.
50+
// +kubebuilder:validation:Minimum=1
51+
// +optional
52+
CompactionInterval *int `json:"compactionInterval,omitempty"`
53+
// OverlapSize is the number of already-compacted invocations pulled back
54+
// into the next sliding window so consecutive summaries overlap.
55+
// +kubebuilder:validation:Minimum=0
56+
// +optional
57+
OverlapSize *int `json:"overlapSize,omitempty"`
58+
// TokenThreshold is the prompt token count at which tail-retention
59+
// compaction summarizes the history before the next model call.
60+
// +kubebuilder:validation:Minimum=1
61+
// +optional
62+
TokenThreshold *int `json:"tokenThreshold,omitempty"`
63+
// EventRetentionSize is the number of most recent events that tail
64+
// retention keeps uncompacted.
65+
// +kubebuilder:validation:Minimum=1
66+
// +optional
67+
EventRetentionSize *int `json:"eventRetentionSize,omitempty"`
68+
// Summarizer selects the model and prompt that write the summaries.
69+
// Omitted summarizes with the agent's own model and the runtime's default
70+
// prompt.
71+
// +optional
72+
Summarizer *KagentHarnessSummarizer `json:"summarizer,omitempty"`
73+
}
74+
75+
// KagentHarnessSummarizer configures the model that summarizes compacted events.
76+
// +kubebuilder:validation:XValidation:rule="!has(self.promptTemplate) || self.promptTemplate.contains('{conversation_history}')",message="promptTemplate must contain {conversation_history}"
77+
type KagentHarnessSummarizer struct {
78+
// ModelConfigRef references the ModelConfig in the Harness namespace that
79+
// writes the summaries. Omitted uses the agent's own model.
80+
// +kubebuilder:validation:XValidation:rule="has(self.name) && self.name != ''",message="name must not be empty"
81+
// +optional
82+
ModelConfigRef *corev1.LocalObjectReference `json:"modelConfigRef,omitempty"`
83+
// PromptTemplate replaces the runtime's default summarization prompt. It
84+
// must contain {conversation_history}, which the runtime replaces with the
85+
// rendered events.
86+
// +kubebuilder:validation:MinLength=1
87+
// +optional
88+
PromptTemplate string `json:"promptTemplate,omitempty"`
3089
}
3190

3291
// KagentHarnessMemory configures kagent's long-term memory service.

‎go/api/v1alpha3/zz_generated.deepcopy.go‎

Lines changed: 65 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎go/core/internal/translator/adkconfig/builder.go‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,48 @@ func (c *Builder) Build(ctx context.Context, input *v2translator.AgentInput) (*R
100100
return c.compileAgent(ctx, input)
101101
}
102102

103+
// ApplyCompaction translates the Harness's kagent compaction policy into the
104+
// ADK context configuration of a compiled root agent. Compaction is a property
105+
// of the runner that drives the root agent, so it is runtime policy on the
106+
// Harness rather than portable behavior on the AgentTemplate.
107+
//
108+
// A summarizer ModelConfig other than the agent's own is resolved like the
109+
// agent model: its runtime configuration lands in config.json, its credentials
110+
// and egress join the revision, and it joins the provenance so a change to it
111+
// compiles a new revision. The agent's own model is left out because the
112+
// runtime already summarizes with it by default.
113+
func (c *Builder) ApplyCompaction(ctx context.Context, result *Result, harness *v1alpha3.Harness, template *v1alpha3.AgentTemplate) error {
114+
spec := harness.Spec.Kagent.Compaction
115+
if spec == nil {
116+
return nil
117+
}
118+
compaction := &adk.AgentCompressionConfig{
119+
CompactionInterval: spec.CompactionInterval,
120+
OverlapSize: spec.OverlapSize,
121+
TokenThreshold: spec.TokenThreshold,
122+
EventRetentionSize: spec.EventRetentionSize,
123+
}
124+
if summarizer := spec.Summarizer; summarizer != nil {
125+
compaction.PromptTemplate = summarizer.PromptTemplate
126+
if ref := summarizer.ModelConfigRef; ref != nil && !isAgentModel(template, ref.Name) {
127+
model, err := c.BuildModel(ctx, harness.Namespace, ref.Name)
128+
if err != nil {
129+
return fmt.Errorf("resolve summarizer ModelConfig %q: %w", ref.Name, err)
130+
}
131+
compaction.SummarizerModel = model.Model
132+
result.Models = append(result.Models, model.Config)
133+
result.Environment = append(result.Environment, model.Environment...)
134+
result.Egress = append(result.Egress, model.Egress...)
135+
}
136+
}
137+
result.Config.ContextConfig = &adk.AgentContextConfig{Compaction: compaction}
138+
return nil
139+
}
140+
141+
func isAgentModel(template *v1alpha3.AgentTemplate, name string) bool {
142+
return template.Spec.ModelConfig != nil && template.Spec.ModelConfig.Name == name
143+
}
144+
103145
func (c *Builder) compileAgent(ctx context.Context, input *v2translator.AgentInput) (*Result, error) {
104146
modelRuntime := &modelRuntime{data: &modelDeploymentData{}}
105147
var modelConfig *v1alpha3.ModelConfig

0 commit comments

Comments
 (0)