[github-actions]

kagent-dev/kagent#3382 — core: support cross-namespace ModelConfig and RemoteMCPServer with allowedNamespaces

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

No code-path rule covers 11 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/configuration-and-compilation.md
• docs/architecture/credential-injection.md
• docs/architecture/cross-namespace-references.md
• docs/architecture/egress-policies.md
• docs/architecture/runtime-and-lifecycle.md
• go/core/internal/controller/collections.go
• ...and 5 more

What changes for users: AgentTemplates and inline Agent templates can reference shared ModelConfigs and RemoteMCPServers in another namespace by setting a separate namespace field. Harness memory and summarizer settings can also reference shared ModelConfigs. The target ModelConfig or RemoteMCPServer controls access with allowedNamespaces, and a denied update preserves the Agent's last successful revision for new Sessions.

What the docs now say: The model provider, MCP tool, Harness memory, context management, operations, debug, and tools ecosystem pages now describe namespace-qualified references, allowedNamespaces, target-local Secrets, and the last-successful-revision behavior. Provider setup pages now say that provider Secrets belong in the ModelConfig namespace, while their examples keep ModelConfigs and AgentTemplates together.

Not verified: No cluster; the configuration is unrun, and internal links are unchecked.

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

• Code PR: core: support cross-namespace ModelConfig and RemoteMCPServer with allowedNamespaces kagent#3382
• 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 pages that claimed ModelConfigs, RemoteMCPServers, memory models, and summarizer models must be local-only.
• Learned: diff-truncated.md says the CRD templates and generated deepcopy file are outside the code diff, and reference/api-ref.md is generated, so I left generated reference rows to the update-ref-docs workflow.
• Did: Updated the authorized 1.x kagent docs pages and one stale MCP concept page found by the literal-string scan.

Why a documentation change is necessary

The release note says that Agents can reference shared ModelConfigs and RemoteMCPServers across namespaces by using allowedNamespaces. The diff changes AgentTemplate.spec.modelConfig, MCP server bindings, and Harness modelConfigRef fields from local references to references with optional namespace fields. Existing pages said that ModelConfigs, MCP servers, memory models, and summarizer models had to be in the same namespace, and provider pages told readers to place Secrets with the AgentTemplates rather than with the ModelConfig that reads them.

What changed on disk

• docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md — Added allowedNamespaces, cross-namespace modelConfig.namespace, and separate name/namespace guidance.
• docs-site/content/kagent/1.x/setup/model-providers/amazon-bedrock.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/anthropic.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/azure-ai-foundry.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/azure-openai.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/byo-agentgateway.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/byo-openai.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/gemini.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/mistral.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/ollama.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/openai.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/setup/model-providers/xai.md — Corrected Secret placement and same-namespace example wording.
• docs-site/content/kagent/1.x/skills-and-mcp/about-tools.md — Updated MCP binding scope and documented mcp.server.namespace.
• docs-site/content/kagent/1.x/get-started/your-first-mcp-tool.md — Updated MCP field descriptions and reference-resolution failure guidance.
• docs-site/content/kagent/1.x/agents/declarative-agents.md — Updated Harness memory model reference guidance.
• docs-site/content/kagent/1.x/agents/agent-memory.md — Updated memory ModelConfig placement and memory.modelConfigRef.namespace.
• docs-site/content/kagent/1.x/agents/context-management.md — Updated summarizer ModelConfig namespace and failure guidance.
• docs-site/content/kagent/1.x/operations/operational-considerations.md — Added recompilation and last-successful-revision behavior for namespace policy changes.
• docs-site/content/kagent/1.x/operations/debug.md — Added allowedNamespaces denial as a ResolvedRefs failure and explained the preserved revision.
• docs-site/content/kagent/1.x/reference/tools-ecosystem.md — Clarified cross-namespace binding to kagent-tool-server.

How to verify this change

1. In a kagent 1.x cluster, create a ModelConfig in a shared namespace with spec.allowedNamespaces.from: All, then create an AgentTemplate in another namespace with spec.modelConfig.name and spec.modelConfig.namespace set to that shared ModelConfig.
2. Create a RemoteMCPServer in a shared namespace with spec.allowedNamespaces.from: Selector, label the AgentTemplate namespace to match, and bind it from the AgentTemplate with spec.tools[].mcp.server.namespace.
3. Run kubectl get agent <agent-name> -n <agent-namespace> -o jsonpath='{.status.desiredRevision}{"\t"}{.status.latestSuccessfulRevision}{"\n"}' and expect both revision values to match after compilation succeeds.
4. Remove the matching namespace label or change allowedNamespaces.from to Same, then inspect the Agent conditions. ResolvedRefs should report ReferenceResolutionFailed, and latestSuccessfulRevision should remain populated with the prior prepared revision.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false. Suggested note: Agents can reference shared ModelConfigs and RemoteMCPServers across namespaces by setting the reference namespace field and permitting the source namespace with allowedNamespaces. If a later namespace policy change denies the reference, kagent keeps the Agent's last successful revision available for new Sessions until another revision prepares successfully.

What was not verified

• Internal links are unchecked because Hugo was not run.
• CRD template and generated-code changes were not checked from the code diff: go/api/v1alpha3/zz_generated.deepcopy.go, helm/kagent-crds/templates/api.kagent.dev_agents.yaml, helm/kagent-crds/templates/api.kagent.dev_agenttemplates.yaml, helm/kagent-crds/templates/api.kagent.dev_harnesses.yaml, and helm/kagent-crds/templates/api.kagent.dev_modelconfigs.yaml were beyond the truncated diff.
• UI test behavior was not checked from the code diff: ui/playwright/tests/agents/agent-crud.spec.ts, ui/src/components/agent-template-form/agentTemplateDraft.test.ts, and ui/src/components/model-form/modelDraft.test.ts were beyond the truncated diff.

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(session)!: remove public suspend and resume controls kagent#3409 and core: support cross-namespace ModelConfig and RemoteMCPServer with allowedNamespaces kagent#3382 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there

Draft a documentation change

kagent-dev/kagent#3382 — core: support cross-namespace ModelConfig and RemoteMCPServer with allowedNamespaces

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Release note: Agents can reference shared ModelConfigs and RemoteMCPServers across namespaces using allowedNamespaces, while policy-related compilation failures preserve the last successful revision for new sessions.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 11 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/configuration-and-compilation.md
  • docs/architecture/credential-injection.md
  • docs/architecture/cross-namespace-references.md
  • docs/architecture/egress-policies.md
  • docs/architecture/runtime-and-lifecycle.md
  • go/core/internal/controller/collections.go
  • ...and 5 more

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

[Rachael-Graham]

Folded into #672.