kagent-dev · artberger · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git a/public/sitemap.xml b/public/sitemap.xml
diff --git a/src/app/docs/kagent/concepts/agents/page.mdx b/src/app/docs/kagent/concepts/agents/page.mdx
@@ -141,8 +141,30 @@ Here's how you could reference an existing agent (`promql-agent`) as a tool:
         toolNames:
         - k8s_get_resources
         - k8s_get_available_api_resources
-    # Referencing an existing agent as a tool
+    # Referencing an existing agent as a tool (same namespace)
     - type: Agent
       agent:
-        ref: promql-agent
-```
+        name: promql-agent
+    # Referencing an agent in another namespace
+    - type: Agent
+      agent:
+        name: promql-agent
+        namespace: other-namespace
+```
+
+### MCP server endpoint
+
+A2A-enabled agents are automatically exposed as an MCP server on the kagent controller. The MCP endpoint is available at `/mcp` on the same port as the A2A endpoint (default 8083).
+
+This MCP server provides two tools:
+
+- **`list_agents`**: Lists invokable kagent agents that are accepted and deployment-ready.
+- **`invoke_agent`**: Invokes a kagent agent via A2A. The agent reference uses the format `namespace/name`.
+
+You can connect MCP clients (such as Cursor, Claude Desktop, or other MCP-compatible tools) to the kagent controller to use your agents as MCP tools, such as when port-forwarding the controller:
+
+```
+http://localhost:8083/mcp
+```
+
+The MCP server uses the same authentication as the A2A endpoints.
diff --git a/src/app/docs/kagent/concepts/tools/page.mdx b/src/app/docs/kagent/concepts/tools/page.mdx
@@ -22,9 +22,60 @@ You can check out the full list of built-in tools [here](/tools).
 
 The built-in tools are meant as a good starting point for any agents running in kubernetes, however we don't envision them covering all possible use-cases, so we support multiple tool extension points to allow you to bring in your own tools.
 
+### Cross-namespace tool references
+
+You can refer to tools from MCP servers in other namespaces by using the `namespace/name` format. This way, you can share tool servers across namespaces without duplicating them.
+
+Example: Reference to a RemoteMCPServer in the `tools` namespace.
+
+```yaml
+tools:
+  - type: McpServer
+    mcpServer:
+      name: kagent-tool-server
+      namespace: tools
+      kind: RemoteMCPServer
+      toolNames:
+        - k8s_get_resources
+```
+
+The same format applies when referring to Services or MCPServers in other namespaces.
+
+### Headers for tool calls
+
+You can add headers to requests sent from an agent to a tool using `headersFrom`. This ability is useful for passing API keys, authentication tokens, or other per-request metadata to MCP servers. Header values are resolved from Secrets or ConfigMaps in the same namespace as the Agent.
+
+Example: Add an API key header when calling a tool.
+
+```yaml
+tools:
+  - type: McpServer
+    mcpServer:
+      name: kagent-tool-server
+      kind: RemoteMCPServer
+      toolNames:
+        - k8s_get_resources
+    headersFrom:
+      - name: Authorization
+        valueFrom:
+          type: Secret
+          name: tool-api-secret
+          key: api-key
+```
+
+Headers specified in `headersFrom` override any headers of the same name configured on the tool itself.
+
 ## Agents as Tools
 
-You also have an option of using agents as tools. Any agent you create can be referenced and used by other agents you have.
+You also have an option of using agents as tools. Any agent you create can be referenced and used by other agents you have. You can refer to agents in other namespaces by using the `namespace/name` format.
+
+```yaml
+tools:
+  - type: Agent
+    agent:
+      name: promql-agent
+      namespace: other-namespace
+```
 
 ## MCP Tools
 

diff --git a/src/app/docs/kagent/examples/a2a-byo/page.mdx b/src/app/docs/kagent/examples/a2a-byo/page.mdx
@@ -4,6 +4,8 @@ pageOrder: 1
 description: "Bring your own ADK agent to kagent"
 ---
 
+import { Tabs, Tab } from '@/components/mdx/tabs';
+
 export const metadata = {
   title: "Bringing your own ADK agent to kagent",
   description: "Learn how to bring your own ADK agent to kagent",
@@ -63,6 +65,12 @@ Now that you have your own custom agent image, you can create a BYO Agent resour
 
 3. Create a BYO Agent resource.
 
+   <Tabs tabs={[
+     { id: 'without-secrets', label: 'Without imagePullSecrets' },
+     { id: 'with-secrets', label: 'With imagePullSecrets' }
+   ]} />
+
+   <div id="without-secrets-tab">
    ```yaml
    kubectl apply -f - <<EOF
    apiVersion: kagent.dev/v1alpha2
@@ -84,6 +92,41 @@ Now that you have your own custom agent image, you can create a BYO Agent resour
                  key: GOOGLE_API_KEY
    EOF
    ```
+   </div>
+
+   <div id="with-secrets-tab">
+   For agent images that are in private container registries, you can use an image pull secret with the credentials to the registry. 
+
+   First, create the Secret.
+   ```sh
+   kubectl create secret docker-registry my-registry-secret --docker-server=<registry> --docker-username=<user> --docker-password=<password> -n kagent
+   ```
+
+   Then, add `imagePullSecrets` to refer to the Secret that you just created.
+   ```yaml
+   kubectl apply -f - <<EOF
+   apiVersion: kagent.dev/v1alpha2
+   kind: Agent
+   metadata:
+     name: basic-agent
+     namespace: kagent
+   spec:
+     description: This agent can do anything.
+     type: BYO
+     byo:
+       deployment:
+         image: ghcr.io/my-org:latest
+         imagePullSecrets:
+           - name: my-registry-secret
+         env:
+           - name: GOOGLE_API_KEY
+             valueFrom:
+               secretKeyRef:
+                 name: kagent-google
+                 key: GOOGLE_API_KEY
+   EOF
+   ```
+   </div>
 
 ## Testing the A2A endpoint
 
@@ -296,3 +339,22 @@ To use lifespan hooks in your ADK agent, create a lifespan function and pass it
        lifespan=lifespan.lifespan  # Pass the lifespan function
    )
    ```
+
+### A2A max payload size
+
+BYO agents accept A2A requests with a default maximum payload size of 10 MB. For agents that need to handle larger payloads (for example, when processing large file attachments), set the `A2A_MAX_CONTENT_LENGTH` environment variable in the agent deployment.
+
+Example: Allow 50 MB payloads:
+
+```yaml
+spec:
+  type: BYO
+  byo:
+    deployment:
+      image: ghcr.io/my-org:latest
+      env:
+        - name: A2A_MAX_CONTENT_LENGTH
+          value: "52428800"  # 50 MB in bytes
+```
+
+Set to `0`, `none`, or `unlimited` for no limit (use with caution).
diff --git a/src/app/docs/kagent/examples/skills/page.mdx b/src/app/docs/kagent/examples/skills/page.mdx
@@ -49,7 +49,6 @@ To create a container-based skill, package your skill files into a container ima
    name: k8s-deploy-skill
    description: Deploy simple applications to Kubernetes with customizable replicas and port
    ---
-
    # Kubernetes simple deploy skill
 
    Use this skill when users want to deploy a basic app on the Kubernetes cluster.
@@ -286,9 +285,9 @@ spec:
           name: kagent-tool-server
           kind: RemoteMCPServer
           toolNames:
-            - k8s_apply_manifest
             - k8s_get_resources
             - k8s_describe_resource
+            - k8s_apply_manifest
     systemMessage: |
       You are a Kubernetes assistant that helps users deploy and manage applications.
       You have access to skills that can help automate common tasks.

diff --git a/src/app/docs/kagent/operations/operational-considerations/page.mdx b/src/app/docs/kagent/operations/operational-considerations/page.mdx
@@ -4,6 +4,8 @@ pageOrder: 1
 description: "Important operational considerations when running kagent in production."
 ---
 
+import { Tabs, Tab } from '@/components/mdx/tabs';
+
 export const metadata = {
   title: "Operational Considerations",
   description: "Important operational considerations when running kagent in production.",
@@ -14,6 +16,57 @@ export const metadata = {
 
 Review the following operational considerations when running kagent in production environments, including database configuration, high availability, and secret management.
 
+## Secure execution environment
+
+Kagent supports Kubernetes security contexts to run agents and tool servers with reduced privileges. Configure `securityContext` and `podSecurityContext` on your Agent or ToolServer resources to enforce secure execution.
+
+Common settings include:
+
+- **`runAsNonRoot: true`**: Ensures the container does not run as root.
+- **`runAsUser`**: Specifies the user ID for the container process.
+- **`readOnlyRootFilesystem`**: Mounts the root filesystem as read-only when possible.
+
+<Tabs tabs={[
+  { id: 'declarative', label: 'Declarative agents' },
+  { id: 'byo', label: 'BYO agents' }
+]} />
+
+<div id="declarative-tab">
+Set these in `spec.declarative.deployment.podSecurityContext` and `spec.declarative.deployment.securityContext`.
+
+```yaml
+spec:
+  type: Declarative
+  declarative:
+    deployment:
+      podSecurityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+      securityContext:
+        allowPrivilegeEscalation: false
+        readOnlyRootFilesystem: false
+```
+</div>
+
+<div id="byo-tab">
+Set these in `spec.byo.deployment.podSecurityContext` and `spec.byo.deployment.securityContext`.
+
+```yaml
+spec:
+  type: BYO
+  byo:
+    deployment:
+      podSecurityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+      securityContext:
+        allowPrivilegeEscalation: false
+        readOnlyRootFilesystem: false
+```
+</div>
+
+At the Helm chart level, you can set global defaults with `podSecurityContext` and `securityContext` in your values. For more information, see the [Kubernetes SecurityContext documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/).
+
 ## Automatic agent restart on secret updates
 
 Kagent automatically restarts agents when you update the secrets that the agents reference. This restart ensures that agents pick up new API keys, TLS certificates, and other secret values without manual intervention.
@@ -60,6 +113,24 @@ controller:
 - **Leader election**: Leader election uses Kubernetes leases and is handled automatically.
 - **Failover**: If the leader fails, another replica automatically becomes the leader.
 
+## Proxy configuration for agent traffic
+
+When agents and MCP servers run behind an API gateway or proxy, you can configure kagent to route agent-to-agent and agent-to-MCP traffic through that proxy. Set `proxy.url` in your Helm values to the proxy endpoint.
+
+The proxy applies to:
+
+- Agent-to-agent traffic (when one agent invokes another as a tool)
- Agent-to-agent traffic (when one agent invokes another as a tool)
+- Agent-to-agent traffic (when one agent invokes another agent as a tool)
- Agent-to-agent traffic (when one agent invokes another as a tool)
+- Agent-to-agent traffic (when one agent invokes another agent as a tool)
+- Agent-to-MCP-server traffic (when agents call ToolServers, Services, or RemoteMCPServers with internal Kubernetes URLs)
+
+Example Helm configuration:
+
+```yaml
+proxy:
+  url: "http://proxy.kagent.svc.cluster.local:8080"
+```
+
+The controller rewrites internal URLs to use the proxy and sets the `x-kagent-host` header so the proxy can route requests to the correct backend. External URLs (for example, RemoteMCPServers pointing to `https://external.example.com`) are not rewritten.
+
 ### Use PostgreSQL for scaling
 
 To scale the controller to multiple replicas, configure PostgreSQL as the database backend. You can enable PostgreSQL by using the Helm `--set` flag or values file.

