# Herramientas del agente

## Objetivo

El agente no debe depender solo de texto. Debe poder pedir herramientas controladas al backend para consultar datos y preparar acciones.

## Tipos de herramienta

### Lectura

Estas herramientas consultan y devuelven datos.

```text
buscar_envio
obtener_envio
listar_envios_riesgo
resumen_operacion
buscar_cliente
buscar_chofer
consultar_cobranzas
consultar_liquidacion
consultar_health
buscar_docs
```

### Navegacion UI

Estas herramientas no cambian datos; preparan botones para la UI.

```text
abrir_modulo
abrir_envio
abrir_cliente
abrir_informe
aplicar_filtros
```

### Preparacion de acciones

Estas herramientas preparan payloads. Siempre requieren confirmacion.

```text
preparar_cambio_estado
preparar_asignacion_chofer
preparar_observacion
preparar_reimpresion
preparar_reprocesar_preenvio
```

## Contrato general

```json
{
  "tool": "buscar_envio",
  "args": {
    "tracking": "SEED-CABA-015"
  }
}
```

Respuesta:

```json
{
  "ok": true,
  "data": {},
  "fuentes": []
}
```

## Herramientas iniciales

### Catalogo de capacidades

Antes de llamar una herramienta, el agente debe elegir una capacidad validada de:

```text
back/lightdata_ai/capacidades.php
```

Esto evita diccionarios por frase. Ejemplos:

| Pregunta | Capacidad | Herramienta | Backend |
|---|---|---|---|
| pendientes por zonas | `informes.porzonas` | `consultarInforme({tipo:"zonas"})` | `ControladorInformes::envios(['por'=>'zona'])` |
| pendientes por cliente | `informes.porcliente` | `consultarInforme({tipo:"clientes"})` | `ControladorInformes::envios(['por'=>'cliente'])` |
| envios cancelados desde una fecha | `envios.listado` | `consultarEnvios` | `ControladorEnvios::listar/resumen` |
| crear ruta por zona para chofer | `ruteate.preparar_asignacion_zona_chofer` | `prepararAsignacionRuta` | `ControladorEnvios` + `sistema_usuarios` + `ruteate.asignacionProcesar` |

### Conocimiento operativo previo

Las capacidades no alcanzan solas. El agente debe tener contexto de tablas/campos/circuitos desde:

```text
back/lightdata_ai/conocimiento.php
```

Ese contexto le dice, por ejemplo:

- estado actual: `envios.estado -> estados_envios.did`;
- fecha de estado: `MAX(envios_historial.fecha)`;
- zona de entrega: `envios_direcciones_destino.didEnvioZona -> envios_zonas.did`;
- informe por zonas: agrupacion de `ControladorInformes::envios(['por'=>'zona'])`;
- pendientes: estados que no son cerrados segun `estados_envios`.
- ruta/asignacion: seleccionar envios ruteables por zona de entrega, resolver chofer operativo y preparar confirmacion; no reasignar envios de otros choferes sin pedido explicito.

### `buscar_envio`

Entrada:

```json
{ "tracking": "SEED-CABA-015", "idVenta": "", "idPack": "" }
```

Salida:

```json
{
  "envios": [
    { "did": 123, "tracking": "SEED-CABA-015", "estado": 3, "cliente": "Deco Hogar" }
  ]
}
```

### `obtener_envio`

Entrada:

```json
{ "did": 123 }
```

Usa `ControladorEnvios::obtener`.

### `resumen_operacion`

Entrada:

```json
{ "fecha": "2026-06-08", "filtros": {} }
```

Primero intenta Redis:

```text
ops:{tenant}:envios:resumen
ops:{tenant}:envios:por_estado
ops:{tenant}:envios:por_zona
ops:{tenant}:envios:por_chofer
```

Si no hay cache, consulta DB y guarda TTL corto.

### `buscar_docs`

Entrada:

```json
{ "query": "como se liquida el costo del chofer", "tags": ["liquidaciones", "costos"] }
```

Salida:

```json
{
  "chunks": [
    {
      "path": "procesos/README.md",
      "titulo": "proceso_chofer_listaprecios",
      "texto": "..."
    }
  ]
}
```

## Acciones sugeridas para UI

El endpoint puede devolver:

```json
{
  "acciones": [
    {
      "tipo": "abrir_modulo",
      "label": "Ver envios demorados",
      "payload": {
        "ruta": "envios.listado",
        "estado": {
          "filtros": { "estados": [3], "asignado": "0" }
        }
      }
    },
    {
      "tipo": "preparar_cambio_estado",
      "label": "Pasar seleccionados a En camino",
      "payload": {
        "dids": [123,124],
        "estado": 4
      },
      "requiereConfirmacion": true
    }
  ]
}
```

## Reglas de seguridad

- Ninguna herramienta escribe sin endpoint especifico y confirmacion UI.
- El backend revalida permisos.
- No se ejecutan SQL libres generados por el modelo.
- No se aceptan nombres de tabla/columna arbitrarios desde el modelo.
- Las herramientas exponen funciones de dominio, no acceso crudo a DB.

## Roadmap de herramientas

Fase 1:

- `buscar_docs`
- `buscar_envio`
- `obtener_envio`
- `resumen_operacion`

Fase 2:

- `listar_envios_riesgo`
- `buscar_cliente`
- `buscar_chofer`
- `consultar_cobranzas`

Fase 3:

- acciones preparadas con confirmacion;
- apertura de modulos con filtros;
- explicaciones de liquidacion/costos.