validação do agente do uip

Valide estritamente e somente leitura um projeto de agente local com "uip agent validate" antes de empacotar, publicar ou depurar.

uip agent validate uma verificação rigorosa e somente leitura . Ele responde a uma única pergunta: o Studio Web aceitaria esse diretório como está? Ele nunca grava nenhum arquivo. Se o esquema de armazenamento do projeto estiver atrasado ou se entry-points.json / bindings_v2.json se tiver desviodo da origem, a validação falha com um código apontando para uip agent refresh — o comando separado que realmente migra arquivos e regenera artefatos derivados.

A validação é somente local — sem necessidade de login.

Resumo

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

[path] e --path são mutuamente exclusivos — passando ambos os lançamentos AgentValidateConflictingPath.

Todas as invocações uip agent validate honram as opções globais (--output, --output-filter, --log-level, --log-file). Os códigos de saída seguem o contrato padrão.

Argumentos

• [path] (opcional, padrão .) — Diretório do projeto do agente. Deve conter agent.json; o modo autônomo também requer entry-points.json e project.uiproj. Não pode ser combinado com --path.

Opções

Bandeira	Padrão	Finalidade
--path <path>	—	Alternativa ao [path] argumento posicional. Não pode ser combinado com ele.
--bindings-target <path>	<projectDir>/bindings_v2.json; para --inline-in-flow, o bindings_v2.json do diretório pai imediato quando ele contiver um arquivo .flow	Caminho para o arquivo bindings_v2.json para comparar. Espelha a mesma opção em uip agent refresh.
--inline-in-flow	desativada	Validar um agente em linha dentro de um projeto de fluxo. Ignora as verificações entry-points.json e project.uiproj.

Exemplos

# 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

O que está marcado

O modo independente é executado em ordem:

1. Arquivos necessários — agent.json, entry-points.json, project.uiproj.
2. porta de estrutura e versão do esquemaagent.json — agent.version deve ser igual à versão atual do esquema da CLI (uma versão mais recente do projeto falha com AgentValidationOutdated e solicita a atualização de uip; uma versão mais antiga informa a você para executar refresh) . Também verifica type === "lowCode", projectId é um UUID, settings.model / settings.engine / settings.mode presente, metadata.storageVersion presente, messages[] tem pelo menos [system, user].
3. messages[].contentTokens — a matriz contentTokens de cada mensagem é novamente derivada de content (dividindo-se em {{…}} / @{…}) e comparada com o que está no disco. Incompatibilidades na contagem, tipo ou string bruta são erros. (Corrigir o desvio aqui é trabalho do refresh — validar apenas relata-lo.)
4. Esquemas de I/O e referências de variável de entrada — inputSchema / outputSchema devem ser cada um { type: "object", properties: {…} }; cada referência {{input.<key>}} em uma mensagem deve resolver para uma chave declarada em inputSchema.properties (um {{key}} vazio sem o prefixo input. é rejeitado — o tempo de execução o deixa como texto literal).
5. Recursos — tanto entradas agent.resources embutidas quanto resources/<Name>/resource.json baseadas em arquivo. Os recursos tool precisam de um UUID id, name, type e — quando location estiver definido — um de "solution" / "external", com properties.folderPath === "solution_folder" quando o local for "solution" ( ou "" para --inline-in-flow). Os recursos escalation e mcp precisam de um UUID e um nome. A nomeação das pastas também é verificada: as pastas de recursos independentes devem ser nomeadas após a name do recurso; as pastas de recursos em linha devem ser nomeadas após o id do recurso (sem diferenciação entre maiúsculas e minúsculas).
6. Sincronização de pontos de entrada — entry-points.json → entryPoints[0].input / output deve corresponder ao inputSchema / outputSchema de agent.json (chaves de propriedades para ambos; arrays necessários apenas para entrada). Ignorado quando --inline-in-flow está definido.
7. project.uiproj — ProjectType === "Agent". Ignorado quando --inline-in-flow está definido.
8. Presença e análise deflow-layout.json (apenas independente) — ausente ou malformado falha com instruções para executar refresh.
9. Porta da versão de armazenamento — a metadata.storageVersion do projeto deve ser igual à versão de migração conhecida mais recente; caso contrário, AgentValidationOutdated (atualize uip ou execute refresh se o projeto for aquele que está para trás).
10. Validação de esquema rigorosa em relação aos esquemas atuais do Studio Web.
11. Presença de recursos da ferramenta de conector IS (apenas --inline-in-flow ) — cada nó de ferramenta de conector do Integration Service conectado ao fluxo deve ter um resources/<id>/resource.json correspondente no disco.
12. Verificação de desvio de arquivos derivados — uma simulação dos mesmos usos de gerador refresh , comparando entry-points.json / bindings_v2.json com o que seria regenerado. Uma falha de integridade referencial (por exemplo, uma ferramenta referenciada, mas não presente como um recurso) é um erro de hardware; uma incompatibilidade de conteúdo é relatada como desvio, ambos apontando para refresh para corrigir.

Os erros estáticos falham rapidamente com o código de saída 1 antes da execução das etapas posteriores.

Formato dos dados (--output json)

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 é um objeto que divide o que o esquema restrito passou — não um booleano. InlineInFlow: true é adicionado para execuções --inline-in-flow e uma matriz Warnings é adicionada quando a verificação de arquivos derivados produziu avisos não fatais.

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

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

Falha estática/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 — projetos de estruturas que validam limpas por padrão.
• uip agent refresh — o comando que realmente migra e regenera arquivos; execute-o sempre que a validação apontar para ele.
• uip agent review — uma aprovação de qualidade pontuada, distinta da verificação de esquema de aprovação/falha de validação.

Veja também

• Opções globais, Códigos de saída.