Aprobaciones y auditoría

Tus agentes trabajan solos, pero nunca a ciegas. Las acciones con efecto en el mundo real esperan tu visto bueno, los topes de gasto frenan automáticamente un uso desbocado y lo que ocurre queda registrado. La gobernanza con humano en el bucle es lo que te permite delegar sin perder el control.

Qué espera tu aprobación

Un agente puede razonar, buscar y redactar por sí solo, pero cuando una acción es irreversible o tiene un efecto externo, se detiene y la deja en la bandeja de Aprobaciones. Nada se ejecuta hasta que una persona con el rol adecuado dice que sí. Estas son las categorías que pasan por revisión:

• Comunicación externa: enviar un correo, responder a un cliente, publicar en un canal o red social, o cualquier mensaje que salga de tu organización.
• Movimientos de dinero: ordenar un pago, emitir o modificar una factura, aprobar un gasto o una transferencia.
• Decisiones de RR. HH. con efecto: aprobar vacaciones, rescindir un contrato, bonus o nóminas.
• Cambios en datos críticos: borrar clientes, vaciar tablas, cambiar ajustes globales o tocar registros que no se pueden recuperar.
• Llamadas sensibles a herramientas: llamadas a herramientas externas fuera de lo que se marcó como seguro de antemano.

Cada herramienta que actúa fuera de Shara está marcada en el producto como requiere aprobación; el agente no puede saltarse esa marca.

Lo que no necesita aprobación: leer, buscar, resumir, analizar, redactar o preparar propuestas. La velocidad se mantiene en todo lo reversible; el freno solo aparece donde hay consecuencias.

La regla es sencilla: si la acción cambia algo fuera de Shara o no se puede deshacer, pasa por ti. Un análisis de ventas se ejecuta solo; el correo que ese análisis propone enviar, no. Amadeus orquesta y delega en los especialistas, pero ninguno de ellos, ni siquiera Amadeus, puede saltarse este control.

Tarjetas de aprobación

Cada petición llega a la bandeja como una tarjeta de aprobación. La tarjeta te dice de un vistazo qué tipo de acción es y lleva la información relevante:

Tarjeta	Qué representa	Datos que muestra
Correo saliente	Un correo listo para enviarse a un destinatario externo.	Destinatario, asunto, cuerpo (editable), agente que lo pide.
Pago / factura	Un movimiento de dinero o la emisión de una factura.	Importe, beneficiario, descripción, método.
Publicación	Una publicación o mensaje para un canal o red social.	Canal, contenido, adjuntos.
Respuesta a cliente	La respuesta a un ticket o consulta entrante.	Hilo, borrador de respuesta (editable).
Herramienta / conector	Una acción sobre una herramienta conectada.	Herramienta, parámetros, efecto esperado.
Datos críticos	Un borrado o cambio irreversible en tus datos.	Recurso afectado, alcance.
Decisión de RR. HH.	Vacaciones, bonus, rescisión de contrato u otra decisión de personal.	Empleado, tipo de decisión, agente.

Severidad y plazos

Cada tarjeta lleva una severidad (alta, media o baja) que ordena tu bandeja y que depende del tipo de acción. Los pagos y los correos salientes son altos; las respuestas a clientes y las publicaciones son medias; el resto son bajos. La bandeja se ordena por severidad y antigüedad, así que lo urgente sube arriba.

Hay dos relojes distintos, y conviene no mezclarlos:

1. Caducidad: hasta 7 días. Una petición que plantea un agente espera tu decisión. Pasados 30 minutos, la conversación queda en espera, hasta 7 días: cuando decidas (aunque sea al día siguiente y desde otra pantalla), el agente sigue donde lo dejó, en la misma conversación. Si nadie decide en ese plazo, la petición caduca y la acción no se ejecuta. El silencio equivale a un no: nada se ejecuta «por defecto». Si sigue teniendo sentido, el agente tiene que volver a pedirla.
2. Plazo de atención: de 10 a 120 minutos, según el tipo. Cada tipo de petición tiene un tiempo razonable para que alguien reaccione. Cuando pasa sin decisión, Shara envía un aviso para que alguien la atienda.

Tipo de petición	Plazo de atención
Llamada a herramienta	10 minutos
Respuesta a un cliente	15 minutos
Correo saliente	30 minutos
Evento de calendario	30 minutos
Publicación, boletín u otra publicación	60 minutos
Cualquier otro tipo	60 minutos
Orden de pago	120 minutos

Un envío que sigue a un borrador que ya aprobaste (por ejemplo, el correo tras el borrador aprobado) se aprueba solo si llega dentro de una ventana corta, de 5 minutos, para que no te pregunten dos veces lo mismo.

La bandeja de aprobaciones

Cada petición muestra qué agente la pide (por ejemplo, Patterson para una oferta comercial o Graham para un pago), la acción descrita en lenguaje natural, el contexto que la motivó y su severidad. Decides con dos botones: Aprobar o Rechazar. Quien decide deja huella en el registro de auditoría. Si tienes la verificación en dos pasos activada, aprobar una acción también exige el segundo factor (o entrar con passkey), igual que el resto de la aplicación.

Cuando rechazas, puedes (y conviene) dejar un motivo. Ese comentario vuelve al agente para que no repita el intento a ciegas, y te ayuda a mejorar las reglas de IDENTITY.md. Un «no» bien explicado mejora la siguiente propuesta. También puedes decidir muchas tarjetas de golpe, o un grupo entero de tarjetas relacionadas.

Modo accept-edit

