# uip agent

> `uip agent` is the Agent tool: it scaffolds, configures, validates, packages, and operates **low-code agents** — the `agent.json`-driven projects authored in Agent Builder / Studio Web. Install it with `uip tools install agent`, or invoke `uip agent …` and let auto-install run. See [Tools (plugins)](./concepts-tools.md) for the install model and [uip tools](./uip-tools.md) for the command that manages tool installation.

`uip agent` is the Agent tool: it scaffolds, configures, validates, packages, and operates **low-code agents** — the `agent.json`-driven projects authored in Agent Builder / Studio Web. Install it with `uip tools install agent`, or invoke `uip agent …` and let auto-install run. See [Tools (plugins)](./concepts-tools.md) for the install model and [uip tools](./uip-tools.md) for the command that manages tool installation.

This tool is distinct from the **coded agent** tool (`uip codedagent`), which targets Python agents built with LangGraph / LlamaIndex / OpenAI Agents. `uip agent` only operates on low-code agent projects: a directory containing `agent.json`, `entry-points.json`, `project.uiproj`, an `evals/` tree, and `features/` / `resources/` folders.

## What a UiPath Agent is

A low-code agent is described declaratively by a single `agent.json` file — model, prompts, input/output schemas, tools, contexts, escalations, and settings. Supporting files describe the entry points that Studio Web uses to invoke the agent, the default evaluation set, and any RAG / HITL resources.

The typical lifecycle covered by `uip agent` is:

1. **Scaffold** a project on disk with `uip agent init`.
2. **Author**: update `agent.json` directly or via the resource-management verbs (`tool`, `context`, `escalation`, `input`, `output`, `eval`).
3. **Validate** the project (`uip agent validate`) — runs static checks and the schema-migration pipeline.
4. **Push** the project into Studio Web so it appears in the Agent Builder UI (`uip agent push`), or keep editing locally and **pack** it into a `.uis` archive (`uip agent pack`).
5. **Publish** the packed agent to Orchestrator as a solution package version (`uip agent publish`).
6. **Deploy** the published package to a folder (`uip agent deploy`) — this creates the folder, installs the process, provisions a serverless machine and robot user, and activates the deployment.
7. **Run** the deployed agent as a job (`uip agent run start`) and monitor it (`uip agent run status`, `uip agent run list`).
8. **Evaluate** the agent against an evaluation set (`uip agent eval run start`), review results (`uip agent eval run results`), and compare against a baseline (`uip agent eval run compare`).

Operations that round-trip a project to and from Studio Web use the `push` / `pull` pair and the `list` / `share` sharing verbs. File-level operations inside a Studio Web project are exposed through `uip agent file`.

## Verbs

| Command | Purpose |
|---|---|
| [init](./uip-agent-init.md) | Scaffold a new agent project on disk (standalone, or inline inside a flow project). |
| [config](./uip-agent-config.md) | Read or update keys in `agent.json` (`model`, `name`, `systemPrompt`, etc.). |
| [validate](./uip-agent-validate.md) | Static-check the project and run the schema-migration pipeline; write migrated files back. |
| [tool](./uip-agent-tool-manage.md) | Add, discover, connect, list, or remove agent tools (Integration Service / process / API workflow / etc.). |
| [context](./uip-agent-context-manage.md) | Add, list, or remove RAG context resources bound to index sources. |
| [escalation](./uip-agent-escalation-manage.md) | Add, list, or remove HITL / escalation resources. |
| [input](./uip-agent-io-manage.md#uip-agent-input) / [output](./uip-agent-io-manage.md#uip-agent-output) | Manage the agent's input and output schema parameters. |
| [eval](./uip-agent-eval.md) | Manage evaluators, evaluation sets, test cases, and evaluation runs. |
| [pack](./uip-agent-pack.md) | Bundle the project into a `.uis` archive. |
| [publish](./uip-agent-publish.md) | Pack and push the agent to Orchestrator as a solution package version. |
| [deploy](./uip-agent-deploy.md) | Install and activate a published package version in an Orchestrator folder. |
| [run](./uip-agent-run.md) | Start, inspect, and list agent jobs on Orchestrator. |
| [list](./uip-agent-list-share.md#uip-agent-list) | List solutions visible to the current user in Studio Web. |
| [pull](./uip-agent-push-pull.md#uip-agent-pull) | Download a solution from Studio Web as a `.uis` archive. |
| [push](./uip-agent-push-pull.md#uip-agent-push) | Import a local project into Studio Web. |
| [file](./uip-agent-file.md) | List, download, and upload files inside a Studio Web project. |
| [share](./uip-agent-list-share.md#uip-agent-share) | Grant, list, or revoke user/group access to a Studio Web solution. |

## Synopsis

```
uip agent <verb> [subverb] [arguments] [options]
```

Always `uip agent`, never `uip agents` or `uip a`. `agent` is the tool's `commandPrefix` (see `uip tools list`).

All `uip agent` verbs honor the four [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the shared [contract](./exit-codes.md).

## End-to-end flow

The minimal expected flow from zero to a running deployed agent:

```bash
# 1. Scaffold
uip agent init ./my-agent --model gpt-4o-2024-11-20

# 2. Validate (run after any edit to agent.json)
uip agent validate ./my-agent

# 3a. Iterate in Studio Web (optional)
uip agent push ./my-agent
# …edit in Studio Web, then pull back:
uip agent pull <solutionId> -d ./downloads --extract

# 3b. Or pack locally for inspection
uip agent pack ./my-agent -d ./dist

# 4. Publish to Orchestrator
uip agent publish ./my-agent --package-version 1.0.0
# → captures PackageVersionKey

# 5. Deploy to a folder (auto-creates folder + provisions machine and user)
uip agent deploy <PackageVersionKey> --name invoice-agent

# 6. Find the release, then run
uip agent run list --folder-id <FolderId>
uip agent run start <ReleaseKey> -i '{"input":"hello"}'
uip agent run status <JobId>

# 7. Evaluate (push must have happened first — eval runs against the cloud project)
uip agent eval run start --set default --path ./my-agent --wait
```

## Authentication

Every verb that talks to Studio Web or Orchestrator (`push`, `pull`, `list`, `share`, `publish`, `deploy`, `run *`, `eval run *`, `file *`) requires a valid CLI session. Run `uip login` first. See [Authentication](./authentication.md) for the session model and `--login-validity` behaviour.

Local-only verbs (`init`, `config`, `validate`, `pack`, `tool`, `context`, `escalation`, `input`, `output`, `eval add` / `eval set` / `eval evaluator`) operate purely on files and do not require a session.

## See also

- [Concepts: tools (plugins)](./concepts-tools.md) — the plugin model and version pinning.
- [Concepts: skills](./concepts-skills.md) — how agents surface as skills and how skills relate to tool resources.
- [Authentication](./authentication.md) — sessions, tenants, and folders.
- [Orchestrator: jobs](./uip-orchestrator-jobs.md) — the underlying job APIs that `uip agent run` delegates to.