UiPath CLI - How-to: deploy a UiPath Agent

uipath-cli

latest

false

UiPath CLI user guide

How-to: deploy a UiPath Agent

Scaffold, refresh, validate, and ship a low-code UiPath Agent to Orchestrator using the `uip agent` and `uip solution` tools.

This page walks through the full lifecycle of a low-code UiPath Agent from the CLI: scaffold it on disk, keep it in sync, validate and review it, then ship it to Orchestrator using uip solution. It uses the uip agent tool, which is distinct from uip codedagent (Python-based coded agents).

uip agent has no pack, publish, or deploy command of its own — an agent project is always shipped as part of a solution. uip agent init handles that automatically: it auto-registers the new project into a surrounding solution's .uipx, or scaffolds a parent <Name>Solution when run outside one.

The lifecycle

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

Verb	Input	Output	Login required
`agent init`	target directory	agent project tree, registered into a solution	No
`agent refresh`	project directory	migrated files + regenerated `entry-points.json`/`bindings_v2.json`	No
`agent validate`	project directory	pass/fail — writes nothing	No
`agent review`	project directory	score, grade, issues	No
`solution pack`	solution directory	`.zip` package	No
`solution publish` / `solution upload`	packed `.zip` or solution dir	published package version / Studio Web solution	Yes
`solution deploy run`	published package	deployed folder + release	Yes

Local verbs (agent init, agent refresh, agent validate, agent review, solution pack) do not require an active session. Everything that talks to Studio Web or Orchestrator needs uip login first.

1. Scaffold

Create a fresh agent project with uip agent init:

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

Run from inside an existing solution directory to register the project into it, or run it standalone — a parent InvoiceAgentSolution/ is scaffolded automatically and the project is nested inside it. Pass --skip-solution-registration to opt out of both behaviors.

This writes a full standalone project tree:

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

The directory name becomes the agent name; it must match [a-zA-Z0-9_ -]+. Pass --force to overwrite a non-empty directory.

For agents that live inside a Maestro flow, use --inline-in-flow instead — it generates a UUID-named subfolder containing only agent.json and flow-layout.json, with no solution auto-registration. See init --inline-in-flow.

2. Author resources

There is no dedicated CLI verb for adding tools, contexts, escalations, or I/O schema entries — author these by hand-editing agent.json directly (and, for file-based tool resources, resources/<name>/resource.json). uip agent tool list and uip agent memory are read/attach helpers, not general resource editors:

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

After any hand-edit to agent.json, move to step 3 — refresh regenerates the derived files these edits depend on.

3. Refresh and validate

Run uip agent refresh after every edit to agent.json: it applies pending schema migrations and regenerates entry-points.json / bindings_v2.json. This is the only command in the lifecycle that writes files.

uip agent refresh ./invoice-agent
uip agent refresh ./invoice-agent

Then run uip agent validate — strict and read-only, it answers "would Studio Web accept this directory as-is?" without writing anything:

uip agent validate ./invoice-agent
uip agent validate ./invoice-agent

Both are local-only (no login required). Run refresh then validate in CI as a gate before packing; together they catch the class of errors (invalid model, broken messages[].contentTokens, missing required entries in schemas, stale derived files) that would otherwise surface much later as an opaque upload failure.

4. Review

uip agent review runs a deterministic rule set for a scored quality verdict — distinct from validate's structural pass/fail:

uip agent review ./invoice-agent
uip agent review ./invoice-agent

Optionally record the grade for tracking over time with uip agent review-history add:

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

5. Debug (optional)

Before shipping, run the agent once against Studio Web with sample inputs using uip agent debug (requires login and a project.uiproj manifest):

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

6. Ship with uip solution

An agent project ships as part of the solution it was registered into in step 1. Pack and publish (or upload, for Studio Web) exactly as you would any other solution:

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

Then deploy to an Orchestrator folder:

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

Re-deploying the same solution to the same --folder-name does not update the existing deployment — deploy run always creates a new one. Use uip solution deploy upgrade with the deployment key from uip solution deploy list to move an existing deployment to a new package version in place.

Full pipeline-ready script

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

Follow with an evaluation run — uip agent eval run start — to validate behaviour against an evaluation set before the deploy is considered green.

Was this page helpful?

PREVIOUSRun tests in a pipeline

NEXTManage Orchestrator assets and queues

The lifecycle​

1. Scaffold​

2. Author resources​

3. Refresh and validate​

4. Review​

5. Debug (optional)​

6. Ship with uip solution​

Full pipeline-ready script​

See also​