# uip agent validate

> `uip agent validate` runs a local static-analysis pass over an agent project and then executes the schema-migration pipeline. It is the command you should run after every hand-edit to `agent.json` (or `entry-points.json`, `project.uiproj`, `resources/*/resource.json`) — and always before packing, publishing, or pushing.

`uip agent validate` runs a local static-analysis pass over an agent project and then executes the schema-migration pipeline. It is the command you should run after every hand-edit to `agent.json` (or `entry-points.json`, `project.uiproj`, `resources/*/resource.json`) — and always before packing, publishing, or pushing.

The pipeline is **in-memory first, then write-back**: migration is computed against the current files, and nothing is written to disk unless every check passes. When checks pass, migrated file contents are written back, and (standalone mode only) the `.agent-builder/` scaffolding is regenerated.

Validate is local-only — no login required.

## Synopsis

```
uip agent validate [path] [--inline-in-flow]
```

All `uip agent validate` 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]` *(optional, default `.`)* — Agent project directory. Must contain `agent.json`; standalone mode additionally requires `entry-points.json` and `project.uiproj`.

## Options

| Flag | Default | Purpose |
|---|---|---|
| `--inline-in-flow` | off | Validate an inline agent inside a flow project. Skips the `entry-points.json` and `project.uiproj` checks, and does not generate `.agent-builder/`. Use this mode whenever the agent was scaffolded with `uip agent init --inline-in-flow`. |

## Examples

```bash
# Validate the current directory
uip agent validate

# Validate a specific standalone project
uip agent validate ./my-agent

# Validate an inline agent (the flow-project subdirectory)
uip agent validate ./my-flow/<uuid> --inline-in-flow
```

## What is checked

Standalone mode runs, in order:

1. **Required files** — `agent.json`, `entry-points.json`, `project.uiproj`.
2. **`agent.json` structure** — `version === "1.1.0"`, `type === "lowCode"`, `projectId` is a UUID, `settings.model` / `settings.engine` / `settings.mode` present, `metadata.storageVersion` present, `messages[]` has at least `[system, user]`.
3. **`messages[].contentTokens`** — each message's `contentTokens` array is re-derived from `content` (splitting on `{{…}}`) and compared to what is on disk. Mismatches in count, type, or raw-string are errors.
4. **I/O schemas** — `inputSchema` and `outputSchema` must each be `{ type: "object", properties: {…} }`, with every entry in `required[]` present in `properties`.
5. **Resources** — both inline `agent.resources` and file-based `resources/<Name>/resource.json` entries. `tool` resources need a UUID `id`, `name`, `type`, and — when `location` is set — one of `"solution"` / `"external"`, with `properties.folderPath === "solution_folder"` when the location is `"solution"`. `escalation` and `mcp` resources need a UUID and a name.
6. **Entry-points sync** — `entry-points.json → entryPoints[0].input` / `output` must match `agent.json`'s `inputSchema` / `outputSchema` (properties keys for both; required arrays for input only).
7. **`project.uiproj`** — `ProjectType === "Agent"`.
8. **Schema-migration pipeline** — the validator migrates files as needed (`storageVersion` bumps, field additions) and runs schema validation against the Studio Web schemas.
9. **`.agent-builder/` generation** — standalone only. Writes scaffolding files and, where possible, patches referenceKeys in `resource.json` files.

Inline mode (`--inline-in-flow`) skips steps 1 (partial — only `agent.json` required), 6, 7, and 9.

Static errors fail fast with exit code `1` before the migration pipeline runs. Migration errors also fail with exit code `1`, with each offending file and path reported.

## Data shape (--output json)

**Valid, no migration applied** (`Code: "AgentValidation"`):

```json
{
  "Code": "AgentValidation",
  "Data": {
    "Status": "Valid",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-4o-2024-11-20",
    "StorageVersion": "47.0.0",
    "MigrationApplied": false,
    "Validated": true
  }
}
```

### Valid, migration applied

```json
{
  "Code": "AgentValidation",
  "Data": {
    "Status": "Valid — migrated to 47.0.0",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-4o-2024-11-20",
    "StorageVersion": "47.0.0",
    "MigrationApplied": true,
    "MigratedFiles": 3,
    "Validated": true,
    "AgentBuilderGenerated": true,
    "AgentBuilderFiles": 5,
    "ReferenceKeysResolved": 2,
    "Warnings": ["…"]
  }
}
```

**Inline mode** adds `"InlineInFlow": true` to the payload and omits `AgentBuilderGenerated` / `AgentBuilderFiles` / `ReferenceKeysResolved`.

**Failure** (`Code: "AgentValidationFailed"`):

```json
{
  "Code": "AgentValidationFailed",
  "Message": "Validation failed with 2 error(s)",
  "Data": {
    "Errors": [
      "agent.json.settings.model: missing or empty",
      "messages[1].contentTokens: contentTokens has 3 entries but content requires 2. Rebuild contentTokens to match content."
    ]
  }
}
```

## Related

- [`uip agent init`](./uip-agent-init.md) — scaffolds projects that always validate cleanly by default.
- Structured edits that keep the agent project consistent: [`uip agent config`](./uip-agent-config.md), [`uip agent input` / `output`](./uip-agent-io-manage.md), [`uip agent tool`](./uip-agent-tool-manage.md), [`uip agent context`](./uip-agent-context-manage.md), [`uip agent escalation`](./uip-agent-escalation-manage.md).
- Consumers of a validated project: [`uip agent pack`](./uip-agent-pack.md), [`uip agent publish`](./uip-agent-publish.md), [`uip agent push`](./uip-agent-push-pull.md).

## See also

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