# 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](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

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

```bash
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"`):

```json
{
  "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**:

```json
{
  "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`](./uip-agent-validate.md) — run first to confirm the project is well-formed; suggested in upload-failure instructions.
- [`uip traces spans get`](./uip-traces.md) — inspect a debug run's trace after a non-successful state.

## See also

- [Authentication](./authentication.md), [Global options](./global-options.md), [Exit codes](./exit-codes.md).