Source Code:
cpp/examples/health_agent.cpp — single-file agent using MCP to run PowerShell diagnostics with a polished terminal UI.Platform: Windows (requires the Windows MCP server and
uvx).
Prerequisite: Lemonade Server running with a model loaded.What This Agent Does
The System Health Agent is an investigative AI agent that diagnoses system problems by gathering data from multiple sources, correlating findings, and reasoning about root causes. When you ask “Why is my system slow?”, it doesn’t just check one metric — it runs 4 PowerShell commands in sequence (CPU, processes, memory, disk), reasons about each result, and delivers a correlated diagnosis. Key differences from the Wi-Fi Troubleshooter:- MCP-based — all tools come from the Windows MCP server, not registered C++ lambdas
- Multi-tool investigations — each query triggers 3-4 correlated tool calls with reasoning between each
- Broader scope — CPU, memory, disk, processes, network, battery, SMART, Windows Update, and more
- Report generation — full diagnostics can write a formatted report to Notepad
Demo
Full diagnostic run on a Ryzen AI PC: the agent gathers CPU, memory, disk, and process data via MCP, reasons about each result, and delivers a correlated diagnosis — all powered by a local LLM on the GPU.Quick Start
Architecture
The agent subclassesgaia::Agent and connects to the Windows MCP server at construction time. Unlike the Wi-Fi agent (which registers tools as C++ lambdas), this agent gets all its tools from the MCP server — every diagnostic runs through mcp_windows_Shell.
How It Works
The agent has noregisterTools() override — all tools come from MCP. The system prompt teaches the LLM investigation strategies: which PowerShell commands to run for each query type, and how to correlate findings:
Investigations
Each menu option triggers a multi-tool investigation. The LLM gathers data, reasons about each result, and correlates findings before answering.| Investigation | Tools Called | What It Checks |
|---|---|---|
| Why is my system slow? | 4 | CPU load, top processes, memory, disk space |
| Is my system secure? | 3 | Windows updates, system errors, startup programs |
| Can I free up disk space? | 3 | Drive usage, temp folder size, largest installed software |
| Diagnose system errors | 3 | Event log errors, disk SMART health, memory status |
| Battery health | 3 | Battery status, top CPU processes, CPU load |
| Full health report | 12+ | All metrics, then writes a report to Notepad |
Available PowerShell Commands
The system prompt provides these commands for the LLM to use viamcp_windows_Shell:
| Category | PowerShell Command | Output |
|---|---|---|
| Memory | Get-CimInstance Win32_OperatingSystem | Total/free RAM in GB |
| Disk | Get-PSDrive -PSProvider FileSystem | Used/free space per drive |
| CPU | Get-CimInstance Win32_Processor | Name, cores, load % |
| GPU | Get-CimInstance Win32_VideoController | Name, VRAM, driver version |
| Top Processes (CPU) | Get-Process | Sort-Object CPU | Top 10 by CPU time |
| Top Processes (Memory) | Get-Process | Sort-Object WorkingSet64 | Top 10 by memory |
| Network | Get-NetIPConfiguration | IP, gateway, DNS per interface |
| Startup Programs | Get-CimInstance Win32_StartupCommand | Name, command, location |
| System Errors | Get-WinEvent (last 24h) | Time, event ID, message |
| Windows Update | Get-HotFix | Recent hotfixes with dates |
| Battery | Get-CimInstance Win32_Battery | Charge %, chemistry, status |
| Installed Software | Registry query | Top 20 by size or install date |
| Temp Folder | Get-ChildItem $env:TEMP | Total size and file count |
| Storage Health | Get-PhysicalDisk | SMART status per disk |
MCP vs Registered Tools
This agent uses MCP while the Wi-Fi Troubleshooter uses registered C++ tools. The tradeoffs:| Health Agent (MCP) | Wi-Fi Agent (Registered Tools) | |
|---|---|---|
| Tool source | Windows MCP server subprocess | C++ lambdas compiled into binary |
| Dependencies | Requires uvx + windows-mcp | Self-contained .exe |
| Flexibility | Any MCP server, any tool set | Fixed at compile time |
| Latency | JSON-RPC roundtrip per tool call | Direct function call |
| Best for | Broad system access, GUI automation | Focused single-purpose agents |
Next Steps
Wi-Fi Troubleshooter Agent
Compare with the registered-tools approach for network diagnostics
Windows System Health Guide
Walkthrough of the MCP-based system health approach
Customizing Your Agent
Custom prompts, tools, MCP servers, and output capture
C++ Framework Overview
Architecture, AgentConfig reference, and project structure