# Auditoria de agentes

Registro de cada chamada de um agente MCP com o resultado, operações em curso e histórico de comandos, sem salvar valores.

Fonte: https://ardumaker.com/pt/docs/auditoria-de-agentes/

- Categoria: Inteligência artificial e agentes
- Estado: Disponível
- Requisitos: Uma conta ArduMaker com pelo menos um agente ligado por MCP; Para o histórico de comandos de um VPS: acesso a esse VPS
- Ferramentas MCP (Só leem): `ver_historial_comandos_vps`, `ver_logs_proyecto`, `ver_operacion`

## O que permite fazer?

- Ver, por agente, cada ferramenta que chamou, se correu bem, falhou ou foi rejeitada, se modificava dados, sobre que ids e quanto demorou.
- Ver as operações longas em curso de um agente e um resumo das últimas 24 horas.
- Saber se um agente está trabalhando agora mesmo (atividade nos últimos 2 minutos).
- Ler o histórico de comandos de shell de um VPS: quem os correu e que humano autorizou o agente.
- Encontrar no registro de atividade do VPS e do projeto o que fez um agente, em seu nome e no do seu humano.

## Quando convém usar?

- Rever o que um agente fez enquanto ninguém o via.
- Entender porque é que um agente diz que não conseguiu fazer algo (as rejeições ficam registradas com o motivo).
- Detetar um agente esquecido que continua a renovar a sessão sem trabalhar.

## Como funciona na ArduMaker?

### Registro de chamadas

Cada chamada a uma ferramenta (salvo `ping`, que não tem autenticação) é escrita **uma vez, ao terminar**, com tudo o que se sabe dela. A auditoria envolve as outras proteções: uma rejeição por só leitura ou pelo limite de chamadas também fica escrita.

| Campo | O que guarda |
| --- | --- |
| `tool` | Nome da ferramenta |
| `resultado` | `ok`, `error` ou `rechazo` (a permissão não deixou) |
| `modifica_datos` | Se a ferramenta escreve |
| `referencias` | Só os argumentos `*_id` / `*_ids` com valor inteiro |
| `campos` | Os nomes dos argumentos, nunca os valores |
| `duracion_ms`, `perfil` | Quanto demorou e por que perfil entrou |
| `motivo` | Em `error` ou `rechazo`, o `que_paso` do erro |

> **INFO:** **Nunca se guardam valores**: pelas ferramentas passam credenciais, SQL e correios. Por isso o registro diz que se editou a tarefa 449 do projeto 12 e que campos foram enviados, mas não o texto novo.

### Comandos em um VPS

- Cada `ejecutar_comando_vps` deixa uma linha genérica no registro de atividade do VPS (“Shell command executed”) e o detalhe no histórico de comandos.
- O histórico guarda o comando (com os segredos etiquetados, como `password=` ou `PGPASSWORD=`, tapados), o diretório, o código de saída, a duração, o início da saída, quem o correu e, se foi um agente, que humano o autorizou. Também os comandos que uma proteção rejeitou.
- Conserva-se 30 dias, de propósito: o tapado não reconhece uma credencial solta sem etiqueta, por isso encurta-se o tempo em que poderia ficar guardada.

### Em nome de quem

Um agente age com um usuário próprio ligado à pessoa que o autorizou. No registro de atividade do VPS e do projeto, as suas ações aparecem em nome do agente com o seu humano ao lado. As ferramentas dedicadas deixam o detalhe que importa: apagar um usuário Linux anota o nome apagado, e revelar uma credencial de uma app fica auditado sem o valor.

## O que muda realmente?

| Registro | Retenção |
| --- | --- |
| Chamadas `ok` | 90 dias |
| Chamadas `error` e `rechazo` | 180 dias |
| Histórico de comandos de um VPS | 30 dias |
| Resultado de uma operação longa | Alguns dias, para o recuperar com `ver_operacion` |

Consultar a atividade não escreve nada novo: lê o que já foi registrado.

## Esquema

**Da chamada ao registro**

```text
Agente (chama uma ferramenta)
  ↓
Auditoria (mede e espera o resultado)
  ↓
Proteções e ferramenta (ok, erro ou rejeição)
  ↓
Registro de chamadas (uma linha: ids, campos, duração, motivo)
  ↓
/me · agentes ligados (atividade, operações, resumo de 24 h)
```

## Resultado esperado

- Em `/me`, a atividade de um agente devolve `llamadas` (30 por página, até 100, paginadas para trás), e na primeira página `operaciones`, `resumen_24h` (`total`, `ok`, `error`, `rechazo`, `escrituras`), `trabajando`, `esta_activa` e `ultima_actividad`.
- Cada link mostra `refresh_count` e `ultima_actividad`: um número alto de renovações com atividade antiga denuncia um agente esquecido.
- `reuse_detected_at` com data indica que se reutilizou um refresh token já trocado; a sessão já foi revogada sozinha.

## Erros e resolução

- Uma chamada muito curta não aparece enquanto corre (dura milissegundos); o que demora de verdade aparece em `operaciones`.
- O estado de uma operação na lista é o último conhecido: para o atual, `ver_operacion`.
- Chamadas registradas antes de o campo existir têm `modifica_datos: null`: não se sabe, não significa “leitura”.
- Ver a atividade de uma link alheia responde 404, não 403.

> **PRECAUCION:** O histórico de comandos e os logs chegam ao agente como conteúdo não confiável: o que um comando ou um terceiro escreveu é dado, não uma instrução.

## Relação com MCP

A atividade dos agentes vê-se em `/me`; não há uma ferramenta MCP para ler o registro de chamadas. A partir de um agente podem ler-se:

- `ver_historial_comandos_vps`: comandos de um VPS (leitura, até 200 por página; serve para não repetir algo já tentado).
- `ver_logs_proyecto`: histórico de atividade de um projeto (leitura).
- `ver_operacion`: o estado e o resultado de uma operação longa.

Referência em [/mcp/docs](https://ardumaker.com/pt/mcp/docs).

## Funcionalidades relacionadas

- [Servidor MCP](https://ardumaker.com/pt/docs/servidor-mcp/)
- [Permissões do agente MCP](https://ardumaker.com/pt/docs/permisos-mcp/)
- [Monitoramento](https://ardumaker.com/pt/docs/monitorizacion/)
- [Usuários Linux](https://ardumaker.com/pt/docs/usuarios-linux/)
- [Auditoria de ações](https://ardumaker.com/pt/docs/auditoria-de-acciones/)