So: Stellen Sie einen UiPath Agent bereit

Auf dieser Seite wird der gesamte Lebenszyklus eines Low-Code-UiPath-Agents über die CLI beschrieben: Erstellen Sie ein Gerüst auf der Festplatte, validieren, packen, veröffentlichen und stellen Sie ihn im Orchestrator bereit – bereit zur Ausführung als Auftrag. Es verwendet das Tool uip agent , das sich von uip codedagent (Python-basierte codierte Agents) unterscheidet.

Wenn Sie bereits mit der uip solution -Bereitstellung zufrieden sind, sollten Sie wissen, dass Agents ohne Lösungs-Wrapper bereitgestellt werden können. Der Befehl uip agent publish führt intern die Pipeline → Migrieren → Lösungspaket → Hochladen aus und uip agent deploy installiert das Ergebnis direkt. Sie müssen nie ein .uipx -Lösungsmanifest für ein Projekt mit einem einzelnen Agenten erstellen.

Der Lebenszyklus

init → validate → pack → publish → deploy → run

Jedes Verb erzeugt, was das nächste verbraucht:

Verb	Eingabe	Ausgabe	Anmeldung erforderlich
init	Zielverzeichnis	agent.json + Projektstruktur	Nein
validate	Projektverzeichnis	Migrierte Dateien auf Festplatte	Nein
pack	Projektverzeichnis	.uis Archiv	Nein
publish	Projektrichtung oder .uis	PackageVersionKey Im Orchestrator	Ja
deploy	PackageVersionKey	bereitgestellter Ordner + Release	Ja

Lokale Verben (init, validate, pack) erfordern keine aktive Sitzung und können in jeder Buildphase ausgeführt werden. Alles, was in den Orchestrator schreibt, benötigt zuerst uip login .

1. Gerüst

Erstellen Sie ein neues Agent-Projekt mit uip agent init:

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

Dadurch wird ein vollständiger eigenständiger Projektbaum geschrieben:

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/

Der Verzeichnisname wird zum Agentnamen; sie muss mit [a-zA-Z0-9_ -]+ übereinstimmen. Übergeben Sie --force um ein nicht leeres Verzeichnis zu überschreiben.

Verwenden Sie für Agents, die sich in einem Maestro-Flow befinden, stattdessen --inline-in-flow – es wird ein UUID-benannter Unterordner generiert, der nur agent.json und flow-layout.json enthält. Siehe init --inline-in-flow.

2. Autorenressourcen

Ein echten Agent benötigt normalerweise drei Arten von Ressourcen. Bearbeiten Sie agent.json direkt, oder verwenden Sie die strukturierten Bearbeitungsbefehle:

• Eingaben und Ausgaben – uip agent input add / uip agent output add für Schemaparameter.
• Tools – uip agent tool add für Integration Service-Connectors, Orchestrator-Prozesse, andere Agents, API-Workflows, Prozessorchestrierungsabläufe und IXP-Fähigkeiten.
• Kontexte – uip agent context add für RAG-Indexbindungen.
• Eskalationen – uip agent escalation add für Übergaben von Human-in-the-Loop.

# 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

Den vollständigen Flagsatz finden Sie auf den jeweiligen Referenzseiten. Bei jeder Bearbeitung bleiben agent.json und entry-points.json synchron.

3. Validieren

Führen Sie nach einer manuellen Bearbeitung von agent.json – oder nach einer Reihe strukturierter Bearbeitungen – uip agent validate aus:

uip agent validate ./invoice-agent

Die Validierung ist nur lokal (keine Anmeldung erforderlich) und führt eine statische Prüfung sowie die Schemamigrationspipeline aus. Bei Erfolg wird der migrierte Dateiinhalt auf den Datenträger zurückgeschrieben und das .agent-builder/ -Gerüst wird neu generiert. Bei einem Fehler erhalten Sie eine Liste von Fehlern mit Dateipfaden und Exitcode 1 – es wird nichts geschrieben.

Ausführen dieser Aktion in CI als Gate vor dem Veröffentlichungsschritt; Es erfasst die Klasse von Fehlern (ungültiges Modell, defektes messages[].contentTokens, fehlende required -Einträge in Schemas), die andernfalls die Veröffentlichung langsam fehlschlagen würden.

4. Packen (optional)

uip agent pack bündelt das Projekt in einem .uis -Archiv. Sie benötigen es nur, wenn:

• Sie möchten, dass ein Artefakt manuell geprüft oder archiviert wird.
• Sie planen, mit uip agent push für die interaktive Bearbeitung in Studio Web zu pushen.
• Ihre Pipeline verwendet einen separaten Build-Agent und Bereitstellungs-Agent und Sie möchten eine einzelne Datei dazwischen übergeben.

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

publish führt eine eigene interne Packpipeline aus, sodass Sie für einen direkten Ablauf „Erstellen und Bereitstellen“ diesen Schritt vollständig überspringen und das Projektverzeichnis direkt an publish übergeben können.

5. Auf dem Orchestrator veröffentlichen

