Skip to main content
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

1

Build

cd cpp
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
Binary: cpp\build\Release\health_agent.exe
2

Start Lemonade Server

lemonade-server serve
3

Run the agent

cpp\build\Release\health_agent.exe
Select GPU or NPU backend, then choose from the investigation menu:
[1] Why is my system slow?
[2] Is my system secure and up to date?
[3] Can I free up disk space?
[4] Diagnose recent system errors
[5] How's my battery holding up?
[6] Full system health report
Or type your own question — the agent will reason about what data to gather.

Architecture

The agent subclasses gaia::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 no registerTools() 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:
class WindowsSystemHealthAgent : public gaia::Agent {
public:
    explicit WindowsSystemHealthAgent(const std::string& modelId)
        : Agent(makeConfig(modelId)) {
        setOutputHandler(std::make_unique<gaia::CleanConsole>());
        init();

        // All tools come from the Windows MCP server
        connectMcpServer("windows", {
            {"command", "uvx"},
            {"args", {"windows-mcp"}}
        });
    }

protected:
    std::string getSystemPrompt() const override {
        return R"(You are an expert Windows system administrator...
            // Investigation strategies per query type
            // PowerShell commands for memory, disk, CPU, processes, etc.
            // Reasoning protocol: FINDING/DECISION after each tool
        )";
    }

private:
    static gaia::AgentConfig makeConfig(const std::string& modelId) {
        gaia::AgentConfig config;
        config.maxSteps = 75;       // full diagnostics needs many tool calls
        config.modelId = modelId;
        config.contextSize = 32768; // 32K for 12+ tool calls with output
        return config;
    }
};
The system prompt contains investigation strategies — each query type maps to a specific sequence of PowerShell commands. The LLM follows the strategy, uses FINDING/DECISION reasoning after each tool result, and delivers a correlated conclusion.

Investigations

Each menu option triggers a multi-tool investigation. The LLM gathers data, reasons about each result, and correlates findings before answering.
InvestigationTools CalledWhat It Checks
Why is my system slow?4CPU load, top processes, memory, disk space
Is my system secure?3Windows updates, system errors, startup programs
Can I free up disk space?3Drive usage, temp folder size, largest installed software
Diagnose system errors3Event log errors, disk SMART health, memory status
Battery health3Battery status, top CPU processes, CPU load
Full health report12+All metrics, then writes a report to Notepad

Available PowerShell Commands

The system prompt provides these commands for the LLM to use via mcp_windows_Shell:
CategoryPowerShell CommandOutput
MemoryGet-CimInstance Win32_OperatingSystemTotal/free RAM in GB
DiskGet-PSDrive -PSProvider FileSystemUsed/free space per drive
CPUGet-CimInstance Win32_ProcessorName, cores, load %
GPUGet-CimInstance Win32_VideoControllerName, VRAM, driver version
Top Processes (CPU)Get-Process | Sort-Object CPUTop 10 by CPU time
Top Processes (Memory)Get-Process | Sort-Object WorkingSet64Top 10 by memory
NetworkGet-NetIPConfigurationIP, gateway, DNS per interface
Startup ProgramsGet-CimInstance Win32_StartupCommandName, command, location
System ErrorsGet-WinEvent (last 24h)Time, event ID, message
Windows UpdateGet-HotFixRecent hotfixes with dates
BatteryGet-CimInstance Win32_BatteryCharge %, chemistry, status
Installed SoftwareRegistry queryTop 20 by size or install date
Temp FolderGet-ChildItem $env:TEMPTotal size and file count
Storage HealthGet-PhysicalDiskSMART 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 sourceWindows MCP server subprocessC++ lambdas compiled into binary
DependenciesRequires uvx + windows-mcpSelf-contained .exe
FlexibilityAny MCP server, any tool setFixed at compile time
LatencyJSON-RPC roundtrip per tool callDirect function call
Best forBroad system access, GUI automationFocused single-purpose agents
Choose MCP when you need access to a wide range of system capabilities. Choose registered tools when you want a self-contained binary with no runtime dependencies.

Next Steps