> 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/it/config/agent.md). # Agent Configuri Devolutions Agent o l'agente Event Hub di PowerShell Universal per eseguire job e comandi su computer remoti. PowerShell Universal supporta due implementazioni di agente remoto. Utilizzi **Devolutions Agent** per le nuove distribuzioni. Si connette a PowerShell Universal tramite gRPC e supporta job remoti, gruppi di computer, comandi di PowerShell remoting e ambienti virtuali multi-pwsh. Il **PowerShell Universal Agent** resta disponibile per l'automazione basata su Event Hub. ## Devolutions Agent Devolutions Agent è l'agente consigliato per le nuove installazioni. Stabilisce una connessione gRPC in uscita e autenticata verso PowerShell Universal; non è necessario configurare PowerShell remoting tra il server e il computer gestito. Scarichi il programma di installazione per Windows dal [Devolutions Download Center](https://devolutions.net/download-center/). Per le distribuzioni in container, utilizzi l'immagine [`devolutions/powershell-universal-agent`](https://hub.docker.com/r/devolutions/powershell-universal-agent) da Docker Hub. ### Prerequisiti e connettività Installi Devolutions Agent sul computer che eseguirà i job. L'agente deve poter raggiungere l'endpoint gRPC di PowerShell Universal tramite HTTP/2. Nella configurazione di sviluppo predefinita si tratta della porta `5006`; in produzione utilizzi l'endpoint HTTPS. Ogni agente necessita di un ID agente univoco e stabile. Quando l'agente si connette, PowerShell Universal crea o aggiorna un record Computer di tipo **Agent**, lo contrassegna come online e aggiunge tag per il nome macchina, il sistema operativo, l'architettura, gli hub e le capacità. Utilizzi questi tag per indirizzare l'agente tramite i gruppi di computer. ### Creare un token app Crei un token app dedicato per ogni Devolutions Agent. Il token deve avere il ruolo integrato **Agent**. Questo ruolo è volutamente limitato alla registrazione dell'agente e non concede autorizzazioni per l'API di gestione, pertanto non riutilizzi un token di amministratore o di automazione. {% code collapsedlinecount="10" %} ```powershell Grant-PSUAppToken ` -IdentityName 'devolutions-agent-01' ` -Role 'Agent' ` -Description 'Devolutions Agent on production-01' ` -Expiry (Get-Date).AddYears(1) ``` {% endcode %} Memorizzi il token restituito come segreto. Lo ruoti prima della scadenza e lo sostituisca nella configurazione dell'agente. L'agente non può connettersi con un token mancante, non valido o privo del ruolo Agent. ### Configurare l'agente Il programma di installazione per Windows può abilitare la funzionalità **PowerShell Universal Agent** e raccogliere l'URL del server PowerShell Universal, il token app, l'ID agente e il nome visualizzato. L'agente può essere configurato anche in `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` accetta il valore del token oppure un riferimento `$secret:` risolto da PowerShell SecretManagement. `AgentId` è l'identificatore utilizzato per indirizzare l'agente. `DisplayName` è un nome descrittivo mostrato in PowerShell Universal. `Hubs` diventano tag computer **Hub**. `PowerShell` può selezionare una versione `multi-pwsh`, utilizzare un percorso eseguibile specifico oppure utilizzare Windows PowerShell. Per l'immagine container Linux, fornisca `PSU_SERVER_URL` e `PSU_APP_TOKEN`; entrambi sono necessari per abilitare l'integrazione 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 %} ### Eseguire job su un agente Dopo che l'agent compare in **Gestisci > Computer e gruppi > Computer**, crei un gruppo di computer i cui tag lo selezionino. Ad esempio, un agent configurato con `"Hubs": ["production"]` ha un tag `Hub` con il valore `production`; un gruppo di computer con il tag `production` seleziona quell'agent. Assegni il gruppo di computer a uno script o a una pianificazione e scelga se eseguire su **qualsiasi** computer corrispondente o su **tutti** i computer corrispondenti. È inoltre possibile invocare uno script su un singolo agente utilizzando il suo ID agente come coda. {% 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 %} Vengono selezionati solo gli agenti online che non sono in modalità di manutenzione. Un'invocazione di gruppo configurata per **All** crea un job per ogni agente corrispondente; **Any** seleziona un agente corrispondente. ### Eseguire comandi con Invoke-PSUCommand `Invoke-PSUCommand` è un alias di `Send-PSUEvent`. Utilizzi `-Computer` per eseguire su un ID agente specifico oppure `-ComputerGroup` per eseguire su ogni computer corrispondente di un gruppo. Il comando restituisce l'output della pipeline e scrive localmente i flussi remoti warning, information, verbose ed error. {% 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 %} Utilizzi `-Timeout` per consentire comandi di lunga durata. L'agente deve rimanere connesso per l'intera invocazione. ### Utilizzare ambienti virtuali multi-pwsh Per un ambiente di esecuzione isolato o in container con un ambiente virtuale abilitato, PowerShell Universal crea automaticamente il pacchetto dell'ambiente virtuale `multi-pwsh` selezionato e indica all'agente remoto di importarlo prima dell'avvio del job. L'agente ospita quindi il job con la versione di PowerShell e il nome dell'ambiente virtuale corrispondenti. Utilizzi questa funzionalità per distribuire i moduli richiesti da un job: 1. Crei o aggiorni l'ambiente virtuale in PowerShell Universal e vi installi i moduli richiesti. 2. Selezioni tale ambiente isolato o in container per lo script. 3. Indirizzi Devolutions Agent direttamente o tramite un gruppo di computer. L'importazione viene eseguita tramite `multi-pwsh venv import`. Non è necessario copiare manualmente i moduli sull'agente; mantenga la definizione dell'ambiente virtuale e i relativi moduli sotto la gestione di PowerShell Universal affinché l'agente riceva il pacchetto previsto. ### Che cosa trasferisce PowerShell Universal PowerShell Universal crea un repository remoto nella directory temporanea dell'agente in `PowerShellUniversal/Repository`, con le cartelle `Scripts` e `Modules`. La cartella Modules del repository viene aggiunta al percorso dei moduli PowerShell remoto. Per un job di script, PowerShell Universal trasferisce lo script di avvio del job nella cartella Scripts remota ed esegue il job tramite il flusso gRPC di PowerShell remoting. Questo trasferimento avviene per ogni esecuzione: lo script di avvio copiato viene rimosso al termine del job. La console di amministrazione non fornisce un'azione **Install on Agent** né un'impostazione **Keep run scripts on agents**. Quando l'ambiente selezionato utilizza un ambiente virtuale multi-pwsh, il relativo pacchetto viene importato prima dell'esecuzione del job. Non presuma che file arbitrari del server, segreti o moduli installati al di fuori dell'ambiente virtuale selezionato vengano trasferiti all'agente; li predisponga esplicitamente nell'ambiente o sul computer gestito. ## PowerShell Universal Agent Il PowerShell Universal Agent è l'agente originale basato su Event Hub. Esegue uno script locale o un comando PowerShell diretto dopo aver ricevuto un'invocazione Event Hub tramite WebSocket. Lo utilizzi quando necessita di un flusso di lavoro Event Hub esistente; utilizzi Devolutions Agent per le nuove distribuzioni di job remoti. ### Configurare agent.json Crei `agent.json` dopo l'installazione. Lo memorizzi in `$env:ProgramData\PowerShellUniversal` per un agente a livello di sistema oppure in `$env:AppData\PowerShellUniversal` per un agente per utente. {% code collapsedlinecount="10" %} ```json { "Connections": [ { "Url": "https://psu.contoso.com", "Hub": "eventHub", "AppToken": "", "ScriptPath": "script.ps1", "Description": "My agent" } ] } ``` {% endcode %} `Url` e `Hub` sono obbligatori. Si autentichi con `AppToken` o `UseDefaultCredentials`. `ScriptPath` è facoltativo perché gli Event Hub possono invocare direttamente comandi PowerShell. Un percorso script relativo viene risolto a partire dalla directory dati di PowerShell Universal; utilizzi un percorso assoluto quando lo script è memorizzato altrove. ### Inviare comandi Event Hub Utilizzi `Invoke-PSUCommand` o `Send-PSUEvent` per invocare l'Event Hub configurato. Per esempi specifici degli Event Hub e opzioni di invocazione, consulti [Event Hubs](/powershell-universal/it/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/it/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.