validação do agente do uip

uip agent validate uma análise estática local sobre um projeto de agente e, em seguida, executa o pipeline de migração de esquema. É o comando que você deve executar após cada edição manual em agent.json (ou entry-points.json, project.uiproj, resources/*/resource.json) — e sempre antes de empacotar, publicar ou enviar por push.

O pipeline está na memória primeiro e depois o Write-back: a migração é calculada em relação aos arquivos atuais, e nada é gravado no disco a menos que todas as verificações sejam aprovadas. Quando as verificações são aprovadas, os conteúdos do arquivo migrado são gravados de volta e (apenas no modo independente) o framework .agent-builder/ é regenerado.

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

Resumo

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

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 independente também requer entry-points.json e project.uiproj.

Opções

Bandeira	Padrão	Finalidade
--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 e não gera .agent-builder/. Use este modo sempre que o agente foi estruturado com uip agent init --inline-in-flow.

Exemplos

# 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

O que está marcado

O modo independente é executado em ordem:

1. Arquivos necessários — agent.json, entry-points.json, project.uiproj.
2. estruturaagent.json — version === "1.1.0", 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.
4. Esquemas de I/O — inputSchema e outputSchema devem ser cada um { type: "object", properties: {…} }, com cada entrada em required[] presente em properties.
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". Os recursos escalation e mcp precisam de um UUID e um nome.
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).
7. project.uiproj — ProjectType === "Agent".
8. Pipeline de migração de esquema — o validador migra arquivos conforme necessário (correspondências storageVersion , adições de campo) e executa a validação de esquema nos esquemas do Studio Web.
9. Geração.agent-builder/ — apenas independente. Grava arquivos de Scaffolding e, quando possível, corrige ChavesDeReferência em arquivos resource.json .

O modo incorporado (--inline-in-flow) pula as etapas 1 (parcial — apenas agent.json necessário), 6, 7 e 9.

Os erros estáticos falham rapidamente com o código de saída 1 antes que o pipeline de migração seja executado. Erros de migração também falham com código de saída 1, com cada arquivo e caminho ofensivas relatados.

Formato dos dados (--output json)

Válido, sem migração aplicada (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
  }
}

Válido, migração aplicada

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

O modo em linha adiciona "InlineInFlow": true à carga e omite AgentBuilderGenerated / AgentBuilderFiles / ReferenceKeysResolved.

Falha (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 — estrutura de projetos que sempre validam limpas por padrão.
• Edições estruturadas que mantêm a consistência do projeto do agente: uip agent config, uip agent input / output, uip agent tool, uip agent context, uip agent escalation.
• Consumidores de um projeto validado: uip agent pack, uip agent publish, uip agent push.

Veja também

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