Backend — plataforma de gestión de agentes

Servicio backend propio, multi-tenant, que permite a los usuarios de la web crear y administrar agentes de IA para su negocio. No reemplaza a Paperclip (orquestación) ni a LiteLLM (gateway de modelos) — los coordina y le agrega la capa de producto: negocios, usuarios, planes y una vista unificada.

Ver ../spec-backend.md para el diseño completo, y AGENTS.md para el estado real de avance, decisiones tomadas y diferencias encontradas entre el spec y las APIs reales.

• Negocios (tenants): cada negocio que se da de alta en la plataforma crea una compañía espejo en Paperclip.

• Usuarios: login/registro con JWT, roles owner / admin / viewer por negocio.

• Agentes: crear un agente desde la web dispara, en un solo flujo:

  1. una virtual key en LiteLLM con el presupuesto mensual indicado,
  2. un alta de agente en Paperclip apuntando al adapter bridge,
  3. un registro propio en la base de datos.

  Si algún paso falla a mitad de camino, se revierte lo ya creado (rollback).

• Estado y actividad: expone el estado del agente (activo/pausado) y sus eventos/tickets recientes proxyando Paperclip, sin duplicar su lógica de orquestación.

• Webhooks: recibe eventos salientes de Paperclip (agent.run.completed, agent.run.failed, issue.status.changed) para mantener el estado local sincronizado.

El frontend nunca recibe credenciales de Paperclip ni de LiteLLM directamente — todo pasa por este backend.

• Rust + Axum, runtime async con Tokio.
• PostgreSQL vía sqlx, con migraciones versionadas en migrations/.
• JWT (jsonwebtoken) para sesiones, argon2 para hash de passwords.
• OpenAPI generado con utoipa y servido con Swagger UI.

• Rust (edition 2021) y cargo.
• Una instancia de PostgreSQL accesible.
• Credenciales de una instancia de Paperclip y de LiteLLM ya desplegadas.

Copiá .env.example a .env y completá los valores:

DATABASE_URL=postgres://usuario:password@host:5432/nombre_db
JWT_SECRET=un-secreto-largo-y-aleatorio

PAPERCLIP_API_URL=https://tu-instancia-de-paperclip
PAPERCLIP_API_KEY=tu-api-key-de-servicio

LITELLM_BASE_URL=https://tu-instancia-de-litellm   # sin /v1 al final
LITELLM_MASTER_KEY=tu-master-key

ADAPTER_BRIDGE_URL=https://tu-adapter-bridge        # ver spec-paperclip-integration.md

PORT=8080

LITELLM_BASE_URL va sin el sufijo /v1 — el backend arma las rutas completas internamente (/v1/models, /key/generate, etc).

cargo run

Al arrancar, el backend aplica automáticamente las migraciones pendientes contra DATABASE_URL (no hace falta correr nada aparte) y queda escuchando en http://localhost:8080 (o el puerto que hayas configurado en PORT).

• Documentación interactiva (Swagger UI): http://localhost:8080/swagger-ui
• Spec OpenAPI en crudo: http://localhost:8080/api-docs/openapi.json
• Healthcheck: GET /health

Para probar los endpoints protegidos en Swagger UI, registrate o logueate en /api/auth/register / /api/auth/login, copiá el token de la respuesta y usá el botón Authorize con Bearer <token>.

El archivo .env solo se lee al arrancar el proceso — cualquier cambio requiere reiniciar cargo run.

src/
  main.rs              punto de entrada, router y documentación OpenAPI
  config.rs            carga de variables de entorno
  state.rs             estado compartido (pool de DB, clients HTTP)
  error.rs             manejo de errores uniforme
  auth.rs              JWT, hash de passwords, extractor de usuario autenticado
  models/              Tenant, Usuario, Agente
  clients/              clientes HTTP hacia Paperclip y LiteLLM
  routes/               handlers de la API (auth, tenants, agents, webhooks, ...)
migrations/            migraciones SQL versionadas

Contrato completo y ejemplos de request/response en Swagger UI.

Este backend está en desarrollo activo. Para el detalle de qué falta, qué decisiones se tomaron donde el spec no alcanzaba a cubrir algo, y qué se descubrió sobre el comportamiento real de Paperclip/LiteLLM (que en algunos puntos difiere de spec-backend.md), ver AGENTS.md.