Herramientas (complementos)

Arquitectura de herramientas en UiPath CLI, que cubre cómo los paquetes npm instalables amplían el host con nuevos comandos de nivel superior.

UiPath CLI es un pequeño host envuelto en un conjunto de herramientas instalables. Cada herramienta es un paquete npm ordinario que registra un comando de nivel superior (y sus subcomandos) con el host. Este es el concepto individual más importante para comprender por qué uip funciona de la forma en que lo hace: qué se instala automáticamente, qué no, cómo se mantienen sincronizadas las versiones y por qué uip --help muestra diferentes comandos en diferentes máquinas.

Host y herramientas

El host (@uipath/cli, el ejecutable uip ) solo posee un conjunto limitado de preocupaciones:

• Autenticación (uip login, uip logout, uip login status, uip login tenant …).
• Gestión de sesiones y credenciales.
• Ciclo de vida de la herramienta (uip tools list / search / install / update / uninstall).
• Habilidades para codificar agentes (uip skills install / update / uninstall).
• El puente del protocolo de contexto del modelo (uip mcp).
• Instalación de finalización de Shell (uip completion).
• Opciones globales (--output, --output-filter, --log-level, --log-file) y el sobre de salida JSON.

Todo lo que afecta a una superficie de UiPath (Orchestrator, soluciones, agentes, flujos, Maestro, empaquetado RPA, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI, flujo de trabajo de API, soluciones verticales, agentes codificados y Coded Apps) reside en un paquete npm independiente que el host carga bajo demanda.

Por qué la división:

• Cadencias de lanzamiento independientes : la herramienta Orchestrator puede enviarse sin volver a lanzar el host, y viceversa.
• Menor huella de instalación : un usuario que solo ejecuta procesos de prueba no necesita las herramientas Flow o Maestro en el disco.
• Contrato estable : las herramientas se comunican con el host a través de una interfaz programática versionada (registro de comandos, sobre de salida, contexto, telemetría), no a través de componentes internos compartidos.
• Inicio más rápido : el código de la herramienta se carga de forma diferida. El host hace lo mínimo para analizar argv e identificar la herramienta relevante, luego requiere el paquete de esa herramienta una vez.

La lista blanca de instalación automática

Un conjunto de herramientas propiedad de UiPath está en una lista blanca de instalación automática. El host los reconoce por su alias de comando y asigna el alias a un paquete npm:

Alias	Paquete	Nombre largo
or	@uipath/orchestrator-tool	Orchestrator (trabajos, carpetas, procesos, paquetes, máquinas, usuarios, roles, licencias, activos, colas, depósitos de almacenamiento, bibliotecas, desencadenadores, webhooks)
solution	@uipath/solution-tool	Solución
rpa	@uipath/rpa-tool	RPA (empaquetado, analizador y restauración de Studio)
agent	@uipath/agent-tool	Agente
codedagent	@uipath/codedagent-tool	Agente codificado
codedapp	@uipath/codedapp-tool	Aplicación codificada
maestro	@uipath/maestro-tool	Maestro
tm	@uipath/test-manager-tool	Test Manager
is	@uipath/integrationservice-tool	Integration Service
vss	@uipath/vertical-solutions-tool	Soluciones verticales
api-workflow	@uipath/api-workflow-tool	Flujo de trabajo de API
df	@uipath/data-fabric-tool	Data Fabric
insights	@uipath/insights-tool	Insights
traces	@uipath/traces-tool	Seguimientos
docsai	@uipath/docsai-tool	IA de Documentos
rpa-legacy	@uipath/rpa-legacy-tool	RPA heredado: contenedor solo para Windows uipcli.exe para los comandos de Studio que aún no se han migrado a la herramienta multiplataforma rpa (depurar, validar, buscar actividades, encontrar paquete, definición de tipo, paquete). Consulta uip rpa-legacy.
eval	@uipath/eval-tool	Evaluación de runtime de paquetes implementados en comparación con un proceso de Orchestrator: evaluadores, conjuntos de evaluación, evaluaciones, programaciones. Paquete independiente, no un subcomando de or.
platform	@uipath/platform-tool	Plataforma: licencias de tenant, paquetes de usuario, reglas de grupo, consumibles
admin	@uipath/admin-tool	Administrador: usuarios, grupos, cuentas de robot, aplicaciones externas, SMTP, autorización, restricción de IP, organizaciones, tenants, puertas de enlace VPN, catálogo de recursos, auditoría
gov	@uipath/gov-tool	Gobernanza: políticas de AOps, políticas de acceso, paquetes de cumplimiento
agenthub	@uipath/agenthub-tool	AgentHub: registros de servidor MCP, herramientas, agentes A2A remotos
ah	@uipath/automation-hub-tool	Automation Hub: ideas, proceso, taxonomía, usuarios
aops	@uipath/aops-tool	StudioAdmin AOps: conexiones, repositorios, proyectos, soluciones, procesos, ejecuciones
coder	@uipath/coder-tool	Coder: agente de codificación de IA (solo compilación de vista previa)
context-grounding	@uipath/context-grounding-tool	Contextualización: puente de Python
conversational	@uipath/conversational-tool	Conversacional: chat, agentes, historial de conversaciones, troncales
function	@uipath/function-tool	Funciones: crear, servir y publicar funciones JS/TS y Python
guardrails	@uipath/guardrails-tool	Barreras de seguridad: configuraciones de barreras de seguridad BYO, AI Trust Layer
ixp	@uipath/ixp-tool	Extracción y Procesamiento Inteligentes (IXP): procesamiento inteligente de documentos (proyectos, taxonomía, documentos, implementaciones)
llm-configuration	@uipath/llmgw-tool	Configuración de LLM: conexiones BYO LLM, AI Trust Layer. Ten en cuenta que el nombre del paquete (llmgw-tool) no coincide con el alias.
llm-gateway	@uipath/llm-gateway-tool	Puerta de enlace de LLM: enumera los modelos disponibles. Un paquete independiente de llm-configuration anterior, a pesar del nombre similar.
model-hub	@uipath/model-hub-tool	Model Hub: configuración de enrutamiento de puerta de enlace de LLM
pm	@uipath/pm-tool	Process Mining: aplicaciones, transformaciones, incorporación de datos
tasks	@uipath/tasks-tool	Tareas de Action Center: catálogos, comentarios, etiquetas, metadatos, datos

