Crear un agente

El agente se crea dentro de Olympus, en la aplicación web, en la misma pantalla en la que se gestiona al equipo. Tarda un par de minutos.

Antes de empezar

• Necesitas administrar el equipo (config.miembros · Administrar) y las integraciones (config.integraciones · Administrar). En la práctica: dueño o administrador del negocio.
• El plan del negocio tiene que incluir API y webhooks (hoy, Mediana y Grande). Si no la incluye, el formulario lo avisa y no deja crear el agente.
• Ten claro qué va a hacer el bot. Cada plantilla es un punto de partida; lo que no necesite, quítaselo.

Paso a paso

1. En Olympus, abre Configuración → Equipo y entra en la pestaña Agentes. Pulsa Nuevo agente.

2. Ponle nombre y descripción. Sé concreto: «Cobranza · n8n», «ERP Odoo · producción». El nombre es lo que verás en el historial de cambios y en el registro de peticiones.

3. Elige una plantilla (ver la tabla de abajo). Rellena los permisos, la autonomía y los límites; todo se puede cambiar después.

4. Elige el responsable: por defecto, tú. Tiene que ser una persona del negocio que tenga, al menos, todo lo que va a tener el agente. Recibe los avisos del agente (pausas automáticas, suspensión) y puede pausarlo y reanudarlo aunque no gestione el equipo.

5. Revisa los permisos con el mismo editor que usas para las personas. Lo que un agente no puede tener aparece deshabilitado como «No disponible para agentes»; tampoco puedes darle nada que no tengas tú ni su responsable. Ver Permisos.

6. Revisa la autonomía y los límites: qué hace solo, qué necesita a una persona y sus topes diarios. Ver Autonomía y límites.

7. Pulsa Crear agente y, en su ficha, Nueva clave:

   Campo	Qué poner
   Nombre	Dónde se usa: «Servidor de producción», «Pruebas en local».
   IPs permitidas	Las IPs o rangos CIDR desde los que llama tu bot (203.0.113.7, 10.0.0.0/24). Muy recomendado: sube la puntuación de seguridad.
   Caducidad	90 días si no pones nada. Como mucho, un año.
   Límite por minuto	Opcional, de 1 a 1200. Sustituye al general para lecturas y escrituras.

8. Olympus muestra la clave una sola vez. Cópiala al gestor de secretos de tu bot. Los propietarios del negocio reciben un aviso de que se creó una clave nueva (salvo tú, si eres uno de ellos).

La clave es del agente, no del modelo de IA

Guárdala donde vive el código que llama a la API, nunca en el prompt de un modelo de lenguaje ni en un repositorio. Ver Seguridad.

Plantillas

Todas parten del rol Solo lectura: Ver en casi todo (KPIs, ventas, compras, gastos, finanzas, inventario, estados contables) y todas las sucursales. Cada plantilla quita lo que no necesita y sube a Operar solo lo que usa. Todas caben bajo el techo de los agentes.

Plantilla	Permisos sobre Solo lectura	Hace hoy por la API	Autonomía de partida	Datos personales
Analista	Ninguno: lee todo lo de Solo lectura	Nada: no escribe	Emitir, otros comprobantes y correos: prohibido	Enmascarados
Asistente de ventas	Operar en facturas, cotizaciones y contactos. Sin compras, gastos, bancos ni estados contables	Nada en automático: emitir facturas y enviarlas por correo pasan por una persona	Emitir facturas y correos: con aprobación. Otros comprobantes: prohibido	Enmascarados
Cobranza	Operar en facturas. Sin compras, gastos, bancos, estados contables ni inventario	Reenviar facturas por correo, hasta 100 al día	Emitir: prohibido. Correos: automático. Cobros: con aprobación	Enmascarados
Compras y gastos	Operar en órdenes de compra, facturas de proveedor y gastos. Sin facturas, notas, cotizaciones, guías ni suscripciones de venta	Nada todavía: registrar gastos y compras por la API llegará más adelante	Emitir: prohibido. Correos y pagos: con aprobación	Enmascarados
Contable (lectura)	Ver en los libros contables (mayor y diario)	Nada: no escribe	Emitir, otros comprobantes y correos: prohibido	Enmascarados
Integración ERP	Operar en facturas, notas, guías, retenciones, facturas de proveedor y contactos	Emitir facturas, notas, retenciones, guías y liquidaciones; reenviarlas por correo	Emitir y correos: automático, hasta 500 comprobantes al día	Visibles: emitir exige el correo y la identificación del comprador

Ninguna plantilla da costos.ver: sin él, los KPIs llegan sin costos, márgenes ni valor del inventario. Si tu bot los necesita, dáselo en el editor de permisos.

Quita lo que el bot no lee

