Docs: write the Context management page for kagent 1.x

[Rachael-Graham]

The 1.x doc set has no page about context management, and the feature it would document now exists. kagent#2790 landed both halves of it — the CRD field and the translator path — and shipped in v1.0.0-alpha2, so a reader can configure compaction today with nothing in the docs to tell them how.

This is new writing rather than an edit, and it is the largest open docs item for the 1.0 release.

What the page covers

Context compaction: summarizing older session events so an agent's prompt stays bounded as a conversation grows. Two strategies ship, and both are configured on the Harness.

The spine of the page is that compaction sits on the Harness, not on the AgentTemplate. Compaction is a property of the runner that drives the root agent, so it is runtime policy rather than portable agent behavior — the same Harness-versus-AgentTemplate split the rest of the 1.0 doc set is built on, showing up in a new place. Lead with that distinction and the rest of the page follows from it.

Interaction models (sync, async, events) are out of scope. They were the original blocker for this page and they are still unconfirmed for 1.0. Write the page about compaction alone.

The configuration surface

Harness.spec.kagent.compaction, defined in go/api/v1alpha3/harness_types.go. Omitting the block leaves the history uncompacted.

Field	Meaning
compactionInterval	The number of new user-initiated invocations that triggers a sliding-window compaction of those invocations. Minimum 1.
overlapSize	The number of already-compacted invocations pulled back into the next window, so consecutive summaries overlap. Minimum 0.
tokenThreshold	The prompt token count at which tail retention summarizes the history before the next model call. Minimum 1.
eventRetentionSize	The number of most recent events that tail retention keeps uncompacted. Minimum 1.
summarizer.modelConfigRef	The ModelConfig in the Harness namespace that writes the summaries. Omitted summarizes with the agent's own model.
summarizer.promptTemplate	Replaces the runtime's default summarization prompt.

The two strategies are worth presenting as two strategies rather than six fields: the sliding window (compactionInterval, optionally overlapSize) summarizes each group of completed invocations, and tail retention (tokenThreshold with eventRetentionSize) bounds the prompt once it passes a token count.

Four rules, enforced at admission

These are CEL validations on the CRD, so a manifest that breaks one is rejected by the API server rather than failing at runtime. State them as rules, not as advice.

• At least one strategy must be configured — compactionInterval or tokenThreshold.
• tokenThreshold and eventRetentionSize must be set together.
• overlapSize requires compactionInterval.
• A promptTemplate must contain {conversation_history}, which the runtime replaces with the rendered events.

One behavior the API does not announce

A summarizer.modelConfigRef naming a model other than the agent's own is resolved the same way the agent model is: its config lands in config.json, its credentials and egress join the revision, and it joins the provenance — so changing the summarizer model compiles a new revision. Naming the agent's own model is deliberately a no-op, because the runtime already summarizes with it by default. A reader hits this and has no way to predict it, so it belongs on the page.

Translation happens in Builder.ApplyCompaction (go/core/internal/translator/adkconfig/builder.go:112), which sets ContextConfig on the ADK config.

Compaction is a spec.kagent setting, so it applies to the kagent runtime only. A Harness that selects codex, claude, or byo has no compaction settings.

Where the page goes

Open question, worth settling in this issue before the PR. The page was originally scoped into substrate-runtime/, next to Identity and Networking and egress control, back when context was expected to be a runtime-plane topic. Now that the whole configuration surface is a Harness field, docs-site/content/kagent/1.x/agents/context-management.md fits the section better — it sits with Agent harness, Agent memory, and System prompts, which are the other Harness and AgentTemplate configuration pages. Agent memory is the closest model for the page's shape.

Before you start

• The generated API reference already documents KagentHarnessCompaction and KagentHarnessSummarizer as of Update kagent 1.x and kmcp reference docs (version conrefs changed) #502, so link to it for the field-by-field schema rather than restating it. The Helm reference has nothing to say here, because compaction is a CRD field rather than a chart value. Neither page is hand-edited; both are generated.
• Test against v1.0.0-alpha2 or later. The field does not exist in alpha1.
• Read Agent harness and Agent memory first, and keep to what this page uniquely owns. The Harness field reference lives on Agent harness and should be linked rather than repeated.

Done when

• The page exists under docs-site/content/kagent/1.x/, with frontmatter and a section weight that matches its neighbors.
• It opens by saying what compaction is and that it is Harness-level runtime policy.
• It carries a complete annotated manifest showing both strategies, with a required/optional field table.
• All four admission rules are stated.
• The summarizer-model revision behavior is documented.
• Every example applies cleanly against an alpha2 cluster and produces the described behavior.
• Links to and from Agent harness, Agent memory, and Core concepts resolve, and each names a section that covers what the link says it covers.
• hugo --config hugo.yaml,hugo.preview.yaml -D --gc builds clean.

Happy to answer questions in this issue for anyone picking it up.