Tutorial: implementar un agente de UiPath

Andamie, actualice, valide y envíe un agente de UiPath de código bajo a Orchestrator utilizando las herramientas `uip agent` y `uip solution`.

Esta página recorre el ciclo de vida completo de un agente de UiPath de código bajo desde la CLI: andamio en el disco, mantenerlo sincronizado, validarlo y revisarlo, y luego enviarlo a Orchestrator utilizando uip solution. Utiliza la herramienta uip agent , que es distinta de uip codedagent (agentes codificados basados en Python).

uip agent no tiene dominio pack, publish o deploy propio: un proyecto de agente siempre se envía como parte de una solución. uip agent init lo gestiona automáticamente: registra automáticamente el nuevo proyecto en una solución circundante .uipx, o aplica andamios a una <Name>Solution principal cuando se ejecuta fuera de una.

El ciclo de vida

init → refresh → validate → review → (uip solution) pack → publish/upload → deploy

Verbo	Entrada	Salida	Se requiere inicio de sesión
agent init	directorio de destino	árbol de proyecto de agente, registrado en una solución	No
agent refresh	directorio del proyecto	archivos migrados + regenerados entry-points.json/bindings_v2.json	No
agent validate	directorio del proyecto	correcto/incorrecto: no escribe nada	No
agent review	directorio del proyecto	puntuación, calificación, incidencias	No
solution pack	directorio de soluciones	.zip Paquete	No
solution publish / solution upload	.zip empaquetado o directorio de solución	versión del paquete publicado/solución de Studio Web	Sí
solution deploy run	paquete publicado	carpeta implementada + versión	Sí

Los verbos locales (agent init, agent refresh, agent validate, agent review, solution pack) no requieren una sesión activa. Todo lo que hable con Studio Web u Orchestrator necesita uip login primero.

1. Andamio

Crea un nuevo proyecto de agente con uip agent init:

uip agent init ./invoice-agent \
  --model gpt-5.4 \
  --system-prompt "You are an invoice triage agent."

Ejecuta desde dentro de un directorio de soluciones existente para registrar el proyecto en él, o ejecútalo de forma independiente: un InvoiceAgentSolution/ principal se andamia automáticamente y el proyecto se anida en su interior. Introduzca --skip-solution-registration para excluirse de ambos comportamientos.

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, sin registro automático de soluciones. Consulta init --inline-in-flow.

2. Recursos de autor

No hay un verbo CLI dedicado para añadir herramientas, contextos, escaladas o entradas de esquema de E/S: créalas editándolas manualmente agent.json directamente (y, para recursos de herramientas basados en archivos, resources/<name>/resource.json). uip agent tool list y uip agent memory son ayudantes de lectura/adjunción, no editores de recursos generales:

# See what tools are already configured
uip agent tool list --path ./invoice-agent

# Attach a memory space for retrieval-augmented recall
uip agent memory add InvoiceHistory \
  --memory-space invoice-recall --folder-path Shared --path ./invoice-agent

# Check available guardrails before wiring one into agent.json
uip agent guardrails list

Después de cualquier edición manual en agent.json, ve al paso 3: la actualización regenera los archivos derivados de los que dependen estas ediciones.

3. Actualizar y validar

Ejecutar uip agent refresh después de cada edición en agent.json: aplica las migraciones de esquema pendientes y regenera entry-points.json / bindings_v2.json. Este es el único comando en el ciclo de vida que escribe archivos.

uip agent refresh ./invoice-agent

A continuación, ejecuta uip agent validate : estricto y de solo lectura, responde "¿aceptaría Studio Web este directorio tal como está?" sin escribir nada:

uip agent validate ./invoice-agent

Ambos son solo locales (no es necesario iniciar sesión). Ejecute refresh y luego validate en CI como puerta antes de empaquetar; juntos capturan la clase de errores (modelo no válido, messages[].contentTokens roto, entradas required faltantes en esquemas, archivos derivados obsoletos) que de otro modo surgirían mucho más tarde como un error de carga opaco.

4. Revisión

uip agent review ejecuta un conjunto de reglas deterministas para un veredicto de calidad puntuado, distinto del aprobado/fallo estructural de validate:

uip agent review ./invoice-agent

Opcionalmente, registra la calificación para el seguimiento a lo largo del tiempo con uip agent review-history add:

uip agent review-history add A --path ./invoice-agent

5. Depurar (opcional)

Antes del envío, ejecuta el agente una vez en Studio Web con entradas de muestra utilizando uip agent debug (requiere inicio de sesión y un manifiesto project.uiproj ):

uip agent debug ./invoice-agent -i '{"invoicePath":"/tmp/sample.pdf"}'

6. Envío con la solución uip

Un proyecto de agente se envía como parte de la solución en la que se registró en el paso 1. Empaqueta y publica (o carga, para Studio Web) exactamente como lo harías con cualquier otra solución:

# Pack the solution containing the agent project
uip solution pack ./InvoiceAgentSolution ./dist --version 1.0.0

# Publish the packed .zip to a tenant feed
uip solution publish ./dist/InvoiceAgentSolution_1.0.0.zip

A continuación, implementa en una carpeta de Orchestrator:

uip solution deploy run ./dist/InvoiceAgentSolution_1.0.0.zip \
  --folder-name invoice-agent-prod

Volver a implementar la misma solución en el mismo --folder-name no actualiza la implementación existente: deploy run siempre crea una nueva. Utiliza uip solution deploy upgrade con la clave de implementación de uip solution deploy list para mover una implementación existente a una nueva versión del paquete en su lugar.

Script completo listo para el proceso

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

AGENT_DIR="./invoice-agent"
SOLUTION_DIR="./InvoiceAgentSolution"
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. Refresh + validate locally - fail fast before packing
uip agent refresh "$AGENT_DIR"
uip agent validate "$AGENT_DIR"

# 3. Pack and publish the solution
uip solution pack "$SOLUTION_DIR" ./dist --version "$VERSION"
uip solution publish "./dist/InvoiceAgentSolution_${VERSION}.zip"

# 4. Deploy (or upgrade an existing deployment - see uip solution deploy upgrade)
uip solution deploy run "./dist/InvoiceAgentSolution_${VERSION}.zip" \
  --folder-name "invoice-agent-${ENVIRONMENT}"

Sigue 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.
• uip solution descripción general : empaquetar, publicar e implementar la solución en la que se encuentra un proyecto de agente.
• 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.