KI-Tools

Mit AI Tools können Sie PowerShell-Skripte als aufrufbare Tools für AI Agents und für externe MCP-Clients bereitstellen. Sie sind nützlich, wenn ein Modell PSU-Daten abrufen, eine kontrollierte Aktion ausführen oder strukturierte Ausgaben an einen Prompt zurückgeben soll.

Jedes Tool kann eine Authentifizierung erfordern, Rollen erzwingen und optional über MCP bereitgestellt werden.

Ein AI Tool erstellen

Navigieren Sie zu Intelligence / AI Tools und klicken Sie auf Create AI Tool. Wählen Sie das bereitzustellende Skript aus und entscheiden Sie dann, ob das Tool verfügbar sein soll:

• nur für PSU AI Agents
• für AI Agents und MCP-Clients, indem Sie MCP aktivieren

Wenn Authenticated aktiviert ist, muss der Aufrufer angemeldet sein. Wenn zusätzlich Rollen zugewiesen sind, muss der Aufrufer mindestens eine dieser Rollen besitzen.

Beschreibung

Die Beschreibung ist einer der wichtigsten Teile des Tools. Sie sollte dem Modell mitteilen:

• wann das Tool zu verwenden ist
• was das Tool zurückgibt
• ob das Tool den Zustand ändert
• alle wichtigen Erwartungen an Parameter

Kurze, konkrete Beschreibungen funktionieren am besten.

Parameter

Parameter werden automatisch aus dem PowerShell-Skript erkannt. Kommentarbasierte Hilfe wird dringend empfohlen, da PSU sie verwendet, um bessere Tool-Beschreibungen und Parameterschemata zu erstellen.

Dieses Beispielskript ist ein gutes AI Tool, da es klare Parameter und eine vorhersehbare Ausgabe hat:

<#
.SYNOPSIS
Returns the top running processes by CPU usage.

.PARAMETER Count
The number of processes to return.
#>
param(
        [Parameter()]
        [int]$Count = 5
)

Get-Process |
        Sort-Object CPU -Descending |
        Select-Object -First $Count Name, Id, CPU

Stellen Sie es als Tool bereit:

New-PSUAiTool -Name 'Get Running Processes' `
    -Description 'Returns the top running processes by CPU usage.' `
    -ScriptFullPath '/tools/Get-RunningProcesses.ps1' `
    -Authenticated `
    -Role @('Operator') `
    -Mcp

Nützliche Cmdlets sind:

• Get-PSUAiTool
• New-PSUAiTool
• Set-PSUAiTool
• Remove-PSUAiTool

Zum Beispiel, um Tools zu überprüfen:

Get-PSUAiTool
Get-PSUAiTool -Name 'Get Running Processes'

Ein Tool in AI Agents verwenden

Innerhalb eines AI Agents können Sie Tool-Namen direkt zuweisen oder Platzhaltermuster wie ticket_* oder * verwenden. PSU stellt diesem Agent nur die übereinstimmenden Tools zur Verfügung.

Der rollenbasierte Zugriff wird auf beiden Ebenen erzwungen:

• der Benutzer muss den Agent ausführen dürfen
• der Benutzer muss zudem das Tool ausführen dürfen

Tool-Ausführungen, die von einem Agent gestartet wurden, erscheinen als untergeordnete Jobs des AI-Prompt-Jobs.

Beispielkonfiguration eines Agents:

Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*')

Ein Tool über MCP verwenden

Das Model Context Protocol (MCP) ermöglicht es Remote-Clients wie GitHub Copilot, Ihre Tools zu erkennen und aufzurufen. PSU stellt MCP unter /api/v1/mcp bereit.

MCP-Clients werden nur Tools mit aktiviertem Mcp angezeigt.

Bei der Bereitstellung über MCP werden Tool-Namen für den Client normalisiert. Zum Beispiel werden Leerzeichen und Punkte in Unterstriche umgewandelt.

Wenn ein MCP-Client eine Verbindung herstellt, filtert PSU die sichtbaren Tools anhand folgender Kriterien:

• ob das Tool für MCP markiert ist
• ob der Aufrufer authentifiziert ist, wenn dies erforderlich ist
• ob der Aufrufer mindestens eine erforderliche Rolle besitzt

Über MCP getätigte Aufrufe erscheinen als MCP-Jobs auf der Seite Jobs.

Wenn Ihr Client Bearer-Token unterstützt, geben Sie beim Verbinden mit dem MCP-Endpunkt ein PSU-App-Token an.

Zugriff in GitHub Copilot

GitHub Copilot kann PSU-Tools aufrufen, wenn VS Code so konfiguriert ist, dass es sich mit dem PSU-MCP-Server verbindet.

In diesem Beispiel umschließt das Tool ein Skript, das laufende Prozesse zurückgibt:

Get-Process | Select-Object Name, Id

Drücken Sie bei aktivierter MCP-Erweiterung Ctrl+Shift+P und führen Sie MCP: Add Server... aus.

Wählen Sie die HTTP-Option und geben Sie die URL des MCP-Endpunkts ein. Standardmäßig ist dies http://localhost:5000/api/v1/mcp.

Der resultierende Inhalt von settings.json sieht etwa so aus.

"mcp": {
    "servers": {
        "PSU": {
            "url": "http://localhost:5000/api/v1/mcp"
        }
    }
}

Wenn die Verbindung erfolgreich ist, zeigt Copilot die Anzahl der verfügbaren Tools an.

Sie können Copilot dann bitten, das PSU-Tool zu verwenden. Zum Beispiel:

Use the PSU tool to list the top 5 processes and create a PowerShell script that writes them to JSON.

Wenn Sie außerdem ein Tool bereitstellen, das einen Prozess startet, kann ein Prompt wie dieser diese Aktion auslösen:

Use the PSU tool to start a new process named calc.

Halten Sie Tool-Beschreibungen und Parameterhilfe klar, damit Copilot das richtige Tool ohne Ausprobieren auswählen kann.