Copy page

Guías

Inventariar los agentes de Lelemon para una auditoría

Documento para el equipo de cumplimiento o de tecnología que tiene que armar, y mantener al día, el inventario de los agentes de Lelemon de su organización: qué agentes hay, cómo están configurados y, sobre todo, a qué terceros viajan los datos de las personas que atienden. Sirve, por ejemplo, para alimentar el registro de actividades de tratamiento (Ley 21.719). Alcanza para implementarlo sin preguntarnos nada.

Base de la API de Lelemon: https://api.lelemon.cl

Qué resuelve esto

Un agente contesta, consulta conocimiento y, si tiene acciones, manda datos a otros sistemas: un ticket al sistema de soporte, un webhook a un n8n, un pedido a un ERP. Para el registro, lo que importa de cada agente es eso: qué datos puede mandar y hacia dónde.

Son tres lecturas, de la más general a la más fina:

1. Listar los agentes.
2. Leer cada uno: su prompt, su modelo, sus topes, sus canales, su conocimiento y las acciones que tiene concedidas, con el origen de cada destino.
3. Mantenerlo al día: releer sólo los agentes que cambiaron desde la última vez, mirando updatedAt.

Todo va con la credencial de organización en la cabecera Authorization:

Code
Authorization: Bearer lel_a1b2c3d4e5f6_<...>

---

Qué alcances pide cada cosa

Qué quieren ver	Alcance
Los agentes, su configuración, su prompt y sus acciones concedidas (slug, nombre, descripción)	agents:read
Las colecciones de conocimiento de cada agente	knowledge:read además
A qué origen sale cada acción (HTTP, servidor MCP o conector), y el catálogo de acciones de un agente	actions:read además

Para un inventario completo emitan una credencial con agents:read, knowledge:read y actions:read. Ninguna escribe: con esas tres no se puede cambiar nada en ningún agente.

El origen viaja con actions:read y no con un permiso aparte porque no abre ninguna puerta: el origen nunca fue el secreto. El secreto es el path (ver más abajo), y ese no sale con ningún alcance. Sin actions:read, el campo destinationOrigin no aparece en la respuesta: no viene vacío ni en null, simplemente no existe.

---

1. Listar los agentes

Code
GET https://api.lelemon.cl/v1/external/agents?limit=50&offset=0

Alcance: agents:read. Devuelve una página:

