UiPath CLI - uip agent init

uipath-cli

latest

false

UiPath CLI user guide

uip agent init

Syntax and options for `uip agent init`, which scaffolds a new low-code agent project on disk.

uip agent init scaffolds a new low-code agent project on disk. When run inside a solution directory, the project is auto-registered in the surrounding solution's .uipx. When run outside any solution, a parent <name>Solution is scaffolded automatically and the agent project is nested inside it — pass --skip-solution-registration to opt out of both behaviors and get a bare, unregistered project tree.

Two scaffolding modes are available:

Standalone (default) — a full agent project tree with agent.json, entry-points.json, project.uiproj, flow-layout.json, an evals/ tree (with a default eval set, semantic evaluator, and trajectory evaluator), plus empty features/ and resources/ directories.
Inline-in-flow (--inline-in-flow) — a UUID-named subdirectory inside an existing flow project containing agent.json and an empty flow-layout.json, with empty evals/eval-sets/, features/, and resources/ folders. No entry-points.json or project.uiproj, and no solution auto-registration. The flow's inline agent node must reference the generated projectId.

Synopsis

uip agent init <path> [--conversational] [--model <model>] [--system-prompt <prompt>] [--force] [--skip-solution-registration] [--inline-in-flow]
uip agent init <path> [--conversational] [--model <model>] [--system-prompt <prompt>] [--force] [--skip-solution-registration] [--inline-in-flow]

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

Arguments

<path> (required) — Target directory for the agent project (relative or absolute). The directory name becomes the agent name in standalone mode; it must match [a-zA-Z0-9_ -]+. When --inline-in-flow is used, <path> is instead the flow project directory, and a UUID-named subdirectory is created inside it.

Options

Flag	Default	Purpose
`--conversational`	off	Scaffold a conversational agent instead of an autonomous one.
`--model <model>`	no static default — picks a recommended model for the autonomous/conversational agent type	LLM model to use. Written into `settings.model` in `agent.json`.
`--system-prompt <prompt>`	—	Initial system prompt written into `messages[0]` of `agent.json`. Only meaningful in standalone mode.
`--force`	off	Overwrite the target directory even if it is not empty. Standalone mode only — inline mode always writes into a fresh UUID folder.
`--skip-solution-registration`	off	Do not auto-register the project in a surrounding solution, and do not auto-create a parent `<name>Solution`.
`--inline-in-flow`	off	Scaffold an inline agent inside a flow project. The `<path>` argument must point to an existing flow project directory (error otherwise).

Standalone mode refuses to proceed if the target directory exists and contains any files, unless --force is set.

Examples

# Simplest: scaffold an autonomous agent with the recommended default model
uip agent init ./my-agent --model gpt-5.4

# Scaffold a conversational agent
uip agent init ./my-agent --conversational --model anthropic.claude-sonnet-4-5-20250929-v1:0

# Scaffold outside any solution — a parent MyAgentSolution is auto-created
uip agent init ./my-agent

# Skip solution auto-registration entirely
uip agent init ./my-agent --skip-solution-registration

# Overwrite an existing non-empty directory
uip agent init ./my-agent --force

# Scaffold an inline agent inside an existing flow project
uip agent init ./my-flow --inline-in-flow
# Simplest: scaffold an autonomous agent with the recommended default model
uip agent init ./my-agent --model gpt-5.4

# Scaffold a conversational agent
uip agent init ./my-agent --conversational --model anthropic.claude-sonnet-4-5-20250929-v1:0

# Scaffold outside any solution — a parent MyAgentSolution is auto-created
uip agent init ./my-agent

# Skip solution auto-registration entirely
uip agent init ./my-agent --skip-solution-registration

# Overwrite an existing non-empty directory
uip agent init ./my-agent --force

# Scaffold an inline agent inside an existing flow project
uip agent init ./my-flow --inline-in-flow

Data shape (--output json)

