UiPath CLI - uip agent validate

uipath-cli

latest

false

UiPath CLI user guide

uip agent validate

Strictly and read-only validate a local agent project with `uip agent validate` before packing, publishing, or debugging.

uip agent validate is a strict, read-only check. It answers a single question: would Studio Web accept this directory as-is? It never writes any files. If the project's storage schema is behind, or if entry-points.json / bindings_v2.json have drifted from source, validate fails with a code pointing at uip agent refresh — the separate command that actually migrates files and regenerates derived artifacts.

Validate is local-only — no login required.

Synopsis

uip agent validate [path] [--path <path>] [--bindings-target <path>] [--inline-in-flow]
uip agent validate [path] [--path <path>] [--bindings-target <path>] [--inline-in-flow]

[path] and --path are mutually exclusive — passing both throws AgentValidateConflictingPath.

All uip agent validate invocations honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

Arguments

[path] (optional, default .) — Agent project directory. Must contain agent.json; standalone mode additionally requires entry-points.json and project.uiproj. Cannot be combined with --path.

Options

Flag	Default	Purpose
`--path <path>`	—	Alternative to the positional `[path]` argument. Cannot be combined with it.
`--bindings-target <path>`	`<projectDir>/bindings_v2.json`; for `--inline-in-flow`, the immediate parent directory's `bindings_v2.json` when it contains a `.flow` file	Path to the `bindings_v2.json` file to compare against. Mirrors the same option on `uip agent refresh`.
`--inline-in-flow`	off	Validate an inline agent inside a flow project. Skips the `entry-points.json` and `project.uiproj` checks.

Examples

# Validate the current directory
uip agent validate

# Validate a specific standalone project
uip agent validate ./my-agent

# Equivalent, using the flag form
uip agent validate --path ./my-agent

# Validate an inline agent (the flow-project subdirectory)
uip agent validate ./my-flow/<uuid> --inline-in-flow
# Validate the current directory
uip agent validate

# Validate a specific standalone project
uip agent validate ./my-agent

# Equivalent, using the flag form
uip agent validate --path ./my-agent

# Validate an inline agent (the flow-project subdirectory)
uip agent validate ./my-flow/<uuid> --inline-in-flow

What is checked

Standalone mode runs, in order:

Required files — agent.json, entry-points.json, project.uiproj.
agent.json structure and schema-version gate — agent.version must equal the CLI's current schema version (a newer project version fails with AgentValidationOutdated and tells you to upgrade uip; an older one tells you to run refresh). Also checks type === "lowCode", projectId is a UUID, settings.model / settings.engine / settings.mode present, metadata.storageVersion present, messages[] has at least [system, user].
messages[].contentTokens — each message's contentTokens array is re-derived from content (splitting on {{…}} / @{…}) and compared to what is on disk. Mismatches in count, type, or raw-string are errors. (Fixing drift here is refresh's job — validate only reports it.)
I/O schemas and input-variable references — inputSchema / outputSchema must each be { type: "object", properties: {…} }; every {{input.<key>}} reference in a message must resolve to a key declared in inputSchema.properties (a bare {{key}} without the input. prefix is rejected — the runtime leaves it as literal text).
Resources — both inline agent.resources and file-based resources/<Name>/resource.json entries. tool resources need a UUID id, name, type, and — when location is set — one of "solution" / "external", with properties.folderPath === "solution_folder" when the location is "solution" (or "" for --inline-in-flow). escalation and mcp resources need a UUID and a name. Folder naming is also checked: standalone resource folders must be named after the resource's name; inline resource folders must be named after the resource's id (case-insensitive).
Entry-points sync — entry-points.json → entryPoints[0].input / output must match agent.json's inputSchema / outputSchema (properties keys for both; required arrays for input only). Skipped when --inline-in-flow is set.
project.uiproj — ProjectType === "Agent". Skipped when --inline-in-flow is set.
flow-layout.json presence and parse (standalone only) — missing or malformed fails with instructions to run refresh.
Storage-version gate — the project's metadata.storageVersion must equal the latest known migration version; otherwise AgentValidationOutdated (upgrade uip, or run refresh if the project is the one that's behind).
Strict schema validation against the current Studio Web schemas.
IS connector tool resource presence (--inline-in-flow only) — every Integration Service connector tool node wired into the flow must have a matching resources/<id>/resource.json on disk.
Derived-files drift check — a dry run of the same generator refresh uses, comparing entry-points.json / bindings_v2.json against what would be regenerated. A referential-integrity failure (e.g. a tool referenced but not present as a resource) is a hard error; a content mismatch is reported as drift, both pointing at refresh to fix.

