validation d’agent uip

Validez strictement et en lecture seule un projet d’agent local avec « uip agent validate » avant la compression, la publication ou le débogage.

uip agent validate est une vérification stricte en lecture seule . Il répond à une seule question: est-ce que Studio Web acceptera ce répertoire tel quel? Il n’écrit jamais de fichiers. Si le schéma de stockage du projet est en retard, ou si entry-points.json / bindings_v2.json ont dérivé depuis la source, la validation échoue avec un code pointant sur uip agent refresh — la commande distincte qui migre réellement les fichiers et régénère les artefacts dérivés.

La validation est locale uniquement — aucune connexion requise.

Synthèse

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

[path] et --path sont mutuellement exclusifs — en transmettant les deux génération de AgentValidateConflictingPath.

Toutes les uip agent validate invocations respectent les options globales (--output, --output-filter, --log-level, --log-file). Les codes de sortie suivent le contrat standard.

Arguments

• [path] (facultatif, . par défaut) — Répertoire du projet d'agent. Doit contenir agent.json; le mode autonome nécessite en outre entry-points.json et project.uiproj. Ne peut pas être combiné avec --path.

Options

Drapeau	Default	Objectif
--path <path>	—	Alternative à l’argument positionnel [path]. Ne peut pas être combiné avec.
--bindings-target <path>	<projectDir>/bindings_v2.json; pour --inline-in-flow, le fichier bindings_v2.json du répertoire parent immédiat lorsqu'il contient un fichier .flow	Chemin d’accès au fichier bindings_v2.json à partir duquel comparer. Reproduise la même option sur uip agent refresh.
--inline-in-flow	désactivé	Validez un agent en ligne dans un projet de flux. Ignore les vérifications entry-points.json et project.uiproj.

Exemples

# 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

Ce qui est coché

Le mode autonome s’exécute dans l’ordre:

1. Fichiers requis — agent.json, entry-points.json, project.uiproj.
2. agent.json structure et passerelle de version de schéma — agent.version doit égaler la version actuelle du schéma de CLI (une version de projet plus récente échoue avec AgentValidationOutdated et vous indique de mettre à niveau uip; une plus ancienne vous indique d'exécuter refresh) . Vérifie également que type === "lowCode", projectId est un UUID, settings.model / settings.engine / settings.mode présent, metadata.storageVersion présent, messages[] a au moins [system, user].
3. messages[].contentTokens — le tableau contentTokens de chaque message est redirigé de content (division sur {{…}} / @{…}) et comparé à ce qui se trouve sur le disque. Les incompatibilités au niveau du nombre, du type ou de la chaîne brute sont des erreurs. (La correction de la dérive est la tâche de refresh - la valider uniquement la signale.)
4. Schémas E/S et références de variables d'entrée — inputSchema / outputSchema doivent chacun être { type: "object", properties: {…} }; chaque référence {{input.<key>}} dans un message doit se résoudre à une clé déclarée dans inputSchema.properties (une barre {{key}} sans le préfixe input. est rejetée - le runtime la laisse sous forme de texte littéral).
5. Ressources - entrées agent.resources en ligne et resources/<Name>/resource.json basées sur des fichiers. Les ressources tool ont besoin d’un UUID id, name, type et — lorsque location est défini — l’un de "solution" / "external", avec properties.folderPath === "solution_folder" lorsque l’emplacement est "solution" ( ou "" pour --inline-in-flow). Les ressources escalation et mcp ont besoin d’un UUID et d’un nom. L'affectation de noms des dossiers est également vérifiée: les dossiers de ressources autonomes doivent être nommés d'après le name de la ressource; les dossiers de ressources intégrés doivent être nommés après le id de la ressource (insensible à la casse).
6. Synchronisation des points d'entrée - entry-points.json → entryPoints[0].input / output doit correspondre à agent.json inputSchema / outputSchema (clés de propriétés pour les deux; tableaux requis pour l'entrée uniquement). Ignoré lorsque --inline-in-flow est défini.
7. project.uiproj — ProjectType === "Agent". Ignoré lorsque --inline-in-flow est défini.
8. flow-layout.json présence et analyse (autonome uniquement) — manquant ou mal formé échoue avec des instructions pour exécuter refresh.
9. Portail de version de stockage — le metadata.storageVersion du projet doit être égal à la dernière version de migration connue; sinon AgentValidationOutdated (mettez à niveau uip ou exécutez refresh si le projet est celui qui est en retard).
10. Validation stricte du schéma par rapport aux schémas Studio Web actuels.
11. Présence de l'outil du connecteur IS (--inline-in-flow uniquement): chaque nœud d'outil du connecteur Integration Service connecté dans le flux doit avoir une resources/<id>/resource.json correspondante sur le disque.
12. Vérification de la dérive des fichiers dérivés - un test du même générateur que refresh utilise, comparant entry-points.json / bindings_v2.json avec ce qui serait régénéré. Un échec d’intégrité référentielle (par exemple, un outil référencé mais non présent en tant que ressource) est une erreur matérielle; une incompatibilité de contenu est signalée comme une dérive, tous deux pointant vers refresh pour corriger.

Les erreurs statiques échouent rapidement avec le code de sortie 1 avant l'exécution des étapes ultérieures.

Format des données (--sortie json)

Valide (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 est un objet qui décompose ce que le schéma strict est vérifié, et non un booléen. InlineInFlow: true est ajouté pour --inline-in-flow exécutions, et un tableau Warnings est ajouté lorsque la vérification des fichiers dérivés a produit des avertissements non fatals.

Obsolète (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."
}

Déplacement (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."
}

Échec statique/schéma (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."
    ]
  }
}

Associé

• uip agent init — élabore des projets qui valident proprement par défaut.
• uip agent refresh — la commande qui migre et régénère réellement les fichiers; Exécutez-le chaque fois que vous validez le point.
• uip agent review — une réussite de qualité notée, distincte de la vérification du schéma de réussite/d'échec de la validation.

Voir également

• Options globales, codes de sortie.