feat: Improve user experience of az aks agent with aks-mcp

Author: nilo19

.gitignore

@@ -127,3 +127,7 @@ _az_debug/
 
 # Ignore test results
 test_results.xml
+
+# Ignore poetry files
+pyproject.toml
+poetry.lock

src/aks-preview/HISTORY.rst

@@ -14,6 +14,13 @@ Pending
 
 18.0.0b28
 +++++++
+* Improve user experience of `az aks agent` with enhanced MCP (Model Context Protocol) integration.
+* Use aks-mcp by default for `az aks agent`.
+* Add comprehensive error handling, status management, and user feedback systems for the agent debugging tool.
+* Implement smart binary management and configuration generation for improved agent reliability.
+
+18.0.0b27
++++++++
 * Add interactive AI-powered debugging tool `az aks agent`.
 
 18.0.0b27
@@ -1948,4 +1955,4 @@ Pending
 +++++
 
 * new feature `enable-cluster-autoscaler`
-* default agentType is VMSS
+* default agentType is VMSS

src/aks-preview/azext_aks_preview/_consts.py

@@ -379,3 +379,10 @@
 CONST_AGENT_NAME = "AKS AGENT"
 CONST_AGENT_NAME_ENV_KEY = "AGENT_NAME"
 CONST_AGENT_CONFIG_FILE_NAME = "aksAgent.yaml"
+# MCP Integration Constants
+CONST_MCP_BINARY_NAME = "aks-mcp"
+CONST_MCP_DEFAULT_PORT = 8003
+CONST_MCP_DEFAULT_URL = "http://localhost:8003/sse"
+CONST_MCP_MIN_VERSION = "0.0.7"
+CONST_MCP_GITHUB_REPO = "Azure/aks-mcp"
+CONST_MCP_BINARY_DIR = "bin"

src/aks-preview/azext_aks_preview/_help.py

@@ -3960,6 +3960,14 @@
     short-summary: Run AI assistant to analyze and troubleshoot Kubernetes clusters.
     long-summary: |-
       This command allows you to ask questions about your Azure Kubernetes cluster and get answers using AI models.
+      By default, the agent uses enhanced MCP (Model Context Protocol) integration for improved capabilities.
+      Use --no-aks-mcp to disable MCP and use traditional built-in toolsets.
+
+      The agent uses smart refresh to optimize performance:
+      • First run or mode changes: Toolsets are refreshed automatically
+      • Subsequent runs in same mode: Uses cached toolsets for faster startup
+      • If expected capabilities are missing: Use --refresh-toolsets to force refresh
+
       Environment variables must be set to use the AI model, please refer to https://docs.litellm.ai/docs/providers to learn more about supported AI providers and models and required environment variables.
     parameters:
         - name: --name -n
@@ -3991,22 +3999,59 @@
           short-summary: Show the output of each tool that was called during the analysis.
         - name: --refresh-toolsets
           type: bool
-          short-summary: Refresh the toolsets status.
+          short-summary: Force refresh of toolsets even when using cached configuration.
+          long-summary: |-
+            By default, the agent uses smart refresh to optimize performance. This flag forces
+            a complete toolset refresh, which is useful if:
+            • Expected tools or capabilities are missing
+            • You've updated your environment or configuration
+            • Troubleshooting toolset-related issues
+            Note: This may increase startup time but ensures all available tools are loaded.
+        - name: --no-aks-mcp
+          type: bool
+          short-summary: Disable AKS MCP integration and use traditional built-in toolsets.
+          is_preview: true
+        - name: --status
+          type: bool
+          short-summary: Show AKS agent configuration and status.
+          long-summary: |-
+            Display information about AKS agent configuration, MCP binary status, server health,
+            and active toolsets. This command helps diagnose agent setup and operational status.
+
+            The status output shows:
+            • Current operation mode (MCP enhanced vs traditional)
+            • MCP binary availability and version information
+            • MCP server status and health (when applicable)
+            • Component-specific error messages and recommendations
+
+            Use this option to:
+            • Verify the agent is properly configured
+            • Troubleshoot MCP integration issues
+            • Check if enhanced capabilities are available
+            • Get recommendations for resolving configuration problems
 
     examples:
