# Monitor en vivo

> Muestra la actividad de un agente en tiempo real.

Fuente: https://developers.plazbot.com/cli/agent/monitor/

### Monitor en tiempo real

Se conecta al monitor en tiempo real del agente y muestra cada evento a medida que ocurre: mensajes entrantes y salientes, llamadas a herramientas, peticiones a APIs, acciones, búsquedas en la base de conocimiento, tokens y errores. Sirve para depurar un agente mientras conversa con clientes reales. Se detiene con Ctrl+C.

```bash
plazbot agent monitor <agentId> [options]
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `agentId` | (posicional) | Sí | ID del agente. |
| Filtro | `-f, --filter <types>` | No | Muestra solo estos tipos de evento, separados por comas (ver tabla). |
| Sin sesión | `--no-session` | No | Oculta el ID corto de sesión en cada línea. |
| JSON | `--json` | No | Imprime un objeto JSON por evento (JSON Lines). Por defecto: `false`. |

### Tipos de evento

| Tipo | Descripción |
|------|-------------|
| `msg_in` | Mensaje entrante del cliente. |
| `msg_out` | Respuesta enviada por el agente. |
| `tool_call` | El agente decidió usar una herramienta. |
| `api_req` | Petición a la API de un servicio. |
| `api_res` | Respuesta de la API de un servicio. |
| `action` | Ejecución de una acción (etiqueta, fase, asignación...). |
| `rag` | Búsqueda en la base de conocimiento. |
| `tokens` | Consumo de tokens. |
| `error` | Error durante el procesamiento. |
| `model` | Modelo de IA usado. |
| `intent` | Intención detectada. |
| `bot_off` | El agente se desactivó en la conversación (derivación a humano). |
| `session_field` | Se guardó un dato de la sesión. |

### Ejemplos

```bash
# Ver todos los eventos de un agente en tiempo real
plazbot agent monitor age_AbcDef123

# Solo mensajes entrantes, salientes y errores
plazbot agent monitor age_AbcDef123 -f msg_in,msg_out,error

# Un evento JSON por línea, para procesarlo con jq
plazbot agent monitor age_AbcDef123 --json | jq -r 'select(.event_type == "error") | .event_title'

```

### Resultado

```text
┌──────────────────────────────────────────────────────────────┐
│  Monitor  ● Live                                             │
│  Agent: Sales Plazbot                                        │
│  Ctrl+C exit | /filter <type> | /clear | /help               │
└──────────────────────────────────────────────────────────────┘

● Connected to the real-time monitor

10:30:15 AM  ● msg_in         ¿Tienen el producto en stock? [3f2a9c]
                   | contact: Juan Pérez
10:30:16 AM  ● tool_call      check_stock 120ms [3f2a9c]
10:30:16 AM  ● api_req        GET https://api.example.com/stock [3f2a9c]
10:30:17 AM  ● api_res        200 OK 340ms [3f2a9c]
10:30:18 AM  ● msg_out        Sí, tenemos 15 unidades disponibles. [3f2a9c]
                   | contact: Juan Pérez
──────────────── new session ────────────────
10:31:02 AM  ● msg_in         Hola [8b1d4e]
```

Cada línea muestra la hora, el tipo de evento, el título (hasta 80 caracteres), la duración si aplica y el ID corto de sesión. Cuando cambia la sesión se imprime un separador `new session`. Si la conexión se corta, el CLI reconecta solo (`⟳ Reconnecting...`, `● Reconnected`).

### Comandos mientras corre

Escribe estos comandos y presiona Enter:

| Comando | Descripción |
|---------|-------------|
| `/filter <type>` | Agrega o quita un tipo de evento del filtro. |
| `/filter clear` | Quita todos los filtros. |
| `/filters` | Muestra los filtros activos. |
| `/raw` | Activa o desactiva el modo crudo (un objeto JSON por evento). |
| `/clear` | Limpia la pantalla. |
| `/help` | Muestra los comandos y los tipos de evento. |

### Salida JSON

Con `--json`, stdout solo contiene eventos, un objeto JSON por línea (JSON Lines). Los mensajes de estado (conexión, reconexión, cierre) van a stderr.

```json
{"timestamp":"2026-10-06T15:30:15.123Z","workspace_id":"wok_AbcDef123","agent_id":"age_AbcDef123","contact_id":"...","contact_name":"Juan Pérez","session_id":"3f2a9c1e-...","event_type":"msg_in","event_title":"¿Tienen el producto en stock?","event_data":"...","duration_ms":0,"level":"info"}
```

| Campo | Descripción |
|-------|-------------|
| `timestamp` | Fecha y hora del evento. |
| `workspace_id`, `agent_id` | Workspace y agente. |
| `contact_id`, `contact_name` | Contacto de la conversación. |
| `session_id` | Sesión de la conversación. |
| `event_type` | Tipo de evento (ver tabla). |
| `event_title` | Resumen del evento. |
| `event_data` | Detalle del evento. |
| `duration_ms` | Duración en milisegundos (0 si no aplica). |
| `level` | Nivel del evento. |

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `Agent "age_AbcDef123" was not found in workspace wok_AbcDef123 (zone LA).` | El ID no existe en el workspace o zona. El monitor no se conecta. | Revisa con `plazbot agent list`, o usa `-w` y `-z`. |
| `Invalid zone "<valor>".` | `-z` no es `LA` ni `EU`. | Usa `-z LA` o `-z EU`. |
| `Could not connect to the monitor: ...` | Falló la conexión en tiempo real o la autorización del monitor. | Revisa tu conexión e inténtalo de nuevo. |
| `You are not signed in.` | No hay sesión activa. | Ejecuta [`plazbot login`](https://developers.plazbot.com/cli/login). |