# 04 · Catálogo requerido

Qué herramientas debe exponer según lo que quiera que el agente resuelva.

## Contexto: el catálogo de referencia

El agente de Asixto opera hoy en producción sobre un catálogo cerrado de **34 herramientas
tipadas** que le entrega la plataforma Asixto. En una integración con sistemas propios ese catálogo
se reparte en dos:

| Lado | Herramientas | Reparto | Qué cubre |
|---|---|---|---|
| **Su empresa** | **25** | 13 de lectura, 11 de escritura, 1 administrativa | Empresa y sedes, catálogo, clientes, casos, oportunidades, agenda |
| **Asixto** | **9** | 5 de contexto, 2 de escritura sobre la conversación, 2 comandos de llamada | Escalado a un asesor, historial de la conversación, memoria del agente, procedimiento del escenario, nota y estado de la conversación, búsqueda en internet, fin y transferencia de llamada |

De las 25 de su lado, **12 mutan** su sistema: las 11 de escritura más la administrativa.

Usted no construye las 9 de Asixto. Dos advertencias sobre ellas, porque afectan a lo que usted sí
construye: el **escalado** necesita destinatario (ver el final de esta página) y en **llamada
telefónica** varias no se ejecutan (ver la sección de divergencia por canal).

## Núcleo obligatorio

Sin estas tres el agente no puede operar: no sabe de qué empresa habla ni con quién.

| Herramienta | Nivel | Debe devolver |
|---|---|---|
| Información de la empresa | `read` | Nombre comercial, actividad, horarios de atención, canales, políticas y datos de contacto públicos. Es la base del *grounding*: sin esto el agente responde genérico o inventa. |
| Consulta de cliente | `read` | Identificación por documento, teléfono o correo. Datos de contacto y estado. Determina si atiende a un cliente conocido. |
| Sedes más cercanas | `read` | **Obligatoria solo con más de una sede.** Dirección, horario y distancia a una referencia dada. Con una sola sede, esa información va en «información de la empresa» y el núcleo queda en dos herramientas. |

## Familias por dominio

| Dominio | Herram. | Operaciones esperadas | Requisito propio |
|---|---|---|---|
| **Catálogo** | 2 | Búsqueda con filtros y paginación · detalle de un ítem | Precio vigente por lista de precios, existencia y unidad. El detalle trae las reglas de venta que el agente no puede inventar. |
| **Clientes** | 1 | Actualización de datos de contacto | Solo campos que el titular puede cambiar por sí mismo. Valida propiedad del registro. |
| **Casos** | 2 | Apertura con tipo y descripción · consulta de estado | Debe devolver un **número de radicado** en la misma respuesta: es lo que el agente le dice al usuario. Idempotente por conversación. |
| **Oportunidades** | 9 | Ver embudo · ver oportunidad · listar cotizaciones · crear oportunidad · mover etapa · crear cotización · enviar cotización · aceptar o rechazar cotización · cerrar oportunidad | Guardas de estado terminal. Montos validados contra su propio catálogo. |
| **Agenda** | 8 | Configuración y duración · franjas disponibles · listar citas · ver una cita · crear · modificar · confirmar o rechazar · cancelar | La disponibilidad manda: rechace una franja ocupada aunque venga solicitada. Modificar y cancelar exigen propiedad de la cita. La cancelación va con `destructiveHint: true`, así que **solo esa herramienta** requiere nivel `admin`; las otras siete funcionan con `write`. |

## Campos mínimos por dominio

El protocolo es autodescriptivo: usted nombra los campos como quiera y el agente lee su esquema. Pero
el agente **promete cosas concretas al cliente final** (un precio, un radicado, una hora), así que hay
un mínimo por dominio. Sin ese mínimo, dos integraciones igualmente correctas producen comportamientos distintos ante el
mismo cliente.

Los nombres de campo son suyos; lo que no es negociable es que **el dato exista y venga resuelto**.

> **Sobre escritura y borrado.** El contrato es de lectura **y escritura**: de las 25 herramientas
> del catálogo de referencia, **12 mutan** (11 de escritura y 1 administrativa). Lo que el agente
> **no** hace es borrado duro: no existe «eliminar cliente», «eliminar producto» ni «eliminar
> oportunidad». La única operación de tipo borrado es **cancelar una cita**, y va con
> `destructiveHint: true`. Si su operación necesita que el agente elimine registros, escálelo antes
> de construirlo: hoy no está en el alcance.

