Tutorial: implementar un agente de UiPath

Esta página recorre el ciclo de vida completo de un agente de UiPath de código bajo desde CLI: andamio en disco, validación, empaquetado, publicación e implementación en Orchestrator, listo para ejecutarse como trabajo. Utiliza la herramienta uip agent , que es distinta de uip codedagent (agentes codificados basados en Python).

Si ya te sientes cómodo con la uip solution implementación, lo más importante que debes saber es que los agentes pueden implementarse sin un envoltorio de solución. El comando uip agent publish ejecuta su propio paquete → migrar → solution-pack → cargar proceso internamente, e uip agent deploy instala el resultado directamente. Nunca necesitarás crear un manifiesto de solución .uipx para un proyecto de agente único.

El ciclo de vida

init → validate → pack → publish → deploy → run

Cada verbo produce lo que consume el siguiente:

Verbo	Entrada	Salida	Se requiere inicio de sesión
init	directorio de destino	agent.json + árbol del proyecto	No
validate	directorio del proyecto	archivos migrados en el disco	No
pack	directorio del proyecto	.uis Archivar	No
publish	directorio del proyecto o .uis	PackageVersionKey En Orchestrator	Sí
deploy	PackageVersionKey	carpeta implementada + versión	Sí

Los verbos locales (init, validate, pack) no requieren una sesión activa y pueden ejecutarse en cualquier etapa de compilación. Todo lo que escribe en Orchestrator necesita uip login primero.

1. Andamio

Crea un nuevo proyecto de agente con uip agent init:

uip agent init ./invoice-agent \
  --model gpt-4o-2024-11-20 \
  --system-prompt "You are an invoice triage agent."

Esto escribe un árbol de proyecto independiente completo:

invoice-agent/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/<semantic>.json
    evaluators/<trajectory>.json
    eval-sets/evaluation-set-default.json
  features/
  resources/

El nombre del directorio se convierte en el nombre del agente; debe coincidir [a-zA-Z0-9_ -]+ Pasa --force para sobrescribir un directorio no vacío.

Para los agentes que viven dentro de un flujo de Maestro, utiliza --inline-in-flow en su lugar: genera una subcarpeta con nombre UUID que contiene solo agent.json y flow-layout.json. Consulta init --inline-in-flow.

2. Recursos de autor

Un agente real suele necesitar tres tipos de recursos. Edita agent.json directamente o utiliza los comandos de edición estructurados:

• Entradas y salidas : uip agent input add / uip agent output add para parámetros de esquema.
• Herramientas : uip agent tool add para conectores de Integration Service, procesos de Orchestrator, otros agentes, flujos de trabajo de API, flujos de Process Orchestration y habilidades de Extracción y Procesamiento Inteligentes (IXP).
• Contextos : uip agent context add para vinculaciones de índice RAG.
• Escaladas : uip agent escalation add para transferencias con intervención humana.

# Add an input parameter
uip agent input add invoicePath --type string \
  --description "Path to the invoice PDF"

# Add an output parameter
uip agent output add verdict --type string

# Add a RAG context bound to an index
uip agent context add invoiceKnowledge --index invoices-kb

# Add a Slack integration tool
uip agent tool add notify --type integration \
  --connector uipath-slack --object-name message

Consulta las páginas de referencia respectivas para ver el conjunto completo de marcadores. Cada edición mantiene sincronizados a agent.json y entry-points.json .

3. Validar

Después de cualquier edición manual de agent.json , o después de una ronda de ediciones estructuradas, ejecuta uip agent validate:

uip agent validate ./invoice-agent

Validar es solo local (no requiere inicio de sesión) y ejecuta un pase de comprobación estática más el proceso de migración de esquema. En caso de éxito, el contenido del archivo migrado se vuelve a escribir en el disco y se regenera el andamio .agent-builder/ . En caso de fallo, obtienes una lista de errores con rutas de archivo y código de salida 1 ; no se escribe nada.

Ejecuta esto en CI como una puerta antes del paso de publicación; detecta la clase de errores (modelo no válido, messages[].contentTokens roto, faltan required entradas en los esquemas) que de otro modo no se publicarían lentamente.

4. Paquete (opcional)

uip agent pack agrupa el proyecto en un archivo .uis . Solo lo necesitas si:

• Quieres que un artefacto se inspeccione manualmente o se archive.
• Planeas enviar a Studio Web con uip agent push para la edición interactiva.
• Tu proceso utiliza un agente de compilación y un agente de implementación independientes, y quieres pasar un único archivo entre ellos.

uip agent pack ./invoice-agent -d ./dist
# → ./dist/invoice-agent.uis

publish ejecuta su propio proceso de paquete interno, por lo que para un flujo directo de "creación e implementación", puedes omitir este paso por completo y pasar el directorio del proyecto a publish directamente.

5. Publicar en Orchestrator

uip agent publish empaqueta el proyecto, lo migra al storageVersion esperado, produce una solución .zip y la carga en la fuente de soluciones del tenant. Requiere uip login.

uip agent publish ./invoice-agent --package-version 1.0.0