Standalone (Code: "AgentInit"):

{
  "Code": "AgentInit",
  "Data": {
    "Status": "Agent project created",
    "Path": "/abs/path/MyAgentSolution/my-agent",
    "Name": "my-agent",
    "Model": "gpt-5.4",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000301",
    "NextSteps": "# Edit agent.json to configure prompts and resources\n...",
    "SolutionRegistration": {
      "Status": "Registered"
    },
    "AutoCreatedSolution": {
      "...": "present only when a parent solution was scaffolded automatically"
    },
    "ProjectArtifacts": {
      "...": "present only when the project was registered into a parent solution"
    }
  }
}
{
  "Code": "AgentInit",
  "Data": {
    "Status": "Agent project created",
    "Path": "/abs/path/MyAgentSolution/my-agent",
    "Name": "my-agent",
    "Model": "gpt-5.4",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000301",
    "NextSteps": "# Edit agent.json to configure prompts and resources\n...",
    "SolutionRegistration": {
      "Status": "Registered"
    },
    "AutoCreatedSolution": {
      "...": "present only when a parent solution was scaffolded automatically"
    },
    "ProjectArtifacts": {
      "...": "present only when the project was registered into a parent solution"
    }
  }
}

SolutionRegistration.Status is always present — one of Registered, AlreadyRegistered, NotInSolution (no parent .uipx found and a new one wasn't auto-created), or OptedOut (--skip-solution-registration was passed). AutoCreatedSolution is present only when a parent <Name>Solution was scaffolded for this run. ProjectArtifacts is present only when SolutionRegistration.Status is Registered or AlreadyRegistered — it mirrors the artifact-resource entries uip solution projects add would produce, so uip solution pack doesn't later omit the project.

Inline (Code: "AgentInitInline"):

{
  "Code": "AgentInitInline",
  "Data": {
    "Status": "Inline agent created inside flow project",
    "Path": "/abs/path/my-flow/<uuid>",
    "ProjectId": "<uuid>",
    "Model": "gpt-5.4",
    "NextSteps": "# Edit agent.json to configure prompts and settings\n..."
  }
}
{
  "Code": "AgentInitInline",
  "Data": {
    "Status": "Inline agent created inside flow project",
    "Path": "/abs/path/my-flow/<uuid>",
    "ProjectId": "<uuid>",
    "Model": "gpt-5.4",
    "NextSteps": "# Edit agent.json to configure prompts and settings\n..."
  }
}

Inline mode never does solution registration — SolutionRegistration / AutoCreatedSolution / ProjectArtifacts are never present on this shape.

ProjectId is a fresh UUID stamped into agent.json and — in inline mode — is also the folder name. In standalone mode, additional UUIDs are generated for the entry point, the semantic evaluator, the trajectory evaluator, and the default evaluation set.

Generated files

Standalone creates:

<path>/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/
      <semantic-evaluator>.json
      <trajectory-evaluator>.json
    eval-sets/
      evaluation-set-default.json
  features/
  resources/
<path>/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/
      <semantic-evaluator>.json
      <trajectory-evaluator>.json
    eval-sets/
      evaluation-set-default.json
  features/
  resources/

Inline-in-flow creates, inside the flow project:

<flow-path>/<new-uuid>/
  agent.json
  flow-layout.json           # empty ({})
  evals/eval-sets/
  features/
  resources/
<flow-path>/<new-uuid>/
  agent.json
  flow-layout.json           # empty ({})
  evals/eval-sets/
  features/
  resources/

uip agent refresh — run after every edit to regenerate entry-points.json and bindings_v2.json.
uip agent validate — strict read-only check before shipping.
uip solution projects add — link the scaffolded agent into a different solution than the one it was auto-registered into.

Was this page helpful?

PREVIOUSuip agent

NEXTvalidate

Synopsis​

Arguments​

Options​

Examples​

Data shape (--output json)​

Generated files​

Related​

See also​