uip agent publish verpackt das Projekt, migriert es zur erwarteten storageVersion, erstellt eine Lösung .zip und lädt sie in den Lösungsfeed des Mandanten hoch. Erfordert uip login.

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

Ausgabe:

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

PackageVersionKey ist das, was deploy verbraucht. Erfassen Sie es in Skripts:

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

Wann --direct verwendet werden sollte

Standardmäßig wird publish über die Lösungs-API hochgeladen. Das Flag --direct umgibt Lösungen und lädt jedes .nupkg direkt in den Paket-Feed des Orchestrator's hoch, wodurch ein Release pro Paket erstellt wird. Gehen Sie so vor, wenn:

• Der Lösungsbereitstellungspfad schlägt aus einem Plattformgrund fehl und Sie müssen die Blockierung aufheben.
• Sie möchten, dass ein Release sofort in einem bestimmten Ordner erstellt wird ( --folder-id übergeben).

Im --direct -Modus hat die Antwort kein PackageVersionKey; Das Äquivalent ist das Key pro Release in Releases[], das direkt mit uip agent run start verwendet werden kann.

6. Bereitstellen

uip agent deploy installiert und aktiviert das veröffentlichte Paket in einem Orchestrator-Ordner. Es steuert die vollständige Bereitstellungspipeline von Lösungen (Konfigurieren → Bereitstellen → Installieren → Bereitstellen → Aktivieren) und fragt jede Phase bis zum Terminal ab.

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

Ohne --folder-key erstellt die Bereitstellung automatisch einen Ordner (benannt nach --name) und außerdem:

1. Weist dem Ordner eine serverlose Maschinenvorlage auf Mandantenebene zu.
2. Gewährt einem zuweisbaren Benutzer die Rolle Automation User für den Ordner.

Bereitstellungsfehler werden als Warnungen angezeigt – die Bereitstellung ist weiterhin erfolgreich; Weisen Sie die Maschine und den Benutzer anschließend manuell zu.

So stellen Sie in einem vorhandenen Ordner bereit:

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

Suchen Sie Ordnerschlüssel mit uip or folders list --all.

Nur installieren und Aktivierung erzwingen

• --skip-activate wird nach der Installation angehalten; nützlich, wenn Sie die Bereitstellung in Orchestrator überprüfen möchten, bevor Sie den Agent für den Datenverkehr freigeben. Rufen Sie uip solution deploy activate später auf, um dies abzuschließen.
• --force-activate wird über eine vorhandene Bereitstellung mit demselben Konfigurationsschlüssel erneut aktiviert. Verwenden Sie dies, um eine laufende Bereitstellung durch eine neue Version zu ersetzen, ohne zuerst zu deinstallieren.

Timeout-Verhalten

--timeout (standardmäßig: 120 Sekunden) begrenzt jede Abrufphase. Bei Timeout beendet deploy 2 – Der Orchestrator kann die Bereitstellung trotzdem im Hintergrund abschließen; Führen Sie sie mit einem längeren Timeout erneut aus oder überprüfen Sie den Status in der Orchestrator-Benutzeroberfläche. Der Austrittscode 2 auf deploy ist eine domänenspezifische Wiederverwendung des Authentifizierungsfehler-Slots, ähnlich wie uip tm wait – siehe die deploy -Austrittscodes.

Vergleichen Sie diese mit Lösungsbereitstellung

Agents können zusammen mit anderen Projekten (Workflows, Testfälle) in einer .uipx -Lösung ausgeliefert werden, aber für ein Projekt mit einem einzelnen Agent ist der direkte Pfad kürzer und einfacher:

Einzelner Agent	Lösung für mehrere Projekte
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 Then uip solution deploy run …
Ordner automatisch erstellt und bereitgestellt	Ordner erstellt pro --folder-name; Bereitstellen über deploy config
Ein .uis -Artefakt	Ein .zip mit mehreren .nupkg

Den Agentenpfad auswählen, wenn der Agent eine eigenständige Einheit ist; Wählen Sie den Lösungspfad aus, wenn Sie einen Agent zusammen mit RPA-Workflows, Bibliotheken oder Testfällen mit gemeinsamen Ressourcen bereitstellen müssen. Siehe uip solution.

Vollständiges Pipeline-Skript

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

Folgen Sie uip agent run start , um einen Auftrag zu starten, oder mit einem Auswertungslauf – uip agent eval run start – um das Verhalten anhand eines Auswertungssatzes zu validieren, bevor die Bereitstellung als grün gilt.

Siehe auch

• uip agent Übersicht – jedes Verb im Agent-Tool.
• uip solution Übersicht – Lösungsbasierte Bereitstellung für Projekte mit mehreren Projekten.
• uip or jobs – Das zugrunde liegende Auftragsmodell, als das Agents ausgeführt werden.
• Authentifizierung – Sitzungen, Mandanten und das Präfix env. .
• Anleitung: Bereitstellung im Orchestrator von CI – CI-spezifische Authentifizierung, Zwischenspeicherung, Versionsheftung.