UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

uip agent debug

Run a low-code agent against Studio Web with sample inputs and stream the result with `uip agent debug`.

uip agent debug runs a low-code agent end-to-end against Studio Web with the inputs you provide, polling until the run finishes and streaming state changes. Requires login.

The project must use a project.uiproj manifest — a project still on the older project.json layout fails fast with conversion instructions (packaging commands like uip solution pack/publish still accept project.json; only Studio-Web-bound commands like this one require the newer manifest).

Synopsis​

uip agent debug <project-path> [-i <json>] [--attachment <field=path>]... [--poll-interval <ms>] [--timeout <seconds>] [--login-validity <minutes>]
uip agent debug <project-path> [-i <json>] [--attachment <field=path>]... [--poll-interval <ms>] [--timeout <seconds>] [--login-validity <minutes>]

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

Arguments​

  • <project-path> (required) — Path to the agent project directory (containing agent.json).

Options​

FlagDefaultPurpose
-i, --inputs <json>{}Input arguments as a JSON object, e.g. '{"input":"hello"}'. Must parse as a plain object. For a job-attachment field, pass an existing Orchestrator attachment reference, {"ID": "<attachment-id>"}, or use --attachment to upload a local file.
--attachment <field=path>—Upload a local file into a job-attachment input field of agent.json. Repeatable. The field must be declared as {"$ref": "#/definitions/job-attachment"} in inputSchema. Repeat the same field only when its schema is an array of job-attachments. The path resolves from the current working directory, not from the agent project directory. Uploaded attachment IDs are returned in Data.Attachments.
--poll-interval <ms>2000Polling interval in milliseconds.
--timeout <seconds>600 seconds (10 minutes)Maximum seconds to wait for the run to finish.
--login-validity <minutes>10Minimum minutes remaining before token expiration required to proceed.

Examples​

uip agent debug ./my-agent -i '{"input":"hello"}'

uip agent debug ./my-agent --timeout 120 --poll-interval 5000

# Upload a local PDF into the job-attachment input field fileIn
uip agent debug ./my-agent --attachment fileIn=./invoice.pdf -i '{"question":"What is the total?"}'
uip agent debug ./my-agent -i '{"input":"hello"}'

uip agent debug ./my-agent --timeout 120 --poll-interval 5000

# Upload a local PDF into the job-attachment input field fileIn
uip agent debug ./my-agent --attachment fileIn=./invoice.pdf -i '{"question":"What is the total?"}'

An --attachment value for a field also present in --inputs overrides the --inputs value, and the command logs a warning. A required job-attachment input that has neither an --attachment nor an --inputs value also produces a warning.

Data shape (--output json)​

Success (Code: "AgentDebug"):

{
  "Code": "AgentDebug",
  "Data": {
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000401",
    "TraceId": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Successful",
    "Output": { "content": "hi there" }
  },
  "Instructions": "Debug run completed: Successful"
}
{
  "Code": "AgentDebug",
  "Data": {
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000401",
    "TraceId": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Successful",
    "Output": { "content": "hi there" }
  },
  "Instructions": "Debug run completed: Successful"
}

Output is present only when the run produced one; Info is present only when the service returned extra diagnostic info.

When the run uploads files with --attachment, Data.Attachments lists each upload:

{
  "Code": "AgentDebug",
  "Data": {
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000401",
    "TraceId": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Successful",
    "Output": { "answer": "1,234.00 USD" },
    "Attachments": [
      {
        "Field": "fileIn",
        "AttachmentId": "c3d4e5f6-0000-0000-0000-000000000002",
        "FileName": "invoice.pdf",
        "MimeType": "application/pdf",
        "Size": 48213
      }
    ]
  }
}
{
  "Code": "AgentDebug",
  "Data": {
    "JobKey": "a1b2c3d4-0000-0000-0000-000000000401",
    "TraceId": "b2c3d4e5-0000-0000-0000-000000000001",
    "State": "Successful",
    "Output": { "answer": "1,234.00 USD" },
    "Attachments": [
      {
        "Field": "fileIn",
        "AttachmentId": "c3d4e5f6-0000-0000-0000-000000000002",
        "FileName": "invoice.pdf",
        "MimeType": "application/pdf",
        "Size": 48213
      }
    ]
  }
}

To reuse an uploaded file in a later run without uploading it again, pass its reference in --inputs, for example '{"fileIn":{"ID":"c3d4e5f6-0000-0000-0000-000000000002"}}'.

Attachment errors — an invalid --attachment value (wrong field=path format, a field that is not a job-attachment input, a missing, empty, or directory path) fails before anything is uploaded or run, with Retry: "RetryWillNotFix". When Orchestrator refuses an upload, no debug job starts.

Non-successful terminal state — same Code: "AgentDebug", but returned as a failure (exit code 1) with Message: "Debug run <state>." and Instructions pointing at uip traces spans get <TraceId> to inspect the run.

Incompatible project manifest:

{
  "Result": "Failure",
  "ErrorCode": "invalid_argument",
  "Message": "...",
  "Instructions": "Convert the listed project(s) to a project.uiproj manifest before debugging: scaffold the accepted layout with 'uip api-workflow init <name>' inside the solution and move Workflow.json (plus entry-points.json and bindings_v2.json) into it, then remove the project.json-based entry from the .uipx. Note that 'uip solution pack' and 'uip solution publish' accept project.json — only Studio Web-bound commands require project.uiproj."
}
{
  "Result": "Failure",
  "ErrorCode": "invalid_argument",
  "Message": "...",
  "Instructions": "Convert the listed project(s) to a project.uiproj manifest before debugging: scaffold the accepted layout with 'uip api-workflow init <name>' inside the solution and move Workflow.json (plus entry-points.json and bindings_v2.json) into it, then remove the project.json-based entry from the .uipx. Note that 'uip solution pack' and 'uip solution publish' accept project.json — only Studio Web-bound commands require project.uiproj."
}
  • uip agent validate — run first to confirm the project is well-formed; suggested in upload-failure instructions.
  • uip traces spans get — inspect a debug run's trace after a non-successful state.

See also​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated