> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/intelligence/ai-tools.md). # KI-Tools Stellen Sie PowerShell-Skripte als AI Tools in PowerShell Universal bereit, damit sie von AI Agents und externen MCP-Clients wie GitHub Copilot verwendet werden können – mit Authentifizierung, Rollen Mit AI Tools können Sie PowerShell-Skripte als aufrufbare Tools für AI Agents und 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, eine Ausführungsumgebung auswählen und optional über MCP bereitgestellt werden. ## Ein AI Tool erstellen Navigieren Sie zu **Build > AI > Tools** und wählen Sie **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 ermittelt. Kommentarbasierte Hilfe wird dringend empfohlen, da PSU sie nutzt, um bessere Tool-Beschreibungen und Parameterschemata zu erstellen. Dieses Beispielskript eignet sich gut als AI Tool, da es klare Parameter und eine vorhersehbare Ausgabe hat: ```powershell <# .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: ```powershell 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 können Sie Tools so überprüfen: ```powershell Get-PSUAiTool Get-PSUAiTool -Name 'Get Running Processes' ``` ## Tools in einer persistenten Umgebung ausführen Standardmäßig startet jeder AI-Tool-Aufruf einen neuen PowerShell-Prozess. Weisen Sie Tools, die häufig von einem AI Agent oder MCP-Client aufgerufen werden, eine lokale Umgebung mit aktivierten **Persistent Runspaces** zu, um den laufenden PowerShell-Prozess wiederzuverwenden und den Prozessstart bei jedem Aufruf zu vermeiden. 1. Erstellen oder bearbeiten Sie eine Umgebung unter **Manage > Environments > Environments**. 2. Aktivieren Sie **Persistent Runspaces** und wählen Sie einen geeigneten Wert für **Max Runspaces**. 3. Erstellen oder bearbeiten Sie das AI Tool. Wählen Sie auf der Registerkarte **Execution** diese Umgebung unter **Run In** aus. Sie können die Umgebung auch in der Konfiguration mit `-Environment` zuweisen: ```powershell New-PSUAiTool -Name 'Get Running Processes' ` -Description 'Returns the top running processes by CPU usage.' ` -ScriptFullPath '/tools/Get-Running-Processes.ps1' ` -Environment 'Persistent Tools' ` -Mcp ``` Jeder Aufruf erzeugt weiterhin seinen eigenen Auftragsdatensatz, Status und seine eigene Ausgabe unter **Run > Jobs**. Persistente Umgebungen verwenden den PowerShell-Prozess wieder und behalten den beabsichtigten Runspace-Zustand zwischen Aufrufen bei, während Auftragsausgabe und Abbruch auf den jeweiligen Aufruf beschränkt bleiben. Die persistente Ausführung gilt für geeignete lokale, nicht minimale Umgebungen. Remote-Agent-, PowerShell-Remoting-, Container- und Minimal-Umgebungen verwenden weiterhin ihre normalen Ausführungspfade. Ein Neustart der Umgebung oder des PSU-Servers startet einen neuen persistenten Prozess, sodass der In-Memory-Runspace-Zustand zurückgesetzt wird. Verwenden Sie persistente Umgebungen nur, wenn die Wiederverwendung des Zustands beabsichtigt ist, und setzen Sie das Runspace-Limit auf die Parallelität, die Ihre Tools erfordern. ## Ein Tool in AI Agents verwenden Weisen Sie innerhalb eines AI Agent Tool-Namen direkt zu oder verwenden Sie Platzhaltermuster wie `ticket_*` oder `*`. PSU stellt diesem Agent nur die passenden Tools zur Verfügung. Der rollenbasierte Zugriff wird auf beiden Ebenen erzwungen: * Der Benutzer muss berechtigt sein, den Agent auszuführen. * Der Benutzer muss außerdem berechtigt sein, das Tool auszuführen. Von einem Agent gestartete Tool-Ausführungen erscheinen als untergeordnete Aufträge des AI-Prompt-Auftrags. Beispiel für eine Agent-Konfiguration: ```powershell 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 angezeigt, bei denen **MCP** aktiviert ist. Bei der Bereitstellung über MCP werden Tool-Namen für den Client normalisiert. Beispielsweise werden Leerzeichen und Punkte in Unterstriche umgewandelt. Wenn sich ein MCP-Client verbindet, filtert PSU die sichtbaren Tools anhand folgender Kriterien: * Ob das Tool für MCP markiert ist. * Ob der Aufrufer authentifiziert ist, sofern erforderlich. * Ob der Aufrufer mindestens eine erforderliche Rolle besitzt. Über MCP erfolgte Aufrufe erscheinen als MCP-Aufträge auf der Seite Jobs. Wenn Ihr Client Bearer-Tokens 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 für die Verbindung mit dem PSU-MCP-Server konfiguriert ist. In diesem Beispiel umschließt das Tool ein Skript, das laufende Prozesse zurückgibt: ```powershell 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: ```json "mcp": { "servers": { "PSU": { "url": "http://localhost:5000/api/v1/mcp" } } } ``` Wenn die Verbindung erfolgreich ist, zeigt Copilot die Anzahl der verfügbaren Tools an. Anschließend können Sie Copilot 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 zusätzlich 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. ## MCP-Serververbindungen benennen PowerShell Universal identifiziert seinen MCP-Server standardmäßig als `Universal.Server`. Legen Sie für jede Umgebung einen eindeutigen Namen fest, damit mehrere PowerShell Universal MCP-Verbindungen in Visual Studio Code leicht unterschieden werden können. Konfigurieren Sie den Namen in `appsettings.json`: ```json { "Mcp": { "ServerName": "Production PSU" } } ``` Für containerisierte oder auf Umgebungsvariablen basierende Bereitstellungen verwenden Sie: ``` Mcp__ServerName=Production PSU ``` Lassen Sie die Einstellung leer oder nicht angegeben, um den Standardnamen `Universal.Server` beizubehalten. ## AI- und MCP-Zugriff steuern Verwenden Sie die globalen AI- und MCP-Einstellungen, um die Serverkapazität zu begrenzen und AI-Funktionen zu deaktivieren, wenn sie in einer Umgebung nicht zulässig sind. ### MCP-Anfragen und -Aufträge begrenzen Gehen Sie zu **Einstellungszahnrad > Automation**, um Folgendes zu konfigurieren: * **MCP requests per minute**: Anfragen oberhalb der konfigurierten Rate werden vor der Ausführung abgelehnt. * **MCP concurrent jobs**: Zusätzliche MCP-Aufträge warten, bis ein Ausführungsplatz verfügbar ist. Der Wert `0` bedeutet unbegrenzt. Negative Werte sind nicht zulässig. Legen Sie beide Grenzwerte entsprechend der für PowerShell Universal verfügbaren Kapazität und den als MCP-Tools bereitgestellten Skripten fest. ### AI-Funktionen deaktivieren Wählen Sie **Disable AI Features** unter **Einstellungszahnrad > Automation**, um AI-Funktionen für den Server zu deaktivieren. Dadurch werden AI Agents, AI Tools und AI Chat in der Administrationskonsole ausgeblendet. Das Deaktivieren von AI entfernt außerdem den MCP-Endpunkt aus der Registrierung neuer Endpunkte und gibt für Anfragen an `/api/v1/mcp` sofort `404 Not Found` zurück. Ein Serverneustart ist nicht erforderlich. Verwenden Sie für Konfigurationsskripte `Set-PSUSetting -DisabledFeatures`, um deaktivierte Produktfunktionen zu verwalten. `-Features` bleibt ein Alias für bestehende Konfigurationen. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/intelligence/ai-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.