Como todas parten de Solo lectura, también Integración ERP puede leer KPIs, compras o gastos. Si tu ERP solo emite, baja a Ninguno en el editor los módulos que no consulta: menos permisos, menos que perder si la clave se filtra.

Datos personales, siempre a propósito

Un agente solo tiene datos.personales si sus permisos lo activan expresamente, también si lo creas desde un rol (Gerente, Vendedor…) en lugar de una plantilla. Sin él, la API le enmascara los datos de contacto y no le deja descargar PDF ni XML. Ver Permisos.

La primera llamada

Comprueba que la clave es de un agente y qué puede hacer con GET /me. Con la clave de un agente, la respuesta trae el bloque agente (recortado aquí):

{
  "agente": {
    "id": "3f6c2a9e-8b1d-4c57-9e0a-5d7f1b2c4e81",
    "nombre": "Cobranza · n8n",
    "estado": "active",
    "responsable": "Ana Torres",
    "permisos": {
      "analisis.finanzas": "view",
      "contactos": "view",
      "ventas.facturas": "operate"
    },
    "permisos_sensibles": ["ventas.ver_ajenas"],
    "alcance_sucursales": "all",
    "autonomia": {
      "invoice.issue": "forbidden",
      "document.issue": "forbidden",
      "document.send_email": "auto",
      "invoice.payment": "approval"
    },
    "limites": {
      "max_document_amount": null,
      "max_daily_amount": null,
      "max_daily_documents": 200,
      "max_daily_rows_read": 20000,
      "max_daily_emails": 100,
      "ari_daily_queries": 200
    },
    "puntuacion_seguridad": 70
  },
  "negocio": { "ruc": "1790012345001", "razon_social": "COMERCIAL ANDINA S.A.", "pais": "EC" },
  "clave": { "prefijo": "dlt_k7Qm2xPa", "scopes": [], "caduca_en": "2027-01-10T15:02:11+00:00" }
}

Con una clave de integración, agente es null.

Después, pide el catálogo de KPIs: qué cifras puede pedir este agente y qué significa cada una. Es lo primero que debería leer un agente de IA antes de interpretar números.

curl

curl https://olympus.atharix.com/api/v1/kpis \
  -H "X-API-Key: $OLYMPUS_AGENT_KEY"

Python

import os

import httpx

olympus = httpx.Client(
    base_url="https://olympus.atharix.com/api/v1",
    headers={"X-API-Key": os.environ["OLYMPUS_AGENT_KEY"]},
    timeout=20,
)
catalogo = olympus.get("/kpis").json()["datos"]
for kpi in catalogo:
    print(kpi["endpoint"], "→", kpi["nombre"])

Node

const respuesta = await fetch("https://olympus.atharix.com/api/v1/kpis", {
  headers: { "X-API-Key": process.env.OLYMPUS_AGENT_KEY },
});
const { datos: catalogo } = await respuesta.json();
for (const kpi of catalogo) console.log(kpi.endpoint, "→", kpi.nombre);

{
  "datos": [
    {
      "endpoint": "/api/v1/kpis/receivables",
      "nombre": "Cobros y cartera",
      "descripcion": "Volumen de comprobantes, ratio de notas de crédito, tasa de autorización fiscal, DSO, antigüedad de la cartera (al día, 1–30, 31–60, 61–90, +90), facturas del periodo y vencidas.",
      "modulo": "analisis.finanzas",
      "parametros": ["desde", "hasta", "sucursal"],
      "definiciones": [
        { "id": "receivables.dso", "nombre": "DSO", "descripcion": "Días medios que tarda en cobrarse una factura.", "unidad": "días" },
        { "id": "receivables.overdue", "nombre": "Vencido", "descripcion": "Facturas vencidas y su saldo pendiente.", "unidad": "importe" }
      ]
    }
  ]
}

El catálogo solo lista lo que el agente puede leer: un agente de Cobranza no ve /kpis/inventory. Sigue en KPIs.

Qué ves después

En la ficha del agente, dentro de Configuración → Equipo → Agentes:

• Estado y botón Pausar. El responsable también puede pausar y reanudar.
• Puntuación de seguridad, con la lista de lo que la baja. Ver Seguridad.
• Claves: crear, rotar (la anterior sigue viva 24 horas por defecto, hasta 7 días; la nueva caduca a los 90 días de la rotación) y revocar, que es inmediato.
• Actividad: su historial (altas, cambios de permisos y autonomía, pausas, claves), su uso por día de los últimos 30 días y sus últimas 100 peticiones.
• Revocar el agente: definitivo. Revoca sus claves y lo saca del negocio; su historial se conserva.

Lo siguiente

• Permisos: qué módulo pide cada endpoint.
• Autonomía y límites: qué significa «con aprobación» hoy.
• KPIs: las cifras, con ejemplos.