Code
{
  "data": [
    {
      "id": "5f0b2f58-1d7e-4d0a-9d86-6b0a4a1f3c11",
      "slug": "ventas",
      "name": "Sofía",
      "description": "Atiende consultas de ventas por WhatsApp.",
      "status": "active",
      "audience": "external",
      "runtimeType": "text",
      "channels": ["whatsapp", "api"],
      "version": 3,
      "createdAt": "2026-08-02T14:10:00.000Z",
      "updatedAt": "2026-09-20T09:30:00.000Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Mientras hasMore sea true, repitan el pedido sumándole limit al offset. El techo de limit es 500.

La lista trae todos los estados (draft, active, paused, archived): un agente pausado sigue teniendo configurada la salida de datos, y conviene que el inventario lo incluya. No trae los borrados, ni al asistente interno de la organización: esa superficie no se administra por API, en ninguna ruta.

Sale del más nuevo al más antiguo. Si se crea un agente mientras recorren las páginas, uno puede aparecer dos veces: deduplíquenlo por id.

---

2. Leer cada agente

Code
GET https://api.lelemon.cl/v1/external/agents/{agentId}

Alcance: agents:read. Con knowledge:read suma knowledge; con actions:read, cada acción suma destinationOrigin. Las acciones que salen en actions son las que el agente tiene concedidas hoy y puede usar: las nativas de Lelemon, las HTTP que registraron ustedes, las de sus servidores MCP y las de sus conectores.

Code
{
  "id": "5f0b2f58-1d7e-4d0a-9d86-6b0a4a1f3c11",
  "slug": "ventas",
  "name": "Sofía",
  "status": "active",
  "audience": "external",
  "channels": ["whatsapp", "api"],
  "version": 3,
  "systemPrompt": "Eres Sofía, la asistente de ventas de ...",
  "model": { "provider": "bedrock", "model": "claude-sonnet-4-6" },
  "maxIterations": 10,
  "maxTokens": 100000,
  "actions": [
    {
      "slug": "crear_ticket",
      "name": "Crear un ticket",
      "description": "Abre un ticket en soporte con lo que cuenta el cliente.",
      "destinationOrigin": "https://n8n.suempresa.cl"
    },
    {
      "slug": "buscar_conocimiento",
      "name": "Buscar en el conocimiento",
      "description": "Busca en los documentos del agente.",
      "destinationOrigin": null
    }
  ],
  "channelDetails": [
    { "slug": "whatsapp", "name": "WhatsApp", "connected": true }
  ],
  "knowledge": [
    { "id": "0c9d6a1e-...", "name": "Precios y garantías" }
  ]
}

Cómo se lee destinationOrigin

Valor	Significa
"https://n8n.suempresa.cl"	La acción manda datos a ese sistema. Es esquema, host y puerto si lo trae (https://api.suempresa.cl:8443). Vale para una llamada HTTP que registraron ustedes, para una acción de un servidor MCP que conectaron (es el origen del servidor) y para una de un conector (es el sitio que conectaron, como https://suempresa.atlassian.net, o el host de BigQuery).
null	Es una herramienta nativa de Lelemon (buscar en el conocimiento, recordar datos del caso, agendar, correo, herramientas del CRM) y no tiene un destino que ustedes hayan configurado. También vale null para una acción concedida que ya no existe, que el agente no puede ejecutar. Ver "Qué significa null".
"(ilegible)"	La acción sale a un destino —HTTP, servidor MCP o conector— pero su dirección guardada no se pudo interpretar. Hay que mirarla en el panel.
el campo no está	La credencial no tiene actions:read.

Qué significa null

null dice una sola cosa: la acción es una herramienta de la plataforma y el destino no lo eligieron ustedes. No dice que los datos no salgan de Lelemon. Algunas nativas usan proveedores que son de Lelemon y no varían por organización: el envío de correo, el calendario, la facturación electrónica. Esos proveedores son encargados de tratamiento de Lelemon, van en el registro como tal y no aparecen en este campo. Una acción que sí sale a un tercero que ustedes pusieron nunca viene en null: viene con su origen o con "(ilegible)".

La lista de acciones que registraron ustedes (GET /v1/external/actions) trae el mismo dato, como origin, con el mismo alcance: es el mismo origen visto por acción en vez de por agente. La lectura por agente es la que responde "¿a dónde manda datos este agente?".

El catálogo de un agente

Code
GET https://api.lelemon.cl/v1/external/agents/{agentId}/actions

Alcance: actions:read. Devuelve el catálogo entero que ese agente puede tener, con enabled diciendo cuáles tiene concedidas hoy y source diciendo de dónde vienen (Tus sistemas, Lelemon, o el nombre del servidor MCP o el conector). Cada entrada trae el mismo destinationOrigin. Sirve para separar lo que el agente tiene de lo que podría tener: para el registro cuenta lo primero, y enabled: true es el filtro. Las acciones de servidores MCP y de conectores traen su origen igual que las HTTP.

---

Qué entrega y qué no, a propósito

Se entrega	No se entrega
El prompt, entero	La URL completa de cada acción, servidor MCP o sitio de conector
Modelo y proveedor, topes de vueltas y de tokens	El path y la query de la URL
Canales y si están conectados	Los valores de las cabeceras (credenciales del sistema de ustedes)
Las colecciones de conocimiento asignadas	Las llaves del proveedor del modelo
Las acciones concedidas: slug, nombre y descripción	Los datos de contacto que hay en el perfil del agente
El origen de cada acción (HTTP, MCP o conector), con actions:read

Por qué el destino sale como origen y no como URL

Es el argumento central de esta guía, y no una limitación que vayamos a levantar: el origen nunca fue el secreto. El secreto es el path.

En un webhook de n8n, el path es el token. Quien tiene https://n8n.suempresa.cl/webhook/a7f3-... puede disparar el flujo de ustedes, sin más credencial. Entregar la URL completa a un inventario sería entregar la llave de cada integración a cualquiera que lea el inventario: el auditor, la planilla donde se copia, el correo donde se adjunta. Una URL puede además traer usuario y clave antes del host.

Y para el registro no hace falta. Lo que la ley pide saber es a qué tercero viajan los datos, y de ahí dónde está y quién es: eso lo dice el origen. Del path, lo único que se podría aprender es cuál flujo de ese tercero, y eso ya lo dice el nombre y la descripción de la acción.

Por eso ninguna credencial, con ningún alcance, recibe el path. El origen sí sale con actions:read: es justo el dato que una auditoría necesita y no sirve para entrar a nada.

---

Lo que el inventario no cubre

• Los proveedores de la plataforma. Las herramientas nativas (correo, calendario, facturación electrónica) usan proveedores de Lelemon, que son los mismos para todas las organizaciones. Salen con destinationOrigin: null y van en el registro como encargados de tratamiento de Lelemon.
• La finalidad y el país de destino que se declararon al autorizar cada acción (art. 15 bis) no se leen por API. Quedan registrados en la organización.
• Las conversaciones y los datos de las personas. El inventario describe el agente, no lo que ha atendido.

---

3. Mantener el inventario al día

Un inventario que se armó una vez deja de ser verdad el día que alguien concede una acción nueva o cambia a dónde apunta una. Se mantiene mirando updatedAt de cada agente y releyendo sólo los que cambiaron.

Qué mueve updatedAt

updatedAt de un agente cambia cuando cambia cualquiera de estas cosas:

• Sus ajustes: prompt, modelo, topes, canales, estado.
• Las acciones que tiene concedidas: se concede o se quita una.
• Lo que hace una acción que tiene concedida: se edita su dirección, su descripción o sus parámetros, se da de baja, o se borra. Una acción es de la organización y la comparten varios agentes, así que editarla mueve updatedAt de todos los que la tienen.
• Lo mismo para un servidor MCP y para un conector: cambiar la dirección del servidor, desconectarlo, que anuncie otro catálogo de herramientas, o cambiar el sitio o los límites del conector mueve a todos los agentes que tienen herramientas suyas.

Es un invariante de la base de datos: lo cumple el panel, la API y cualquier otra forma de escribir.

No lo mueven, a propósito, las llamadas de los agentes, la salud de un servidor MCP ni volver a verificar una credencial: nada de eso cambia a dónde van los datos.

Dos cosas que updatedAt no refleja, y que conviene releer de vez en cuando: las colecciones de conocimiento asignadas y si un canal está conectado. Ninguna de las dos cambia a dónde van los datos personales.

version no sirve para esto

version es el candado de expectedVersion al modificar un agente con PATCH: sube cuando se modifica el agente (PATCH, activar, pausar, dar de baja) y sirve para que dos personas no se pisen. No sube al conceder o quitar una acción, ni al editar una acción. Si subiera al editar una acción, cualquier PATCH que alguien preparó leyendo el agente antes recibiría un 409 por un cambio que ese PATCH ni toca. Para saber si algo cambió, usen updatedAt.

El ciclo

La primera vez se lee todo. Desde la segunda:

1. GET /agents y se siguen las páginas hasta hasMore: false. Cada agente trae su id y su updatedAt.
2. Se compara contra lo guardado la vez anterior, agente por agente:
   • un id que no estaba: es nuevo, se lee;
   • un updatedAt distinto del guardado: cambió, se lee;
   • el mismo updatedAt: no cambió, no se lee;
   • un id guardado que ya no está en la lista: se dio de baja o se borró, va a revisión.
3. De cada agente que se lee, GET /agents/{agentId}. Se guarda su updatedAt y lo que importa: status, systemPrompt, model, channels, knowledge y, por cada acción, slug y destinationOrigin.
4. Se compara con la lectura anterior de ese agente. Lo que cambió va a revisión de una persona.

Se compara el updatedAt contra el guardado de ese mismo agente, y no contra la hora del reloj de ustedes: así no hay que preocuparse por relojes desfasados.

Un cambio de origen es lo que más importa del ciclo: pasar de n8n.suempresa.cl a otro host es un tercero nuevo, y el registro hay que actualizarlo.

Una lectura completa cada semana, ignorando updatedAt, cubre lo que la fecha no refleja (las colecciones de conocimiento y la conexión de los canales).

Cuánto cuesta

El techo es de 200 pedidos por minuto desde una misma dirección IP (y 3.000 por credencial). La primera vez, un inventario de N agentes son 1 + N pedidos (y una página más cada 500 agentes). Después son 1 + K, con K los agentes que cambiaron, que casi siempre son pocos. Con hasta 200 pedidos entra en un minuto; con más, espacien los pedidos y reintenten con un 429. Una lectura diaria alcanza para la mayoría de las organizaciones.

Ejemplo con curl

Code
BASE=https://api.lelemon.cl/v1/external
AUTH="Authorization: Bearer $LELEMON_API_KEY"
GUARDADO=agentes-vistos.json   # {"<id>": "<updatedAt>", ...}; "{}" la primera vez

curl -s "$BASE/agents?limit=500" -H "$AUTH"   | jq -r --slurpfile visto "$GUARDADO"       '.data[] | select($visto[0][.id] != .updatedAt) | .id'   | while read -r ID; do
      curl -s "$BASE/agents/$ID" -H "$AUTH"         | jq '{id, updatedAt, slug, status, model, channels, acciones: [.actions[] | {slug, destinationOrigin}]}'
      sleep 2
    done

---

Códigos de estado

Código	Cuándo
200	Lectura correcta.
401	Credencial ausente, revocada o inválida.
403	A la credencial le falta agents:read (o actions:read en el catálogo). En la lectura de un agente, si le falta actions:read no da 403: responde sin destinationOrigin.
404	El agente no existe, no es de la organización, o es el asistente interno.
429	Pasaron un techo por minuto: 3.000 pedidos por credencial o 200 por dirección IP. Esperen lo que diga Retry-After.