Procédures: déployer un agent UiPath

Cette page parcourt le cycle de vie complet d'un agent UiPath low-code à partir de la CLI: élaboration sur le disque, validation, compression, publication et déploiement dans Orchestrator — prêt à être exécuté sous forme de tâche. Il utilise l'outil uip agent , qui est différent de uip codedagent (agents codés basés sur Python).

Si vous êtes déjà à l'aise avec le déploiement de uip solution , l'élément clé à savoir est que les agents peuvent se déployer sans encapsuleur de solution. La commande uip agent publish exécute son propre pipeline pack → Migr → solution-pack → téléchargement en interne, et uip agent deploy installe directement le résultat. Vous n'avez jamais besoin de créer un manifeste de solution .uipx pour un projet à agent unique.

Le cycle de vie

init → validate → pack → publish → deploy → run

Chaque verbe produit ce que le suivant consomme:

Verbe	Entrée	Sortie	Connexion requise
init	Répertoire cible	agent.json + Arborescence du projet	Non (No)
validate	Répertoire du projet	fichiers disque migrés	Non (No)
pack	Répertoire du projet	.uis Archiver	Non (No)
publish	dir du projet ou .uis	PackageVersionKey Dans Orchestrator	Oui (Yes)
deploy	PackageVersionKey	dossier déployé + version	Oui (Yes)

Les verbes locaux (init, validate, pack) ne nécessitent pas une session active et peuvent s’exécuter dans n’importe quelle étape de création. Tout ce qui écrit dans Orchestrator nécessite d'abord uip login .

1. Élaboration

Créez un nouveau projet d'agent avec uip agent init:

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

Cela écrit une arborescence de projet autonome complète:

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/

Le nom du répertoire devient le nom de l’agent; il doit correspondre à [a-zA-Z0-9_ -]+. Transmettez --force pour écraser un répertoire non vide.

Pour les Agents qui résident dans un flux Maestro, utilisez --inline-in-flow à la place — cela génère un sous-dossier nommé par UUID contenant uniquement agent.json et flow-layout.json. Voir init --inline-in-flow.

2. Ressources d’auteur

Un agent réel a généralement besoin de trois types de ressources. Modifiez agent.json directement ou utilisez les commandes de modification structurées:

• Entrées et sorties - uip agent input add / uip agent output add pour les paramètres de schéma.
• Outils — uip agent tool add pour les connecteurs Integration Service, les processus Orchestrator, d'autres agents, les workflows d'API, les flux d'orchestration de processus et les compétences IXP.
• Contextes — uip agent context add pour les liaisons d'index RAG.
• Escalades — uip agent escalation add pour les transferts avec intervention humaine.

# 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

Consultez les pages de référence respectives pour l'ensemble complet d'indicateurs. Chaque modification aura pour effet de synchroniser agent.json et entry-points.json .

3. Valider

Après une modification manuelle vers agent.json — ou après une série de modifications structurées — exécutez uip agent validate:

uip agent validate ./invoice-agent

La validation est effectuée en local uniquement (aucune connexion requise) et exécute une vérification statique ainsi que le pipeline de migration du schéma. Si cela réussit, les contenus du fichier migré sont réécrits sur le disque et l’élaboration de .agent-builder/ est régénérée. En cas d'échec, vous obtenez une liste d'erreurs avec des chemins d'accès aux fichiers et le code de sortie 1 — rien n'est écrit.

Exécutez-le dans CI comme une passerelle avant l'étape de publication; il capture la classe d’erreurs (modèle non valide, messages[].contentTokens cassé, entrées required manquantes dans les schémas) qui échoueront lentement la publication.

4. Créer un package (facultatif)

uip agent pack regroupe le projet dans une archive .uis . Vous n'en avez besoin que si:

• Vous souhaitez qu’un artefact soit inspecté manuellement ou archivé.
• Vous prévoyez de transmettre à Studio Web avec uip agent push pour des modifications interactives.
• Votre pipeline utilise un agent de développement et un agent de déploiement distincts, et vous souhaitez transmettre un seul fichier entre eux.

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

publish exécute son propre pipeline de paquets interne. Ainsi, pour un flux de « création et de déploiement» direct, vous pouvez ignorer entièrement cette étape et transmettre directement le répertoire du projet à publish .

