UIP-Agent validieren

Strikte und schreibgeschützte Validierung eines lokalen Agent-Projekts mit „uip agent validate“ vor dem Packen, Veröffentlichen oder Debuggen.

uip agent validate ist eine strikte, schreibgeschützte Prüfung. Damit wird eine einzige Frage beantwortet: würde Studio Web dieses Verzeichnis so akzeptieren, wie es ist? Es schreibt nie Dateien. Wenn das Speicherschema des Projekts zurücksteht oder wenn entry-points.json / bindings_v2.json von der Quelle abgewichen sind, schlägt die Validierung mit einem Code fehl, der auf uip agent refresh verweist – der separate Befehl, der tatsächlich Dateien migriert und abgeleitete Artefakte neu generiert.

Die Validierung ist nur lokal – keine Anmeldung erforderlich.

Zusammenfassung

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

[path] und --path schließen sich gegenseitig aus – beide Trigger werden übergeben AgentValidateConflictingPath.

Alle uip agent validate -Aufrufe berücksichtigen die globalen Optionen (--output, --output-filter, --log-level, --log-file). Austrittscodes folgen dem Standardvertrag.

Argumente

• [path] (optional, Standard .) – Agent-Projektverzeichnis. Muss agent.json enthalten; Der eigenständige Modus erfordert zusätzlich entry-points.json und project.uiproj. Kann nicht mit --path kombiniert werden.

Optionen

Markieren	Standard	Zweck
--path <path>	–	Alternative zum Positionalargument [path]. Kann nicht damit kombiniert werden.
--bindings-target <path>	<projectDir>/bindings_v2.json; für --inline-in-flow das bindings_v2.json des unmittelbar übergeordneten Verzeichnisses, wenn es eine .flow -Datei enthält	Pfad zur bindings_v2.json -Datei, mit der verglichen werden soll. Spiegelt die gleiche Option für uip agent refresh.
--inline-in-flow	aus	Validieren Sie einen Inline-Agent innerhalb eines Flow-Projekts. Überspringt die Prüfungen entry-points.json und project.uiproj.

Beispiele

# 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

Was ist aktiviert

Ausführungen im eigenständigen Modus, in dieser Reihenfolge:

1. Erforderliche Dateien – agent.json, entry-points.json, project.uiproj.
2. agent.json -Struktur und Schema-Versionsgate – agent.version müssen der aktuellen Schemaversion der CLI entsprechen (eine neuere Projektversion schlägt mit AgentValidationOutdated fehl und fordert Sie auf, uip zu aktualisieren; eine ältere fordert Sie auf, refresh auszuführen) . Überprüft auch, ob type === "lowCode" vorhanden ist, projectId ist eine UUID, settings.model / settings.engine / settings.mode vorhanden, metadata.storageVersion vorhanden, messages[] hat mindestens [system, user].
3. messages[].contentTokens – Das contentTokens -Array jeder Nachricht wird von content erneut abgeleitet (Aufteilung in {{…}} / @{…}) und mit dem auf der Festplatte verglichen. Abweichungen in der Anzahl, im Typ oder in der Rohzeichenfolge sind Fehler. (Die Behebung der Abweichung ist die Aufgabe von refresh – die Validierung meldet dies nur.)
4. E/A-Schemas und Eingabevariablenverweise – inputSchema / outputSchema müssen jeweils { type: "object", properties: {…} } sein; Jeder {{input.<key>}} -Verweis in einer Nachricht muss in einen Schlüssel aufgelöst werden, der in inputSchema.properties deklariert ist (ein einfacher {{key}} ohne das Präfix input. wird abgelehnt – die Laufzeit lässt es als Literaltext zurück).
5. Ressourcen – Sowohl Inline-Einträge agent.resources als auch dateibasierte resources/<Name>/resource.json -Einträge. tool Ressourcen benötigen eine UUID id, name, type, und – wenn location festgelegt ist – eine von "solution" / "external", mit properties.folderPath === "solution_folder", wenn der Speicherort "solution" ist ( oder "" für --inline-in-flow). escalation - und mcp -Ressourcen benötigen eine UUID und einen Namen. Die Ordnerbenennung wird ebenfalls überprüft: Eigenständige Ressourcenordner müssen nach dem name der Ressource benannt werden; Inline-Ressourcenordner müssen nach dem id der Ressource benannt werden (keine Beachtung von Groß-/Kleinschreibung).
6. Synchronisierung der Einstiegspunkte – entry-points.json → entryPoints[0].input / output muss mit agent.json des inputSchema / outputSchema übereinstimmen (Eigenschaftsschlüssel für beide; nur erforderliche Arrays für die Eingabe). Wird übersprungen, wenn --inline-in-flow festgelegt ist.
7. project.uiproj – ProjectType === "Agent". Wird übersprungen, wenn --inline-in-flow festgelegt ist.
8. flow-layout.json Vorhandensein und Parsen (nur eigenständig) – fehlend oder falsch formatiert schlagen mit Anweisungen zum Ausführen von refresh fehl.
9. Speicherversionsgate – metadata.storageVersion des Projekts muss der neuesten bekannten Migrationsversion entsprechen; andernfalls AgentValidationOutdated (Aktualisieren Sie uip oder führen Sie refresh aus, wenn das Projekt dasjenige ist, das jetzt zur Verfügung steht).
10. Strikte Schemavalidierung gegen die aktuellen Studio Web-Schemas.
11. Vorhandensein von IS-Connector-Tool-Ressourcen (nur --inline-in-flow ) – Jeder Integration Service-Connector-Tool-Knoten, der mit dem Flow verkettet ist, muss einen übereinstimmenden resources/<id>/resource.json auf dem Datenträger haben.
12. Flow-Prüfung für abgeleitete Dateien – ein Schreibtischtest des gleichen Generators, den refresh verwendet, und vergleicht entry-points.json / bindings_v2.json mit dem, was neu generiert werden würde. Ein Fehler bei der Referenzintegrität (z. B. ein Tool, auf das verwiesen, aber nicht als Ressource vorhanden ist) ist ein schwerwiegender Fehler; Eine Inhaltsinkonsistenz wird als Abweichung gemeldet, wobei beide auf refresh zur Behebung verweisen.

Statische Fehler schlagen mit dem Exitcode 1 schnell fehl, bevor spätere Schritte ausgeführt werden.

Datenform (--output json)

Gültig (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 ist ein Objekt, das aufschlüsselt, was der strenge Schema übergeben hat – kein boolescher Wert. InlineInFlow: true wird für --inline-in-flow -Ausführungen hinzugefügt, und ein Warnings -Array wird hinzugefügt, wenn die Prüfung auf abgeleitete Dateien nicht schwerwiegende Warnungen erzeugt hat.

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

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

Statischer/Schema-Fehler (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."
    ]
  }
}

Zugehörig

• uip agent init – Erstellt ein Gerüst für Projekte, die standardmäßig sauber validiert werden.
• uip agent refresh – der Befehl, der Dateien tatsächlich migriert und neu generiert; Führen Sie sie immer dann aus, wenn die Validierung darauf hinweist.
• uip agent review – Ein bewertete Qualitätssicherung, die sich von der Bestehen-/Fehlschemaprüfung der Validierung unterscheidet.

Siehe auch

• Globale Optionen, Exitcodes.