> 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/fr/config/agent.md). # Agent Configurez Devolutions Agent ou l'agent Event Hub de PowerShell Universal pour exécuter des tâches et des commandes sur des ordinateurs distants. PowerShell Universal prend en charge deux implémentations d'agent distant. Utilisez **Devolutions Agent** pour les nouveaux déploiements. Il se connecte à PowerShell Universal via gRPC et prend en charge les tâches distantes, les groupes d'ordinateurs, les commandes de communication à distance PowerShell et les environnements virtuels multi-pwsh. L'agent **PowerShell Universal Agent** demeure disponible pour l'automatisation basée sur Event Hub. ## Devolutions Agent Devolutions Agent est l'agent recommandé pour les nouvelles installations. Il établit une connexion gRPC sortante et authentifiée vers PowerShell Universal; la communication à distance PowerShell n'a pas besoin d'être configurée entre le serveur et l'ordinateur géré. Téléchargez l'installateur Windows depuis le [Centre de téléchargement Devolutions](https://devolutions.net/download-center/). Pour les déploiements en conteneur, utilisez l'image [`devolutions/powershell-universal-agent`](https://hub.docker.com/r/devolutions/powershell-universal-agent) de Docker Hub. ### Prérequis et connectivité Installez Devolutions Agent sur l'ordinateur qui exécutera les tâches. L'agent doit pouvoir atteindre le point de terminaison gRPC de PowerShell Universal via HTTP/2. Dans la configuration de développement par défaut, il s'agit du port `5006`; utilisez le point de terminaison HTTPS en production. Chaque agent a besoin d'un ID d'agent unique et stable. Lorsque l'agent se connecte, PowerShell Universal crée ou met à jour un enregistrement d'ordinateur de type **Agent**, le marque comme étant en ligne et ajoute des étiquettes pour son nom de machine, son système d'exploitation, son architecture, ses hubs et ses capacités. Utilisez ces étiquettes pour cibler l'agent avec des groupes d'ordinateurs. ### Créer un jeton d'application Créez un jeton d'application dédié pour chaque Devolutions Agent. Le jeton doit avoir le rôle intégré **Agent**. Ce rôle est volontairement limité à l'enregistrement de l'agent et n'accorde pas de permissions sur l'API de gestion; n'utilisez donc pas de nouveau un jeton d'administrateur ou d'automatisation. {% code collapsedlinecount="10" %} ```powershell Grant-PSUAppToken ` -IdentityName 'devolutions-agent-01' ` -Role 'Agent' ` -Description 'Devolutions Agent on production-01' ` -Expiry (Get-Date).AddYears(1) ``` {% endcode %} Stockez le jeton retourné comme un secret. Faites-le pivoter avant son expiration et remplacez-le dans la configuration de l'agent. L'agent ne peut pas se connecter avec un jeton manquant, invalide ou n'ayant pas le rôle Agent. ### Configurer l'agent L'installateur Windows peut activer la fonctionnalité **PowerShell Universal Agent** et recueillir l'URL du serveur PowerShell Universal, le jeton d'application, l'ID de l'agent et le nom d'affichage. L'agent peut aussi être configuré dans `agent.json`. {% 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` accepte soit la valeur du jeton, soit une référence `$secret:` résolue par PowerShell SecretManagement. `AgentId` est l'identifiant utilisé pour cibler l'agent. `DisplayName` est un nom convivial affiché dans PowerShell Universal. `Hubs` devient des étiquettes d'ordinateur **Hub**. `PowerShell` peut sélectionner une version `multi-pwsh`, utiliser un chemin d'exécutable spécifique ou utiliser Windows PowerShell. Pour l'image de conteneur Linux, fournissez `PSU_SERVER_URL` et `PSU_APP_TOKEN`; les deux sont requis pour activer l'intégration PSU. {% 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 %} ### Exécuter des tâches sur un agent Une fois que l'agent apparaît dans **Manage > Computers & Groups > Computers**, créez un groupe d'ordinateurs dont les étiquettes le sélectionnent. Par exemple, un agent configuré avec `"Hubs": ["production"]` possède une étiquette `Hub` ayant la valeur `production`; un groupe d'ordinateurs avec l'étiquette `production` sélectionne cet agent. Attribuez le groupe d'ordinateurs à un script ou à une planification, puis choisissez si l'exécution doit se faire sur **n'importe quel** ordinateur correspondant ou sur **tous** les ordinateurs correspondants. Vous pouvez aussi invoquer un script sur un seul agent en utilisant son ID d'agent comme file d'attente. {% 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 %} Seuls les agents en ligne qui ne sont pas en mode maintenance sont sélectionnés. Une invocation de groupe configurée pour **All** crée une tâche pour chaque agent correspondant; **Any** sélectionne un seul agent correspondant. ### Exécuter des commandes avec Invoke-PSUCommand `Invoke-PSUCommand` est un alias de `Send-PSUEvent`. Utilisez `-Computer` pour exécuter sur un ID d'agent en particulier, ou `-ComputerGroup` pour exécuter sur chaque ordinateur correspondant d'un groupe. La commande retourne la sortie du pipeline et écrit localement les flux distants d'avertissement, d'information, détaillé et d'erreur. {% 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 %} Utilisez `-Timeout` pour permettre des commandes de plus longue durée. L'agent doit rester connecté pendant toute l'invocation. ### Utiliser des environnements virtuels multi-pwsh Pour un environnement d'exécution isolé ou en conteneur avec un environnement virtuel activé, PowerShell Universal empaquette automatiquement l'environnement virtuel `multi-pwsh` sélectionné et demande à l'agent distant de l'importer avant le début de la tâche. L'agent héberge ensuite la tâche avec la version de PowerShell et le nom d'environnement virtuel correspondants. Utilisez ceci pour livrer les modules requis par une tâche : 1. Créez ou mettez à jour l'environnement virtuel dans PowerShell Universal et installez-y les modules requis. 2. Sélectionnez cet environnement isolé ou en conteneur pour le script. 3. Ciblez Devolutions Agent directement ou par l'entremise d'un groupe d'ordinateurs. L'importation s'exécute via `multi-pwsh venv import`. Vous n'avez pas besoin de copier manuellement les modules vers l'agent; gardez la définition de l'environnement virtuel et ses modules sous la gestion de PowerShell Universal afin que l'agent reçoive le paquet attendu. ### Ce que PowerShell Universal transfère PowerShell Universal crée un dépôt distant sous le répertoire temporaire de l'agent, à `PowerShellUniversal/Repository`, avec les dossiers `Scripts` et `Modules`. Le dossier Modules du dépôt est ajouté au chemin des modules PowerShell distant. Pour une tâche de script, PowerShell Universal transfère le script de démarrage de la tâche vers le dossier Scripts distant et exécute la tâche par l'entremise du flux de communication à distance PowerShell gRPC. Ce transfert se fait à chaque exécution : le script de démarrage copié est supprimé une fois la tâche terminée. La console d'administration ne fournit pas d'action **Install on Agent** ni de paramètre **Keep run scripts on agents**. Lorsque l'environnement sélectionné utilise un environnement virtuel multi-pwsh, son paquet est importé avant l'exécution de la tâche. Ne présumez pas que des fichiers de serveur, des secrets ou des modules arbitraires installés en dehors de l'environnement virtuel sélectionné sont transférés à l'agent; provisionnez-les explicitement dans l'environnement ou sur l'ordinateur géré. ## PowerShell Universal Agent PowerShell Universal Agent est l'agent original basé sur Event Hub. Il exécute un script local ou une commande PowerShell directe après avoir reçu une invocation Event Hub via WebSockets. Utilisez-le lorsque vous avez besoin d'un flux de travail Event Hub existant; utilisez Devolutions Agent pour les nouveaux déploiements de tâches distantes. ### Configurer agent.json Créez `agent.json` après l'installation. Stockez-le sous `$env:ProgramData\PowerShellUniversal` pour un agent à l'échelle du système, ou sous `$env:AppData\PowerShellUniversal` pour un agent par utilisateur. {% code collapsedlinecount="10" %} ```json { "Connections": [ { "Url": "https://psu.contoso.com", "Hub": "eventHub", "AppToken": "", "ScriptPath": "script.ps1", "Description": "My agent" } ] } ``` {% endcode %} `Url` et `Hub` sont requis. Authentifiez-vous avec `AppToken` ou `UseDefaultCredentials`. `ScriptPath` est optionnel, car les Event Hubs peuvent invoquer directement des commandes PowerShell. Un chemin de script relatif est résolu à partir du répertoire de données de PowerShell Universal; utilisez un chemin absolu lorsque le script est stocké ailleurs. ### Envoyer des commandes Event Hub Utilisez `Invoke-PSUCommand` ou `Send-PSUEvent` pour invoquer l'Event Hub configuré. Pour des exemples spécifiques aux Event Hubs et les options d'invocation, consultez [Event Hubs](/powershell-universal/fr/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/fr/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.