-        - name: Ask about pod issues in the cluster with Azure OpenAI
+        - name: Ask about pod issues in the cluster with Azure OpenAI (MCP mode - default)
           text: |-
             export AZURE_API_BASE="https://my-azureopenai-service.openai.azure.com/"
             export AZURE_API_VERSION="2025-01-01-preview"
             export AZURE_API_KEY="sk-xxx"
             az aks agent "Why are my pods not starting?" --name MyManagedCluster --resource-group MyResourceGroup --model azure/my-gpt4.1-deployment
-        - name: Ask about pod issues in the cluster with OpenAI
+        - name: Ask about pod issues using traditional toolsets (no MCP)
+          text: |-
+            export AZURE_API_BASE="https://my-azureopenai-service.openai.azure.com/"
+            export AZURE_API_VERSION="2025-01-01-preview"
+            export AZURE_API_KEY="sk-xxx"
+            az aks agent "Why are my pods not starting?" --name MyManagedCluster --resource-group MyResourceGroup --model azure/my-gpt4.1-deployment --no-aks-mcp
+        - name: Ask about pod issues in the cluster with OpenAI (MCP mode - default)
           text: |-
             export OPENAI_API_KEY="sk-xxx"
             az aks agent "Why are my pods not starting?" --name MyManagedCluster --resource-group MyResourceGroup --model gpt-4o
         - name: Run in interactive mode without a question
           text: az aks agent "Check the pod status in my cluster" --name MyManagedCluster --resource-group MyResourceGroup --model azure/my-gpt4.1-deployment --api-key "sk-xxx"
-        - name: Run in non-interactive batch mode
+        - name: Run in non-interactive batch mode (traditional toolsets)
+          text: az aks agent "Diagnose networking issues" --no-interactive --max-steps 15 --model azure/my-gpt4.1-deployment --no-aks-mcp
+        - name: Run in non-interactive batch mode (MCP mode - default)
           text: az aks agent "Diagnose networking issues" --no-interactive --max-steps 15 --model azure/my-gpt4.1-deployment
         - name: Show detailed tool output during analysis
           text: az aks agent "Why is my service workload unavailable in namespace workload-ns?" --show-tool-output --model azure/my-gpt4.1-deployment
@@ -4016,6 +4061,21 @@
           text: az aks agent "What is the status of my cluster?" --no-echo-request --model azure/my-gpt4.1-deployment
         - name: Refresh toolsets to get the latest available tools
           text: az aks agent "What is the status of my cluster?" --refresh-toolsets --model azure/my-gpt4.1-deployment
+        - name: Troubleshoot missing capabilities by forcing toolset refresh
+          text: |-
+            # If the agent seems to be missing expected capabilities, force a refresh:
+            az aks agent "Debug my networking issues" --refresh-toolsets --show-tool-output --model azure/my-gpt4.1-deployment
+        - name: Show basic agent status
+          text: az aks agent --status
+        - name: Check if MCP integration is working
+          text: |-
+            # This will show if the MCP binary is downloaded and server is healthy
+            az aks agent --status
+        - name: Troubleshoot agent setup issues
+          text: |-
+            # Use status output to identify configuration problems
+            az aks agent --status
+            # Follow the recommendations shown in the output
         - name: Run agent with config file
           text: |
             az aks agent "Check kubernetes pod resource usage" --config-file /path/to/custom.yaml

src/aks-preview/azext_aks_preview/_params.py

@@ -2785,6 +2785,7 @@ def load_arguments(self, _):
         c.positional(
             "prompt",
             help="Ask any question and answer using available tools.",
+            nargs="?",
         )
         c.argument(
             "resource_group_name",
@@ -2844,6 +2845,19 @@ def load_arguments(self, _):
             help="Refresh the toolsets status.",
             action="store_true",
         )
+        c.argument(
+            "no_aks_mcp",
+            options_list=["--no-aks-mcp"],
+            action="store_true",
+            help="Disable AKS MCP integration and use traditional built-in toolsets",
+            is_preview=True,
+        )
+        c.argument(
+            "status",
+            options_list=["--status"],
+            action="store_true",
+            help="Show AKS agent configuration and status information",
+        )
 
 
 def _get_default_install_location(exe_name):