@uipath/codedagent-tool

Coded Agent Tool

A command-line tool over uipath-python, installed as the codedagent tool in the uip CLI.

Features

• Automatic Python version detection
• Python path caching for improved performance
• Package installation verification
• A fixed whitelist of project commands forwarded to the Python uipath CLI

Commands

setup and review run natively in the CLI. Every other command is forwarded to the Python uipath CLI, which owns its own arguments and --help output.

The forwarded set is a fixed whitelist (WHITELISTED_COMMANDS in src/config.ts); anything outside it is rejected before it reaches Python:

$ uip codedagent exec --output json
{
  "Result": "ValidationError",
  "ErrorCode": "invalid_argument",
  "Message": "error: unknown command 'exec'",
  "Instructions": "Run 'uip --help' to list available commands.",
  "Retry": "RetryWillNotFix"
}

setup

Detects the Python installation, locates the uipath executable, and caches both.

uip codedagent setup [options]

Options:

• --force - Force re-detection of Python even if cached

If the current directory contains a .venv but no virtual environment is activated, setup stops and tells you to activate it first.

review

Reviews a coded agent project against the deterministic rule set. Returns a verdict (PASS/FAIL), score (0-100), grade (A+...F), and a list of issues.

uip codedagent review [path]

Options:

• --checks <categories> - Comma-separated rule categories to run (default: all). Known categories: evals, schema, tools, guardrails, code, general.

Project commands

Forwarded to the Python uipath CLI. Run uip codedagent <command> --help to see each command's own options.

Command	Description
add	Create a local resource.
debug	Debug the project interactively.
deploy	Pack and publish the project.
dev	Launch UiPath Developer Console.
eval	Run an evaluation set against the agent.
init	Initialize or regenerate the project.
invoke	Invoke an agent published in my workspace.
list-models	List available LLM models.
new	Scaffold a quick-start project.
pack	Pack the project.
publish	Publish the package.
pull	Pull remote project files from Studio Web.
push	Push local project files to Studio Web.
register	Register a local resource.
run	Execute the project.

The wrapper adds no flags of its own, and forwards the arguments you typed with one exception: --force is always stripped before forwarding, because the Python CLI does not accept it. It is a real option on setup, which runs natively.

Two forwarded commands need something set up first:

push requires a project id. Set UIPATH_PROJECT_ID in the environment, or in a .env file in the current directory:

echo "UIPATH_PROJECT_ID=<id>" >> .env
uip codedagent push

deploy -w / publish -w require a workspace scope. Publishing to the personal workspace calls Orchestrator GetCurrentUserExtended, so the login token needs either the umbrella OrchestratorApiUserAccess scope or the granular OR.Users.Read. Re-run uip login to pick it up, or publish to the tenant feed with -t / --tenant to skip the lookup entirely.

dev takes a positional terminal|web. It used to take an --interactive flag, which the Python CLI replaced with that positional in uipath 2.13.

Guards and exit codes

These checks run in the CLI wrapper before anything is forwarded to Python, so CI and the VS Code extension can branch on the result envelope rather than parsing a Python error:

Situation	Result	Exit code
Command outside the whitelist	ValidationError	3
Python not configured (setup never run)	ConfigError	1
push without UIPATH_PROJECT_ID	ConfigError	1
deploy / publish -w without the workspace scope	ConfigError	1
setup with an unactivated .venv	Failure	1

The Python-not-configured guard runs first, so it fires regardless of whether the command's other prerequisites are met.

Configuration

Static Configuration

The following settings are configured in the code:

Python Versions

Accepted versions: 3.14, 3.13, 3.12, 3.11

This is an allowlist, not a priority order. setup walks a list of candidate commands and takes the first one whose reported major.minor is accepted:

• Windows - python, python3, then python<version> for each accepted version, then py -<version> for each, then py.
• Linux/macOS - python<version> for each accepted version, then python3, then python.

So on Windows a bare python on PATH wins whenever its version is accepted, no matter which versions sit earlier in the list; the list order only sequences the python<version> and py -<version> fallbacks. On Linux/macOS those version-specific candidates come first, so there the list order does act as a preference.

Override with the PYTHON_TOOL_PYTHON_VERSIONS environment variable, which replaces the list entirely:

# Windows
set PYTHON_TOOL_PYTHON_VERSIONS=3.14,3.13,3.12,3.11

# Linux/macOS
export PYTHON_TOOL_PYTHON_VERSIONS=3.14,3.13,3.12,3.11

Cache File

setup writes ~/.uipath/.uipath-python-cache.json, shared with context-grounding-tool — the other uipath-python-bridge consumer. It stores:

• Detected Python path
• Python version
• Last validation timestamp
• Package name
• Resolved uipath executable path
• Installed package version

If the cached path no longer exists, setup re-detects automatically. The forwarded commands do not re-detect - they fail with a ConfigError pointing back at setup:

$ uip codedagent run --output json
{
  "Result": "ConfigError",
  "Message": "uipath executable not found. Please install it using 'pip install uipath' or 'uv add uipath'.",
  "Instructions": "Run 'uip codedagent setup' first to configure the environment. If you are using a virtual environment, activate it first.",
  "ErrorCode": "configuration_error",
  "Retry": "RetryWillNotFix"
}

Examples

# Detect Python and verify the uipath package is installed
uip codedagent setup

# Force re-detection
uip codedagent setup --force

# Scaffold a project, then initialize it
uip codedagent new my-agent
uip codedagent init

# Execute the project
uip codedagent run

# See a forwarded command's own options
uip codedagent run --help

# Launch the developer console in the browser
uip codedagent dev web

# Review a project, schema and eval rules only
uip codedagent review . --checks schema,evals

# Push local files to Studio Web
echo "UIPATH_PROJECT_ID=<id>" >> .env
uip codedagent push

# Publish to the tenant feed instead of the personal workspace
uip codedagent deploy --tenant

# Restrict Python detection to a single version
export PYTHON_TOOL_PYTHON_VERSIONS=3.13
uip codedagent setup