Windows Process

Overview

Gives the agent the same view as Task Manager: see what's running, launch an app, or stop one — but anything that changes state is approved by you first, and the agent can never accidentally kill a critical Windows service.

How it works

Wraps Get-Process / Start-Process / Stop-Process via PowerShell. 'list' returns name, PID, working set, CPU, and start time and never requires approval. 'start' and 'kill' build a MutationPlan and route through SupervisedMutationGuard. The denylist refuses to kill core system processes (svchost, lsass, winlogon, csrss, services, smss). Pass apply=true to execute; otherwise the tool returns a dry-run plan.

Example

When a user asks:

Restart Notepad — close any running instances and launch a fresh one.

the agent calls the tool:

windows_process(operation="kill", name="notepad.exe", apply=true) then windows_process(operation="start", path="notepad.exe", apply=true)

and gets back: two approval prompts, then a confirmation that the old notepad processes ended and a new one started.

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

swarmai.tools.windows.enabled required

Master switch for the Windows tool category.

swarmai.tools.windows.process.kill-denylist optional

Comma-separated list of process names that 'kill' must always refuse. Defaults to svchost, lsass, winlogon, csrss, services, smss.

swarmai.tools.windows.auto-approve optional

Skip the y/N prompt and auto-approve every mutation. Intended for non-interactive runs only.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# pc-control.yaml
name: pc-control-crew
process: SEQUENTIAL

agents:
  - id: operator
    role: Desktop Operator
    goal: Manage the user's running applications safely
    tools:
      - windows_process
      - windows_window

tasks:
  - id: pc-control-task
    agent: operator
    description: Close any running Notepad instances and launch a fresh one.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.windows.WindowsProcessTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired WindowsProcessTool windowsProcessTool;

Agent operator = Agent.builder()
    .role("Desktop Operator")
    .goal("Manage the user's running applications safely")
    .chatClient(chatClient)
    .tool(windowsProcessTool)
    .build();

Task operatorTask = Task.builder()
    .description("Close any running Notepad instances and launch a fresh one.")
    .agent(operator)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(operator)
    .task(operatorTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Inspect what's running before deciding whether to kill or start an app

Restart a stuck application as part of a recovery workflow

Launch a tool the next agent needs (e.g. open a viewer before windows_window focuses it)

Build operator-style 'PC butler' agents that act with explicit consent

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/windows/WindowsProcessTool.java in the swarm-ai repository.

Open windows_process on GitHub →