validation d’agent uip

uip agent validate exécute une analyse statique locale sur un projet d’agent, puis exécute le pipeline de migration de schéma. Il s'agit de la commande que vous devez exécuter après chaque modification manuelle de agent.json (ou entry-points.json, project.uiproj, resources/*/resource.json) et toujours avant la compression, la publication ou la transmission.

Le pipeline est d'abord en mémoire, puis en écriture: la migration est calculée par rapport aux fichiers actuels, et rien n'est écrit sur le disque, sauf si chaque vérification est réussie. Lorsque les vérifications sont respectées, les contenus des fichiers migrés sont réécrits et (mode autonome uniquement) l’élaboration .agent-builder/ est régénérée.

La validation est locale uniquement — aucune connexion requise.

Synthèse

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

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.

Options

Drapeau	Default	Objectif
--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 , et ne génère pas .agent-builder/ Utilisez ce mode chaque fois que l'agent a été élaboré avec uip agent init --inline-in-flow.

Exemples

# 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

Ce qui est coché

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

1. Fichiers requis — agent.json, entry-points.json, project.uiproj.
2. Structureagent.json — version === "1.1.0", 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.
4. Schémas E/S — inputSchema et outputSchema doivent chacun être { type: "object", properties: {…} }, avec chaque entrée de required[] présente dans properties.
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, ou l’un de "solution" / "external", avec properties.folderPath === "solution_folder" lorsque l’emplacement est "solution". Les ressources escalation et mcp ont besoin d’un UUID et d’un nom.
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).
7. project.uiproj — ProjectType === "Agent".
8. Pipeline de migration de schéma — le validateur migre les fichiers selon les besoins (storageVersion bogues, ajouts de champs) et exécute la validation du schéma par rapport aux schémas Studio Web.
9. Génération.agent-builder/ — autonome uniquement. Écrit des fichiers d'élaboration et, dans la mesure du possible, corrige les clés de référence dans les fichiers resource.json .

Le mode en ligne (--inline-in-flow) ignore les étapes 1 (partielle — uniquement agent.json requise), 6, 7 et 9.

Les erreurs statiques échouent rapidement avec le code de sortie 1 avant l'exécution du pipeline de migration. Les erreurs de migration échouent également avec le code de sortie 1, avec chaque fichier et chemin incriminé signalés.

Format des données (--sortie json)

Valide, aucune migration appliquée (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
  }
}

Valide, migration appliquée

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

Le mode en ligne ajoute "InlineInFlow": true à la charge utile et omet AgentBuilderGenerated / AgentBuilderFiles / ReferenceKeysResolved.

Échec (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 toujours proprement par défaut.
• Modifications structurées qui préservent la cohérence du projet d'agent: uip agent config, uip agent input / output, uip agent tool, uip agent context, uip agent escalation.
• Consommateurs d’un projet validé: uip agent pack, uip agent publish, uip agent push.

Voir également

• Options globales, codes de sortie.