Using PowerShell with an AI Agent

The GENESIS PowerShell interface is a text-based, self-describing, scriptable surface for configuration, which makes it a natural fit for an AI agent—a large-language-model assistant that can run commands on your behalf. An agent can list modules, read command help, inspect existing configuration, and compose the commands needed to carry out a request, all through the same interface a person uses.

This combination is powerful because the interface gives an agent everything it needs to orient itself: Get-Command enumerates what is possible, Get-Help describes how each command works, and the Get commands let the agent observe the current state before and after it acts. It is also consequential, because the agent is changing live configuration that synchronizes with the running system. The practices below help you get reliable results while keeping that configuration safe.

Prefer Generated Scripts Over Direct Interaction

The most stable and reproducible way to apply changes is to have the agent learn the interface first and then author a script that performs the work, rather than having it run commands against the interface one at a time. In this pattern, the agent uses the discovery commands to understand the modules, commands, and parameters involved, writes a .ps1 script that carries out the requested change, and that reviewed script—not an improvised sequence of live commands—is what runs against the configuration.

Separating the work this way improves consistency and mitigates unpredictable results:

  • The change becomes a reviewable artifact.

    A script can be read, approved, and corrected before anything is written, so you can see exactly what will happen instead of discovering it command by command.

  • It is reproducible.

    The same script applied to another system, or the same system later, produces the same configuration, which is difficult to guarantee when an agent composes commands on the fly.

  • It removes per-step variability.

    An agent that decides each command interactively may take a slightly different path each time; a fixed script does not, so the outcome does not depend on the agent improvising the same way twice.

  • It separates reasoning from execution.

    The agent does its open-ended work—discovery and authoring—up front, leaving a deterministic script to perform the actual configuration changes.

Use the discovery step below to ground the script in the real commands, and then apply the review and safety practices in the rest of this topic to the script before you run it.

Let the Agent Discover Before It Acts

An agent works best when it grounds itself in the actual system rather than assumptions. Encourage a workflow that does the following:

  • Discovers the real commands.

    Have the agent run Get-Command and Get-Help -Full to confirm that a command and its parameters exist as expected, rather than relying on recalled syntax. See Discovering Commands and Accessing Help.

  • Reads before it writes.

    Have the agent get the current configuration first, so it changes the right entity and knows the starting state.

  • Verifies after it writes.

    Have the agent get the entity again after a New or Set command to confirm that the result matches the intent.

Protect the Configuration

Because every command takes effect immediately, put guardrails around what the agent can do:

  • Back up the configuration and test against a non-production system first.

    Validate a routine on a test configuration before letting it touch production, and take a backup you can roll back to. When the configuration is hosted on SQL Server, the Workbench module backs up and restores entire configuration databases: Set-WbBackupDatabase creates a named backup of a database, Get-WbRestorePoints lists the backups available for it, and Set-WbRestoreDatabase restores the database from a selected backup.

  • Use a security account scoped to the task.

    The interface enforces GENESIS security, so signing the agent in as a user with only the permissions required for the task limits the blast radius of a mistake.

  • Confirm the target host.

    Have the agent check Get-WbHost before making changes to verify that it is configuring the intended system.

Review and Constrain the Work

  • Review generated scripts before running them.

    Treat a script that an agent produces as a proposal to read and approve, particularly where it includes Remove commands or affects many entities.

  • Prefer small, verifiable batches.

    A routine that changes a few entities and reports back is easier to check than one sweeping change. Since the changes commit incrementally, smaller batches also make it clear where a routine stopped if something fails.

  • Design routines to be safely re-runnable.

    Reading an entity before creating it or having the agent report what it would change before actually making the change makes a partially completed routine safe to run again.