> 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/structured-output.md).

# Salida estructurada

Impón la salida del Agente basándote en el esquema proporcionado.

{% hint style="warning" %}

#### Habilidad del agente de programación

Usa **`/neuron-structured-output`** para enseñarle a tu agente de programación cómo aprovechar las capacidades de Neuron para extraer de forma fiable una salida estructurada de la respuesta del LLM.

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

Hay muchos casos de uso en los que necesitamos que los agentes entiendan lenguaje natural, pero generen una *formato estructurado*. Un caso de uso común es extraer datos de texto para insertarlos en una base de datos o utilizarlos con algún otro sistema posterior. Esta guía explica cómo Neuron te permite imponer salidas estructuradas del agente.

<figure><img src="https://content.gitbook.com/content/GHx4l2LknIex7vFIUg1R/blobs/xv9XXEsc2zlqYCQSFsKa/Neuron%20AI.png" alt=""><figcaption></figcaption></figure>

{% embed url="<https://www.youtube.com/watch?v=T8PM-t_AQ-c>" %}

### Cómo usar la salida estructurada

El concepto central es que la estructura de salida de las respuestas del LLM debe representarse de alguna manera. El esquema contra el que Neuron valida se define mediante las anotaciones de tipo de PHP. Básicamente tienes que definir una clase con propiedades estrictamente tipadas:

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que le gusta comer al usuario.', 
        required: false
    )]
    public string $preference;
}
```

Neuron genera el esquema JSON correspondiente a partir del objeto PHP para indicar al modelo subyacente el formato de datos que necesitas. Luego el agente analiza la salida del LLM para extraer los datos y devuelve una instancia del objeto rellenada con los valores adecuados:

```php
use NeuronAI\Chat\Messages\UserMessage;

// Habla con el agente solicitando la salida estructurada
$person = MyAgent::make()
    ->setThreadId('chat_id')
    ->structured(
        new UserMessage("¡Soy John y me gusta la pizza!"),
        Person::class
    );

echo $person->name.' le gusta '.$person->preference;
// John prefiere pizza
```

### Clase de salida predeterminada

También puedes encapsular el formato de salida en la implementación del agente, de modo que sea el formato de salida estándar del agente. Siempre necesitas llamar al `structured()` método para exigir una salida estricta.

```php
use NeuronAI\Chat\Messages\UserMessage;

// Encapsula el formato de salida predeterminado 
class MyAgent extends Agent
{
    ...

    protected function getOutputClass(): string
    {
        return Person::class;
    }
}

// Usa siempre el método structured si quieres obtener una salida estructurada
$person = MyAgent::make()
    ->setThreadId('chat_id')
    ->structured(new UserMessage("Soy John y me gusta la pizza"));

echo $person->name.' le gusta '.$person->preference;
// John prefiere pizza
```

### Controla la generación de la salida

Neuron requiere que definas dos capas de reglas para crear la clase de salida estructurada.

La primera es la `SchemaProperty` anotación que te permite controlar el esquema JSON enviado al LLM para que entienda el formato de datos requerido.

La segunda capa es la validación. Los atributos de validación garantizarán que los datos obtenidos de la respuesta del LLM sean coherentes con tus requisitos.

<figure><img src="https://content.gitbook.com/content/GHx4l2LknIex7vFIUg1R/blobs/QnOl7e0NLtP9VRBiwaPo/Structured%20Output%20Control.png" alt=""><figcaption></figcaption></figure>

### SchemaProperty

El `SchemaProperty` anotación te permite definir los parámetros del esquema JSON de cada propiedad:

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.',
        required: true,
        minLength: 3,
        maxLength: 255,
    )]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que le gusta comer al usuario.', 
        required: false,
        min: 18,
        max: 64,
    )]
    public ?int $age = null;
}
```

Usar `SchemaProperty` un atributo PHP puro no te permite inyectar información dinámica, como la de una base de datos, porque los atributos están fuera de los bloques de código normales. Imagina que necesitas que las descripciones del esquema sigan la configuración regional del usuario, algo que un atributo PHP no puede hacer.

Tu clase DTO puede implementar la `SchemaPropertiesInterface` y proporcionar el método estático `schemaProperties()`. Indexados por nombre de propiedad, los valores son `SchemaProperty` objetos construidos en tiempo de ejecución:

```php
use NeuronAI\StructuredOutput\SchemaPropertiesInterface;
use NeuronAI\StructuredOutput\SchemaProperty;

class Invoice implements SchemaPropertiesInterface
{
    public string $customerName;

    public float $total;

    // Los atributos siguen funcionando — este no tiene una entrada en tiempo de ejecución, así que se usa el atributo
    #[SchemaProperty(description: 'El número de factura en el formato INV-XXXX')]
    public string $number;

    #[SchemaProperty(anyOf: [InvoiceLine::class])]
    public array $lines;

    public static function schemaProperties(): array
    {
        return [
            // Cualquier PHP en tiempo de ejecución está disponible aquí: traductores, configuración, entorno...
            'customerName' => new SchemaProperty(
                description: translate('invoice.customer_name'), // obtener traducción
                required: true,
            ),
            'total' => new SchemaProperty(
                description: 'Importe total en '.config('billing.currency'), // Desde la configuración de la app
                min: 0,
            ),
        ];
    }
}
```

Las reglas de resolución:

* Una propiedad listada en `schemaProperties()` usa ese `SchemaProperty` objeto (lo **reemplaza** el atributo por completo para esa propiedad — los dos no se fusionan campo por campo).
* Una propiedad no listada recurre a su `#[SchemaProperty]` atributo, si existe.
* Todo funciona idénticamente a los atributos posteriores, incluyendo `anyOf` — así que incluso podrías construir dinámicamente la lista de clases para un array polimórfico, y el `Deserializer` lo hidratará correctamente

### Clase anidada

Puedes construir estructuras de salida complejas utilizando otros objetos PHP como tipo de propiedad. Siguiendo el ejemplo de la `Person` clase, podemos añadir la `dirección` propiedad tipada como otra clase estructurada.

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Property;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Valid;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    #[NotBlank]
    public string $name;
    
    #[SchemaProperty(
        description: 'Lo que le gusta comer al usuario.', 
        required: true
    )]
    public string $preference;
    
    #[SchemaProperty(
        description: 'La dirección para completar la entrega.', 
        required: true
    )]
    public Address $address;
}
```

En el `Address` en la definición requerimos solo las propiedades de calle y código postal, y permitimos que la ciudad esté vacía.

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Address
{
    #[SchemaProperty(
        description: 'El nombre de la calle.', 
        required: true
    )]
    #[NotBlank]
    public string $street;

    #[SchemaProperty(
        description: 'El nombre de la ciudad.', 
        required: false
    )]
    public string $city;

    #[SchemaProperty(
        description: 'El código postal de la dirección.', 
        required: true
    )]
    #[NotBlank]
    public string $zip;
}
```

Ahora, cuando le pidas al agente la salida estructurada, obtendrás de vuelta la instancia rellenada:

```php
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Observability\AgentMonitoring;

// Habla con el agente solicitando la salida estructurada
$person = MyAgent::make()->structured(
    new UserMessage("¡Soy John y quiero una pizza en la calle St. James 00560!"),
    Person::class
);

echo $person->name.' le gusta '.$person->preference.'. Dirección: '.$person->address->street;
// John prefiere pizza. Dirección: St. James Street
```

## Array

Si declaras una propiedad como un array, Neuron asume que la lista de elementos es una lista de cadenas. Si quieres que el array contenga una lista de otros objetos estructurados, puedes especificarlo usando el `anyOf` argumento:

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Person 
{
    #[SchemaProperty(
        description: 'El nombre de usuario.', 
        required: true
    )]
    #[NotBlank]
    public string $name;
    
    #[SchemaProperty(
        description: 'La lista de etiquetas para el perfil del usuario.', 
        required: true,
        anyOf: [Tag::class]
    )]
    public array $tags;
}
```

Y aquí está la implementación hipotética de la `Tag` clase con sus propias reglas de validación e información de propiedades:

```php
<?php

namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\SchemaProperty;
use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Tag
{
    #[SchemaProperty(
        description: 'El nombre de la etiqueta', 
        required: true,
    )]
    #[NotBlank]
    public string $name;
}
```

#### Array con múltiples tipos

Como puedes notar en el ejemplo anterior, el argumento anyOf es un array. Neuron también admite la composición de arrays con múltiples tipos de objeto. Solo enumera los objetos estructurados que el array puede contener y Neuron incluirá todas sus especificaciones en el esquema JSON para el LLM.

```php
class Report
{
    #[SchemaProperty(
        description: 'El contenido del informe', 
        required: true,
        anyOf: [TextBlock::class, TableBlock::class, ImageBlock::class]
    )]
    public array $content;
}
```

## Máximo de reintentos

Dado que el LLM no es perfectamente determinista, es obligatorio contar con un mecanismo de reintento si falta algo en la respuesta del LLM.

Por defecto, Neuron extrae y valida los datos de la respuesta del LLM y, si hay uno o más errores de validación, reintenta automáticamente la solicitud una vez más, informando al LLM sobre lo que salió mal y para qué propiedades.

Eventualmente puedes personalizar el número de veces que el agente debe reintentar para obtener una respuesta correcta del LLM:

```php
$person = MyAgent::make()->structured(
    messages: new UserMessage("¡Soy John y me gusta la pizza!"),
    class: Person::class,
    maxRetries: 3
);
```

Si trabajas con un LLM menos capaz, considera usar un número de reintentos que equilibre la probabilidad de obtener una respuesta válida y el posible consumo de tokens.

Puedes desactivar el reintento simplemente pasando cero. Será un intento único:

```php
$person = MyAgent::make()->structured(
    messages: new UserMessage("¡Soy John y me gusta la pizza!"),
    class: Person::class,
    maxRetries: 0
);
```

## Monitoreo y depuración

Muchas de las aplicaciones que construyas con Neuron contendrán múltiples pasos con múltiples invocaciones de llamadas a LLM. A medida que estas aplicaciones se vuelven cada vez más complejas, resulta crucial poder inspeccionar exactamente qué está ocurriendo dentro de tu sistema agéntico. La mejor manera de hacerlo es con [Inspector](https://inspector.dev/).

{% embed url="<https://docs.inspector.dev/guides/neuron-ai>" %}

## Reglas de validación

Dado que los LLM son sistemas no deterministas y la coherencia de su salida puede verse muy influida por la calidad del contexto que reciben como entrada, y aun así pueden alucinar, proporcionamos un conjunto de reglas de validación que puedes añadir a las propiedades de clases estructuradas para indicar a Neuron que verifique el conjunto final de datos generado por el LLM.

Las reglas de validación permiten a Neuron reenviar la solicitud de generación al LLM varias veces con un informe detallado de lo que estaba mal si una o más propiedades no son válidas, hasta que alcance el valor de [maxRetries](#max-retries) valor.

Si no defines ninguna regla de validación, los datos extraídos de la respuesta del LLM se rellenarán directamente en la clase de salida estructurada.

### #\[NotBlank]

La propiedad bajo validación no puede estar vacía. Acepta la `allowNull` bandera para tratar explícitamente un valor nulo como equivalente a vacío o no.

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\NotBlank;

class Person 
{
    #[NotBlank(allowNull: false)]
    public string $name;
}
```

### #\[Length]

Determina si la longitud de una `cadena` cumple los criterios dados:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Length;

class Person 
{
    #[Length(min: 1, max: 10)]
    public string $name;
    
    #[Length(exactly: 5)]
    public string $zip_code;
}
```

### #\[WordsCount]

Determina si el número de palabras en una `cadena` cumple los criterios dados:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\WordsCount;

class Person 
{
    #[WordsCount(exactly: 10)]
    public string $title;
    
    #[WordsCount(min: 1, max: 10)]
    public string $content;
}
```

### #\[Count]

Determina si el tamaño de un `array` cumple los criterios dados:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Count;

class Person 
{
    #[Count(min: 1, max: 3)]
    public array $dogs;
    
    #[Count(exactly: 1)]
    public array $children;
}
```

### #\[EqualTo] - #\[NotEqualTo]

Estas reglas tienen la misma estructura y significado, y aceptan un único argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente igual (*#\[EqualTo]*) o diferente (*#\[NotEqualTo]*) que el valor de referencia:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\EqualTo;
use NeuronAI\StructuredOutput\Validation\Rules\NotEqualTo;

class Person 
{
    #[EqualTo(reference: 'Rome')]
    public string $city;
    
    #[NotEqualTo(reference: '00502')]
    public string $zip_code;
}
```

### #\[GreaterThan] - #\[GreaterThanEqual]

