Validación del agente de UIP

uip agent validate un pase de análisis estático local sobre un proyecto de agente y luego ejecuta el proceso de migración de esquema. Es el comando que debes ejecutar después de cada edición manual en agent.json (o entry-points.json, project.uiproj, resources/*/resource.json), y siempre antes de empaquetar, publicar o enviar.

El proceso es primero en memoria y luego de escritura diferida: la migración se calcula en función de los archivos actuales y no se escribe nada en el disco a menos que se pasen todas las comprobaciones. Cuando se superan las comprobaciones, el contenido del archivo migrado se vuelve a escribir y (solo en modo independiente) se regenera el andamio .agent-builder/ .

Validar es solo local: no es necesario iniciar sesión.

Sinopsis

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

Todas las invocaciones uip agent validate respetan las opciones globales (--output, --output-filter, --log-level, --log-file). Los códigos de salida siguen el contrato estándar.

Argumentos

• [path] (opcional, predeterminado .) — Directorio del proyecto del agente. Debe contener agent.json; el modo independiente requiere además entry-points.json y project.uiproj.

Opciones

Marca	Predeterminado	Propósito
--inline-in-flow	Desactivado	Valida un agente en línea dentro de un proyecto de flujo. Omite las comprobaciones entry-points.json y project.uiproj , y no genera .agent-builder/. Usa este modo siempre que el agente se haya andamiado con uip agent init --inline-in-flow.

Ejemplos

# 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

Qué se comprueba

El modo independiente se ejecuta, en orden:

1. Archivos necesarios : agent.json, entry-points.json, project.uiproj.
2. Estructuraagent.json : version === "1.1.0", type === "lowCode", projectId es un UUID, settings.model / settings.engine / settings.mode presente, metadata.storageVersion presente, messages[] tiene al menos [system, user].
3. messages[].contentTokens — la matriz contentTokens de cada mensaje se vuelve a derivar de content (dividiéndose en {{…}}) y se compara con lo que hay en el disco. Las discrepancias en el recuento, el tipo o la cadena sin procesar son errores.
4. Esquemas de E/S : inputSchema y outputSchema deben ser { type: "object", properties: {…} } cada uno, con cada entrada en required[] presente en properties.
5. Recursos : tanto las entradas en línea agent.resources como las basadas en archivos resources/<Name>/resource.json . Los recursos tool necesitan un UUID id, name, type y, cuando se establece location , uno de "solution" / "external", con properties.folderPath === "solution_folder" cuando la ubicación es "solution". Los recursos escalation y mcp necesitan un UUID y un nombre.
6. Sincronización de puntos de entrada : entry-points.json → entryPoints[0].input / output debe coincidir con inputSchema / outputSchema de agent.json (claves de propiedades para ambos; matrices requeridas solo para la entrada).
7. project.uiproj — ProjectType === "Agent".
8. Proceso de migración de esquema : el validador migra archivos según sea necesario (storageVersion golpes, adiciones de campo) y ejecuta la validación del esquema contra los esquemas de Studio Web.
9. generación.agent-builder/ : solo independiente. Escribe archivos de andamiaje y, cuando es posible, parchea las claves de referencia en los archivos resource.json .

El modo en línea (--inline-in-flow) omite los pasos 1 (parcial: solo se requiere agent.json ), 6, 7 y 9.

Los errores estáticos fallan rápidamente con el código de salida 1 antes de que se ejecute el proceso de migración. Los errores de migración también fallan con el código de salida 1, con cada archivo y ruta infractores informados.

Forma de datos (--json de salida)

Válido, no se aplica ninguna migración (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": ["…"]
  }
}

El modo en línea añade "InlineInFlow": true a la carga útil y omite AgentBuilderGenerated / AgentBuilderFiles / ReferenceKeysResolved.

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

Relacionado

• uip agent init : proyectos de andamios que siempre se validan limpiamente de forma predeterminada.
• Ediciones estructuradas que mantienen la coherencia del proyecto del agente: uip agent config, uip agent input / output, uip agent tool, uip agent context, uip agent escalation.
• Consumidores de un proyecto validado: uip agent pack, uip agent publish, uip agent push.

Ver también

• Opciones globales, códigos de salida.