uip agent init

uip agent init scaffolds a new low-code agent project on disk. It creates only the agent project files — it does not create or link a solution. Use uip solution new followed by uip solution project add to place the scaffolded agent inside a solution.

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. The flow's inline agent node must reference the generated projectId.

Synopsis

uip agent init <path> [--model <model>] [--system-prompt <prompt>] [--force] [--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.

Argumentos

• <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.

Opciones

Marca	Predeterminado	Propósito
--model <model>	gpt-4o-2024-11-20	LLM model the agent will 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.
--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.

Ejemplos

# Simplest: scaffold with defaults into ./my-agent
uip agent init ./my-agent

# Override the model and seed a system prompt
uip agent init ./invoice-agent \
  --model gpt-4o-2024-11-20 \
  --system-prompt "You are an invoice triage agent."

# 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": "./my-agent",
    "Name": "my-agent",
    "Model": "gpt-4o-2024-11-20",
    "ProjectId": "a1b2c3d4-0000-0000-0000-000000000301",
    "NextSteps": "# Edit agent.json to configure prompts and resources\n…"
  }
}

Inline (Code: "AgentInitInline"):

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

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/

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

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

Related

• uip agent validate — run static checks and schema migration after editing the scaffolded agent.json.
• uip agent config — update individual keys in agent.json without hand-editing the file.
• uip agent input / uip agent output — manage the agent's input and output schema after scaffolding.
• uip agent push — push the scaffolded project to Studio Web.

Ver también

• Concepts: skills — how an agent's entry points surface as skills.
• Global options, Exit codes.