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.

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 (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

参数

• [path] (optional, default .) — Agent project directory. Must contain agent.json; standalone mode additionally requires entry-points.json and project.uiproj.

选项

标记	默认	用途
--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.

示例

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

{
  "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:

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

{
  "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 — scaffolds projects that always validate cleanly by default.
• Structured edits that keep the agent project consistent: uip agent config, uip agent input / output, uip agent tool, uip agent context, uip agent escalation.
• Consumers of a validated project: uip agent pack, uip agent publish, uip agent push.

另请参阅

• Global options, Exit codes.