avaliação do agente da UIP

Sintaxe e opções para a "avaliação do agente do uip", que gerencia avaliadores, conjuntos de avaliação, casos de teste e é executada no runtime do agente.

uip agent eval o grupo de comando de avaliação. Ele gerencia avaliadores, conjuntos de avaliação e casos de teste no disco e realiza execuções de avaliação no serviço do Agent Runtime. Quatro árvores de subcomando residem abaixo:

• uip agent eval evaluator … — gerenciar avaliadores (evals/evaluators/*.json).
• — gerenciar conjuntos de avaliação evals/eval-sets/*.json uip agent eval set … .
• uip agent eval add | list | remove gerencie casos de teste (avaliações) dentro de um conjunto de avaliação.
• uip agent eval run … iniciar, monitorar, listar e comparar execuções de avaliação com o serviço do Agent Runtime.

Tudo, exceto uip agent eval run *, é somente local. Os subcomandos run exigem uma sessão de CLI ativa (uip login) e resolvem seu destino de três maneiras: um --solution-id explícito, um SolutionStorage.json detectado automaticamente deixado por uip solution upload ou — quando nenhum dos dois estiver presente e o projeto se parece com um espaço de trabalho local — um caminho de avaliação implícito no espaço de trabalho local que é executado nos arquivos do projeto diretamente sem um upload anterior.

Todos os subcomandos uip agent eval respeitam as opções globais (--output, --output-filter, --log-level, --log-file). Os códigos de saída seguem o contrato padrão.

Resumo

uip agent eval evaluator add    <name> --type <type> [--description <d>] [--prompt <p>] [--target-key <k>] [--path <dir>]
uip agent eval evaluator list                                                                                 [--path <dir>]
uip agent eval evaluator remove <id>                                                                           [--path <dir>]

uip agent eval set add    <name>  [--evaluators <ids>]                                                         [--path <dir>]
uip agent eval set list                                                                                         [--path <dir>]
uip agent eval set remove <id>                                                                                  [--path <dir>]

uip agent eval add    <name> --set <name> --inputs <json>
                              [--expected <json>] [--expected-agent-behavior <text>]
                              [--simulation-instructions <text>]
                              [--simulate-input] [--simulate-tools]
                              [--input-generation-instructions <text>]
                              [--path <dir>]
uip agent eval list   --set <name>                                                                              [--path <dir>]
uip agent eval remove <id> --set <name>                                                                         [--path <dir>]

uip agent eval run start   --set <name> [--solution-id <id>] [--wait] [--timeout <s>]                           [--path <dir>]
uip agent eval run status  <evalSetRunId> --set <name>                                                          [--path <dir>]
uip agent eval run results <evalSetRunId> --set <name> [--only-failed] [--verbose] [--export-format <json|csv>] [--path <dir>]
uip agent eval run list    --set <name>                                                                         [--path <dir>]
uip agent eval run compare <evalSetRunId> --compare-to <id> --set <name>                                        [--path <dir>]

avaliador de avaliação do agente do uip

Gerenciar avaliadores — os classificadores que pontuam a saída de um agente.

adição de avaliador de avaliação

Argumentos

• <name> (necessário) — Nome do avaliador. Usado como o nome do arquivo padrão.

Opções

Bandeira	Padrão	Required	Finalidade
--type <type>	—	sim	Tipo de avaliador. Os valores conhecidos incluem SemanticSimilarity, Trajectory e LLM-as-judge; execute uip agent eval evaluator add --help para obter a lista completa compatível com sua instalação.
--description <desc>	—		Descrição em texto livre.
--prompt <prompt>	—		Solicitação de avaliação personalizada (para avaliadores baseados em solicitação).
--target-key <key>	—		Chave de saída de destino para avaliar.
--path <path>	.		Caminho para o diretório do projeto do agente.

Exemplo

uip agent eval evaluator add content-check \
  --type SemanticSimilarity \
  --path ./my-agent

Formato dos dados (--output json)

{
  "Code": "AgentEvaluatorAdd",
  "Data": {
    "Status": "Evaluator added",
    "Name": "content-check",
    "Type": "SemanticSimilarity",
    "Id": "a1b2c3d4-0000-0000-0000-000000000130",
    "File": "content-check.json"
  }
}

lista de avaliadores de avaliação

Opções

• ( . --path <path>

Formato dos dados

{
  "Code": "AgentEvaluatorList",
  "Data": [
    { "Name": "content-check", "Type": "SemanticSimilarity", "Id": "…", "File": "content-check.json" }
  ]
}

Os projetos vazios retornam Data: { "Message": "No evaluators configured" }.

remover avaliador de avaliação

Argumentos

• <id> — ID ou nome do avaliador.

Opções

• ( . --path <path>

Formato dos dados

{ "Code": "AgentEvaluatorRemove", "Data": { "Status": "Evaluator removed", "Id": "content-check" } }

conjunto de avaliação do agente uip

Gerenciar conjuntos de avaliação — coleções nomeadas de casos de teste mais os avaliadores que devem pontua-los.

adicionar conjunto de avaliação

Argumentos

• <name> nome do conjunto de avaliação.

Opções

Bandeira	Padrão	Finalidade
--evaluators <ids>	todos os avaliadores no projeto	IDs de avaliadores separados por vírgulas a serem incluídos.
--path <path>	.	Caminho para o diretório do projeto do agente.

Exemplo

uip agent eval set add smoke-tests \
  --evaluators a1b2c3d4-0000-0000-0000-000000000130,a1b2c3d4-0000-0000-0000-000000000131 \
  --path ./my-agent

Formato dos dados

{
  "Code": "AgentEvalSetAdd",
  "Data": {
    "Status": "Evaluation set created",
    "Name": "smoke-tests",
    "Id": "a1b2c3d4-0000-0000-0000-000000000110",
    "Evaluators": 2
  }
}

lista de conjuntos de avaliação

Opções

• ( . --path <path>

Formato dos dados

{
  "Code": "AgentEvalSetList",
  "Data": [
    { "Name": "smoke-tests", "Id": "…", "Evaluations": 5, "Evaluators": 2 }
  ]
}

remoção do conjunto de avaliação

Argumentos

• <id> ID ou nome de conjunto de avaliação.

Opções

• ( . --path <path>

avaliação do agente uip adicionar | lista | remover (casos de teste)

Gerenciar os casos de teste (avaliações) dentro de um conjunto. Esses subcomandos ficam diretamente sob eval, não sob eval set.

adição de avaliação

Argumentos

• <name> nome do caso de teste.

Opções

Bandeira	Padrão	Required	Finalidade
--set <name>	—	sim	Nome ou ID do conjunto de avaliação.
--inputs <json>	—	sim	Insira valores como uma string JSON. Analisado; JSON inválido falha rapidamente.
--expected <json>	—		Saída esperada como JSON.
--expected-agent-behavior <text>	—		Descrição do comportamento esperado para avaliadores de trajetória (por exemplo, "Must call Web Search tool").
--simulation-instructions <text>	—		Instruções para simular o comportamento do agente durante a avaliação.
--simulate-input	desativada		Habilite a simulação de entrada para este caso de teste.
--simulate-tools	desativada		Habilitar a simulação de ferramentas para este caso de teste.
--input-generation-instructions <text>	—		Instruções para sintetizar entradas.
--path <path>	.		Caminho para o diretório do projeto do agente.

Exemplo

uip agent eval add simple-greeting \
  --set default \
  --inputs '{"input":"hello"}' \
  --expected '{"content":"world"}' \
  --path ./my-agent

Formato dos dados

{
  "Code": "AgentEvalAdd",
  "Data": {
    "Status": "Evaluation added",
    "Name": "simple-greeting",
    "Id": "a1b2c3d4-0000-0000-0000-000000000120",
    "Set": "default"
  }
}

lista de avaliações

Opções

• --set <name> (Necessário)
• ( . --path <path>

Formato dos dados

{
  "Code": "AgentEvalList",
  "Data": [
    {
      "Name": "simple-greeting",
      "Id": "…",
      "Inputs": "{\"input\":\"hello\"}",
      "Expected": "{\"content\":\"world\"}",
      "ExpectedBehavior": "-"
    }
  ]
}

remoção de avaliação

Argumentos

• <id> — ID ou nome da avaliação.

Opções

• --set <name> (Necessário)
• ( . --path <path>

execução de avaliação do agente uip

Execute, monitore e compare execuções de avaliação por meio do serviço Agent Runtime (EvalsTenantExecutionApi). Requer uip login.

início da execução de avaliação

Inicie uma execução de avaliação. O agente já deve estar no Studio Web (uip solution upload) — passe --solution-id explicitamente ou confie em SolutionStorage.json, que uip solution upload grava automaticamente.

Opções

Bandeira	Padrão	Required	Finalidade
--set <name>	—	sim	Nome ou ID do conjunto de avaliação.
--solution-id <id>	De SolutionStorage.json		ID da solução do Cloud. Se omitido, o comando lê SolutionStorage.json do projeto; se nenhum dos dois estiver disponível, ele falhará.
--path <path>	.		Caminho para o diretório do projeto do agente.
--wait	desativada		Pesquise até que a execução seja concluída e, em seguida, emita resumo + linhas por caso de teste.
--timeout <seconds>	600		Máximo de segundos para pesquisar quando --wait está definido.

Exemplo

uip agent eval run start --set default --path ./my-agent --wait

Formato dos dados — início (Code: "AgentEvalRunStarted"):

{
  "Code": "AgentEvalRunStarted",
  "Data": {
    "EvalSetRunId": "a1b2c3d4-0000-0000-0000-000000000101",
    "EvalSetName": "default",
    "TestCases": 5,
    "Evaluators": 2
  }
}

Com --wait, duas cargas adicionais seguem após a pesquisa:

• Code: "AgentEvalRunCompleted" — resumo (Status, Score, Duration, EvaluatorScores, TestCases).
• Code: "AgentEvalRunResults" — linhas por caso de teste (mesmo formato que eval run results).

status de execução de avaliação

Pesquise o status de uma execução em andamento ou concluída.

Argumentos

• <evalSetRunId> ID de execução de eval run start.

Opções

• --set <name> (Necessário)
• ( . --path <path>

Formato dos dados

{
  "Code": "AgentEvalRunStatus",
  "Data": {
    "EvalSetRunId": "…",
    "Status": "completed",
    "Score": 0.86,
    "Duration": "42.5s",
    "EvaluatorScores": "semantic: 0.9, trajectory: 0.82"
  }
}

resultados da execução de avaliação

Buscar resultados por caso de teste.

Argumentos

• <evalSetRunId>.

Opções

Bandeira	Padrão	Required	Finalidade
--set <name>	—	sim	Nome ou ID do conjunto de avaliação.
--path <path>	.		Caminho para o diretório do projeto do agente.
--only-failed	desativada		Mostrar apenas casos de teste com falha ou erro.
--verbose	desativada		Inclua as justificativas do avaliador na saída.
--export-format <json|csv>	—		Grave as linhas formatadas em eval-results-<timestamp>.(json|csv) em vez de imprimi-las.

Exemplo

uip agent eval run results <evalSetRunId> --set default --verbose --only-failed

Formato dos dados (em linha — sem exportação):

{
  "Code": "AgentEvalRunResults",
  "Data": [
    {
      "TestCase": "simple-greeting",
      "Status": "completed",
      "Score": 1,
      "EvaluatorScores": "semantic: 0.95",
      "Tokens": 320,
      "Duration": "1.8s",
      "Error": "-"
    }
  ]
}

Quando --export-format é definido, a carga útil se torna Code: "AgentEvalRunExported" com Format, File e Records.

lista de execução de avaliação

Lista todas as execuções para um determinado conjunto de avaliação.

Opções

• --set <name> (Necessário)
• ( . --path <path>

Formato dos dados

{
  "Code": "AgentEvalRunList",
  "Data": [
    {
      "EvalSetRunId": "…",
      "Status": "completed",
      "Score": 0.86,
      "TestCases": 5,
      "Duration": "42.5s",
      "EvaluatorScores": "semantic: 0.9, trajectory: 0.82",
      "CreatedAt": "2025-04-15T10:30:00Z"
    }
  ]
}

comparação de execução de avaliação

Compare duas execuções lado a lado. Útil para solicitações de testes A/B ou alterações de modelo.

Argumentos

• <evalSetRunId> ID da primeira execução (linha de base).

Opções

Bandeira	Padrão	Required	Finalidade
--compare-to <id>	—	sim	ID da segunda execução para comparar.
--set <name>	—	sim	Nome ou ID do conjunto de avaliação.
--path <path>	.		Caminho para o diretório do projeto do agente.

Formato dos dados (Code: "AgentEvalRunComparison")

{
  "Code": "AgentEvalRunComparison",
  "Data": {
    "RunA": { "Id": "…", "Score": 0.86, "Status": "completed" },
    "RunB": { "Id": "…", "Score": 0.80, "Status": "completed" },
    "ScoreDelta": 0.06,
    "TestCases": [
      { "TestCase": "simple-greeting", "ScoreA": 1, "ScoreB": 0.9, "Delta": "+0.1", "StatusA": "completed", "StatusB": "completed" }
    ]
  }
}

Relacionado

• uip solution upload — envia o agente para o Studio Web e deixa o SolutionStorage.json que eval run start detecta automaticamente (a menos que --solution-id seja fornecido ou que o projeto se qualifique para o caminho do espaço de trabalho local implícito).
• uip agent validate — o conjunto de avaliação padrão e os avaliadores são criados por init; validate os mantém consistentes.
• uip agent debug — execute o agente uma vez no Studio Web com entradas de amostra; distinta de uma execução de avaliação do Agent Runtime.

Veja também

• Autenticação — sessões e validade do token para os subcomandos eval run .
• Opções globais, Códigos de saída.