Evaluación de agente de UIP

Sintaxis y opciones para `uip agent eval`, que gestiona evaluadores, conjuntos de evaluación, casos de prueba y se ejecuta en el runtime del agente.

uip agent eval es el grupo de comandos de evaluación. Gestiona evaluadores, conjuntos de evaluación y casos de prueba en el disco, y ejecuta ejecuciones de evaluación en el servicio Agent Runtime. Debajo hay cuatro árboles de subcomandos:

• uip agent eval evaluator … — gestionar evaluadores (evals/evaluators/*.json).
• uip agent eval set … : gestionar conjuntos de evaluación (evals/eval-sets/*.json).
• uip agent eval add | list | remove — gestionar casos de prueba (evaluaciones) dentro de un conjunto de evaluación.
• uip agent eval run … : inicia, supervisa, enumera y compara ejecuciones de evaluación con el servicio Agent Runtime.

Todo excepto uip agent eval run * es solo local. Los subcomandos run requieren una sesión CLI activa (uip login) y resuelven su destino de una de tres maneras: un --solution-id explícito, un SolutionStorage.json detectado automáticamente dejado por uip solution upload, o — cuando ninguno está presente y el proyecto parece un espacio de trabajo local: una ruta de evaluación implícita del espacio de trabajo local que se ejecuta en los archivos del proyecto directamente sin una carga previa.

Todos los subcomandos uip agent eval respetan las opciones globales (--output, --output-filter, --log-level, --log-file). Los códigos de salida siguen el contrato estándar.

Sinopsis

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>]

evaluador de evaluación de agente de uip

Gestionar evaluadores: los calificadores que puntúan la salida de un agente.

añadir evaluador eval

Argumentos

• <name> (obligatorio) : nombre del evaluador. Se utiliza como nombre de archivo predeterminado.

Opciones

Marca	Predeterminado	Obligatorio	Propósito
--type <type>	—	Sí	Tipo de evaluador. Los valores conocidos incluyen SemanticSimilarity, Trajectory y LLM-as-judge; ejecuta uip agent eval evaluator add --help para obtener la lista completa compatible con tu instalación.
--description <desc>	—		Descripción de texto libre.
--prompt <prompt>	—		Solicitud de evaluación personalizada (para evaluadores basados en solicitudes).
--target-key <key>	—		Clave de salida de destino contra la que evaluar.
--path <path>	.		Ruta al directorio del proyecto del agente.

Ejemplo

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

Forma de datos (--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 evaluadores de eval

Opciones

• --path <path> (predeterminado .)

Forma de datos

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

Los proyectos vacíos devuelven Data: { "Message": "No evaluators configured" }.

eliminar evaluador eval

Argumentos

• <id> — ID o nombre del evaluador.

Opciones

• --path <path> (predeterminado .)

Forma de datos

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

conjunto de evaluación de agente de uip

Gestionar conjuntos de evaluación: colecciones con nombre de casos de prueba más los evaluadores que deben puntuarlos.

añadir conjunto de evaluación

Argumentos

• <name> — nombre del conjunto de evaluación.

Opciones

Marca	Predeterminado	Propósito
--evaluators <ids>	todos los evaluadores del proyecto	ID de evaluadores separados por comas que se incluirán.
--path <path>	.	Ruta al directorio del proyecto del agente.

Ejemplo

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

Forma de datos

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

lista de conjuntos de evaluación

Opciones

• --path <path> (predeterminado .)

Forma de datos

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

conjunto de evaluación eliminar

Argumentos

• <id> — ID o nombre del conjunto de evaluación.

Opciones

• --path <path> (predeterminado .)

adición de evaluación de agente de uip | lista | eliminar (casos de prueba)

Gestiona los casos de prueba (evaluaciones) dentro de un conjunto. Estos subcomandos se encuentran directamente bajo eval, no bajo eval set.

añadir evaluación

Argumentos

• <name> — nombre del caso de prueba.

Opciones

Marca	Predeterminado	Obligatorio	Propósito
--set <name>	—	Sí	Nombre o ID del conjunto de evaluación.
--inputs <json>	—	Sí	Valores de entrada como una cadena JSON. Analizado; JSON no válido falla rápidamente.
--expected <json>	—		Salida esperada como JSON.
--expected-agent-behavior <text>	—		Descripción del comportamiento esperado para los evaluadores de trayectoria (por ejemplo, "Must call Web Search tool").
--simulation-instructions <text>	—		Instrucciones para simular el comportamiento del agente durante la evaluación.
--simulate-input	Desactivado		Habilite la simulación de entrada para este caso de prueba.
--simulate-tools	Desactivado		Habilite la simulación de herramientas para este caso de prueba.
--input-generation-instructions <text>	—		Instrucciones para sintetizar entradas.
--path <path>	.		Ruta al directorio del proyecto del agente.

Ejemplo

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

Forma de datos

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

lista de evaluación

Opciones

• --set <name> (obligatorio)
• --path <path> (predeterminado .)

Forma de datos

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

evaluación eliminar

Argumentos

• <id> — ID o nombre de evaluación.

Opciones

• --set <name> (obligatorio)
• --path <path> (predeterminado .)

ejecución de evaluación del agente de uip

Ejecutar, supervisar y comparar ejecuciones de evaluación a través del servicio Agent Runtime (EvalsTenantExecutionApi). Requiere uip login.

inicio de ejecución de evaluación

Inicia una ejecución de evaluación. El agente ya debe estar en Studio Web (uip solution upload): transmite --solution-id explícitamente o confía en SolutionStorage.json, que uip solution upload escribe automáticamente.

Opciones

Marca	Predeterminado	Obligatorio	Propósito
--set <name>	—	Sí	Nombre o ID del conjunto de evaluación.
--solution-id <id>	De SolutionStorage.json		ID de la solución en la nube. Si se omite, el comando lee SolutionStorage.json del proyecto; si ninguno está disponible, se produce un error.
--path <path>	.		Ruta al directorio del proyecto del agente.
--wait	Desactivado		Encuesta hasta que se complete la ejecución y luego emite resumen + filas por caso de prueba.
--timeout <seconds>	600		Máximo de segundos para sondear cuando se establece --wait .

Ejemplo

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

Forma de datos — inicio (Code: "AgentEvalRunStarted"):

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

Con --wait, siguen dos cargas útiles adicionales después del sondeo:

• Code: "AgentEvalRunCompleted" : resumen (Status, Score, Duration, EvaluatorScores, TestCases).
• Code: "AgentEvalRunResults" — filas por caso de prueba (la misma forma que eval run results).

estado de ejecución de evaluación

Sondea el estado de una ejecución en curso o finalizada.

Argumentos

• <evalSetRunId> — ID de ejecución desde eval run start.

Opciones

• --set <name> (obligatorio)
• --path <path> (predeterminado .)

Forma de datos

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

resultados de la ejecución de evaluación

Obtener resultados por caso de prueba.

Argumentos

• <evalSetRunId>.

Opciones

Marca	Predeterminado	Obligatorio	Propósito
--set <name>	—	Sí	Nombre o ID del conjunto de evaluación.
--path <path>	.		Ruta al directorio del proyecto del agente.
--only-failed	Desactivado		Mostrar solo casos de prueba fallidos o con errores.
--verbose	Desactivado		Incluye las justificaciones del evaluador en la salida.
--export-format <json|csv>	—		Escribe las filas formateadas en eval-results-<timestamp>.(json|csv) en lugar de imprimirlas.

Ejemplo

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

Forma de datos (en línea, sin exportación):

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

Cuando se establece --export-format , la carga útil se convierte en Code: "AgentEvalRunExported" con Format, File y Records.

lista de ejecución de evaluación

Enumerar todas las ejecuciones para un conjunto de evaluación determinado.

Opciones

• --set <name> (obligatorio)
• --path <path> (predeterminado .)

Forma de datos

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

comparación de ejecución de evaluación

Compara dos ejecuciones una al lado de la otra. Útil para cambios de solicitud o modelo de pruebas A/B.

Argumentos

• <evalSetRunId> : primer ID de ejecución (base de referencia).

Opciones

Marca	Predeterminado	Obligatorio	Propósito
--compare-to <id>	—	Sí	ID de segunda ejecución con el que comparar.
--set <name>	—	Sí	Nombre o ID del conjunto de evaluación.
--path <path>	.		Ruta al directorio del proyecto del agente.

Forma de datos (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 — envía el agente a Studio Web y deja el SolutionStorage.json que eval run start detecta automáticamente (a menos que se proporcione --solution-id , o el proyecto califique para la ruta implícita del espacio de trabajo local).
• uip agent validate — el conjunto de evaluación predeterminado y los evaluadores son creados por init; validate los mantiene coherentes.
• uip agent debug : ejecuta el agente una vez en Studio Web con entradas de muestra; distinta de una ejecución de evaluación de Agent Runtime.

Ver también

• Autenticación : sesiones y validez del token para los subcomandos eval run .
• Opciones globales, códigos de salida.