| Dominio | Su respuesta DEBE traer | Motivo |
|---|---|---|
| **Empresa** | Nombre comercial, actividad, horarios de atención, medios de contacto públicos y políticas que el agente pueda citar | Es el *grounding*: sin esto el agente responde genérico o inventa |
| **Sedes** | Por sede: nombre, dirección, horario y, si hay referencia de ubicación, distancia | Sin dirección y horario, «la sede más cercana» no significa nada |
| **Catálogo · búsqueda** | Por ítem: identificador **opaco y estable**, nombre, **precio final** en la moneda del `_meta`, disponibilidad y unidad. Además `total`, `limit`, `offset` | El agente cotiza de palabra: si el precio no viene resuelto, no puede decirlo |
| **Catálogo · detalle** | Lo anterior más descripción corta, variantes y **reglas de venta** (mínimos, requisitos, restricciones) | Las reglas que no vengan, el modelo las improvisa |
| **Clientes · consulta** | Si existe o no, nombre, estado y medios de contacto | Determina si atiende a un cliente conocido y si puede continuar |
| **Clientes · actualización** | Qué campos quedaron efectivamente actualizados | El agente confirma al cliente solo lo que usted confirme |
| **Casos · apertura** | **Número de radicado** y estado, en la misma respuesta | Es lo que el agente le dice al cliente. Sin radicado no hay cierre de la conversación |
| **Casos · consulta** | Estado, fecha de última actualización y un resumen legible | «Su caso sigue abierto» sin fecha no sirve de respuesta |
| **Agenda · configuración** | Duración de la cita, anticipación mínima y horarios de atención | Sin esto el agente ofrece horas imposibles |
| **Agenda · franjas** | Cada franja como **instante ISO con offset** y, además, texto pronunciable | En llamada se lee en voz alta; en chat se necesita el dato exacto |
| **Agenda · cita** | Identificador, instante, estado y titular | El estado es lo que permite rechazar operaciones sobre citas canceladas |
| **Embudo · oportunidad** | Identificador, etapa actual, **etapas válidas siguientes**, monto con moneda y estado | Sin las etapas válidas, el agente propone transiciones que usted rechaza |
| **Embudo · cotización** | Identificador, estado, monto con moneda y vigencia | La vigencia evita que el agente ofrezca un precio caducado |

> **Lo que NO debe traer, en ningún dominio:** claves primarias internas, identificadores de sistema,
> campos administrativos, datos de terceros, URLs de imagen (la media es inerte en la v1) ni nada que
> no pueda decirse en voz alta.

## Claves canónicas de escenario

Son los valores admitidos en `com.asixto/capability` ([página 02](./02-tool-contract.md)). Cualquier
otro valor se rechaza en la certificación.

```
actualizacion_datos      cambio_plan          garantia                notificaciones     reclamo_calidad
agenda                   cancelacion          general                 pqr                renovacion
busqueda_web             consulta_estado      informacion_empresa     reactivacion       reporte_fraude
encuestas_satisfaccion   emergencia           informacion_productos   seguimiento_postventa
facturacion              felicitacion         informacion_servicios   solicitud_documentos
lead                     soporte              ventas
```

Si su operación necesita un escenario que no está en la lista, escálelo: se evalúa como capacidad
nueva del agente, no se improvisa con una clave inventada.

## Escenario → herramientas requeridas

El agente organiza la atención en **26 escenarios de negocio**. Cada uno declara qué necesita:
**si su sistema no lo expone, ese escenario no se enciende**. Así se acota el alcance sin
ambigüedad.

| Escenario | Herramientas que debe exponer |
|---|---|
| Información de la empresa · consultas generales · facturación · felicitaciones · encuestas de satisfacción · seguimiento posventa · solicitud de documentos | Solo el núcleo obligatorio. Son escenarios conversacionales: los diferencian las instrucciones del agente, no herramientas extra. |
| Información de productos · información de servicios · ventas · cambio de plan | Búsqueda en catálogo + detalle de ítem |
| Reactivación · renovación | Búsqueda en catálogo |
| Actualización de datos · gestión de notificaciones | Actualización de cliente |
| Consulta de estado de un caso | Consulta de estado de caso |
| PQR · soporte técnico | Apertura de caso + consulta de estado + búsqueda en catálogo |
| Garantía · reclamo de calidad · cancelación | Apertura de caso + detalle de ítem + búsqueda en catálogo |
| Emergencia · reporte de fraude | Apertura de caso |
| Agenda de citas | Las 8 operaciones de agenda |
| Captación y calificación de oportunidades | Catálogo + las 9 operaciones del embudo |
| Búsqueda en internet | Ninguna: la aporta Asixto |

