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>] [--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

Flag	Default	Purpose
-i, --inputs <json>	{}	Input arguments as a JSON object, e.g. '{"input":"hello"}'. Must parse as a plain object.
--poll-interval <ms>	2000	Polling interval in milliseconds.
--timeout <seconds>	600 seconds (10 minutes)	Maximum seconds to wait for the run to finish.
--login-validity <minutes>	10	Minimum 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

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"
}

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

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."
}

Related

• 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

• Authentication, Global options, Exit codes.