Manage agents

1. List the agents that are available in your cluster. Update the kubecontext accordingly.

   kubectl get agents -A --context $context1

2. Review the details of an agent, such as for k8s-agent.

   kubectl get agent k8s-agent -n kagent --context $context1 -o yaml

   Example output: Review the table that follows the example configuration file to understand more about the fields.

   apiVersion: kagent.dev/v1alpha2
   kind: Agent
   metadata:
     annotations:
       meta.helm.sh/release-name: kagent
       meta.helm.sh/release-namespace: kagent
     creationTimestamp: "2026-06-15T19:10:57Z"
     generation: 1
     labels:
       app.kubernetes.io/instance: kagent
       app.kubernetes.io/managed-by: Helm
       app.kubernetes.io/name: k8s-agent
       app.kubernetes.io/part-of: kagent
       app.kubernetes.io/version: 0.5.3
       helm.sh/chart: k8s-agent-0.5.3
     name: k8s-agent
     namespace: kagent
     resourceVersion: "42479"
     uid: 5158ca2a-7ef1-48c3-a5c9-a6b4c3954196
   spec:
     declarative:
       a2aConfig:
         skills:
         - description: The ability to analyze and diagnose Kubernetes Cluster issues.
           examples:
           - What is the status of my cluster?
           - How can I troubleshoot a failing pod?
           - What are the resource limits for my nodes?
           id: cluster-diagnostics
           name: Cluster Diagnostics
           tags:
           - cluster
           - diagnostics
         - description: The ability to manage and optimize Kubernetes resources.
           examples:
           - Scale my deployment X to 3 replicas.
           - Optimize resource requests for my pods.
           - Reserve more CPU for my nodes.
           id: resource-management
           name: Resource Management
           tags:
           - resource
           - management
         - description: The ability to audit and enhance Kubernetes security.
           examples:
           - Check for RBAC misconfigurations.
           - Audit my network policies.
           - Identify potential security vulnerabilities in my cluster.
           id: security-audit
           name: Security Audit
           tags:
           - security
           - audit
       deployment:
         resources:
           limits:
             cpu: 1000m
             memory: 1Gi
           requests:
             cpu: 100m
             memory: 256Mi
       modelConfig: default-model-config
       promptTemplate:
         dataSources:
         - alias: builtin
           kind: ConfigMap
           name: kagent-builtin-prompts
       runtime: python
       systemMessage: |
         # Kubernetes AI Agent System Prompt
   
         You are KubeAssist, an advanced AI agent specialized in Kubernetes troubleshooting and operations. You have deep expertise in Kubernetes architecture, container orchestration, networking, storage systems, and resource management. Your purpose is to help users diagnose and resolve Kubernetes-related issues while following best practices and security protocols.
   
         ## Core Capabilities
   
         - **Expert Kubernetes Knowledge**: You understand Kubernetes components, architecture, orchestration principles, and resource management.
         - **Systematic Troubleshooting**: You follow a methodical approach to problem diagnosis, analyzing logs, metrics, and cluster state.
         - **Security-First Mindset**: You prioritize security awareness including RBAC, Pod Security Policies, and secure practices.
         - **Clear Communication**: You provide clear, concise technical information and explain complex concepts appropriately.
         - **Safety-Oriented**: You follow the principle of least privilege and avoid destructive operations without confirmation.
   
         ## Operational Guidelines
   
         {{include "builtin/kubernetes-context"}}
   
         ## Available Tools
   
         You have access to the following tools to help diagnose and solve Kubernetes issues:
   
         ### Informational Tools
         - `GetResources`: Retrieve information about Kubernetes resources. Always prefer "wide" output unless specified otherwise. Specify the exact resource type.
         - `DescribeResource`: Get detailed information about a specific Kubernetes resource.
         - `GetEvents`: View events in the Kubernetes cluster to identify recent issues.
         - `GetPodLogs`: Retrieve logs from specific pods for troubleshooting.
         - `GetResourceYAML`: Obtain the YAML representation of a Kubernetes resource.
         - `GetAvailableAPIResources`: View supported API resources in the cluster.
         - `GetClusterConfiguration`: Retrieve the Kubernetes cluster configuration.
         - `CheckServiceConnectivity`: Verify connectivity to a service.
         - `ExecuteCommand`: Run a command inside a pod (use cautiously).
   
         ### Modification Tools
         - `CreateResource`: Create a new resource from a local file.
         - `CreateResourceFromUrl`: Create a resource from a URL.
         - `ApplyManifest`: Apply a YAML resource file to the cluster.
         - `PatchResource`: Make partial updates to a resource.
         - `DeleteResource`: Remove a resource from the cluster (use with caution).
         - `LabelResource`: Add labels to resources.
         - `RemoveLabel`: Remove labels from resources.
         - `AnnotateResource`: Add annotations to resources.
         - `RemoveAnnotation`: Remove annotations from resources.
         - `GenerateResourceTool`: Generate YAML configurations for Istio, Gateway API, or Argo resources.
   
         ## Tool Usage Best Practices
   
         {{include "builtin/tool-usage-best-practices"}}
   
         ## Safety Protocols
   
         {{include "builtin/safety-guardrails"}}
   
         ## Response Format
   
         When responding to user queries:
   
         1. **Initial Assessment**: Briefly acknowledge the issue and establish what you understand about the situation.
         2. **Information Gathering**: If needed, state what additional information you require.
         3. **Analysis**: Provide your analysis of the situation in clear, technical terms.
         4. **Recommendations**: Offer specific recommendations and the tools you'll use.
         5. **Action Plan**: Present a step-by-step plan for resolution.
         6. **Verification**: Explain how to verify the solution worked correctly.
         7. **Knowledge Sharing**: Include brief explanations of relevant Kubernetes concepts.
   
         ## Limitations
   
         8. You cannot directly connect to or diagnose external systems outside of the Kubernetes cluster.
         9. You must rely on the tools provided and cannot use kubectl commands directly.
         10. You cannot access or modify files on the host system outside of the agent's environment.
         11. Remember that your suggestions impact production environments - prioritize safety and stability.
   
         Always start with the least intrusive approach, and escalate diagnostics only as needed. When in doubt, gather more information before recommending changes.
       tools:
       - mcpServer:
           apiGroup: kagent.dev
           kind: RemoteMCPServer
           name: kagent-tool-server
           toolNames:
           - k8s_check_service_connectivity
           - k8s_patch_resource
           - k8s_remove_annotation
           - k8s_annotate_resource
           - k8s_remove_label
           - k8s_label_resource
           - k8s_create_resource
           - k8s_create_resource_from_url
           - k8s_get_events
           - k8s_get_available_api_resources
           - k8s_get_cluster_configuration
           - k8s_describe_resource
           - k8s_delete_resource
           - k8s_get_resource_yaml
           - k8s_execute_command
           - k8s_apply_manifest
           - k8s_get_resources
           - k8s_get_pod_logs
         type: McpServer
     description: An Kubernetes Expert AI Agent specializing in cluster operations, troubleshooting,
       and maintenance.
     type: Declarative
   status:
     conditions:
     - lastTransitionTime: "2026-06-15T19:10:58Z"
       message: Agent configuration accepted
       observedGeneration: 1
       reason: Reconciled
       status: "True"
       type: Accepted
     - lastTransitionTime: "2026-06-15T19:17:56Z"
       message: Deployment is ready
       observedGeneration: 1
       reason: DeploymentReady
       status: "True"
       type: Ready
     observedGeneration: 1

   Review the following table to understand this configuration.

   Field	Description
   declarative	The configuration block for a declarative agent. For more information, see Types in the about agent page.
   a2aConfig	The configuration for the agent-to-agent protocol.
   skills	The skills or capabilities that an agent has to act more autonomously. The description and examples provide context for the agent to know what sorts of things that it is expected to do. The ID and tags provide ways to identify the skill for managing and comparing similarities with other agents. For more information, see Skills in the about agent page.
   deployment	The resource limits and requests for the agent’s pod.
   modelConfig	The model that the agent uses to generate responses. For more information, see Models in the about agent page.
   promptTemplate	The data sources for prompt includes, such as ConfigMaps that supply built-in prompt snippets.
   runtime	The runtime environment for the agent, such as python.
   systemMessage	The system instructions that the agent uses to guide how it responds. For more information, see System instructions in the about agent page.
   tools	The tools that the agent can use. The example agent includes tools from a RemoteMCPServer that provides tools for interacting with the Kubernetes API. For more information, see Tools in the about agent page.
   status	The status of the agent. Make sure that the status of AgentReconciliation is accepted and that the deployment is ready.

List the agents that are available in your cluster. Update the kubecontext accordingly.

kubectl get agents -A --context $context1

To invoke an agent from the CLI, port-forward the kagent controller and use the --url-override flag to point directly at the agent’s A2A endpoint. Replace {agent-name} with the name of the agent you want to invoke.

kubectl port-forward svc/kagent-controller 8083:8083 -n kagent --context $context1 &
kagent invoke \
  --url-override "http://localhost:8083/api/a2a/kagent/{agent-name}" \
  --task "Are any pods not in a running state in the kagent namespace?"

1. Save the configuration file of your agent.

   kubectl get agent -n kagent my-k8s-agent --context $context1 -o yaml > my-k8s-agent.yaml

2. Open and edit the configuration file as you want.

3. Follow the Custom resources tab in the Create an agent guide for more details about creating and testing out your agent updates.

1. Delete the agent.

   kubectl delete agent -n kagent my-k8s-agent --context $context1

2. Review the agents in your cluster to confirm that the agent is deleted.

   kubectl get agent -A --context $context1