> 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/es/config/agent.md). # Agente Configure Devolutions Agent o el agente Event Hub de PowerShell Universal para ejecutar trabajos y comandos en ordenadores remotos. PowerShell Universal admite dos implementaciones de agente remoto. Use **Devolutions Agent** para los nuevos despliegues. Se conecta a PowerShell Universal mediante gRPC y admite trabajos remotos, grupos de ordenadores, comandos de PowerShell remoting y entornos virtuales multi-pwsh. El **PowerShell Universal Agent** sigue estando disponible para la automatización basada en Event Hub. ## Devolutions Agent Devolutions Agent es el agente recomendado para las nuevas instalaciones. Establece una conexión gRPC saliente y autenticada con PowerShell Universal; no es necesario configurar PowerShell remoting entre el servidor y el ordenador gestionado. Descargue el instalador de Windows desde el [Centro de descargas de Devolutions](https://devolutions.net/download-center/). Para despliegues en contenedores, utilice la imagen [`devolutions/powershell-universal-agent`](https://hub.docker.com/r/devolutions/powershell-universal-agent) de Docker Hub. ### Requisitos previos y conectividad Instale Devolutions Agent en el ordenador que ejecutará los trabajos. El agente debe poder acceder al punto de conexión gRPC de PowerShell Universal a través de HTTP/2. En la configuración de desarrollo predeterminada, es el puerto `5006`; en producción, use el punto de conexión HTTPS. Cada agente necesita un ID de agente único y estable. Cuando el agente se conecta, PowerShell Universal crea o actualiza un registro de ordenador con el tipo **Agent**, lo marca como en línea y añade etiquetas para su nombre de máquina, sistema operativo, arquitectura, hubs y capacidades. Use estas etiquetas para seleccionar el agente mediante grupos de ordenadores. ### Crear un token de aplicación Cree un token de aplicación dedicado para cada Devolutions Agent. El token debe tener el rol integrado **Agent**. Este rol está intencionadamente limitado al registro del agente y no concede permisos de la API de gestión, por lo que no reutilice un token de administrador o de automatización. {% code collapsedlinecount="10" %} ```powershell Grant-PSUAppToken ` -IdentityName 'devolutions-agent-01' ` -Role 'Agent' ` -Description 'Devolutions Agent on production-01' ` -Expiry (Get-Date).AddYears(1) ``` {% endcode %} Almacene el token devuelto como un secreto. Rótelo antes de que caduque y sustitúyalo en la configuración del agente. El agente no puede conectarse con un token ausente, no válido o que no tenga el rol Agent. ### Configurar el agente El instalador de Windows puede habilitar la función **PowerShell Universal Agent** y recoger la URL del servidor de PowerShell Universal, el token de aplicación, el ID del agente y el nombre para mostrar. El agente también se puede configurar en `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` acepta el valor del token o una referencia `$secret:` resuelta por PowerShell SecretManagement. `AgentId` es el identificador que se usa para seleccionar el agente. `DisplayName` es un nombre descriptivo que se muestra en PowerShell Universal. Los `Hubs` se convierten en etiquetas de ordenador **Hub**. `PowerShell` puede seleccionar una versión `multi-pwsh`, usar una ruta de ejecutable específica o usar Windows PowerShell. Para la imagen de contenedor de Linux, proporcione `PSU_SERVER_URL` y `PSU_APP_TOKEN`; ambos son obligatorios para habilitar la integración con 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 %} ### Ejecutar trabajos en un agente Una vez que el agente aparezca en **Gestionar > Equipos y grupos > Equipos**, cree un grupo de equipos cuyas etiquetas lo seleccionen. Por ejemplo, un agente configurado con `"Hubs": ["production"]` tiene una etiqueta `Hub` con el valor `production`; un grupo de equipos con la etiqueta `production` selecciona ese agente. Asigne el grupo de ordenadores a un script o a una programación y elija si se ejecuta en **cualquier** ordenador coincidente o en **todos** los ordenadores coincidentes. También puede invocar un script en un único agente usando su ID de agente como cola. {% 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 %} Solo se seleccionan los agentes en línea que no están en modo de mantenimiento. Una invocación de grupo configurada como **Todos** crea un trabajo para cada agente coincidente; **Cualquiera** selecciona un agente coincidente. ### Ejecutar comandos con Invoke-PSUCommand `Invoke-PSUCommand` es un alias de `Send-PSUEvent`. Use `-Computer` para ejecutar en un ID de agente concreto o `-ComputerGroup` para ejecutar en cada ordenador coincidente de un grupo. El comando devuelve la salida de la canalización y escribe localmente los flujos remotos de advertencia, información, detallado y 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 %} Use `-Timeout` para permitir comandos de ejecución más prolongada. El agente debe permanecer conectado durante toda la invocación. ### Usar entornos virtuales multi-pwsh Para un entorno de ejecución aislado o en contenedor con un entorno virtual habilitado, PowerShell Universal empaqueta automáticamente el entorno virtual `multi-pwsh` seleccionado e indica al agente remoto que lo importe antes de que comience el trabajo. A continuación, el agente aloja el trabajo con la versión de PowerShell y el nombre de entorno virtual correspondientes. Use esto para enviar los módulos que requiere un trabajo: 1. Cree o actualice el entorno virtual en PowerShell Universal e instale en él los módulos necesarios. 2. Seleccione ese entorno aislado o en contenedor para el script. 3. Apunte a Devolutions Agent directamente o a través de un grupo de ordenadores. La importación se ejecuta mediante `multi-pwsh venv import`. No es necesario copiar manualmente los módulos en el agente; mantenga la definición del entorno virtual y sus módulos bajo la gestión de PowerShell Universal para que el agente reciba el paquete esperado. ### Qué transfiere PowerShell Universal PowerShell Universal crea un repositorio remoto en el directorio temporal del agente, en `PowerShellUniversal/Repository`, con las carpetas `Scripts` y `Modules`. La carpeta Modules del repositorio se añade a la ruta de módulos de PowerShell remota. Para un trabajo de script, PowerShell Universal transfiere el script de inicio del trabajo a la carpeta Scripts remota y ejecuta el trabajo a través del flujo de PowerShell remoting de gRPC. Esta transferencia se realiza por ejecución: el script de inicio copiado se elimina cuando finaliza el trabajo. La consola de administración no proporciona una acción **Instalar en el agente** ni un ajuste **Mantener los scripts ejecutados en los agentes**. Cuando el entorno seleccionado usa un entorno virtual multi-pwsh, su paquete se importa antes de que se ejecute el trabajo. No asuma que se transfieren al agente ficheros arbitrarios del servidor, secretos o módulos instalados fuera del entorno virtual seleccionado; aprovisiónelos explícitamente en el entorno o en el ordenador gestionado. ## PowerShell Universal Agent El PowerShell Universal Agent es el agente original basado en Event Hub. Ejecuta un script local o un comando de PowerShell directo tras recibir una invocación de Event Hub a través de WebSockets. Úselo cuando necesite un flujo de trabajo de Event Hub existente; use Devolutions Agent para nuevos despliegues de trabajos remotos. ### Configurar agent.json Cree `agent.json` después de la instalación. Guárdelo en `$env:ProgramData\PowerShellUniversal` para un agente para todo el sistema o en `$env:AppData\PowerShellUniversal` para un agente por usuario. {% code collapsedlinecount="10" %} ```json { "Connections": [ { "Url": "https://psu.contoso.com", "Hub": "eventHub", "AppToken": "", "ScriptPath": "script.ps1", "Description": "My agent" } ] } ``` {% endcode %} `Url` y `Hub` son obligatorios. Autentíquese con `AppToken` o `UseDefaultCredentials`. `ScriptPath` es opcional porque los Event Hubs pueden invocar comandos de PowerShell directamente. Una ruta de script relativa se resuelve a partir del directorio de datos de PowerShell Universal; use una ruta absoluta cuando el script se almacene en otra ubicación. ### Enviar comandos de Event Hub Use `Invoke-PSUCommand` o `Send-PSUEvent` para invocar el Event Hub configurado. Para ver ejemplos y opciones de invocación específicos de Event Hub, consulte [Event Hubs](/powershell-universal/es/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/es/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.