Los descriptores de handlers determinan la visibilidad de los agentes de IA
En un producto con una interfaz de escritura/consulta, los agentes de IA no podían encontrar handlers que sí existían porque faltaba el campo de descripción. El omitirlo hace que el handler desaparezca del manifiesto del agente.
En una integración de un agente de IA dentro de un producto que ya disponía de una capa de escritura y consulta, el equipo descubrió que la mayoría de los handlers necesarios no aparecían en la lista de herramientas del agente. Los handlers sí existían, pero carecían de la cadena de descripción que el agente requiere para incluirlos en su manifiesto. El manifiesto se construye a partir de los features que la aplicación monta: handlers, pantallas y entidades. Cada entrada necesita una descripción breve, escrita junto al handler; sin ella, la entrada se descarta y el agente no la conoce.
Para los humanos la ausencia de descripción no impide la operación: el UI sigue funcionando y los usuarios pueden hacer clic en los botones. Pero el agente, al no haber visto el nombre del handler, lo considera inexistente. De esta forma, handlers que permiten escribir se vuelven invisibles al agente, aunque el endpoint esté disponible.
El equipo añadió pruebas de “gap” que detectan handlers sin descripción. El primer test verifica que el número de brechas sea cero, mientras que el segundo compara los niveles de riesgo entre un delete-golden (alta) y un set-policy (media). Estas pruebas se ejecutan automáticamente al generar una nueva feature.
El riesgo está determinado por la propiedad agent.risk del handler. Los writes que no pueden revertirse se marcan como high. Los que sí tienen una revisión restorable permanecen en mid o low. El modelo de permisos “always allow” sólo se aplica a los handlers de riesgo bajo.
El resultado fue que la única forma de hacer visible un handler al agente es incluir una descripción al momento de definirlo. Una frase que indique qué cambia y si el cambio es reversible basta. Si el write es irreversible o afecta a otra feature, marcarlo como high evita que el agente lo invoque sin confirmación.
El equipo ahora verifica que el agente pueda listar todas las herramientas disponibles y compara esa lista con los handlers de escritura. Cuando falta una descripción, el test falla antes de que el agente sea desplegado, evitando sorpresas durante una demo.
El mensaje que se transmite es claro: la descripción es el contrato que permite que el handler exista en el mundo del agente; el riesgo es el contrato que decide si puede ser llamado de forma permanente.
Repositorio de la publicación