## Secuencia recomendada

| Fase | Herramientas | Qué habilita | Riesgo |
|---|---|---|---|
| **1** | 5 (núcleo + catálogo) | Atender, informar, cotizar de palabra, escalar a humano | Nulo: todas son de lectura, ninguna escribe en sus sistemas |
| **2** | +3 (casos + actualización de cliente) | Agente resolutivo: abre radicados y corrige datos | Entran idempotencia y validación de propiedad ([página 05](./05-guarantees.md)) |
| **3** | +17 (agenda + embudo) | Agenda citas y gestiona el pipeline comercial | Los dos dominios con estado y transiciones. Aborde uno por vez, con las fases 1 y 2 ya en producción |

Cada fase se certifica y se activa por separado. Agregar una fase no obliga a recertificar las
anteriores, salvo que cambie una herramienta ya certificada.

## Control de exposición

Sus herramientas entran al catálogo del agente sujetas al filtro de la plataforma:

1. **Capacidad activa**: el escenario está habilitado para el tenant. Si no, la herramienta no
   existe para el modelo.
2. **Nivel**: `read` ⊆ `write` ⊆ `admin`, derivado de sus anotaciones.

Hay una tercera capa (**interruptor por acción sensible**) que hoy solo opera sobre herramientas
del catálogo nativo, porque cada interruptor necesita una clave declarada en el catálogo de
capacidades del backend. Para una herramienta suya, **mientras esa clave no exista, el interruptor
no la protege**: la protegen la capacidad y el nivel. Si necesita un interruptor por acción para una
operación concreta, se coordina y se da de alta; no lo asuma incluido.

Consecuencia para su diseño: **la guarda de último recurso de una operación irreversible vive en su
sistema**, no en nuestra configuración. Ver el aviso sobre confirmación en la
[página 02](./02-tool-contract.md).

## Divergencia por canal: qué NO ocurre en una llamada

El agente atiende chat y teléfono con el mismo catálogo, pero **en llamada hay familias enteras que
no se ejecutan**, por diseño: en tiempo real, sin pantalla y sin poder confirmar por escrito, esas
acciones exigen validación humana.

| En llamada telefónica | Qué pasa |
|---|---|
| Apertura de caso | **No se ejecuta.** Un PQR pedido por teléfono no abre radicado, aunque usted exponga la herramienta. El agente toma el caso y ofrece transferir o registrar el contacto. |
| Nota interna en la conversación | No se ejecuta. |
| Búsqueda en internet | No se ejecuta. |
| Escalado a un asesor | No existe como herramienta; su sustituto es la **transferencia de la llamada**. |
| Lectura de catálogo, clientes, agenda y embudo | Se ejecutan con normalidad. |

Si su operación necesita que una llamada abra un caso en su sistema, hay dos caminos: exponer la
apertura de caso como parte de otra familia que sí corra en voz, o aceptar que el registro ocurra
después, con la transcripción. Conviene decidirlo antes de construir las herramientas de esa familia.

Además, en voz aplican las restricciones de forma de la [página 07](./07-limits.md): máximo 3
elementos por lista, nada de URLs ni correos, y fechas en ISO **y** en texto pronunciable.

## Escalado a un humano: a quién

El escalado lo aporta Asixto, con un matiz que afecta a su operación: la herramienta de escalado **reasigna la conversación dentro de la plataforma Asixto** y
necesita un asesor dado de alta ahí. Tres escenarios:

| Su situación | Qué hacer |
|---|---|
| Sus asesores atenderán las conversaciones en Asixto | Nada. Se dan de alta como usuarios y el escalado funciona. |
| Sus asesores viven en su propio CRM | **Exponga una herramienta de handoff** (crear tarea, asignar conversación, notificar) y decláremela como la vía de escalado de su tenant. |
| Atención telefónica | Facilite un **número de destino para transferencia**. Sin él, en llamada el agente solo puede ofrecer que alguien devuelva la llamada. |

Si no resuelve esto, el escalado queda sin destinatario: el agente dirá que un asesor lo contactará
y nadie lo contactará. La conversación termina con una promesa que nadie va a atender.