5. Publier sur Orchestrator

uip agent publish compresse le projet, le migre vers le storageVersion attendu, produit une solution .zip et la charge dans le flux de solution du locataire. Nécessite uip login.

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

Sortie :

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

Le PackageVersionKey est ce que deploy consomme. Capturez-le dans des scripts:

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

Quand utiliser --direct

Par défaut, publish sont téléchargés via l'API Solutions. L'indicateur --direct contourne les Solutions et télécharge chaque .nupkg directement dans le flux de packages d'Orchestrator, créant un Release par package. Utilisez cette option lorsque dans les cas suivants:

• Le chemin de déploiement des solutions échoue pour une raison de la plateforme et vous devez le débloquer.
• Vous souhaitez qu’une version soit créée immédiatement dans un dossier spécifique (passez --folder-id).

En mode --direct , la réponse n'a pas de PackageVersionKey; l'équivalent est le package par version Key dans Releases[], qui est directement utilisable avec uip agent run start.

6. Déployer

uip agent deploy installe et active le package publié dans un dossier Orchestrator. Il entraîne le pipeline de déploiement complet des solutions (configurer → déployer → installer → enregistrer → activer) et interroge chaque phase au terminal.

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

Sans --folder-key, le déploiement crée automatiquement un dossier (nommé par --name) et aussi:

1. Affecte un modèle de machine sans serveur au niveau du locataire au dossier.
2. Accorde à un utilisateur attribuable le rôle Automation User par rapport au dossier.

Les échecs d'enregistrement font l'objet d'avertissements: le déploiement réussit toujours; affecter manuellement la machine et l'utilisateur par la suite.

Pour déployer dans un dossier existant:

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

Recherchez des clés de dossier avec uip or folders list --all.

Installer uniquement et activer de force

• --skip-activate s’arrête après l’installation; utile si vous souhaitez examiner le déploiement dans Orchestrator avant de publier l’agent sur le trafic. Appelez uip solution deploy activate ultérieurement pour la finaliser.
• --force-activate se réactive sur un déploiement existant avec la même clé de configuration. Utilisez cette option pour remplacer un déploiement en cours par une nouvelle version sans désinstaller au préalable.

Comportement du délai d’expiration

--timeout (par défaut 120 secondes) limite chaque phase d'interrogation. Au moment du délai d'expiration, deploy quitte 2 — Orchestrator peut toujours terminer le déploiement en arrière-plan; réexécutez avec un délai d’expiration plus long, ou vérifiez le statut dans l’interface utilisateur d’Orchestrator. Le code de sortie 2 sur deploy est une réutilisation spécifique au domaine de l'emplacement d'erreur d'authentification, analogue à uip tm wait — voir les codes de sortiedeploy .

Contrairement au déploiement de la solution

Les agents peuvent être livrés dans une .uipx solution avec d'autres projets (workflows, cas de test), mais pour un projet à agent unique, le chemin direct est plus court et plus simple:

Agent unique	Solution multi-projets
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 Puis (Then) uip solution deploy run …
Dossier créé automatiquement + enregistré	Dossier créé par --folder-name; enregistrement via deploy config
Un artefact .uis	Un .zip contenant plusieurs .nupkg

Choisissez le chemin de l'agent lorsque l'agent est une unité autonome; choisissez le chemin de la solution lorsque vous devez expédier un agent avec des workflows RPA, des bibliothèques ou des cas de test qui partagent des ressources. Voir uip solution.

Script complet prêt pour le pipeline

#!/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

Suivez avec uip agent run start pour démarrer une tâche, ou avec une exécution d'évaluation — uip agent eval run start — pour valider le comportement par rapport à un ensemble d'évaluation avant que le déploiement ne soit considéré comme vert.

Voir également

• Vue d’ensemble deuip agent — chaque verbe dans l’outil d’agent.
• Vue d'ensemble deuip solution — Déploiement basé sur une solution pour les projets multi-projets.
• uip or jobs — le modèle de tâche sous-jacent sous lequel les agents s'exécutent.
• Authentification : sessions, locataires et préfixe env. .
• Procédures: déployer dans Orchestrator depuis CI — Authentification spécifique à CI, mise en cache, épinglage de version.