El host trata todo lo demás como si no fuera una herramienta. Esta tabla coincide exactamente con la TOOLS_WHITELIST actual: cada entrada tiene una página de referencia en este sitio. @uipath/flow-tool y @uipath/case-tool están ausentes deliberadamente: no están en la lista blanca de forma independiente, sino que son dependencias que @uipath/maestro-tool importa directamente para registrar sus ramas flow y case (consulta la nota sobre Acerca de UiPath CLI).

Qué se instala automáticamente y qué no

No hay nada preinstalado. Un nuevo npm install -g @uipath/cli pone solo el host en el disco.

Dos formas de instalar una herramienta en tu máquina:

1. Instalación automática en el primer uso. La primera vez que invocas un comando cuyo prefijo coincide con una entrada de la lista blanca, por ejemplo, uip or folders list antes de que se instale la herramienta Orchestrator, el host descarga e instala @uipath/orchestrator-tool desde npm y luego ejecuta tu comando. Las invocaciones posteriores utilizan la herramienta instalada directamente, por lo que la segunda ejecución es rápida.

2. Instalación explícita. Ejecuta uip tools install <alias> (o el nombre completo del paquete). Mismo estado final; más rápido en runtime porque no se necesita ningún paso de instalación automática. Consulta la referencia de herramientas de UIP.

Utiliza la instalación explícita en ejecutores de CI y para entornos sin conexión para que los tiempos de compilación sean deterministas y el primer comando de un trabajo no pague el coste de descarga único. Consulta la sección de instalación automática de la guía de instalación para ver la compensación completa.

Nota:

CI=true no deshabilita la instalación automática : esa variable no se consulta en ningún lugar de la ruta de instalación automática. La verdadera opción de exclusión es UIPATH_CLI_DISABLE_AUTOINSTALL=true, que desactiva por completo las instalaciones de herramientas implícitas, incluida la comprobación diaria de actualización por herramienta (consulta Resolución de versiones a continuación). Sin ella, la solución pragmática sigue siendo preinstalar las herramientas que sabes que utilizarás: la instalación automática no funciona cuando la herramienta ya está presente.

Las herramientas de terceros no son compatibles con UiPath CLI 1.x. El host se valida con la lista blanca en el momento de la instalación, por lo que uip tools install my-company/some-tool falla con un ValidationError. Un mecanismo de extensión público puede aparecer en una versión posterior; por ahora, uip solo carga las herramientas de la tabla anterior.

Dónde residen las herramientas en el disco

Las herramientas se instalan en una carpeta @uipath/ bajo el prefijo npm que posee el script de entrada de CLI:

• Si instalaste @uipath/cli globalmente (npm install -g @uipath/cli), las herramientas se instalan globalmente junto a él, en $(npm root -g)/@uipath/<tool-name>/.
• Si instalaste el CLI en un proyecto local (npm install @uipath/cli dentro de un paquete), las herramientas se instalan localmente junto a él, en el node_modules/@uipath/<tool-name>/ de ese proyecto.

En otras palabras, las herramientas siguen la CLI: CLI global, herramientas globales; CLI local, herramientas locales. Esto se gestiona automáticamente: no es necesario pasar ningún marcador de ámbito a uip tools install.

Ejecuta uip tools list para ver qué herramientas están instaladas y qué versión. Ejecuta npm root -g para encontrar la ruta de instalación global en tu máquina.

