Una ficha de una página para cada agente de IA antes de que toque trabajo real

La forma más rápida de perder el control de un programa de agentes es dejar que los agentes se acumulen como prompts. Alguien escribe una instrucción ingeniosa, la conecta a una herramienta, consigue una buena demo y la despliega. Seis meses después hay cuarenta de estos en producción, cada uno un párrafo de texto en un repositorio que nadie audita, y nadie puede responder a las preguntas básicas de gobernanza: quién posee esto, qué puede tocar, cuánto cuesta y qué pasa cuando se equivoca.

La solución es pequeña y de gran efecto. Cada agente recibe un manifiesto antes de tocar producción. El manifiesto es el contrato entre el agente y la organización, y escribirlo fuerza las decisiones que de otro modo afloran como incidentes.

Qué es un manifiesto de skill

Un manifiesto de skill es un único registro declarativo que define un agente como un objeto gobernado. No es documentación escrita a posteriori. Es la fuente de verdad que el runtime lee, la puerta de enlace aplica y el revisor de seguridad audita. Si el manifiesto no permite una herramienta, el agente no puede llamarla. Si el manifiesto fija un tope de coste, la puerta de enlace lo aplica antes de que llegue la factura.

Los campos son deliberadamente aburridos, porque lo aburrido es auditable:

• name y owner. Una persona o equipo responsable de este agente. No “el proyecto de IA”. Un nombre.
• workflow. El proceso de negocio al que sirve, de modo que el agente se corresponda con algo que operaciones reconozca.
• usuarios y roles permitidos. Quién puede invocarlo, expresado con el mismo RBAC que usa el resto de la infraestructura.
• herramientas permitidas. La superficie exacta de herramientas, incluidas las herramientas deliberadamente retenidas. La ausencia de una herramienta de escritura es una decisión registrada por escrito.
• esquema de entrada y de salida. La forma de lo que entra y lo que sale, de modo que el contrato del agente sea verificable por máquina.
• fuentes de conocimiento. De qué índices y documentos puede recuperar, filtrados de forma consciente de permisos para que el agente solo vea lo que el usuario que llama puede ver.
• requisitos de aprobación. Qué debe firmar una persona, y en qué paso.
• nivel de riesgo. Una clasificación que determina cuán ajustado se fija todo lo demás.
• tope de coste. Un techo para el coste por tarea completada, aplicado en la puerta de enlace.
• registro. Dónde aterrizan las trazas, de modo que cada ejecución sea reconstruible.
• pruebas de evaluación. La batería de regresión que condiciona cualquier cambio.
• política de fallo y reversión. Qué hace el agente cuando no puede continuar, y cómo se deshace una acción equivocada.

Un manifiesto trabajado

Lo concreto gana a lo abstracto. Aquí hay un manifiesto para un agente de finanzas que resuelve excepciones de facturas en cuentas por pagar.

name:        invoice-exception-resolver
owner:       finance-ap@cliente
workflow:    cuentas-por-pagar / gestion de excepciones
risk_tier:   2          # financiero, reversible, humano en el bucle
allowed_roles:
  - ap-clerk
  - ap-manager
allowed_tools:
  - erp.read           # consultar OC, proveedores, historial
  - erp.match          # proponer una conciliacion a tres bandas
  - ticket.create      # abrir un ticket de excepcion
  # erp.post NO se concede intencionadamente
input_schema:   { invoice_id, vendor_id, amount, gl_hint? }
output_schema:  { match_result, confidence, proposed_action, evidence[] }
knowledge:
  - maestro-proveedores   # consciente de permisos
  - historial-oc
  - politica-ap
approval:     ejecutar-con-aprobacion (L3); ap-manager firma los asientos
cost_cap:     0,60 EUR por tarea completada
logging:      trace-lake (convenciones OpenTelemetry GenAI)
evals:        42 casos; puerta de promocion >= 0,95 coincidencia en conjunto reservado
failure_policy: confianza baja -> enviar a la cola humana, no adivinar
rollback:     anular ticket, devolver a la cola humana, alertar al responsable

Lee lo que decide el manifiesto. El agente puede leer el ERP y proponer una conciliación, pero erp.post no está en su lista de herramientas, así que físicamente no puede mover dinero. Esa es la decisión de radio de impacto tomada por escrito en lugar de descubierta en un incidente. El tope de 0,60 EUR es la defensa de finanzas, fijada antes de que se ejecute la primera factura. Las fuentes de conocimiento conscientes de permisos responden a “¿puede este agente leer algo que el usuario que lo invoca no puede?” con “no”. La puerta de evaluación convierte la promoción en aritmética en lugar de en opinión. La reversión nombra exactamente cómo se deshace un ticket erróneo.

El nivel de riesgo fija todo lo demás

El campo más útil es el nivel de riesgo, porque es el que calibra a todos los demás. Un nivel es una clasificación corta y honesta de lo que pasa cuando el agente se equivoca: ¿es la acción reversible, toca datos regulados, mueve dinero, llega a un cliente?

Una clasificación práctica:

• Nivel 0: solo lectura, interno. Las respuestas equivocadas malgastan el tiempo de una persona y nada más. Topes holgados, aprobación ligera, iteración rápida.
• Nivel 1: acciones internas reversibles. Crear un ticket, redactar un registro. Las acciones equivocadas son molestas y baratas de deshacer.
• Nivel 2: acciones reversibles que tocan dinero o clientes, o leen datos regulados. Topes más ajustados, aprobación humana, reproducción completa requerida.
• Nivel 3: acciones irreversibles o de alto valor, o cualquier cosa que una clasificación de riesgo del Reglamento de IA de la UE marcaría. El manifiesto aquí es estricto por defecto: herramientas estrechas, topes bajos, aprobación obligatoria, reversión probada, y ningún camino a la autonomía plena sin evidencia sostenida.

El nivel es lo que impide que la gobernanza sea uniforme y, por tanto, inútil. No quieres la misma ceremonia de aprobación en un agente de preguntas frecuentes interno que en un agente que emite reembolsos. El nivel deja que el agente de preguntas frecuentes vaya rápido y el agente de reembolsos vaya con cuidado, desde el mismo marco.

Cuatro manifiestos en cuatro funciones

La forma del manifiesto se mantiene entre departamentos. Los campos siguen siendo los mismos; los valores cambian con el trabajo.

• Invoice Exception Resolver (Finanzas / AP). Lee el ERP, propone conciliaciones a tres bandas, abre tickets de excepción. Sin herramienta de asiento. Nivel 2, aprobación humana en cualquier cosa que se convierta en un asiento.
• Support Escalation Agent (Soporte). Lee el historial de tickets y la base de conocimiento, redacta una resolución o la enruta a la cola correcta, puede cerrar un ticket que resolvió. Nivel 1 para enrutar, Nivel 2 para cualquier acción que toque un sistema de cara al cliente.
• Contract Review Assistant (Legal). Lee contratos y la biblioteca de cláusulas, marca desviaciones del manual de juego, redacta correcciones. No envía nada externamente. Nivel 1, porque cada salida la revisa la asesoría jurídica antes de que salga del edificio.
• IT Service Desk Agent (TI). Lee los sistemas de activos e identidad, restablece ajustes conocidos como seguros, crea tickets de cambio para cualquier cosa privilegiada. Nivel 2, con las acciones privilegiadas retenidas tras aprobación y una reversión probada.

Los mismos once campos. Distintos responsables, herramientas, fuentes de conocimiento y niveles. Esa igualdad es el punto: un revisor que ha leído un manifiesto puede leerlos todos, y un agente nuevo es un formulario que rellenar en lugar de una discusión nueva que tener.

Regla práctica: si un agente en producción no se puede describir con un manifiesto completo, no está gobernado, solo está desplegado.

El manifiesto es lo que la puerta de enlace aplica

Un manifiesto que es solo un documento es un deseo. La razón por la que funciona es que el runtime y la puerta de enlace de IA lo leen y lo aplican. La lista de herramientas permitidas es la superficie real de herramientas que se le da al agente, no una descripción de intención. El tope de coste es un presupuesto que la puerta de enlace comprueba antes de la llamada. Las fuentes de conocimiento son los únicos índices que tocará el paso de recuperación, filtrados por los permisos de quien llama. La batería de evaluación se ejecuta automáticamente antes de que se permita desplegar cualquier cambio en el agente.

Esto es lo que convierte el manifiesto en la unidad de control de cambios. Cuando alguien quiere dar al agente de facturas la herramienta erp.post, eso no es una edición de código enterrada en una pull request. Es un cambio en el manifiesto, que eleva el nivel de riesgo, que dispara la aprobación que el nivel superior requiere, que vuelve a ejecutar la batería de evaluación, que aterriza en el registro de auditoría. El manifiesto convierte “le dimos al agente una nueva capacidad” de algo que ocurre en silencio en algo que ocurre sobre el registro.

Dónde rinde el manifiesto

Tres momentos, en concreto.

En la revisión de seguridad, el manifiesto es el artefacto que responde a las preguntas puntuales en una línea cada una. ¿Qué puede tocar este agente? La lista de herramientas permitidas. ¿Puede leer datos que el usuario no puede? No, las fuentes de conocimiento son conscientes de permisos. ¿Cuánto cuesta? El tope. La revisión lee los manifiestos en lugar de interrogar al equipo.

En la decisión de promoción, el manifiesto contiene la puerta de evaluación y el peldaño actual, de modo que subir un agente por la escalera de autonomía es una comprobación contra umbrales nombrados en lugar de una votación. La evidencia y el listón viven en el mismo sitio.

En la revisión de incidentes, el manifiesto más la traza responden a “¿qué se le permitía hacer a este agente, y qué hizo en realidad?” sin que nadie reconstruya la intención de memoria. La distancia entre ambas es el hallazgo.

Un programa de agentes que funciona sobre manifiestos es más lento para arrancar un agente y mucho más rápido para ejecutar cuarenta. La disciplina se carga por adelantado en un formulario. Rellénalo antes de producción, aplícalo en la puerta de enlace, cámbialo sobre el registro, y los agentes dejan de ser un montón de prompts y empiezan a ser una flota gobernada.