UIP 智能体验证

uip agent validate对智能体项目运行本地静态分析，然后执行架构迁移管道。此命令应在每次手动编辑agent.json （或entry-points.json 、 project.uiproj 、 resources/*/resource.json ）后运行，且始终在打包、发布或推送前运行。

管道先在内存中，然后在回写式：根据当前文件计算迁移，并且除非每次检查都通过，否则不会将任何内容写入磁盘。检查通过后，写回迁移的文件内容，并重新生成.agent-builder/框架（仅限独立模式）。

仅在本地验证 — 无需登录。

大纲

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

所有uip agent validate调用都遵循全局选项（ --output 、 --output-filter 、 --log-level 、 --log-file ）。退出代码遵循标准合同。

参数

• [path] （可选，默认为. ） — 智能体项目目录。必须包含agent.json ；独立模式还需要entry-points.json和project.uiproj 。

选项

标记	默认	用途
--inline-in-flow	关闭	在流程项目中验证内联智能体。跳过entry-points.json和project.uiproj检查，并且不生成.agent-builder/ 。每当使用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

选中的内容

独立模式按顺序运行：

1. 所需文件— agent.json 、 entry-points.json 、 project.uiproj 。
2. agent.json结构— version === "1.1.0" 、 type === "lowCode" 、 projectId为 UUID，、 settings.model / settings.engine / settings.mode存在， metadata.storageVersion存在， messages[]至少包含[system, user] 。
3. messages[].contentTokens — 每条消息的contentTokens数组根据content重新派生（在{{…}}上拆分），并与磁盘上的数组进行比较。计数、类型或原始字符串的不匹配项均属于错误类型。
4. I/O 架构— inputSchema和outputSchema必须均为{ type: "object", properties: {…} } ， required[]中的每个条目都在properties中。
5. 资源— 内联agent.resources和基于文件的resources/<Name>/resource.json条目。tool资源需要 UUID id 、 name 、 type （当设置location时），以及"solution" / "external"中的一个，其中当位置为properties.folderPath === "solution_folder"时使用"solution" 。escalation和mcp资源需要 UUID 和名称。
6. 入口点同步— entry-points.json → entryPoints[0].input / output必须与agent.json的inputSchema / outputSchema匹配（两者的属性键；仅输入的必需数组）。
7. project.uiproj — ProjectType === "Agent" 。
8. 架构迁移管道— 验证程序根据需要（ storageVersion颠倒、添加字段）迁移文件，并根据 Studio Web 架构运行架构验证。
9. .agent-builder/生成— 仅限独立版。写入框架文件，并在可能的情况下修补resource.json文件中的引用密钥。

内联模式 ( --inline-in-flow ) 会跳过步骤 1（部分 — 仅需要agent.json ）、6、7 和 9。

在迁移管道运行之前，静态错误快速失败，退出代码为1 。报告每个有问题的文件和路径时，迁移错误也会失败，并报告退出代码1 。

数据形状（--输出 json）

有效，未应用迁移( 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
  }
}

有效，已应用迁移

{
  "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": ["…"]
  }
}

内联模式将"InlineInFlow": true添加到有效负载中，并省略AgentBuilderGenerated / AgentBuilderFiles / ReferenceKeysResolved 。

失败( 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."
    ]
  }
}

相关内容

• uip agent init — 默认情况下始终能够干净地进行验证的框架项目。
• 可保持智能体项目一致性的结构化编辑： uip agent config 、 uip agent input / output 、 uip agent tool 、 uip agent context 、 uip agent escalation 。
• 已验证项目的使用者： uip agent pack 、 uip agent publish 、 uip agent push 。

另请参阅

• 全局选项，退出代码。