Estas reglas tienen la misma estructura y significado, y aceptan un único argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente mayor (*#\[GreaterThan]*) o igual (*#\[GreaterThanEqual]*) que el valor de referencia:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\GreaterThan;
use NeuronAI\StructuredOutput\Validation\Rules\GreaterThanEqual;

class Person 
{
    #[GreaterThan(reference: 17)]
    public int $age;
    
    #[GreaterThanEqual(reference: 1)]
    public int $cars;
}
```

### #\[LowerThan] - #\[LowerThanEqual]

Estas reglas tienen la misma estructura y significado, y aceptan un único argumento para definir el valor con el que comparar. La propiedad bajo validación debe ser estrictamente menor (*#\[LowerThan]*) o igual (*#\[LowerThanEqual]*) que el valor de referencia:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\LowerThan;
use NeuronAI\StructuredOutput\Validation\Rules\LowerThanEqual;

class Person 
{
    #[LowerThan(reference: 50)]
    public int $age;
    
    #[LowerThanEqual(reference: 1)]
    public int $cars;
}
```

### #\[OutOfRange]

Determina si un `número` está fuera del rango dado:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\InRange;

class Person 
{
    #[OutOfRange(min: 18, max: 35)]
    public int $age;
    
    // El argumento strict obliga a mantenerse estrictamente fuera de los límites del rango
    #[OutOfRange(min: 48, max: 54, strict: true)]
    public int $size;
}
```

### #\[IsFalse] - #\[IsTrue]

La propiedad bajo validación debe tener exactamente el valor booleano definido por la regla:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IsFalse;
use NeuronAI\StructuredOutput\Validation\Rules\IsTrue;

class Phone
{
    #[IsFalse]
    public bool $iphone;
    
    #[IsTrue]
    public bool $refurbed;
}
```

### #\[IsNull] - #\[IsNotNull]

La propiedad bajo validación debe respetar la condición de nulidad definida por la regla:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IsNotNull;
use NeuronAI\StructuredOutput\Validation\Rules\IsNull;

class Phone
{
    #[IsNotNull]
    public string $brand;
    
    #[IsNull]
    public ?string $test;
}
```

### #\[Json]

La propiedad bajo validación debe contener una cadena JSON válida:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Json;

class Person
{
    #[Json]
    public string $address;
}
```

### #\[Url]

La propiedad bajo validación debe contener una URL válida:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Url;

class Person
{
    #[Url(schemes: ['http', 'https'])]
    public string $website;
}
```

### #\[Email]

La propiedad bajo validación debe contener una dirección de correo electrónico válida:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Email;

class Person
{
    #[Email]
    public string $email;
}
```

### #\[IpAddress]

La propiedad bajo validación debe contener una dirección IP válida:

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\IpAddress;

class Person
{
    #[IpAddress]
    public string $ip;
}
```

### #\[ArrayOf]

La propiedad bajo validación debe ser un array que contenga todos los objetos del tipo dado. Ten en cuenta que también necesitas añadir el doc-block para que el agente pueda instanciar la clase correcta. Usa el nombre completo de la clase en el doc-block.

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\ArrayOf;

class Person
{
    /**
     * @var \App\Neuron\Output\Tag[]
     */
    #[ArrayOf(Tag::class)]
    public array $tags;
}
```

### #\[Regex]

La propiedad bajo validación debe respetar la expresión regular dada.

```php
namespace App\Neuron\Output;

use NeuronAI\StructuredOutput\Validation\Rules\Regex;

class Coupon
{
    #[Regex('/^[A-Z]{2}\\d{4}$/')]
    public string $code;
}
```

## Reglas de validación personalizadas

Las reglas de validación son atributos de PHP, así que para crear una nueva debes extender la AbstractValidationRule del framework y marcar la clase como un atributo de PHP:

```php
namespace App\Neuron\Output;

use Attribute;
use NeuronAI\StructuredOutput\Validation\Rules\AbstractValidationRule;

#[Attribute(Attribute::TARGET_PROPERTY)]
class MyFormatRule extends AbstractValidationRule
{
    public function __construct(protected string $format)
    {
    }

    public function validate(string $name, mixed $value, array &$violations): void
    {
        if (!is_string($value)) {
            $violations[] = $this->buildMessage($name, '{name} debe ser una cadena.');
        } else if (!$this->respectFormat($this->format, $value)) {
            $violations[] = $this->buildMessage(
                $name,
                '{name} debe coincidir con el formato {format}',
                ['format' => $this->pattern]
            );
        }
    }
    
    protected function respectFormat(string $value)
    {
        ...
    }
}
```

Ahora ya puedes usar la regla en tu clase de salida estructurada:

```php
namespace App\Neuron\Output;

class Route
{
    #[MyFormatRule('apps/{id}/show')]
    public string $path;
}
```
