How-to: deploy a UiPath Agent

This page walks through the full lifecycle of a low-code UiPath Agent from the CLI: scaffold it on disk, validate, pack, publish, and deploy it to Orchestrator — ready to run as a job. It uses the uip agent tool, which is distinct from uip codedagent (Python-based coded agents).

If you are already comfortable with uip solution deployment, the key thing to know is that Agents can deploy without a Solution wrapper. The uip agent publish command runs its own pack → migrate → solution-pack → upload pipeline internally, and uip agent deploy installs the result directly. You never need to author a .uipx solution manifest for a single-agent project.

The lifecycle

init → validate → pack → publish → deploy → run

Each verb produces what the next one consumes:

Verb	Input	Output	Login required
init	target directory	agent.json + project tree	No
validate	project directory	migrated files on disk	No
pack	project directory	.uis archive	No
publish	project dir or .uis	PackageVersionKey in Orchestrator	Yes
deploy	PackageVersionKey	deployed folder + release	Yes

Local verbs (init, validate, pack) do not require an active session and can run in any build stage. Everything that writes to Orchestrator needs uip login first.

1. Scaffold

Create a fresh agent project with uip agent init:

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

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/

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. See init --inline-in-flow.

2. Author resources

A real agent usually needs three kinds of resources. Edit agent.json directly, or use the structured edit commands:

• Inputs and outputs — uip agent input add / uip agent output add for schema parameters.
• Tools — uip agent tool add for Integration Service connectors, Orchestrator processes, other agents, API workflows, Process Orchestration flows, and IXP skills.
• Contexts — uip agent context add for RAG index bindings.
• Escalations — uip agent escalation add for human-in-the-loop hand-offs.

# 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

See the respective reference pages for the full flag set. Every edit keeps agent.json and entry-points.json in sync.

3. Validate

After any hand-edit to agent.json — or after a round of structured edits — run uip agent validate:

uip agent validate ./invoice-agent

Validate is local-only (no login required) and runs a static-check pass plus the schema-migration pipeline. On success, migrated file contents are written back to disk and .agent-builder/ scaffolding is regenerated. On failure, you get a list of errors with file paths and exit code 1 — nothing is written.

Run this in CI as a gate before the publish step; it catches the class of errors (invalid model, broken messages[].contentTokens, missing required entries in schemas) that would otherwise fail publish slowly.

4. Pack (optional)

uip agent pack bundles the project into a .uis archive. You only need this if:

• You want an artifact to hand-inspect or archive.
• You plan to push to Studio Web with uip agent push for interactive editing.
• Your pipeline uses a separate build agent and deploy agent, and you want to pass a single file between them.

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

publish runs its own internal pack pipeline, so for a straight "build-and-deploy" flow you can skip this step entirely and pass the project directory to publish directly.

5. Publish to Orchestrator

uip agent publish packs the project, migrates it to the expected storageVersion, produces a solution .zip, and uploads it to the tenant's solution feed. Requires uip login.

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

Output:

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

The PackageVersionKey is what deploy consumes. Capture it in scripts:

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

When to use --direct

By default, publish uploads via the Solutions API. The --direct flag bypasses Solutions and uploads each .nupkg directly to Orchestrator's package feed, creating a Release per package. Use this when:

• The Solutions deployment path is failing for a platform reason and you need to unblock.
• You want a release created immediately in a specific folder (pass --folder-id).

In --direct mode the response has no PackageVersionKey; the equivalent is the per-release Key in Releases[], which is directly usable with uip agent run start.

6. Deploy

uip agent deploy installs and activates the published package in an Orchestrator folder. It drives the full Solutions deployment pipeline (configure → deploy → install → provision → activate) and polls each phase to terminal.

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

With no --folder-key, deploy auto-creates a folder (named by --name) and also:

1. Assigns a tenant-level serverless machine template to the folder.
2. Grants an assignable user the Automation User role on the folder.

Provisioning failures surface as warnings — the deployment still succeeds; assign the machine and user manually afterwards.

To deploy into an existing folder:

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

Find folder keys with uip or folders list --all.

Install-only and force-activate

• --skip-activate stops after install; useful if you want to review the deployment in Orchestrator before releasing the agent to traffic. Call uip solution deploy activate later to complete it.
• --force-activate re-activates over an existing deployment at the same configuration key. Use this to replace a running deployment with a new version without uninstalling first.

Timeout behaviour

--timeout (default 120 seconds) bounds each polling phase. On timeout, deploy exits 2 — Orchestrator may still complete the deployment in the background; re-run with a longer timeout, or check status in the Orchestrator UI. Exit code 2 on deploy is a domain-specific reuse of the authentication-error slot, analogous to uip tm wait — see the deploy exit codes.

Contrast with Solution deployment

Agents can ship inside a .uipx Solution alongside other projects (workflows, test cases), but for a single-agent project the direct path is shorter and simpler:

Single-agent	Multi-project Solution
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 …
Folder auto-created + provisioned	Folder created per --folder-name; provisioning via deploy config
One .uis artifact	One .zip containing multiple .nupkg

Pick the agent path when the agent is a standalone unit; pick the solution path when you need to ship an agent together with RPA workflows, libraries, or test cases that share resources. See uip solution.

Full pipeline-ready script

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

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

See also

• uip agent overview — every verb in the agent tool.
• uip solution overview — Solution-based deployment for multi-project projects.
• uip or jobs — the underlying job model that agents run as.
• Authentication — sessions, tenants, and the env. prefix.
• How-to: deploy to Orchestrator from CI — CI-specific auth, caching, version pinning.