Salida:

{
  "Code": "AgentPublish",
  "Data": {
    "Status": "Published successfully",
    "Name": "invoice-agent",
    "Version": "1.0.0",
    "PackageVersionKey": "a1b2c3d4-0000-0000-0000-000000000050"
  }
}

El PackageVersionKey es lo que consume deploy . Captúralo en scripts:

PVK=$(uip agent publish ./invoice-agent \
  --package-version 1.0.0 \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

Cuándo utilizar --direct

De forma predeterminada, publish carga a través de la API de soluciones. El marcador --direct omite Soluciones y carga cada .nupkg directamente a la fuente de paquetes de Orchestrator, creando un Release por paquete. Usa esto cuando:

• La ruta de implementación de soluciones está fallando por un motivo de plataforma y debe desbloquearla.
• Quieres que se cree una versión inmediatamente en una carpeta específica (paso --folder-id).

En modo --direct , la respuesta no tiene PackageVersionKey; el equivalente es el Key por versión en Releases[], que se puede utilizar directamente con uip agent run start.

6. Implementar

uip agent deploy instala y activa el paquete publicado en una carpeta de Orchestrator. Impulsa el proceso completo de implementación de soluciones (configurar → implementar → instalar → aprovisionar → activar) y sondea cada fase al terminal.

uip agent deploy "$PVK" --name invoice-agent

Sin --folder-key, la implementación crea automáticamente una carpeta (nombrada por --name) y también:

1. Asigna una plantilla de máquina sin servidor en el nivel de tenant a la carpeta.
2. Otorga a un usuario asignable el rol Automation User en la carpeta.

Los fallos de aprovisionamiento aparecen como advertencias: la implementación sigue teniendo éxito; asignar la máquina y el usuario manualmente después.

Para implementar en una carpeta existente:

uip agent deploy "$PVK" --folder-key <folder-guid> --name invoice-agent

Buscar claves de carpeta con uip or folders list --all.

Solo instalar y activar de forma forzada

• --skip-activate se detiene después de la instalación; útil si quieres revisar la implementación en Orchestrator antes de liberar el agente al tráfico. Llama a uip solution deploy activate más tarde para completarlo.
• --force-activate se reactiva sobre una implementación existente en la misma clave de configuración. Utilízalo para reemplazar una implementación en ejecución por una nueva versión sin desinstalar primero.

Comportamiento del tiempo de espera

--timeout (predeterminado: 120 segundos) limita cada fase de sondeo. En el tiempo de espera, deploy sale de 2 : Orchestrator aún puede completar la implementación en segundo plano; volver a ejecutar con un tiempo de espera más largo o comprobar el estado en la interfaz de usuario de Orchestrator. El código de salida 2 en deploy es una reutilización específica del dominio de la ranura de error de autenticación, análoga a uip tm wait — consulta los códigos de salidadeploy .

Contraste con implementación de soluciones

Los agentes pueden enviarse dentro de una solución .uipx junto con otros proyectos (flujos de trabajo, casos de prueba), pero para un proyecto de agente único, la ruta directa es más corta y simple:

Agente único	Solución multiproyecto
uip agent publish ./my-agent --package-version 1.0.0	uip solution pack ./my-solution ./dist --version 1.0.0
uip agent deploy <PackageVersionKey>	uip solution publish ./dist/my-solution.1.0.0.zip Entonces uip solution deploy run …
Carpeta creada automáticamente + aprovisionada	Carpeta creada por --folder-name; aprovisionamiento a través de deploy config
Un artefacto .uis	Uno .zip que contiene varias .nupkg

Elige la ruta del agente cuando el agente es una unidad independiente; elige la ruta de la solución cuando necesites enviar un agente junto con flujos de trabajo de RPA, bibliotecas o casos de prueba que comparten recursos. Consulta uip solution.

Script completo listo para el proceso

#!/usr/bin/env bash
set -euo pipefail

AGENT_DIR="./invoice-agent"
VERSION="${AGENT_VERSION:-1.0.0}"

# 1. Auth (External App in CI)
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

# 2. Validate locally — fail fast before uploading
uip agent validate "$AGENT_DIR"

# 3. Publish
PVK=$(uip agent publish "$AGENT_DIR" \
  --package-version "$VERSION" \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

# 4. Deploy
uip agent deploy "$PVK" \
  --name "invoice-agent-${ENVIRONMENT}" \
  --timeout 300

Sigue con uip agent run start para iniciar un trabajo, o con una ejecución de evaluación ( uip agent eval run start ) para validar el comportamiento en comparación con un conjunto de evaluación antes de que la implementación se considere verde.

Ver también

• uip agent descripción general : cada verbo en la herramienta del agente.
• Información generaluip solution : implementación basada en soluciones para proyectos de varios proyectos.
• uip or jobs : el modelo de trabajo subyacente en el que se ejecutan los agentes.
• Autenticación : sesiones, tenants y el prefijo env. .
• Tutorial: implementar en Orchestrator desde CI : autenticación específica de CI, caché, fijación de versiones.