Windows系统健康检查代理

winscout-ai

A LangChain / LangGraph ReAct agent that checks a Windows machine for system anomalies and gives you a plain-English health summary.

It talks to Windows entirely through PowerShell -- no agent, service, or extra software needs to run beyond Python, uv, and Ollama. Works running directly on Windows (tested in cmd) as well as from a Linux environment with powershell.exe reachable on PATH.

What it checks

The agent has 7 tools and decides for itself which ones to call based on your question:

The agent is instructed to base its summary only on data the tools actually return (never invented event IDs, process names, or numbers), and to flag anomalies like high CPU/memory, low disk space, stopped services, disabled Defender, or a process opening an unusually large number of connections to one destination.

Requirements

• powershell.exe reachable on PATH
• uv for dependency management
• Ollama running locally with a tool-calling-capable model pulled (default qwen2.5)

Setup

1. Clone the repository:
   复制

   git clone https://github.com/kumar-albert/winscout-ai.git
   cd winscout-ai
   

2. Install dependencies:
   复制

   make install
   

   On Windows (cmd/PowerShell, no make required):
   复制

   make.bat install
   

3. Copy the env template and adjust if needed:
   复制

   cp .env.example .env
   

4. Pull the model:
   复制

   ollama pull qwen2.5
   

Usage

One-shot health check -- asks the agent the question in DEFAULT_AGENT_QUESTION (see .env.example) and prints its summary:

make run          # or, on Windows: make.bat run

Interactive chat -- a REPL that keeps conversation history across turns, so follow-up questions ("is that high?") work without repeating context. Type exit, quit, or q to leave:

make chat          # or, on Windows: make.bat chat

To ask a single specific question programmatically, use run_agent() directly:

from src.agent import run_agent

print(run_agent("Is anything wrong with my disk space or Defender status?"))

Configuration

All tunables live in .env (see .env.example for defaults), loaded via src/config.py:

Logging

Every layer logs through src/logger.py. At the default INFO level you get agent lifecycle events (run start/finish, timing) and warnings for real findings (stopped services, Defender disabled, PowerShell failures) -- nothing about routine tool tracing. Set LOG_LEVEL=DEBUG in .env to also see every tool call's arguments, the PowerShell command it ran, timing, and result size.

Project layout

main.py                    # entry point, calls run_agent()
makefile                    # make targets (install, run, clean, pre-requisites)
make.bat                    # same targets, for native Windows cmd/PowerShell
src/
  agent.py                 # builds the ChatOllama LLM + create_react_agent, system prompt
  tools.py                 # LangChain @tool wrappers (agent-facing surface)
  windows_system.py        # resource/disk/process/service/Defender/connections logic
  windows_event_log.py     # event log fetching logic
  powershell.py            # shared subprocess + .NET date parsing helpers
  config.py                # .env-backed constants
  logger.py                # logging setup

Architecture

graph LR
    A[ReAct Agent - LangGraph]
    B[ChatOllama]
    C[Windows tools - src/tools.py]
    D[Domain logic - windows_system.py / windows_event_log.py]
    E[PowerShell: Get-WinEvent, Get-CimInstance, Get-Process, Get-Service, Get-MpComputerStatus, Get-NetTCPConnection]

    A <--> B
    A --> C --> D --> E

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.

License

MIT.

Contact

For any inquiries, please reach out to the repository owner, kumar-albert.