diff --git a/src/app/docs/kagent/resources/helm/page.mdx b/src/app/docs/kagent/resources/helm/page.mdx
@@ -108,9 +108,9 @@ A Helm chart for kagent, built with Google ADK
 | controller.service.ports.port | int | `8083` |  |
 | controller.service.ports.targetPort | int | `8083` |  |
 | controller.service.type | string | `"ClusterIP"` |  |
-| controller.streaming.initialBufSize | string | `"4Ki"` |  |
-| controller.streaming.maxBufSize | string | `"1Mi"` |  |
-| controller.streaming.timeout | string | `"600s"` |  |
+| controller.streaming.initialBufSize | string | `"4Ki"` | Initial size of the A2A streaming buffer. |
+| controller.streaming.maxBufSize | string | `"1Mi"` | Maximum size of the A2A streaming buffer. |
+| controller.streaming.timeout | string | `"600s"` | Timeout for A2A streaming connections. |
 | controller.tolerations | list | `[]` | Node taints which will be tolerated for `Pod` [scheduling](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/). |
 | controller.volumeMounts | list | `[]` |  |
 | controller.volumes | list | `[]` |  |
@@ -126,7 +126,7 @@ A Helm chart for kagent, built with Google ADK
 | grafana-mcp.resources.requests.cpu | string | `"100m"` |  |
 | grafana-mcp.resources.requests.memory | string | `"128Mi"` |  |
 | imagePullPolicy | string | `"IfNotPresent"` |  |
-| imagePullSecrets | list | `[]` |  |
+| imagePullSecrets | list | `[]` | Image pull secrets for pulling agent and tool images from private registries. You can also set `imagePullSecrets` per agent in the Agent `deployment` spec. |
 | kagent-tools.enabled | bool | `true` |  |
 | kagent-tools.fullnameOverride | string | `"kagent-tools"` |  |
 | kagent-tools.replicaCount | int | `1` |  |
@@ -178,7 +178,7 @@ A Helm chart for kagent, built with Google ADK
 | providers.openAI.apiKeySecretRef | string | `"kagent-openai"` |  |
 | providers.openAI.model | string | `"gpt-4.1-mini"` |  |
 | providers.openAI.provider | string | `"OpenAI"` |  |
-| proxy.url | string | `""` |  |
+| proxy.url | string | `""` | Proxy URL for routing agent-to-agent and agent-to-MCP traffic through a gateway (for example, `http://proxy.kagent.svc.cluster.local:8080`). When set, the controller routes internal Kubernetes URLs (agents, MCP servers, services) through this proxy. The proxy uses the `x-kagent-host` header for routing. Omit for direct connections. |
 | querydoc.image.pullPolicy | string | `"IfNotPresent"` |  |
 | querydoc.image.registry | string | `"ghcr.io"` |  |
 | querydoc.image.repository | string | `"kagent-dev/doc2vec/mcp"` |  |