# Auditoría de agentes

Registro de cada llamada de un agente MCP con su resultado, operaciones en curso e historial de comandos, sin guardar valores.

Fuente: https://ardumaker.com/docs/auditoria-de-agentes/

- Categoría: Inteligencia artificial y agentes
- Estado: Disponible
- Requisitos: Una cuenta de ArduMaker con al menos un agente conectado por MCP; Para el historial de comandos de un VPS: acceso a ese VPS
- Herramientas MCP (Solo leen): `ver_historial_comandos_vps`, `ver_logs_proyecto`, `ver_operacion`

## ¿Qué permite hacer?

- Ver, por agente, cada herramienta que llamó, si salió bien, falló o fue rechazada, si modificaba datos, sobre qué ids y cuánto tardó.
- Ver las operaciones largas en curso de un agente y un resumen de las últimas 24 horas.
- Saber si un agente está trabajando ahora mismo (actividad en los últimos 2 minutos).
- Leer el historial de comandos de shell de un VPS: quién los corrió y qué humano autorizó al agente.
- Encontrar en el registro de actividad del VPS y del proyecto lo que hizo un agente, a su nombre y al de su humano.

## ¿Cuándo conviene usarlo?

- Revisar qué hizo un agente mientras no se lo miraba.
- Entender por qué un agente dice que no pudo hacer algo (los rechazos quedan registrados con su motivo).
- Detectar un agente olvidado que sigue renovando su sesión sin trabajar.

## ¿Cómo funciona en ArduMaker?

### Registro de llamadas

Cada llamada a una herramienta (salvo `ping`, que no tiene autenticación) se escribe **una vez, al terminar**, con todo lo que se sabe de ella. La auditoría envuelve a las demás guardas: un rechazo por solo lectura o por el límite de llamadas también queda escrito.

| Campo | Qué guarda |
| --- | --- |
| `tool` | Nombre de la herramienta |
| `resultado` | `ok`, `error` o `rechazo` (el permiso no lo dejó) |
| `modifica_datos` | Si la herramienta escribe |
| `referencias` | Solo los argumentos `*_id` / `*_ids` con valor entero |
| `campos` | Los nombres de los argumentos, nunca sus valores |
| `duracion_ms`, `perfil` | Cuánto tardó y por qué perfil entró |
| `motivo` | En `error` o `rechazo`, el `que_paso` del error |

> **INFO:** **Nunca se guardan valores**: por las herramientas pasan credenciales, SQL y correos. Por eso el registro dice que se editó la tarea 449 del proyecto 12 y qué campos se mandaron, pero no el texto nuevo.

### Comandos en un VPS

- Cada `ejecutar_comando_vps` deja una línea genérica en el registro de actividad del VPS («Shell command executed») y el detalle en el historial de comandos.
- El historial guarda el comando (con los secretos etiquetados, como `password=` o `PGPASSWORD=`, tapados), el directorio, el código de salida, la duración, el principio de la salida, quién lo corrió y, si fue un agente, qué humano lo autorizó. También los comandos que una guarda rechazó.
- Se conserva 30 días, a propósito: el tapado no reconoce una credencial suelta sin etiqueta, así que se acorta el tiempo en que podría quedar guardada.

### A nombre de quién

Un agente actúa con un usuario propio vinculado a la persona que lo autorizó. En el registro de actividad del VPS y del proyecto, sus acciones aparecen a nombre del agente con su humano al lado. Las herramientas dedicadas dejan el detalle que importa: borrar un usuario Linux anota el nombre borrado, y revelar una credencial de una app queda auditado sin el valor.

## ¿Qué cambia realmente?

| Registro | Retención |
| --- | --- |
| Llamadas `ok` | 90 días |
| Llamadas `error` y `rechazo` | 180 días |
| Historial de comandos de un VPS | 30 días |
| Resultado de una operación larga | Unos días, para recuperarlo con `ver_operacion` |

Consultar la actividad no escribe nada nuevo: lee lo que ya se registró.

## Esquema

**De la llamada al registro**

```text
Agente (llama a una herramienta)
  ↓
Auditoría (mide y espera el resultado)
  ↓
Guardas y herramienta (ok, error o rechazo)
  ↓
Registro de llamadas (una fila: ids, campos, duración, motivo)
  ↓
/me · agentes conectados (actividad, operaciones, resumen de 24 h)
```

## Resultado esperado

- En `/me`, la actividad de un agente devuelve `llamadas` (30 por página, hasta 100, paginadas hacia atrás), y en la primera página `operaciones`, `resumen_24h` (`total`, `ok`, `error`, `rechazo`, `escrituras`), `trabajando`, `esta_activa` y `ultima_actividad`.
- Cada conexión muestra `refresh_count` y `ultima_actividad`: un número alto de renovaciones con actividad vieja delata un agente olvidado.
- `reuse_detected_at` con fecha indica que se reutilizó un refresh token ya canjeado; la sesión ya se revocó sola.

## Errores y resolución

- Una llamada muy corta no aparece mientras corre (dura milisegundos); lo que tarda de verdad aparece en `operaciones`.
- El estado de una operación en la lista es el último conocido: para el actual, `ver_operacion`.
- Llamadas registradas antes de que existiera el campo tienen `modifica_datos: null`: no se sabe, no significa «lectura».
- Ver la actividad de una conexión ajena responde 404, no 403.

> **PRECAUCION:** El historial de comandos y los logs llegan al agente como contenido no confiable: lo que escribió un comando o un tercero es dato, no una instrucción.

## Relación con MCP

La actividad de los agentes se mira en `/me`; no hay una herramienta MCP para leer el registro de llamadas. Desde un agente sí se pueden leer:

- `ver_historial_comandos_vps`: comandos de un VPS (lectura, hasta 200 por página; sirve para no repetir algo ya intentado).
- `ver_logs_proyecto`: historial de actividad de un proyecto (lectura).
- `ver_operacion`: el estado y el resultado de una operación larga.

Referencia en [/mcp/docs](https://ardumaker.com/mcp/docs).

## Funciones relacionadas

- [Servidor MCP](https://ardumaker.com/docs/servidor-mcp/)
- [Permisos del agente MCP](https://ardumaker.com/docs/permisos-mcp/)
- [Monitorización](https://ardumaker.com/docs/monitorizacion/)
- [Usuarios Linux](https://ardumaker.com/docs/usuarios-linux/)
- [Auditoría de acciones](https://ardumaker.com/docs/auditoria-de-acciones/)