Validación del agente de UIP

Valide de forma estricta y de solo lectura un proyecto de agente local con `validación de agente de uip` antes de empaquetar, publicar o depurar.

uip agent validate es una comprobación estricta de solo lectura . Responde a una sola pregunta: ¿aceptaría Studio Web este directorio tal como está? Nunca escribe ningún archivo. Si el esquema de almacenamiento del proyecto está atrasado, o si entry-points.json / bindings_v2.json se han desviado del origen, la validación falla con un código que apunta a uip agent refresh : el comando independiente que realmente migra archivos y regenera artefactos derivados.

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

Sinopsis

uip agent validate [path] [--path <path>] [--bindings-target <path>] [--inline-in-flow]

[path] y --path son mutuamente excluyentes: pasan ambos lanzamientos AgentValidateConflictingPath.

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. No se puede combinar con --path.

Opciones

Marca	Predeterminado	Propósito
--path <path>	—	Alternativa al argumento posicional [path]. No se puede combinar con él.
--bindings-target <path>	<projectDir>/bindings_v2.json; para --inline-in-flow, el bindings_v2.json del directorio principal inmediato cuando contiene un archivo .flow	Ruta al archivo bindings_v2.json con el que comparar. Refleja la misma opción en uip agent refresh.
--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.

Ejemplos

# Validate the current directory
uip agent validate

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

# Equivalent, using the flag form
uip agent validate --path ./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 y puerta de versión de esquema : agent.version debe ser igual a la versión actual del esquema de CLI (una versión más reciente del proyecto falla con AgentValidationOutdated y te dice que actualices uip; una más antigua te dice que ejecutes refresh) . También comprueba 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 (dividiendo 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. (Corregir la deriva aquí es trabajo de refresh; validate solo lo informa).
4. Esquemas de E/S y referencias de variables de entrada : inputSchema / outputSchema debe ser { type: "object", properties: {…} } cada uno; cada referencia {{input.<key>}} en un mensaje debe resolverse en una clave declarada en inputSchema.properties (se rechaza un {{key}} simple sin el prefijo input. ; el runtime lo deja como texto literal).
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" ( o "" para --inline-in-flow). Los recursos escalation y mcp necesitan un UUID y un nombre. También se comprueba la denominación de las carpetas: las carpetas de recursos independientes deben llevar el nombre del name del recurso; las carpetas de recursos en línea deben llevar el nombre del id del recurso (sin distinguir entre mayúsculas y minúsculas).
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). Se omite cuando se establece --inline-in-flow.
7. project.uiproj — ProjectType === "Agent". Se omite cuando se establece --inline-in-flow.
8. Presenciaflow-layout.json y análisis (solo independiente): falta o malformado falla con las instrucciones para ejecutar refresh.
9. Puerta de versión de almacenamiento : el metadata.storageVersion del proyecto debe ser igual a la última versión de migración conocida; de lo contrario, AgentValidationOutdated (actualiza uip o ejecuta refresh si el proyecto es el que está detrás).
10. Validación estricta del esquema frente a los esquemas actuales de Studio Web.
11. Presencia del recurso de la herramienta del conector de IS (solo --inline-in-flow ): cada nodo de la herramienta del conector de Integration Service conectado al flujo debe tener un resources/<id>/resource.json coincidente en el disco.
12. Comprobación de deriva de archivos derivados : una ejecución en seco de los refresh usos del generador, comparando entry-points.json / bindings_v2.json con lo que se regeneraría. Un fallo de integridad referencial (por ejemplo, una herramienta referenciada pero no presente como recurso) es un error grave; una falta de coincidencia de contenido se informa como deriva, ambos apuntan a refresh para corregir.

Los errores estáticos fallan rápidamente con el código de salida 1 antes de que se ejecuten los pasos posteriores.

Forma de datos (--json de salida)

Válido (Code: "AgentValidation"):

{
  "Code": "AgentValidation",
  "Data": {
    "Status": "Valid",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-5.4",
    "StorageVersion": "47.0.0",
    "Validated": {
      "agent": true,
      "resources": 2,
      "evalSets": 0,
      "evaluators": 0
    }
  }
}

Validated es un objeto que desglosa lo que comprobó el pase de esquema estricto, no un booleano. InlineInFlow: true se añade para ejecuciones --inline-in-flow, y se añade una matriz Warnings cuando la comprobación de archivos derivados produce advertencias no fatales.

Obsoleto (Code: "AgentValidationOutdated"):

{
  "Code": "AgentValidationOutdated",
  "Message": "Storage version 45.0.0 is outdated; latest is 47.0.0.",
  "Data": { "CurrentVersion": "45.0.0", "LatestVersion": "47.0.0" },
  "Instructions": "Run `uip agent refresh` to migrate."
}

Deriva (Code: "AgentValidationDrift"):

{
  "Code": "AgentValidationDrift",
  "Message": "Derived artifacts are out of sync with source (1 issue(s))",
  "Data": { "Errors": ["bindings_v2.json: out of sync — tool \"InvoiceLookup\" binding changed"] },
  "Instructions": "Run `uip agent refresh` to regenerate entry-points.json and bindings_v2.json."
}

Fallo estático/de esquema (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 se validan limpiamente de forma predeterminada.
• uip agent refresh : el comando que realmente migra y regenera archivos; ejecútalo cada vez que validar lo apunte.
• uip agent review : una calificación de calidad aprobada, distinta de la comprobación de esquema de aprobación/error de validar.

Ver también

• Opciones globales, códigos de salida.