> 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/inteligencia/ai-tools.md). # Herramientas de IA Exponga scripts de PowerShell como herramientas de IA en PowerShell Universal para que los utilicen agentes de IA y clientes MCP externos como GitHub Copilot, con autenticación, roles y entornos persi Las herramientas de IA le permiten exponer scripts de PowerShell como herramientas invocables para agentes de IA y clientes MCP externos. Son útiles cuando desea que un modelo recupere datos de PSU, ejecute una acción controlada o devuelva una salida estructurada a un prompt. Cada herramienta puede requerir autenticación, aplicar roles, elegir un entorno de ejecución y, opcionalmente, exponerse a través de MCP. ## Crear una herramienta de IA Vaya a **Compilación > IA > Herramientas** y seleccione **Crear herramienta de IA**. Seleccione el script que desea exponer y, a continuación, decida si la herramienta debe estar disponible: * Solo para los agentes de IA de PSU. * Tanto para agentes de IA como para clientes MCP, activando **MCP**. Si **Autenticado** está activado, el llamador debe haber iniciado sesión. Si también se asignan roles, el llamador debe tener al menos uno de esos roles. ### Descripción La descripción es una de las partes más importantes de la herramienta. Debe indicar al modelo: * Cuándo usar la herramienta. * Qué devuelve la herramienta. * Si la herramienta cambia el estado. * Cualquier expectativa importante sobre los parámetros. Las descripciones breves y concretas funcionan mejor. ### Parámetros Los parámetros se detectan automáticamente a partir del script de PowerShell. Se recomienda encarecidamente la ayuda basada en comentarios, ya que PSU la utiliza para crear mejores descripciones de herramientas y esquemas de parámetros. Este script de ejemplo es una buena herramienta de IA porque tiene parámetros claros y una salida predecible: ```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 ``` Expóngalo como herramienta: ```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 ``` Entre los cmdlets útiles se incluyen: * `Get-PSUAiTool` * `New-PSUAiTool` * `Set-PSUAiTool` * `Remove-PSUAiTool` Por ejemplo, revise las herramientas con: ```powershell Get-PSUAiTool Get-PSUAiTool -Name 'Get Running Processes' ``` ## Ejecutar herramientas en un entorno persistente De forma predeterminada, cada invocación de una herramienta de IA inicia un nuevo proceso de PowerShell. Para las herramientas que un agente de IA o un cliente MCP llaman con frecuencia, asigne un entorno local con **Runspaces persistentes** activado para reutilizar el proceso de PowerShell en ejecución y evitar el inicio de un proceso en cada llamada. 1. Cree o edite un entorno en **Gestionar > Entornos > Entornos**. 2. Active **Runspaces persistentes** y elija un valor adecuado para **Máx. de runspaces**. 3. Cree o edite la herramienta de IA. En la pestaña **Ejecución**, seleccione ese entorno en **Ejecutar en**. También puede asignar el entorno en la configuración con `-Environment`: ```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 ``` Cada invocación sigue creando su propio registro de trabajo, estado y salida en **Ejecutar > Trabajos**. Los entornos persistentes reutilizan el proceso de PowerShell y conservan el estado intencionado del runspace entre llamadas, mientras que la salida del trabajo y la cancelación permanecen aisladas en la invocación individual. La ejecución persistente se aplica a los entornos locales no mínimos que son aptos. Los entornos de agente remoto, comunicación remota de PowerShell, contenedor y Minimal siguen utilizando sus rutas de ejecución normales. Al reiniciar el entorno o el servidor de PSU se inicia un nuevo proceso persistente, por lo que el estado del runspace en memoria se restablece. Utilice entornos persistentes solo cuando la reutilización del estado sea intencionada y establezca el límite de runspaces según la concurrencia que requieran sus herramientas. ## Usar una herramienta en agentes de IA Dentro de un agente de IA, asigne nombres de herramientas directamente o utilice patrones con comodines como `ticket_*` o `*`. PSU solo pone a disposición de ese agente las herramientas coincidentes. El acceso basado en roles se aplica en ambos niveles: * El usuario debe tener permiso para ejecutar el agente. * El usuario también debe tener permiso para ejecutar la herramienta. Las ejecuciones de herramientas iniciadas por un agente aparecen como trabajos secundarios del trabajo de prompt de IA. Ejemplo de configuración de agente: ```powershell Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*') ``` ## Usar una herramienta a través de MCP Model Context Protocol (MCP) permite que clientes remotos como GitHub Copilot descubran y llamen a sus herramientas. PSU expone MCP en `/api/v1/mcp`. Solo las herramientas con **MCP** activado se muestran a los clientes MCP. Cuando se exponen a través de MCP, los nombres de las herramientas se normalizan para el cliente. Por ejemplo, los espacios y los puntos se convierten en guiones bajos. Cuando un cliente MCP se conecta, PSU filtra las herramientas visibles según: * Si la herramienta está marcada para MCP. * Si el llamador está autenticado cuando se requiere. * Si el llamador tiene al menos uno de los roles requeridos. Las llamadas realizadas a través de MCP aparecen como trabajos MCP en la página Trabajos. Si su cliente admite tokens de portador (bearer), proporcione un token de aplicación de PSU al conectarse al endpoint de MCP. ## Acceso en GitHub Copilot GitHub Copilot puede llamar a herramientas de PSU cuando VS Code está configurado para conectarse al servidor MCP de PSU. En este ejemplo, la herramienta envuelve un script que devuelve los procesos en ejecución: ```powershell Get-Process | Select-Object Name, Id ``` Con la extensión MCP activada, pulse `Ctrl+Shift+P` y ejecute `MCP: Add Server...`. Elija la opción HTTP e introduzca la URL del endpoint de MCP. De forma predeterminada, es `http://localhost:5000/api/v1/mcp`. El contenido resultante de `settings.json` será similar a esto: ```json "mcp": { "servers": { "PSU": { "url": "http://localhost:5000/api/v1/mcp" } } } ``` Si la conexión es correcta, Copilot muestra el número de herramientas disponibles. A continuación, puede pedirle a Copilot que utilice la herramienta de PSU. Por ejemplo: ``` Use the PSU tool to list the top 5 processes and create a PowerShell script that writes them to JSON. ``` Si también expone una herramienta que inicia un proceso, un prompt como este puede desencadenar esa acción: ``` Use the PSU tool to start a new process named calc. ``` Mantenga claras las descripciones de las herramientas y la ayuda de los parámetros para que Copilot pueda elegir la herramienta correcta sin necesidad de prueba y error. ## Nombrar las conexiones del servidor MCP PowerShell Universal identifica su servidor MCP como `Universal.Server` de forma predeterminada. Establezca un nombre distinto para cada entorno para que resulte fácil distinguir varias conexiones MCP de PowerShell Universal en Visual Studio Code. Configure el nombre en `appsettings.json`: ```json { "Mcp": { "ServerName": "Production PSU" } } ``` Para implementaciones en contenedores o basadas en variables de entorno, utilice: ``` Mcp__ServerName=Production PSU ``` Deje el valor en blanco o sin especificar para conservar el nombre predeterminado `Universal.Server`. ## Controlar el acceso a IA y MCP Utilice la configuración global de IA y MCP para limitar la capacidad del servidor y para desactivar las funciones de IA cuando no estén permitidas en un entorno. ### Limitar las solicitudes y los trabajos de MCP Vaya al **engranaje de Configuración > Automatización** para configurar: * **Solicitudes MCP por minuto**: las solicitudes que superen la tasa configurada se rechazan antes de su ejecución. * **Trabajos MCP concurrentes**: los trabajos MCP adicionales esperan hasta que haya una ranura de ejecución disponible. Un valor de `0` significa ilimitado. Los valores negativos no son válidos. Establezca ambos límites según la capacidad disponible para PowerShell Universal y los scripts expuestos como herramientas MCP. ### Desactivar las funciones de IA Seleccione **Desactivar funciones de IA** en el **engranaje de Configuración > Automatización** para desactivar las capacidades de IA del servidor. Esto oculta los agentes de IA, las herramientas de IA y el chat de IA en la consola de administración. Al desactivar la IA también se elimina el endpoint de MCP del registro de nuevos endpoints y se devuelve `404 Not Found` inmediatamente para las solicitudes a `/api/v1/mcp`. No es necesario reiniciar el servidor. Para los scripts de configuración, utilice `Set-PSUSetting -DisabledFeatures` para gestionar las funciones del producto desactivadas. `-Features` sigue siendo un alias para las configuraciones existentes. --- # 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/inteligencia/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.