# Libretas de órdenes

Las libretas de órdenes son un mecanismo sencillo de integrar a los agentes y listo para usar que permite llevar un registro de lo que los usuarios solicitan.

Por ejemplo, un restaurante puede crear una libreta de "Pedidos a domicilio", un laboratorio de análisis clínicos una libreta de "Recolección de muestras" y una 
refaccionaria por su parte una libreta de "Órdenes de compra", por citar algunos casos de uso.

Es posible crear libretas de órdenes ilimitadas y para cada una de ellas definir los campos relevantes (que se muestran de primera mano), así como los usuarios 
(perfiles de Induxsoft) que pueden acceder a ellas. 

Existen dos roles principales para trabajar con las libretas: El rol administrativo a cargo del usuario propietario de la libreta, que define sus características y 
el rol operativo que asumen todos los usuarios a quienes se les otorgue el acceso.

Cada orden en una libreta se registra con el estado 'Recibida' (usualmente es el Agente IA quien la registra) y los usuarios operativos pueden cambiar ese estado
a "Atendida" o "Descartada" agregando además una nota.

Este procedimiento simple de gestión de órdenes permite adaptarlo a diferentes escenarios rápidamente sin requerir un sistema especializado de inmediato.

Las órdenes permanecerán disponibles por 30 días, luego el sistema de Induxsoft las eliminará automáticamente.

## Integración

Para conectar una intención a una libreta de órdenes y permitir que el agente las agregue, use el siguiente convenio de llamada:

```
Punto final: https://agent.induxsoft.net/orders/{id_libreta}/
Método: POST
```

Consideraciones:
- La respuesta será un texto basado en la plantilla definida en la configuración de la libreta o bien un mensaje de error
- La carga útil que se admite es la que corresponde al protocolo de integración del agente
- Se sugiere definir un token de autorización a la libreta y configurar el mismo en la intención del agente

Campos especiales:

En la carga útil (según el protocolo de integración del agente), puede incluir los 
siguientes campos que tienen un uso en particular:

- order_guid. Si se establece con un valor correspondiente a una orden existente, 
en lugar de agregar una nueva, el servicio intentará actualizarla.
- order_operation. Si ha establecido el ```order_guid``` use el valor 'discard' para cambiar el estado de la orden a descartada, cualquier otro valor será ignorado.

Importante: Mientras que ```order_guid``` es un identificador global único para cada orden, 
el número (id) de la orden es únicamente un entero consecutivo que inicia en 1 para cada libreta pero que es útil únicamente como referencia rápida para humanos.

### Otras operaciones admitidas

Listar las órdenes de un block

```
Método: GET
Punto final: https://agent.induxsoft.net/orders/{id_libreta}/?limit=n&sd=fechainicio&ed=fechafinal&fil_text=texto libre de búsqueda
```

Actualizar una orden

```
Método: PUT
https://agent.induxsoft.net/order/{order_guid}/
```

Recuperar una orden

```
Método:GET
https://agent.induxsoft.net/order/{order_guid}/
```


Eliminar una orden

```
Método: DELETE

https://agent.induxsoft.net/order/{order_guid}/
```

### Descartar una órden
Para descartar una órden, debe indicar el campo `order_operation` con el valor `discard` dentro de la carga útil de la herramienta. 
Este campo puede enviarse tanto en `params` como en `data`, dependiendo de la estructura utilizada en la solicitud.

## Configuración de la libreta

El nombre de la libreta es requerido y debe ser único.

El campo Tipo de la configuración de la libreta permite indicar qué clase o uso se le está dando a la libreta, por ejemplo: "Pedido" u "Órden a domicilio".

Columnas visibles

Considere que la carga útil esperada es la que corresponde al [protocolo de integración](https://docs.induxsoft.net/es/iae/agentes/protocolo-integracion.md)

```
{
	"intention":"Id de la intención",
	"preliminary_answer":"Respuesta preliminar del LLM",
	"original_question":"Pregunta o mensaje original del usuario",
	"reformulated_question":"Pregunta o mensaje del usuario reformulado por el LLM",
	"agent_id":"Id del agente",
	"agent_name":"Nombre del agente",
	"source_url":"URL desde la que el agente hace la solicitud (opcional)",
	"user_sid":"Token de sesión que fue suministrado al agente para ser validado",
	"user":"Id del usuario si está autenticado",
	"user_name":"Nombre para mostrar del usuario",
	"data":{ ... Un objeto con los datos especificados en las instrucciones de la intención ...},
	"params":{... Un conjunto de pares clave/valor que han sido provistos al agente por 
				la aplicación, página que lo ha invocado, definidos de manera constante 
				en la configuración de la intención o en la configuración del agente... }
}
```

Use la definición de hasta 3 columnas (campos) visibles en la tarjeta de la orden que se muestra en la sección operativa, 
indicando el campo de la carga útil y su título según la siguiente sintaxis:

- Si el atributo se encuentra dentro del campo `data` de la carga útil, solo escriba su nombre
- Si el atributo está en la raíz del objeto de la carga útil (como `intention`), deberá anteponer un caracter `@` (ejemplo `@intention`)
- Si el atributo está dentro de `params` de la carga útil, anteponga `$` al nombre para referenciarlo

Plantilla de respuesta

Para definir la plantilla de respuesta, siga las mismas reglas anteriores para los nombres de atributos, pero deberá encerrarlos entre llaves, por ejemplo 
`{{@agent_name}}` para hacer referencia al nombre del agente.

- `@@json` datos especificados en la instrucción de la intención.
- `@@webhook_response` respuesta del webhook invocado.

##### Columnas en la vista de informe

Permite definir las columnas que se mostrarán en la vista de informe de la orden.
Cuenta con un solo campo de entrada, en el cual se deben especificar los atributos a mostrar, separados por comas, utilizando la misma sintaxis y reglas que el módulo de columnas para tarjetas.

El comportamiento del módulo es el siguiente:

- Si el campo contiene valores, se realizará la búsqueda de cada atributo dentro de los datos de la orden, de acuerdo con la definición utilizada en el módulo de columnas para tarjetas.
- Si el campo se encuentra vacío, el sistema tomará como referencia los valores configurados en el módulo de columnas para tarjetas.
- Si los tres campos del módulo de columnas para tarjetas están vacíos, se utilizarán por defecto los siguientes atributos de la orden:

```
@folio
@sys_guid
@status_text
@fecha
data/order_guid
data/precio
```