Static errors fail fast with exit code 1 before later steps run.

Data shape (--output json)

Valid (Code: "AgentValidation"):

{
  "Code": "AgentValidation",
  "Data": {
    "Status": "Valid",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-5.4",
    "StorageVersion": "47.0.0",
    "Validated": {
      "agent": true,
      "resources": 2,
      "evalSets": 0,
      "evaluators": 0
    }
  }
}
{
  "Code": "AgentValidation",
  "Data": {
    "Status": "Valid",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-5.4",
    "StorageVersion": "47.0.0",
    "Validated": {
      "agent": true,
      "resources": 2,
      "evalSets": 0,
      "evaluators": 0
    }
  }
}

Validated is an object breaking down what the strict schema pass checked — not a boolean. InlineInFlow: true is added for --inline-in-flow runs, and a Warnings array is added when the derived-files check produced non-fatal warnings.

Outdated (Code: "AgentValidationOutdated"):

{
  "Code": "AgentValidationOutdated",
  "Message": "Storage version 45.0.0 is outdated; latest is 47.0.0.",
  "Data": { "CurrentVersion": "45.0.0", "LatestVersion": "47.0.0" },
  "Instructions": "Run `uip agent refresh` to migrate."
}
{
  "Code": "AgentValidationOutdated",
  "Message": "Storage version 45.0.0 is outdated; latest is 47.0.0.",
  "Data": { "CurrentVersion": "45.0.0", "LatestVersion": "47.0.0" },
  "Instructions": "Run `uip agent refresh` to migrate."
}

Drift (Code: "AgentValidationDrift"):

{
  "Code": "AgentValidationDrift",
  "Message": "Derived artifacts are out of sync with source (1 issue(s))",
  "Data": { "Errors": ["bindings_v2.json: out of sync — tool \"InvoiceLookup\" binding changed"] },
  "Instructions": "Run `uip agent refresh` to regenerate entry-points.json and bindings_v2.json."
}
{
  "Code": "AgentValidationDrift",
  "Message": "Derived artifacts are out of sync with source (1 issue(s))",
  "Data": { "Errors": ["bindings_v2.json: out of sync — tool \"InvoiceLookup\" binding changed"] },
  "Instructions": "Run `uip agent refresh` to regenerate entry-points.json and bindings_v2.json."
}

Static/schema failure (Code: "AgentValidationFailed"):

{
  "Code": "AgentValidationFailed",
  "Message": "Validation failed with 2 error(s)",
  "Data": {
    "Errors": [
      "agent.json.settings.model: missing or empty",
      "messages[1].contentTokens: contentTokens has 3 entries but content requires 2. Rebuild contentTokens to match content."
    ]
  }
}
{
  "Code": "AgentValidationFailed",
  "Message": "Validation failed with 2 error(s)",
  "Data": {
    "Errors": [
      "agent.json.settings.model: missing or empty",
      "messages[1].contentTokens: contentTokens has 3 entries but content requires 2. Rebuild contentTokens to match content."
    ]
  }
}

uip agent init — scaffolds projects that validate cleanly by default.
uip agent refresh — the command that actually migrates and regenerates files; run it whenever validate points at it.
uip agent review — a scored quality pass, distinct from validate's pass/fail schema check.

Was this page helpful?

PREVIOUSinit

NEXTrefresh

Synopsis​

Arguments​

Options​

Examples​

What is checked​

Data shape (--output json)​

Related​

See also​