Resolución de versiones: herramientas que realizan un seguimiento del host

De forma predeterminada, cada versión de la herramienta se ancla a la línea major.minor de CLI. Al ejecutar uip tools install or con CLI 1.0.x, el host resuelve la última @uipath/orchestrator-tool cuya versión comienza con 1.0. y la instala. Al ejecutar uip tools update, cada herramienta instalada se actualiza a la última versión que aún se encuentra dentro de la línea major.minor de CLI.

Las consecuencias prácticas:

• Actualizar CLI a una nueva versión MENOR es una operación de dos pasos. Después de npm install -g @uipath/cli@1.1.0, ejecute uip tools update para llevar todas las herramientas instaladas a la versión 1.1.x línea.
• Anclar el CLI ancla de forma efectiva todas las herramientas. npm install -g @uipath/cli@1.0.3 y luego uip tools update produce un conjunto determinista de versiones de herramientas en cualquier máquina.
• El host y las herramientas envían cambios de protocolo compatibles juntos. Una herramienta creada para 1.1.x puede llamar al contrato interno que 1.0.x no conoce: permitir versiones mixtas de CLI+herramienta correría el riesgo de cargar una herramienta que el host no puede entender.

Puedes anular el valor predeterminado e instalar una versión específica de la herramienta explícitamente:

uip tools install orchestrator-tool@1.2.3
uip tools update --name @uipath/orchestrator-tool --version 1.2.5

Las compilaciones de vista previa no se seleccionan con una etiqueta de dist npm como @beta en el comando de instalación: esa sintaxis no existe. En cambio, el canal de lanzamiento en todo CLI es un ajuste de configuración, core.updateChannel, gestionado con uip config:

uip config set updateChannel preview   # opt into preview tool builds
uip tools install orchestrator-tool    # now resolves the preview line

uip config set updateChannel stable    # switch back

updateChannel es uno de stable (predeterminado) o preview; existe un tercer canal dev no anunciado para las compilaciones CLI publicadas desde main. Los comandos de vista previa dentro de una herramienta estable se etiquetan de forma independiente; consulta Control de versiones y estabilidad.

El CLI también se mantiene actualizado a sí mismo y a sus herramientas automáticamente. Una vez al día, el primer uip comando elegible busca una versión CLI más reciente en el canal configurado y se vuelve a ejecutar en él si existe (nunca cruza una nueva versión PRINCIPAL unattended); por separado, cada herramienta instalada se actualiza a la última versión en la propia línea de CLI la primera vez que la utilizas cada día. Ambas comprobaciones fallan al cerrarse en lugar de omitirse silenciosamente si no se pueden completar. Deshabilita ambos con UIPATH_CLI_DISABLE_VERSION_SYNC=true. Para congelar la línea de versión en lugar de realizar el seguimiento de "más reciente", fíjala con uip config set version <major.minor[.patch]> — consulta uip config para el contrato version/updateChannel exacto.

Consejo:

Para verificar qué versiones de herramientas hay en una máquina después de una implementación, uip tools list --output json imprime el nombre, la versión y el prefijo de comando de cada herramienta instalada. Compara esto con una instantánea en buen estado para detectar la deriva.

Cómo carga el host las herramientas

Cuando se ejecuta uip <alias> … :

1. El host lee argv, elimina los marcadores globales (--output, --log-level, etc.) e identifica el primer token sin marcador como un alias de herramienta potencial.
2. Si el alias coincide con una herramienta instalada, el host carga esa herramienta bajo demanda y le pide que registre sus subcomandos.
3. Si el alias está en la lista blanca pero la herramienta no está instalada, el host ejecuta la instalación automática (ver arriba) y luego va al paso 2.
4. Si el alias no está en la lista blanca y no es un comando de host reconocido, el host falla con "comando desconocido" e imprime el uso.

Ese es todo el modelo de carga. No hay manifiesto de complemento, no hay archivo de configuración de registro, no hay lista editable por el usuario. La lista blanca integrada en el paquete del host es la fuente de la verdad.

Qué leer a continuación

• Referencia de herramientas de UIP : sintaxis completa y ejemplos para cada subcomando uip tools .
• Instalar UiPath CLI : instala el host; las herramientas siguen a partir de ahí.
• Herramienta de control de la instalación automática : UIPATH_CLI_DISABLE_AUTOINSTALL y la solución alternativa previa a la instalación para CI.
• Gestionar herramientas y habilidades : flujos de trabajo cotidianos (actualización, anclar versiones, inspeccionar deriva).
• Habilidades : un sistema paralelo para enseñar a los agentes de codificación a utilizar uip. Las habilidades no son herramientas, y uip skills es un grupo de comandos independiente.
• Control de versiones y estabilidad : cómo se coordinan las versiones del host y la herramienta en semver.