> 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/config/agent.md). # Agent Konfigurieren Sie Devolutions Agent oder den PowerShell Universal Event Hub-Agenten, um Jobs und Befehle auf Remote-Computern auszuführen. PowerShell Universal unterstützt zwei Remote-Agent-Implementierungen. Verwenden Sie **Devolutions Agent** für neue Bereitstellungen. Er verbindet sich über gRPC mit PowerShell Universal und unterstützt Remote-Jobs, Computergruppen, PowerShell-Remoting-Befehle und Multi-pwsh-virtuelle Umgebungen. Der **PowerShell Universal Agent** bleibt für Event Hub-basierte Automatisierung verfügbar. ## Devolutions Agent Devolutions Agent ist der empfohlene Agent für neue Installationen. Er stellt eine ausgehende, authentifizierte gRPC-Verbindung zu PowerShell Universal her; PowerShell-Remoting muss nicht zwischen dem Server und dem verwalteten Computer konfiguriert werden. Laden Sie das Windows-Installationsprogramm aus dem [Devolutions Download Center](https://devolutions.net/download-center/) herunter. Verwenden Sie für Container-Bereitstellungen das Image [`devolutions/powershell-universal-agent`](https://hub.docker.com/r/devolutions/powershell-universal-agent) aus Docker Hub. ### Voraussetzungen und Konnektivität Installieren Sie Devolutions Agent auf dem Computer, der die Jobs ausführen soll. Der Agent muss den gRPC-Endpunkt von PowerShell Universal über HTTP/2 erreichen können. In der Standard-Entwicklungskonfiguration ist dies der Port `5006`; verwenden Sie in der Produktion den HTTPS-Endpunkt. Jeder Agent benötigt eine eindeutige, stabile Agent-ID. Wenn sich der Agent verbindet, erstellt oder aktualisiert PowerShell Universal einen Computer-Datensatz vom Typ **Agent**, markiert ihn als online und fügt Tags für seinen Computernamen, sein Betriebssystem, seine Architektur, seine Hubs und seine Fähigkeiten hinzu. Verwenden Sie diese Tags, um den Agenten mit Computergruppen anzusprechen. ### App-Token erstellen Erstellen Sie für jeden Devolutions Agent ein dediziertes App-Token. Das Token muss die integrierte Rolle **Agent** besitzen. Diese Rolle ist absichtlich auf die Agent-Registrierung beschränkt und gewährt keine Berechtigungen für die Verwaltungs-API. Verwenden Sie daher kein Administrator- oder Automatisierungstoken erneut. {% code collapsedlinecount="10" %} ```powershell Grant-PSUAppToken ` -IdentityName 'devolutions-agent-01' ` -Role 'Agent' ` -Description 'Devolutions Agent on production-01' ` -Expiry (Get-Date).AddYears(1) ``` {% endcode %} Speichern Sie das zurückgegebene Token als Secret. Rotieren Sie es, bevor es abläuft, und ersetzen Sie es in der Agent-Konfiguration. Der Agent kann sich mit einem fehlenden, ungültigen oder nicht der Agent-Rolle zugeordneten Token nicht verbinden. ### Den Agenten konfigurieren Das Windows-Installationsprogramm kann die Funktion **PowerShell Universal Agent** aktivieren und die PowerShell Universal-Server-URL, das App-Token, die Agent-ID und den Anzeigenamen erfassen. Der Agent kann auch in `agent.json` konfiguriert werden. {% code collapsedlinecount="10" %} ```json { "PsuAgent": { "Enabled": true, "ServerUrl": "https://psu.contoso.com:5006", "AgentId": "devolutions-agent-01", "DisplayName": "Production agent 01", "AppToken": "$secret:psu-agent-token", "Hubs": ["production"], "PowerShell": { "VersionSelector": "7.6" } } } ``` {% endcode %} `AppToken` akzeptiert entweder den Tokenwert oder eine `$secret:`-Referenz, die von PowerShell SecretManagement aufgelöst wird. `AgentId` ist der Bezeichner, mit dem der Agent angesprochen wird. `DisplayName` ist ein benutzerfreundlicher Name, der in PowerShell Universal angezeigt wird. `Hubs` werden zu **Hub**-Computer-Tags. `PowerShell` kann eine `multi-pwsh`-Version auswählen, einen bestimmten Pfad zur ausführbaren Programmdatei verwenden oder Windows PowerShell verwenden. Geben Sie für das Linux-Container-Image `PSU_SERVER_URL` und `PSU_APP_TOKEN` an; beide sind erforderlich, um die PSU-Integration zu aktivieren. {% code collapsedlinecount="10" %} ```powershell docker run --rm ` --add-host host.docker.internal:host-gateway ` --env PSU_SERVER_URL='http://host.docker.internal:5006' ` --env PSU_APP_TOKEN='' ` --env PSU_AGENT_ID='devolutions-agent-linux' ` --env PSU_HUBS='production' ` devolutions/powershell-universal-agent:latest ``` {% endcode %} ### Jobs auf einem Agenten ausführen Nachdem der Agent unter **Manage > Computers & Groups > Computers** erscheint, erstellen Sie eine Computergruppe, deren Tags ihn auswählen. Beispielsweise hat ein Agent, der mit `"Hubs": ["production"]` konfiguriert ist, ein `Hub`-Tag mit dem Wert `production`; eine Computergruppe mit dem Tag `production` wählt diesen Agent aus. Weisen Sie die Computergruppe einem Skript oder einem Zeitplan zu und wählen Sie, ob die Ausführung auf **einem beliebigen** übereinstimmenden Computer oder auf **allen** übereinstimmenden Computern erfolgen soll. Sie können ein Skript auch für einen einzelnen Agenten aufrufen, indem Sie dessen Agent-ID als Queue verwenden. {% code collapsedlinecount="10" %} ```powershell # Run on one named Devolutions Agent. Invoke-PSUScript -Name '.\Inventory.ps1' -Queue 'devolutions-agent-01' # Run on any online computer selected by the production-agents group. Invoke-PSUScript -Name '.\Inventory.ps1' -ComputerGroup 'production-agents' ``` {% endcode %} Es werden nur Online-Agenten ausgewählt, die sich nicht im Wartungsmodus befinden. Ein für **All** konfigurierter Gruppenaufruf erstellt einen Job für jeden übereinstimmenden Agenten; **Any** wählt einen übereinstimmenden Agenten aus. ### Befehle mit Invoke-PSUCommand ausführen `Invoke-PSUCommand` ist ein Alias für `Send-PSUEvent`. Verwenden Sie `-Computer`, um auf einer bestimmten Agent-ID auszuführen, oder `-ComputerGroup`, um auf jedem übereinstimmenden Computer in einer Gruppe auszuführen. Der Befehl gibt Pipeline-Ausgaben zurück und schreibt die Remote-Streams für Warnungen, Informationen, ausführliche Ausgaben und Fehler lokal. {% code collapsedlinecount="10" %} ```powershell # Run a script block on one Devolutions Agent. Invoke-PSUCommand ` -Computer 'devolutions-agent-01' ` -ScriptBlock { Get-CimInstance Win32_OperatingSystem } # Run a command on all agents selected by a computer group. Invoke-PSUCommand ` -ComputerGroup 'production-agents' ` -Command Get-Service ` -Parameters @{ Name = 'Spooler' } ``` {% endcode %} Verwenden Sie `-Timeout`, um länger laufende Befehle zu ermöglichen. Der Agent muss während des gesamten Aufrufs verbunden bleiben. ### Multi-pwsh-virtuelle Umgebungen verwenden Für eine isolierte oder Container-Ausführungsumgebung mit aktivierter virtueller Umgebung packt PowerShell Universal automatisch die ausgewählte virtuelle `multi-pwsh`-Umgebung und weist den Remote-Agenten an, sie vor dem Start des Jobs zu importieren. Der Agent hostet den Job anschließend mit der passenden PowerShell-Version und dem Namen der virtuellen Umgebung. Verwenden Sie dies, um die von einem Job benötigten Module bereitzustellen: 1. Erstellen oder aktualisieren Sie die virtuelle Umgebung in PowerShell Universal und installieren Sie die erforderlichen Module darin. 2. Wählen Sie diese isolierte oder Container-Umgebung für das Skript aus. 3. Sprechen Sie den Devolutions Agent direkt oder über eine Computergruppe an. Der Import erfolgt über `multi-pwsh venv import`. Sie müssen die Module nicht manuell auf den Agenten kopieren; behalten Sie die Definition der virtuellen Umgebung und ihre Module unter der Verwaltung von PowerShell Universal, damit der Agent das erwartete Paket erhält. ### Was PowerShell Universal überträgt PowerShell Universal erstellt ein Remote-Repository im temporären Verzeichnis des Agenten unter `PowerShellUniversal/Repository` mit den Ordnern `Scripts` und `Modules`. Der Modules-Ordner des Repositorys wird dem Remote-PowerShell-Modulpfad hinzugefügt. Für einen Skript-Job überträgt PowerShell Universal das Startskript des Jobs in den Remote-Scripts-Ordner und führt den Job über den gRPC-PowerShell-Remoting-Stream aus. Diese Übertragung erfolgt pro Ausführung: Das kopierte Startskript wird nach Abschluss des Jobs entfernt. Die Admin-Konsole bietet weder eine Aktion **Install on Agent** noch eine Einstellung **Keep run scripts on agents**. Wenn die ausgewählte Umgebung eine virtuelle multi-pwsh-Umgebung verwendet, wird deren Paket vor der Ausführung des Jobs importiert. Gehen Sie nicht davon aus, dass beliebige Serverdateien, Secrets oder Module, die außerhalb der ausgewählten virtuellen Umgebung installiert wurden, an den Agenten übertragen werden; stellen Sie diese explizit in der Umgebung oder auf dem verwalteten Computer bereit. ## PowerShell Universal Agent Der PowerShell Universal Agent ist der ursprüngliche Event Hub-basierte Agent. Er führt ein lokales Skript oder einen direkten PowerShell-Befehl aus, nachdem er einen Event Hub-Aufruf über WebSockets erhalten hat. Verwenden Sie ihn, wenn Sie einen bestehenden Event Hub-Workflow benötigen; verwenden Sie Devolutions Agent für neue Remote-Job-Bereitstellungen. ### agent.json konfigurieren Erstellen Sie `agent.json` nach der Installation. Speichern Sie die Datei unter `$env:ProgramData\PowerShellUniversal` für einen systemweiten Agenten oder unter `$env:AppData\PowerShellUniversal` für einen benutzerspezifischen Agenten. {% code collapsedlinecount="10" %} ```json { "Connections": [ { "Url": "https://psu.contoso.com", "Hub": "eventHub", "AppToken": "", "ScriptPath": "script.ps1", "Description": "My agent" } ] } ``` {% endcode %} `Url` und `Hub` sind erforderlich. Authentifizieren Sie sich mit `AppToken` oder `UseDefaultCredentials`. `ScriptPath` ist optional, da Event Hubs PowerShell-Befehle direkt aufrufen können. Ein relativer Skriptpfad wird ausgehend vom Datenverzeichnis von PowerShell Universal aufgelöst; verwenden Sie einen absoluten Pfad, wenn das Skript an einem anderen Ort gespeichert ist. ### Event Hub-Befehle senden Verwenden Sie `Invoke-PSUCommand` oder `Send-PSUEvent`, um den konfigurierten Event Hub aufzurufen. Event Hub-spezifische Beispiele und Aufrufoptionen finden Sie unter [Event Hubs](/powershell-universal/de/api/event-hubs.md). --- # 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/config/agent.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.