[github-actions]

kagent-dev/kagent#3453 — refactor(api)!: make pre-RC API breaks for future machine principals

Docs versions: 1.x (first shipped in v1.0.0-rc1)

No code-path rule covers 19 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/a2a-gateway.md
• go/api/client/a2a.go
• go/api/gen/kagent/api/v1/agent_templates.pb.go
• go/api/gen/kagent/api/v1/sessions.pb.go
• go/api/gen/kagent/runtime/v1/memory.pb.go
• go/api/gen/kagent/runtime/v1/memory_grpc.pb.go
• ...and 13 more

What changes for users: Sessions now record the Agent reference and Kubernetes UID from the revision that created them. Deleting an Agent and creating another one with the same namespace and name does not move existing Sessions to the replacement Agent.

What the docs now say: The operational considerations page now states that running Sessions keep the original Agent identity and revision, and that a new Session is required to pick up replacement Agent configuration.

Not verified: No cluster command was run; cluster-facts.md records API surface only, the configuration is unrun, and internal links are unchecked.

How kagent-3453 was drafted, and what was not verified

• Code PR: refactor(api)!: make pre-RC API breaks for future machine principals kagent#3453
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-rc1
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Update the page that already explains how configuration changes reach running Sessions.
• Learned: agents/agent-memory.md already documents exact namespace/name memory keys, and no target page owns client-authored A2A message IDs.
• Did: Added the Session Agent UID behavior to operations/operational-considerations.md.

Why a documentation change is necessary

The pull request changes Session.agent from a plain resource reference to AgentProvenance{ref, uid} and stores the Agent UID from the pinned revision. The target page already says that a running Session keeps its original revision for life, but it did not say that a same-name replacement Agent is also a different identity. Without that detail, a reader might expect deleting and recreating an Agent to move old conversations onto the new Agent definition.

What changed on disk

• docs-site/content/kagent/1.x/operations/operational-considerations.md — clarifies that existing Sessions stay tied to the original Agent identity and revision after an Agent is deleted and recreated with the same namespace and name.

How to verify this change

1. Create a test Session against an Agent and save the Session ID.

   export OLD_SESSION_ID=$(kagent agent session create --agent my-first-agent -o json | jq -r '.session.id')

2. Read the Session's recorded Agent identity.

   kagent agent session get "$OLD_SESSION_ID" -o json | jq '.session.agent'

   The output shows ref.name: my-first-agent and a non-empty uid.
3. Delete and recreate the Agent with the same namespace and name, then create a second Session.

   kubectl delete agent my-first-agent -n kagent
   kubectl apply -f my-first-agent.yaml
   export NEW_SESSION_ID=$(kagent agent session create --agent my-first-agent -o json | jq -r '.session.id')

4. Compare the two Session records.

   kagent agent session get "$OLD_SESSION_ID" -o json | jq -r '.session.agent.uid'
   kagent agent session get "$NEW_SESSION_ID" -o json | jq -r '.session.agent.uid'
   kubectl get agent my-first-agent -n kagent -o jsonpath='{.metadata.uid}{"\n"}'

   The old Session keeps the old UID, and the new Session UID matches the recreated Agent.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false for this product run.

Pre-RC Session and memory API breaks

Sessions now return agent as AgentProvenance, with ref and uid, so clients that read Session.agent.namespace or Session.agent.name must read Session.agent.ref instead. Memory list, search, and delete calls now match only the exact namespace/name Agent key, and A2A messages with IDs that start with scheduled-run/ are rejected unless they come from the in-process scheduler.

What was not verified

• The cluster state was not contacted from this sandbox, and no configuration was applied or run.
• cluster-facts.md was used only as API-surface evidence.
• Internal links are unchecked because Hugo was not run.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• refactor(api)!: make pre-RC API breaks for future machine principals kagent#3453 and chore: upgrade Substrate to v1.0.0-rc1 kagent#3457 look like one change split across pull requests (same author, same source file, both on docs-site/content/kagent/1.x/observability/launch-ui.md), but one of them is already grouped with another author's change; merge them if both drafts do land there

Draft a documentation change

kagent-dev/kagent#3453 — refactor(api)!: make pre-RC API breaks for future machine principals

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): These are the breaking changes that are cheap to make before the release candidate but would need a compatibility path once it freezes the API. They keep room for machine principals, such as a scheduler acting as its own identity, without adopting that design now. The existing schedule API is unchanged.
• Not tested: a cluster was used only to dry-run the YAML manifests the draft added; prose, inline field paths and commands are unrun
• No rule covers 19 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/a2a-gateway.md
  • go/api/client/a2a.go
  • go/api/gen/kagent/api/v1/agent_templates.pb.go
  • go/api/gen/kagent/api/v1/sessions.pb.go
  • go/api/gen/kagent/runtime/v1/memory.pb.go
  • go/api/gen/kagent/runtime/v1/memory_grpc.pb.go
  • ...and 13 more

Draft branch: pr-tracker-draft-kagent-3453

[Rachael-Graham]

Closing as folded into #652. operational-considerations.md now says that a Session records the Agent's UID, and that a same-name replacement Agent gets a new UID while existing Sessions keep the old UID and revision. Live-tested at v1.0.0-rc1, which also showed that deleting an Agent does not end its Sessions; they keep answering, and the page now says so.