En las acciones que producen contenido (un correo, una publicación, la respuesta a un ticket) no solo aprobas o rechazas: puedes editar el resultado propuesto antes de aceptarlo. Corriges el tono o un detalle y Aceptas la versión final, o Rechazas y devuelves el trabajo al agente con tu comentario. Lo que se ejecuta es la versión que revisaste y aprobaste.

Quién puede aprobar qué

La capacidad de decidir depende del rol de cada persona. La lista completa está en Roles y permisos.

Rol	Qué puede decidir
Owner y Administrador	Todas las peticiones de la empresa.
Director	Las peticiones que se le delegan y las de los agentes de su propio departamento.
Operador, IT y Visualizador	Nada. Sus acciones sensibles van al director del departamento, o al owner y a los administradores si no hay director.

Una aprobación es un acto personal: necesita una sesión iniciada de una persona. Una API key no puede aprobar nada, por diseño. El registro muestra siempre quién aprobó, no «el sistema».

Un ejemplo de principio a fin

Imagina que le pides a Amadeus cerrar la semana de soporte y escribir a los clientes con más incidencias. Wanamaker (atención al cliente) resume los tickets (una acción reversible: se ejecuta sola) y redacta tres correos de seguimiento. Esos correos no se envían: aparecen en tu bandeja como tres tarjetas de Correo saliente.

1. Abres la primera tarjeta: ves destinatario, asunto y cuerpo, con el contexto.
2. Corriges una frase del cuerpo y Aceptas. El correo sale con tu versión.
3. El segundo te parece innecesario: Rechazas con el motivo «este cliente ya cerró por teléfono». Wanamaker lo anota.
4. Dejas el tercero para luego. Si nadie decide, la conversación queda en espera hasta 7 días; pasado ese plazo caduca y no se envía nada.
5. Cada decisión queda en el registro de auditoría con tu nombre.

Topes de gasto

Además de tu revisión manual, tres topes de gasto detienen la ejecución sin intervención humana en cuanto se superan. Protegen frente a un bucle inesperado, un prompt malicioso o una tarea mal calibrada. Se miden en STU:

Tope	Por defecto	Qué corta
Por ejecución	1 M de STU en una ejecución	Corta esa ejecución. Evita que una sola tarea se desboque.
Por hora	10 M de STU en los últimos 60 minutos	Pausa la inferencia mientras la ventana móvil siga alta.
Por día	80 M de STU en las últimas 24 horas	Pausa la inferencia mientras la ventana móvil siga alta. Es el tope duro.

Un owner o administrador puede editar los tres valores o desactivar cualquiera de ellos, en Ajustes → Límites y alertas. Los topes por hora y por día se levantan solos cuando su ventana baja del umbral; el de ejecución, pasada una hora. Un administrador puede levantar un tope antes, o dejar una pausa manual que no se levanta sola.

Cuando salta un tope, la API responde 429 kill_switch y los administradores reciben un aviso. Los topes son defensa, no facturación: una ejecución detenida no te cobra de más. Para las alertas de consumo, la misma pantalla te deja elegir cuándo te avisan sobre tu cuota (por defecto al 80 %, 90 % y 100 %). Mira STU y cuotas.

Registro de auditoría

El registro de auditoría anota lo que pasa en tu empresa, para que puedas demostrar quién hizo qué. Cada registro tiene estos campos:

Campo	Significado
id	Identificador único del registro.
tenantId	Tu empresa.
actorUserId, actorName, actorEmail	Quién lo hizo (vacíos si lo hizo el sistema o la persona ya no existe).
action	Qué ocurrió, por ejemplo identity.patch.
resource, resourceId	Sobre qué ocurrió.
before, after	El estado antes y después del cambio.
createdAt	Cuándo.

{
  "id": "5b0c8d2e-7a41-4c1f-9d3e-2f6a1b9c0e55",
  "tenantId": "c2a9…",
  "actorUserId": "7d41…",
  "actorName": "Marta Ruiz",
  "actorEmail": "marta@example.com",
  "action": "identity.patch",
  "resource": "agent_identity",
  "resourceId": "patterson",
  "before": { "length": 1280, "hash": "9f2c1a7b", "version": 14 },
  "after": { "length": 1342, "hash": "3e7d5c10", "version": 15, "mode": "append", "reason": "Bajar el umbral de descuento" },
  "createdAt": "2026-07-11T10:42:07.000Z"
}

El contenido de before y after depende de la acción. En los cambios de identidad lleva un resumen (longitud, un hash corto y la versión) en lugar del texto completo.

Solo pueden leerlo los owner y administradores, con GET /audit (filtros: type, actor, resource, resourceId, from, to, limit y cursor).

Verificar la cadena

Cada registro lleva el hash SHA-256 del anterior, formando una cadena. GET /audit/verify-chain recorre la cadena (hasta 200 registros por llamada por defecto) y responde con un status (intact, broken o empty), el número de registros válidos e inválidos y, si hay un problema, el primer registro que no cuadra. Si alguien altera un registro intermedio, la comprobación lo detecta.

La base de datos solo permite añadir registros: modificar, borrar o vaciar el registro se rechaza, también para la propia aplicación. Además, la cadena demuestra que el historial no se cambió después; es una comprobación que puedes lanzar tú, no una promesa. La regla no es absoluta: un administrador de la base con privilegios máximos podría saltársela, pero no pasaría inadvertido: cada hora se guarda una copia firmada de la última línea de la cadena de cada empresa en un almacenamiento con bloqueo de borrado de 30 días, fuera de la base, y cada día se comprueba que la base coincide con esas copias. El registro de auditoría vive en la UE.

Más contexto sobre las capas de seguridad, los roles y el cumplimiento en Seguridad y cumplimiento.