> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-es/agente/evaluation.md).

# Evaluaciones

Evaluación de la salida y el comportamiento de tu sistema agéntico

{% hint style="warning" %}

#### Habilidad del agente de programación

Usa **`/neuron-evaluation`** para enseñarle a tu agente de programación cómo implementar un conjunto completo de evaluaciones para tus entidades agénticas.

[Desarrollo asistido por IA](https://docs.neuron-ai.dev/neuron-v3-es/resumen/agentic-development.md)
{% endhint %}

Esta guía cubre enfoques para evaluar agentes. Una evaluación eficaz es esencial para medir el rendimiento del agente, seguir las mejoras y garantizar que tu sistema agéntico cumpla los estándares de calidad.

Es importante considerar diversos factores cualitativos y cuantitativos, incluidas la sintaxis de la respuesta, la finalización de la tarea, el éxito y las inexactitudes o alucinaciones. En las evaluaciones, también es importante comparar distintas configuraciones para optimizar resultados específicos deseados. Dada la naturaleza dinámica y no determinista de los LLM, también es importante realizar evaluaciones rigurosas y frecuentes para garantizar una línea base coherente que permita seguir mejoras o regresiones.

### Por qué necesitas evaluaciones

Las evaluaciones cumplen un papel que va más allá de la práctica técnica y no tienen equivalente en el desarrollo de software tradicional. La calidad de un agente es probabilística: no existe un binario «funciona» al que apuntar, así que la pregunta «¿está listo?» no tiene una respuesta obvia. Un conjunto sólido de evaluaciones se convierte en esa respuesta, en una definición compartida y objetiva de «suficientemente bueno» que construyes junto con tu cliente o las partes interesadas. Cuando preguntan cómo va el proyecto, no respondes con anécdotas e impresiones de las demos: muestras la tasa de éxito en un conjunto de datos que todos acordaron que representa los casos de uso reales, y cómo ha cambiado desde la última versión. Cuando un cliente informa de una mala interacción, esa interacción se convierte en un nuevo elemento del conjunto de datos: una queja convertida en un caso de prueba medible que ya no puede degradarse silenciosamente.

Esto es algo profundamente distinto de las pruebas unitarias. Las pruebas unitarias nunca tuvieron este papel: son una herramienta interna de ingeniería, invisible fuera del equipo; nadie ha discutido jamás el estado de un proyecto con un cliente mirando un conjunto de pruebas. Las evaluaciones miran hacia afuera. Son el instrumento que usas para negociar expectativas mientras iteras, para gestionar la relación con las personas que dependen del sistema y para demostrar, versión tras versión, que el agente mejora en lo que de verdad les importa.

### Configuración de tu aplicación

Al igual que con las pruebas unitarias, podría ser mejor recopilar los evaluadores de tu sistema de IA en un directorio dedicado. Así, puedes añadir la configuración siguiente a tu aplicación `composer.json` archivo para indicarle a Composer cómo incluir tus evaluadores en los espacios de nombres de la aplicación:

```json
"autoload-dev": {
    "psr-4": {
        ...,
        "App\\Evaluators\\": "evaluators/"
    }
},
```

A continuación crea el `evaluators` directorio en la carpeta raíz de tu proyecto. Mantener el código de evaluación separado del código de producción crea un límite claro entre lo que se despliega en producción y lo que existe únicamente para el desarrollo y el aseguramiento de la calidad.

### Archivo bootstrap personalizado

Por defecto, la `neuron` CLI solo carga el autoloader de Composer de tu proyecto (`vendor/autoload.php`). Eso es suficiente cuando tus clases son PHP puro y resolubles por Composer, pero a menudo no lo son: un evaluador podría leer la configuración mediante los ayudantes de tu framework, necesitar variables de entorno cargadas desde `.env`, depender de constantes o requerir que se inicialice un contenedor de servicios. En esos casos, el comando fallaría con errores de clase no encontrada o de configuración faltante, porque el código que normalmente prepara ese entorno —el bootstrap de tu framework— nunca se ejecuta.

El `--autoload-file` opción resuelve esto al permitirte indicar a la CLI un archivo PHP que se ejecutará *antes de* cuando comienza el comando, además del autoloader de Composer predeterminado:

```bash
vendor/bin/neuron evaluation /path/to/evaluators --autoload-file=bootstrap.php
```

El archivo puede hacer cualquier cosa que haría un bootstrap normal: registrar autoloaders adicionales, cargar variables de entorno, definir constantes o arrancar tu framework. Por ejemplo, para ejecutar evaluadores que dependen de una aplicación Laravel:

```php
<?php
// bootstrap.php

require __DIR__.'/vendor/autoload.php';

$app = require_once __DIR__.'/bootstrap/app.php';
$app->make(Illuminate\\Contracts\\Console\\Kernel::class)->bootstrap();
```

### Creación de evaluadores

Usa el siguiente comando para crear la `AgentEvaluator` clase en la carpeta de evaluadores:

{% tabs %}
{% tab title="Unix" %}

```bash
vendor/bin/neuron make:evaluator App\\Neuron\\Evaluators\\AgentEvaluator
```

{% endtab %}

{% tab title="Windows" %}

```powershell
.\vendor\bin\neuron make:evaluators App\Neuron\Evaluators\AgentEvaluator
```

{% endtab %}
{% endtabs %}

La clase que se creará tendrá la siguiente estructura:

```php
namespace App\Neuron\Evaluators;

use NeuronAI\Evaluation\Assertions\StringContains;
use NeuronAI\Evaluation\BaseEvaluator;
use NeuronAI\Evaluation\Contracts\DatasetInterface;
use NeuronAI\Evaluation\Dataset\JsonDataset;

class AgentEvaluator extends BaseEvaluator
{
    /**
     * 1. Obtén el conjunto de datos contra el que evaluar
     */
    public function getDataset(): DatasetInterface
    {
        return new JsonDataset(__DIR__ . '/datasets/dataset.json');
    }

    /**
     * 2. Ejecuta la lógica del agente que se está probando
     */
    public function run(array $datasetItem): mixed
    {
        $response = MyAgent::make()->chat(
            new UserMessage($datasetItem['input'])
        )->getMessage();
        
        return $response->getContent();
    }

    /**
     * 3. Evalúa la salida frente a los resultados esperados, con aserciones
     */
    public function evaluate(mixed $output, array $datasetItem): void
    {
        $this->assert(
            new StringContains($datasetItem['reference']),
            $output,
        );
    }
} 
```

La lógica es bastante sencilla. El evaluador primero carga el conjunto de datos y luego ejecuta la evaluación para cada elemento del conjunto de datos.

En el `run` método puedes ejecutar tus entidades agénticas con la entrada de ejemplo y devolver la salida. Luego, la salida se pasa al `evaluar` método donde puedes realizar aserciones comparando la salida con un valor de referencia o con cualquier otra lógica que quieras.

### Cargador de conjuntos de datos

Puedes usar lo que quieras como conjunto de datos. No existe un formato predefinido. La clase evaluadora simplemente te permite cargar una lista de casos de prueba y ejecutar los evaluadores contra ellos. Tienes dos cargadores de conjuntos de datos.

#### ArrayDataset

```php
class AgentEvaluator extends BaseEvaluator
{
    public function getDataset(): DatasetInterface
    {
        return new ArrayDataset([
            [
                'input' => 'Hi',
                'reference' => 'help'
            ]
        ]);
    }
    
    ...
}
```

#### JsonDataset

```php
class AgentEvaluator extends BaseEvaluator
{
    public function getDataset(): DatasetInterface
    {
        return new JsonDataset(__DIR__ . '/datasets/dataset.json');
    }
    
    ...
}
```

Eventualmente, puedes crear un cargador de conjunto de datos personalizado implementando `NeuronAI\Evaluation\Contracts\DatasetInterface`.

### Ejecución de evaluaciones

Si has configurado correctamente tu archivo composer, puedes usar la CLI de Neuron para lanzar los evaluadores:

{% tabs %}
{% tab title="Unix" %}

```bash
vendor/bin/neuron evaluations --path=evaluators
```

{% endtab %}

{% tab title="Windows" %}

```powershell
.\vendor\bin\neuron evaluations --path=evaluators
```

{% endtab %}
{% endtabs %}

### Aserciones

Proporcionamos un conjunto de aserciones integradas para el caso de uso más común. También puedes implementar tu propia aserción para diseñar sistemas de puntuación personalizados. Consulta la siguiente sección.

**StringContains**

```php
$this->assert(new StringContains('positive'), $output);
```

**StringContainsAll**

Comprueba si la salida contiene todas las palabras clave:

```php
$this->assert(new StringContainsAll(['hello', 'world']), $output);
```

**StringContainsAny**

Comprueba si la salida contiene alguna de las palabras clave:

```php
$this->assert(new StringContainsAny(['success', 'completed']), $output);
```

**StringStartsWith**

Comprueba si la salida comienza con un prefijo:

```php
$this->assert(new StringStartsWith('Hello'), $output);
```

**StringEndsWith**

Comprueba si la salida termina con un sufijo:

```php
$this->assert(new StringEndsWith('!'), $output);
```

**StringLengthBetween**

Comprueba si la longitud de la cadena está dentro del rango:

```php
$this->assert(new StringLengthBetween(10, 100), $output);
```

**StringDistance**

Comprueba la similitud de cadenas usando la distancia de Levenshtein:

```php
$this->assert(new StringDistance(
    reference: 'expected text',
    threshold: 0.5, // Puntuación mínima de similitud
    maxDistance: 50 // Número máximo de ediciones permitido
), $output);
```

**StringSimilarity**

Comprueba la similitud de cadenas usando embeddings:

```php
use NeuronAI\Evaluation\Assertions\StringSimilarity;
use NeuronAI\RAG\Embeddings\OpenAI\OpenAIEmbeddings;

$this->assert(new StringSimilarity(
    reference: 'The quick brown fox',
    embeddingsProvider: new OpenAIEmbeddings(key: 'YOUR_KEY'),
    threshold: 0.6
), $output);
```

**MatchesRegex**

Coincide con una expresión regular:

```php
$this->assert(new MatchesRegex('/^\d{3}-\d{2}-\d{4}$/'), $output);
```

**IsValidJson**

Comprueba si la salida es JSON válido:

```php
$this->assert(new IsValidJson(), $output);
```

### IA como juez

Usa un agente de IA para evaluar las salidas con criterios personalizados. Neuron te proporciona la clase primitiva AgentJudge para definir tus propios criterios personalizados; de lo contrario, puedes usar una de las aserciones de juez integradas.

```php
use NeuronAI\Evaluation\Assertions\AgentJudge;

class AgentJudgeEvaluator extends BaseEvaluator
{
    protected AgentInterface $judge;

    public function setUp(): void
    {
        $this->judge = Agent::make()
            ->setAiProvider(
                new Antrhopic(...)
            )
            ->setInstructions('You are an expert evaluator for customer support responses.');
    }

    public function getDataset(): DatasetInterface
    {
        return new JsonDataset(...);
    }

    public function run(array $datasetItem): mixed
    {
        $response = MyAgent::make()->chat(
            new UserMessage($datasetItem['input'])
        )->getMessage();
        
        return $response->getContent();
    }
    
    public function evaluate(mixed $output, array $datasetItem): void
    {
        $this->assert(new AgentJudge(
            judge: $this->judge,
            criteria: 'Response should be helpful, polite, and address the customer\'s question directly',
            threshold: $datasetItem['threshold']
        ), $output);
    }
}
```

#### Juez de fidelidad

Comprueba si la salida está fundamentada en el contexto (sin alucinaciones):

```php
$this->assert(new FaithfulnessJudge(
    judge: $this->judge,
    context: $retrievedDocuments,
    threshold: 0.7
), $output);
```

#### Juez de corrección

Comparar con la respuesta esperada:

```php
$this->assert(new CorrectnessJudge(
    judge: $judge,
    expected: $datasetItem['expected_answer'],
    threshold: 0.7
), $output);
```

#### Juez de relevancia

Comprueba si la salida responde a la pregunta:

```php
$this->assert(new RelevanceJudge(
    judge: $judge,
    question: $datasetItem['question'],
    threshold: 0.7
), $output);
```

#### Juez de utilidad

Evalúa la utilidad y la capacidad de acción:

```php
$this->assert(new HelpfulnessJudge(
    judge: $judge,
    threshold: 0.7
), $output);
```

### Creación de aserciones personalizadas

```php
use NeuronAI\Evaluation\Assertions\AbstractAssertion;
use NeuronAI\Evaluation\AssertionResult;

class GreaterThanAssertion extends AbstractAssertion
{
    public function __construct(
        private readonly float $threshold
    ) {}

    public function evaluate(mixed $actual): AssertionResult
    {
        if (!is_numeric($actual)) {
            return AssertionResult::fail(
                0.0,
                'Se esperaba un valor numérico, se obtuvo ' . gettype($actual),
            );
        }

        if ($actual > $this->threshold) {
            return AssertionResult::pass(1.0);
        }

        return AssertionResult::fail(
            0.0,
            "Se esperaba que {$actual} fuera mayor que {$this->threshold}",
        );
    }
}
```

### Salida

El módulo de evaluación usa un archivo de configuración de PHP para controlar cómo se muestran los resultados de la evaluación. El sistema de configuración admite varios controladores de salida, lo que permite enviar los resultados a la consola, archivos, bases de datos o APIs externas simultáneamente.

#### **Archivo de configuración**

Crea el `evaluation.php` archivo en la raíz de tu proyecto:

```php
<?php

use NeuronAI\Evaluation\OutputDrivers\ConsoleDriver;
use NeuronAI\Evaluation\OutputDrivers\JsonDriver;

return [
    'output' => [
        // Muestra los resultados en la consola
        ConsoleDriver::class,
        // nueva ConsoleDriver(verbose: true),

        // Guarda los resultados en un archivo json
        new JsonDriver(path: 'evaluation-results.json'),
    ],
];
```

Puedes proporcionar una cadena de clase para clases con constructor sin argumentos o directamente una instancia concreta.

**Si no existe un archivo de configuración**, el sistema usa por defecto `ConsoleDriver` con salida estándar.

#### Creación de salida personalizada

Implementa `EvaluationOutputInterface` para crear controladores de salida personalizados:

```php
namespace App\Neuron\Evaluations;

use NeuronAI\Evaluation\Contracts\EvaluationOutputInterface;
use NeuronAI\Evaluation\Runner\EvaluatorSummary;

class DatabaseOutput implements EvaluationOutputInterface
{
    public function __construct(
        private readonly \PDO $pdo,
        private readonly string $table = 'evaluations'
    ) {}

    public function output(EvaluatorSummary $summary): void
    {
        $stmt = $this->pdo->prepare(
            "INSERT INTO {$this->table} (passed, failed, success_rate, total_time, created_at, updated_at) VALUES (?, ?, ?, ?, NOW(), NOW())"
        );
        $stmt->execute([
            $summary->getPassedCount(),
            $summary->getFailedCount(),
            $summary->getSuccessRate(),
            $summary->getTotalExecutionTime(),
        ]);
    }
}
```

Una vez que hayas creado tu clase de salida, puedes registrarla en el archivo de configuración para que se use la próxima vez que ejecutes las evaluaciones.

```php
<?php

use NeuronAI\Evaluation\OutputDrivers\ConsoleDriver;
use NeuronAI\Evaluation\OutputDrivers\JsonDriver;

return [
    'output' => [
        // Muestra los resultados en la consola
        new ConsoleDriver(verbose: true),

        // Guarda los resultados en un archivo json
        //new JsonDriver(path: 'evaluation-results.json'),
        
        // Guarda los resultados en la base de datos
        new DatabaseOutput(
            pdo: new \PDO(...),
            table: 'evaluations',
        )
    ],
];
```

### Evaluaciones en paralelo

De forma predeterminada, el comando de evaluación procesa los elementos del conjunto de datos uno por uno. Como la mayoría de los evaluadores pasa su tiempo esperando respuestas del proveedor de IA, puedes reducir drásticamente el tiempo total de ejecución procesando varios elementos del conjunto de datos en paralelo con la `--concurrency` opción:

```bash
vendor/bin/neuron evaluation path/to/evaluators --concurrency=3
```

Con `--concurrency=3`, se evalúan hasta 3 elementos del conjunto de datos al mismo tiempo, cada uno en su propio proceso hijo de PHP. Una evaluación que hace una llamada al LLM de 2 segundos por elemento sobre un conjunto de datos de 100 elementos baja de \~200 segundos a \~66 segundos.

#### Requisitos

La ejecución en paralelo se basa en la creación de procesos hijo, lo cual requiere:

* El [pcntl](https://www.php.net/manual/en/book.pcntl.php) extensión de PHP (disponible en Linux y macOS — no en Windows)
* El [spatie/fork](https://github.com/spatie/fork) paquete:

```bash
composer require --dev spatie/fork
```

Si falta cualquiera de los dos, el comando muestra un aviso y vuelve automáticamente a la ejecución secuencial, de modo que el mismo comando funciona en cualquier entorno.

#### Cómo elegir un nivel de concurrencia

Cada elemento en curso es una solicitud activa a tu proveedor de IA. Empieza con un valor moderado (3–5) y súbelo mientras no alcances los límites de frecuencia del proveedor. Si ves que aparecen errores de límite de frecuencia como fallos de prueba, baja el valor.

#### Cómo funciona y qué debes vigilar

Cada elemento del conjunto de datos se ejecuta en una copia bifurcada de tu evaluador, y su resultado se envía de vuelta al proceso principal. Esto tiene varias implicaciones prácticas:

* **Los resultados no se ven afectados.** Los elementos se evalúan de forma independiente, los resultados conservan el orden de su conjunto de datos y el informe final es idéntico al de una ejecución secuencial.
* **El estado no se comparte entre elementos.** Cada elemento ve el estado del evaluador tal como estaba después de `setUp()`. Los efectos secundarios realizados al procesar un elemento (incrementar una propiedad, añadir a un archivo) no son visibles para los demás elementos. Si tu evaluador depende de acumular estado entre elementos, ejecútalo de forma secuencial.
* **Las salidas deben ser serializables.** El valor devuelto por `run()` cruza un límite de proceso mediante `serialize()`. Si no puede serializarse (por ejemplo, contiene un cierre o una conexión abierta), los resultados de la aserción se conservan, pero la salida mostrada en los informes se sustituye por una cadena de marcador de posición.

#### Informe del tiempo de ejecución

El tiempo total informado es la duración real en tiempo de reloj de la ejecución, mientras que el tiempo medio por prueba refleja la duración real de cada elemento individual; así que, en ejecución paralela, el promedio por prueba puede ser mayor que el total dividido por el número de pruebas.

## Evaluación de conversaciones de varios turnos

Los evaluadores que has visto hasta ahora siguen un patrón sencillo: ejecutas tu agente una vez, obtienes una salida y haces aserciones sobre ella. Esto funciona bien para tareas de una sola pasada, pero no refleja cómo funcionan realmente las aplicaciones agénticas. Un agente de IA aporta valor a lo largo de toda una conversación: recopila información en varios turnos, decide qué herramientas llamar y con qué argumentos, pide a un humano aprobación antes de acciones peligrosas y se recupera cuando esa aprobación se deniega.

Evaluar solo la respuesta final se pierde la mayor parte de este comportamiento. El agente puede haber dado una respuesta perfectamente educada mientras llamaba a la herramienta equivocada, omitía una búsqueda necesaria o ejecutaba una acción que debía haber enviado primero para aprobación.

Neuron proporciona dos componentes para cerrar esta brecha, y una frase resume cómo se relacionan: **ejecutas una Conversación; evalúas su Trayectoria.**

* `Conversación` es el ayudante de ejecución. Conduce a tu agente a través de un intercambio de varios turnos dentro del `run()` método del evaluador —entregando turnos de usuario, respondiendo a solicitudes de aprobación o incluso dejando que otra IA haga de usuario.
* `Trayectoria` es el sujeto registrado. Envuelve los mensajes de la conversación y responde preguntas de evaluación sobre lo que realmente ocurrió: qué herramientas se invocaron, con qué argumentos, qué se aprobó o rechazó y qué dijo finalmente el agente.

### Ejecución de una conversación

Usa `Conversación` dentro de `run()` para guionizar un intercambio de varios turnos. Cada turno solo se entrega después de que el anterior se haya completado por completo:

```php
use NeuronAI\Evaluation\BaseEvaluator;
use NeuronAI\Evaluation\Contracts\DatasetInterface;
use NeuronAI\Evaluation\Conversation\Conversation;
use NeuronAI\Evaluation\Dataset\JsonDataset;

class RefundConversationEvaluator extends BaseEvaluator
{
    public function getDataset(): DatasetInterface
    {
        return new JsonDataset(__DIR__ . '/datasets/refunds.json');
    }

    public function run(array $datasetItem): mixed
    {
        return Conversation::make(MyAgent::make())
            ->withTurns($datasetItem['turns'])
            ->run();
    }

    public function evaluate(mixed $trajectory, array $datasetItem): void
    {
        // Aserta contra la Trayectoria devuelta (siguientes secciones)
    }
}
```

Los turnos son una lista simple, así que pueden vivir directamente en tu conjunto de datos JSON:

```json
[
    {
        "turns": [
            "Hi, I want a refund for order #123",
            "Yes, please proceed."
        ]
    }
]
```

Las entradas pueden ser cadenas simples o `UserMessage` instancias, así que también puedes guionizar turnos que contengan imágenes o documentos.

### La Trayectoria

Un historial de chat es una lista en bruto de mensajes, y hacer aserciones directamente sobre él significa escribir la misma plantilla en cada evaluador: emparejar las llamadas a herramientas con sus resultados, leer los estados de aprobación, extraer la respuesta final. La `Trayectoria` devuelta por `Conversation::run()` hace este trabajo una sola vez y expone lo que realmente quieres preguntar:

```php
$trajectory->toolCalls();                // cada llamada a herramienta, en orden de ejecución
$trajectory->toolCalls('refund_order'); // filtrado por nombre de la herramienta
$trajectory->lastToolCall();            // la llamada más reciente (o null)
$trajectory->finalAnswer();             // la última respuesta del agente ('' si no hay ninguna)
$trajectory->userMessages();            // el lado del usuario de la conversación
$trajectory->usage();                   // uso agregado de tokens de toda la conversación
$trajectory->toTranscript();            // transcripción legible por humanos (lo que leen los jueces de IA)
$trajectory->messages();                // los mensajes subyacentes, con fidelidad completa
```

`toolCalls()` devuelve los propios `ToolInterface` objetos del framework, así que los inspeccionas con la API que ya conoces — `getInputs()`, `getResult()`, `getApprovalState()`. Cuando una llamada aparece dos veces en el historial (la instantánea pendiente cuando el agente la propuso y el resultado final después de ejecutarse), la Trayectoria las fusiona en una sola entrada, y prevalece el resultado final.

No necesitas el `Conversación` ayudante para obtener una Trayectoria. Si conduces el agente tú mismo —con un bucle personalizado, streaming o un flujo de trabajo a medida— puedes proyectar cualquier historial de chat y usar las mismas aserciones:

```php
use NeuronAI\Evaluation\Trajectory\Trajectory;

$trajectory = Trajectory::fromChatHistory($agent->getChatHistory());
```

Dado que `usage()` agrega los recuentos de tokens informados por el proveedor en cada turno, también puedes vigilar las regresiones de coste como parte de tu conjunto de evaluación:

```php
$this->assert(
    new GreaterThanAssertion($datasetItem['token_budget']),
    $trajectory->usage()->getTotal()
);
```

### Aserciones de trayectoria

Estas aserciones responden a preguntas que las comprobaciones de la salida final no pueden responder: ¿tomó el agente el camino correcto hacia la respuesta?

#### **ToolWasCalled**

Verifica que el agente haya invocado una herramienta, restringiendo opcionalmente sus argumentos. La forma de arreglo es una coincidencia por subconjunto: cada clave listada debe estar presente y ser igual, y se permiten argumentos adicionales:

```php
use NeuronAI\Evaluation\Assertions\Trajectory\ToolWasCalled;

// La herramienta fue llamada, con cualquier argumento
$this->assert(new ToolWasCalled('search_orders'), $trajectory);

// La herramienta fue llamada con estos argumentos
$this->assert(
    new ToolWasCalled('refund_order', ['order_id' => '123']),
    $trajectory
);

// Control total con una callable
$this->assert(
    new ToolWasCalled('refund_order', fn (array $inputs): bool => $inputs['amount'] <= 100),
    $trajectory
);
```

#### **ToolWasNotCalled**

La aserción de protección — verifica que el agente lo hizo *no* tomar una ruta prohibida:

```php
use NeuronAI\Evaluation\Assertions\Trajectory\ToolWasNotCalled;

$this->assert(new ToolWasNotCalled('delete_account'), $trajectory);
```

#### **TrajectoryMatches**

Verifica la secuencia de llamadas a herramientas frente a una lista esperada de nombres de herramientas. El `Mode` enum decide cuán estricta es la comparación:

```php
use NeuronAI\Evaluation\Assertions\Trajectory\Mode;
use NeuronAI\Evaluation\Assertions\Trajectory\TrajectoryMatches;

$this->assert(
    new TrajectoryMatches(['search_orders', 'refund_order'], Mode::Subset),
    $trajectory
);
```

* `Mode::Strict` — exactamente estas llamadas, en este orden, nada más. Lo mejor para fijar una línea base de regresión.
* `Mode::Unordered` — las mismas llamadas, en cualquier orden.
* `Mode::Subset` — las llamadas esperadas aparecen en este orden; se permiten llamadas adicionales entre medio. Ideal cuando te importa la ruta esencial pero toleras llamadas incidentales.
* `Mode::Superset` — ninguna llamada fuera del conjunto esperado. La lista esperada actúa como una lista permitida.

La lista esperada son cadenas de texto simples, así que puede vivir en tu conjunto de datos junto a los turnos.

#### **ToolWasApproved / ToolWasRejected**

Verifica la decisión humana registrada en una llamada a herramienta (consulta la siguiente sección para ver cómo se producen esas decisiones durante una evaluación):

```php
use NeuronAI\Evaluation\Assertions\Trajectory\ToolWasApproved;
use NeuronAI\Evaluation\Assertions\Trajectory\ToolWasRejected;

$this->assert(new ToolWasApproved('send_email'), $trajectory);
$this->assert(new ToolWasRejected('refund_order'), $trajectory);
```

Observa que no hay aserciones dedicadas para la respuesta final: todo lo que aprendiste en las secciones anteriores sigue aplicando. Pasa `$trajectory->finalAnswer()` a las aserciones de cadena, o a un juez de IA:

```php
$this->assert(new StringContains('no se puede procesar'), $trajectory->finalAnswer());
```

### Evaluación con intervención humana

Si tu agente usa el `ToolApproval` middleware, `chat()` no devuelve una respuesta cuando se solicita una herramienta con control de acceso — se suspende, esperando una decisión humana. En producción, una persona ve la acción pendiente y la aprueba o la rechaza. En una evaluación no hay una persona, así que sin ayuda la conversación simplemente se quedaría atascada.

Al mismo tiempo, estos son precisamente los flujos que más quieres probar: ¿el agente solicita aprobación antes de acciones peligrosas? ¿Se recupera con elegancia cuando la persona dice que no?

El `withApprovals()` método te permite programar al aprobador. La función callable que pasas se invoca cada vez que el agente se suspende —en cualquier punto de la conversación— y devuelve las decisiones:

```php
use NeuronAI\Evaluation\Trajectory\Trajectory;
use NeuronAI\Workflow\Interrupt\ApprovalRequest;

Conversation::make($agent)
    ->withTurns($datasetItem['turns'])
    ->withApprovals(function (ApprovalRequest $request, Trajectory $soFar): array {
        $payload = [];

        foreach ($request->getActions() as $action) {
            if ($action->isPending()) {
                $payload[$action->id] = 'approve';   // o ['reject', 'el motivo']
            }
        }

        return $payload;
    })
    ->run();
```

Es un método separado —no una entrada en el guion de turnos— porque no puedes saber de antemano en *qué* turno decidirá el modelo invocar la herramienta restringida. La política no depende de la posición: responde siempre que ocurre la suspensión.

El segundo argumento te da la conversación hasta el momento, que es como escribes decisiones que dependen de los argumentos de la herramienta:

```php
->withApprovals(function (ApprovalRequest $request, Trajectory $soFar): array {
    $payload = [];

    foreach ($request->getActions() as $action) {
        $args = $soFar->lastToolCall($action->name)?->getInputs();

        $payload[$action->id] = ($args['amount'] ?? 0) > 100
            ? ['reject', 'Por encima del umbral de aprobación automática']
            : 'approve';
    }

    return $payload;
})
```

Dos reglas mantienen honestas las evaluaciones, ambas aplicadas con una `EvaluationException` que marca el elemento del conjunto de datos como un error:

* Si el agente se suspende y no hay ninguna política configurada, la evaluación falla de forma explícita. Deliberadamente no hay un valor predeterminado de "aprobar todo" —eso falsearía en silencio el comportamiento humano exacto que estás midiendo.
* El payload devuelto debe contener una decisión para cada acción pendiente. El sistema de aprobación de Neuron nunca trata el silencio como consentimiento, y un conjunto de decisiones incompleto dejaría el flujo de trabajo suspendido para siempre.

El rechazo, el motivo entregado al modelo y la recuperación del agente terminan todos en la Trayectoria —donde `ToolWasRejected` y las aserciones de cadena sobre `finalAnswer()` pueden verificarlas.

### Usuarios simulados

Una lista de turnos guionizada tiene un límite: no puede reaccionar a lo que el agente realmente dice. Si el agente hace una pregunta de aclaración que tu guion no anticipó, el siguiente turno guionizado sonará inconexo. Los usuarios reales se adaptan —y probar cómo tu agente maneja a un interlocutor adaptativo requiere uno.

`UserSimulator` es un agente de IA que hace de usuario. Le das una personalidad y un objetivo, y en cada paso lee la conversación hasta el momento y decide: continuar con un nuevo mensaje, o detenerse porque el objetivo se ha cumplido (o porque se rinde):

```php
use NeuronAI\Evaluation\Conversation\UserSimulator;

$simulator = UserSimulator::make()
    ->withPersona('Un cliente impaciente que da respuestas cortas')
    ->withGoal('Obtener un reembolso para el pedido #123');

$simulator->setAiProvider(new Anthropic(key: '...', model: '...'));

$trajectory = Conversation::make($agent)
    ->withUser($simulator, maxTurns: 10)
    ->run();
```

`withUser()` sustituye `withTurns()` — una conversación es o bien guionizada o bien simulada, no ambas. Algunas cosas que conviene saber:

* `maxTurns` es obligatorio. Es un límite estricto para el número de turnos del usuario, y no existe un valor predeterminado infinito. Alcanzar el límite termina la conversación *normalmente*: si una conversación inacabada cuenta como un fallo es una decisión para tus aserciones (el `TaskCompletionJudge` de abajo encaja de forma natural), no para el ejecutor.
* El simulador decide por sí mismo cuándo se alcanza el objetivo —no interviene ningún modelo árbitro separado.
* El simulador nunca responde a solicitudes de aprobación. En producción, el usuario que conversa con tu agente y la persona que aprueba sus acciones son personas distintas, y la evaluación preserva esa separación: las aprobaciones se quedan con `withApprovals()`, también en conversaciones simuladas.

Dado que `UserSimulator` es un agente normal de Neuron, puedes respaldarlo con cualquier proveedor —incluso con un modelo más barato que el que se está probando.

### Evaluando toda la conversación

Los jueces de IA que viste antes evalúan una sola pieza de texto. Pero algunas preguntas solo pueden responderse mirando todo el intercambio: ¿el agente realmente logró lo que el usuario venía a buscar, considerando las herramientas que ejecutó, las aprobaciones que le fueron denegadas y todo lo que dijo en el camino?

Todos los jueces ahora aceptan una `Trayectoria` directamente. Cuando pasas una, el juez recibe la transcripción completa de la conversación —turnos del usuario y del asistente, llamadas a herramientas con sus argumentos y resultados, y decisiones de aprobación con sus motivos:

```php
use NeuronAI\Evaluation\Assertions\Judges\TaskCompletionJudge;

$this->assert(
    new TaskCompletionJudge(
        judge: $this->judge,
        goal: $datasetItem['goal'],
        threshold: 0.7
    ),
    $trajectory
);
```

`TaskCompletionJudge` está calibrado precisamente para esta pregunta. Puntúa el cumplimiento del objetivo a lo largo de toda la trayectoria y sabe cómo ponderar los resultados con intervención humana: a un agente cuya acción fue rechazada por el aprobador se le juzga por cómo manejó el rechazo, no se le castiga por la negativa en sí.

El genérico `AgentJudge` y los demás jueces preconfigurados aceptan una Trajectory de la misma manera, así que puedes evaluar el tono, la utilidad o criterios personalizados frente a la conversación completa en lugar de un solo mensaje.

### Poniéndolo todo junto

Un evaluador completo para un escenario de reembolso con aprobación humana:

```php
use NeuronAI\Evaluation\Assertions\Judges\TaskCompletionJudge;
use NeuronAI\Evaluation\Assertions\StringContains;
use NeuronAI\Evaluation\Assertions\Trajectory\Mode;
use NeuronAI\Evaluation\Assertions\Trajectory\ToolWasRejected;
use NeuronAI\Evaluation\Assertions\Trajectory\TrajectoryMatches;
use NeuronAI\Evaluation\BaseEvaluator;
use NeuronAI\Evaluation\Contracts\DatasetInterface;
use NeuronAI\Evaluation\Conversation\Conversation;
use NeuronAI\Evaluation\Dataset\JsonDataset;
use NeuronAI\Evaluation\Trajectory\Trajectory;
use NeuronAI\Workflow\Interrupt\ApprovalRequest;

class RefundConversationEvaluator extends BaseEvaluator
{
    private AgentInterface $judge;

    public function setUp(): void
    {
        $this->judge = JudgeAgent::make();
    }

    public function getDataset(): DatasetInterface
    {
        return new JsonDataset(__DIR__ . '/datasets/refunds.json');
    }

    public function run(array $datasetItem): mixed
    {
        return Conversation::make(RefundAgent::make())
            ->withTurns($datasetItem['turns'])
            ->withApprovals(function (ApprovalRequest $request, Trajectory $soFar) use ($datasetItem): array {
                $payload = [];

                foreach ($request->getActions() as $action) {
                    $payload[$action->id] = $datasetItem['decisions'][$action->name] ?? 'approve';
                }

                return $payload;
            })
            ->run();
    }

    public function evaluate(mixed $trajectory, array $datasetItem): void
    {
        // El agente siguió la ruta esencial
        $this->assert(new TrajectoryMatches($datasetItem['expected_tools'], Mode::Subset), $trajectory);

        // El reembolso fue denegado por el aprobador
        $this->assert(new ToolWasRejected('refund_order'), $trajectory);

        // ...y el agente lo comunicó en lugar de fingir que funcionó
        $this->assert(new StringContains('no puede'), $trajectory->finalAnswer());

        // En general: ¿la conversación le fue útil al usuario, dado el rechazo?
        $this->assert(new TaskCompletionJudge($this->judge, goal: $datasetItem['goal']), $trajectory);
    }
}
```

Con el conjunto de datos correspondiente:

```json
[
    {
        "goal": "Obtener un reembolso para el pedido #123",
        "turns": [
            "Hi, I want a refund for order #123",
            "Yes, please proceed."
        ],
        "decisions": {
            "refund_order": ["reject", "El importe supera el límite automático de reembolsos"]
        },
        "expected_tools": ["search_orders", "refund_order"]
    }
]
```

Todo lo demás que sabes sobre el marco de evaluación se aplica sin cambios: la Trajectory no es más que el resultado de `run()`, así que la ejecución en paralelo, los controladores de salida y el ejecutor de CLI funcionan exactamente igual que antes.
