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

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

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

## Examples

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

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

```json
{
  "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`](./uip-agent-validate.md) — run static checks and schema migration after editing the scaffolded `agent.json`.
- [`uip agent config`](./uip-agent-config.md) — update individual keys in `agent.json` without hand-editing the file.
- [`uip agent input`](./uip-agent-io-manage.md#uip-agent-input) / [`uip agent output`](./uip-agent-io-manage.md#uip-agent-output) — manage the agent's input and output schema after scaffolding.
- [`uip agent push`](./uip-agent-push-pull.md#uip-agent-push) — push the scaffolded project to Studio Web.

## See also

- [Concepts: skills](./concepts-skills.md) — how an agent's entry points surface as skills.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).