AgentSphere API

Concepto

AgentSphere resuelve la sobrecarga de mensajería de las pymes: agentes de IA "no-code" que atienden WhatsApp Business e Instagram Direct 24/7, califican leads y escalan a un humano cuando hace falta. Modelo SaaS por niveles según volumen de conversaciones y canales conectados.

Este repo es el MVP backend: Spring Boot 4.0.4 + Java 25.

Arquitectura

controller/   REST endpoints (auth, business, knowledge-base, webhooks, conversations)
service/      lógica de negocio (auth, business, RAG, IA, conversaciones, webhooks)
client/       clientes OpenFeign hacia OpenAI y la API Graph de Meta
security/     JWT (emisión/validación), filtro, UserDetailsService
repository/   Spring Data JPA sobre PostgreSQL
model/        entidades JPA + enums
dto/          records de entrada/salida por dominio (auth, business, knowledge, conversation)
config/       SecurityConfig, FeignConfig, *Properties (@ConfigurationProperties), JacksonConfig (pre-existente)
exception/    GlobalExceptionHandler + errores tipados

Capas separadas, inyección por constructor, DTOs como records, entidades JPA como clases mutables (JPA no soporta records como entidades gestionadas).

Motor RAG (simulado, sin dependencias externas)

KnowledgeBaseService trocea el texto ingerido (PDF/FAQ ya extraído a texto plano, o HTML de una URL vía RestClient), calcula un embedding ligero por hashing de términos (256 dims) y recupera los fragmentos más relevantes por similitud coseno. Sustituye a una base vectorial real (Pinecone/Weaviate) para el MVP; la interfaz (buildRelevantContext) es el punto de reemplazo cuando se integre una BD vectorial de verdad.

IA generativa

AiResponseService arma el prompt (contexto RAG + mensaje del cliente) y llama a %%INLINE4%% (Feign) contra %%INLINE5%%. Si openai.api-key no está configurada o la llamada falla, cae a una respuesta simulada basada en el contexto recuperado — el flujo completo funciona sin credenciales reales.

Canales de mensajería

MetaGraphClient (Feign) envía mensajes salientes a la API Graph de Meta (%%INLINE8%%) para WhatsApp e Instagram. %%INLINE9%% expone la verificación (%%INLINE10%%, handshake %%INLINE11%%) y la recepción (POST) de mensajes entrantes en tiempo real; WebhookService los parsea y ConversationService decide si responde la IA o si la conversación está pausada/escalada.

Endpoints

Método	Ruta	Auth	Descripción
POST	/api/auth/register	pública	Alta de dueño de negocio + negocio inicial, devuelve JWT
POST	/api/auth/login	pública	Login, devuelve JWT
GET	/api/businesses/me	JWT	Datos del negocio autenticado
POST	/api/businesses/me/channels	JWT	Conecta WhatsApp o Instagram (tokens obtenidos vía OAuth de Meta)
POST	/api/knowledge-base/documents	JWT	Ingesta texto (PDF ya extraído / FAQ) para el agente
POST	/api/knowledge-base/url	JWT	Ingesta la web del negocio por URL
GET	/api/webhooks/meta	pública	Verificación del webhook (Meta)
POST	/api/webhooks/meta	pública	Recepción de mensajes entrantes (Meta)
GET	/api/conversations	JWT	Lista conversaciones del negocio
GET	/api/conversations/{id}/messages	JWT	Historial de una conversación
POST	/api/conversations/{id}/messages	JWT	Envío manual (pausa la IA, escala a humano)
POST	/api/conversations/{id}/resume-ai	JWT	Reactiva la IA en la conversación

Referencias

• technicalRequirements del BusinessCase: LLM (OpenAI vía Feign), RAG

(embeddings + similitud coseno in-memory, sustituible por vector DB), API Graph de Meta (Feign + webhooks), JWT (jjwt 0.12.6).

• implementationGuide: seguido paso a paso — setup, seguridad JWT,

conexión de canales, ingesta RAG, procesamiento de webhook, envío de respuesta, dashboard.

Análisis de negocio

• Valor: automatiza el primer nivel de atención en los canales donde ya

están las pymes (WhatsApp/Instagram), sin requerir personal 24/7.

• Diferenciación: especialización en mensajería directa (no un CRM

genérico), constructor de agentes sin código, handoff a humano con un clic desde el dashboard.

• Monetización: el modelo de datos ya separa negocio/canales/mensajes,

base natural para medir conversaciones/mes y canales conectados por cliente (tiers de suscripción).

• Riesgo técnico cubierto en el MVP: si no hay credenciales de

OpenAI o Meta, el sistema sigue operando (respuestas simuladas, mensajes visibles en el dashboard) — permite hacer demos y pruebas de flujo antes de dar de alta las integraciones reales.

Cómo ejecutar

# Requiere PostgreSQL accesible; configurar spring.datasource.* en
# application.yml o variables de entorno si no se usa el default embebido.
mvn clean compile
mvn spring-boot:run

Variables de entorno relevantes (todas opcionales, con defaults de desarrollo):

JWT_SECRET, JWT_EXPIRATION-MS
META_GRAPH-API-BASE-URL, META_WEBHOOK-VERIFY-TOKEN, META_APP-ID, META_APP-SECRET
OPENAI_BASE-URL, OPENAI_API-KEY, OPENAI_MODEL

Flujo de prueba end-to-end:

1. POST /api/auth/register → obtener JWT.
2. POST /api/knowledge-base/documents con una FAQ → entrena al agente.
3. %%INLINE31%% con %%INLINE32%% → simula

conexión OAuth.

1. POST /api/webhooks/meta con un payload de mensaje entrante → la IA

responde usando el contexto cargado (visible en GET /api/conversations/{id}/messages).

1. POST /api/conversations/{id}/messages → toma control manual.

---

FinOps Analysis para AgentSphere

Resumen de Costos y Rentabilidad

AgentSphere, en su fase de micro-startup con 20 clientes iniciales, demuestra una estructura de costos extremadamente eficiente y un margen de beneficio notablemente alto. Esto se debe principalmente a la elección estratégica de un modelo LLM de bajo costo (gpt-4o-mini) y una infraestructura cloud lean.

• Ingresos Mensuales Estimados: $750 (basado en 15 clientes Basic @ $25/mes y 5 clientes Standard @ $75/mes).
• Costos Operativos Mensuales Estimados: $70

* LLM (OpenAI gpt-4o-mini): $15 (cubriendo ~14M tokens, incluyendo chat y embeddings). * Cloud Hosting (AWS): $55 (incluye una instancia EC2 t3.small para la API, una instancia RDS db.t3.micro para PostgreSQL, almacenamiento S3 mínimo, transferencia de datos y monitoreo básico. Se asume el tier gratuito de Pinecone para la base de datos vectorial).

• Margen de Beneficio: 91%

Desglose de Uso y Costos de LLM

La estimación de tokens se basa en un total de 4,000 conversaciones gestionadas al mes (promedio de 200 conversaciones por cliente), con cada conversación involucrando aproximadamente 3,300 tokens (entrada y salida combinados). Adicionalmente, se incluyen tokens para la actualización mensual de datos RAG y las consultas de embedding.

La elección de %%INLINE37%% es un factor clave en la contención de costos, ya que su precio por token es significativamente menor que el de modelos más grandes o incluso %%INLINE38%%, manteniendo un rendimiento adecuado para la mayoría de los casos de uso de mensajería.

Estrategia de Infraestructura Cloud

La infraestructura se ha diseñado para ser minimalista, utilizando servicios de AWS con instancias de bajo costo (%%INLINE39%% y %%INLINE40%%). Esto es apropiado para una micro-startup que busca validar su producto y optimizar el gasto inicial. La dependencia del tier gratuito de Pinecone para el vector store es una ventaja crucial en esta etapa.

Recomendaciones FinOps para Optimización de Costos

Para mantener este alto margen de beneficio y escalar de manera sostenible, AgentSphere debería considerar las siguientes optimizaciones FinOps:

1. Caché de Respuestas LLM: Implementar una capa de caché robusta para las respuestas generadas por el LLM, especialmente para preguntas frecuentes o consultas idénticas. Esto reducirá drásticamente las llamadas redundantes a la API de OpenAI y, por ende, el consumo de tokens.
2. Optimización de RAG y Prompt Engineering: Refinar continuamente las estrategias de chunking y recuperación de documentos para el RAG. Asegurarse de que solo el contexto más relevante y conciso se envíe al LLM para cada consulta, minimizando así el número de tokens de entrada. La optimización de los prompts también puede reducir el tamaño del input.
3. Exploración de Serverless para Cargas Intermitentes: Para componentes específicos con cargas de trabajo intermitentes (ej. el endpoint de webhook de Meta para recibir mensajes o el servicio de ingesta de documentos), evaluar la migración a funciones serverless (como AWS Lambda). Esto permite pagar solo por la ejecución, lo que puede ser más rentable que mantener instancias siempre activas para tráfico variable.
4. Gestión Inteligente de la Base de Datos Vectorial: Si el volumen de vectores supera el tier gratuito de Pinecone, antes de escalar a un plan de pago, considerar la implementación de pgvector directamente en la base de datos PostgreSQL existente. Esto consolidaría los datos y evitaría un costo adicional de un servicio de vector database separado, aunque podría requerir ajustes en la gestión de la base de datos.
5. Monitoreo y 'Rightsizing' Continuo de Recursos Cloud: Utilizar herramientas de monitoreo (ej. AWS CloudWatch) para supervisar de cerca la utilización de CPU y RAM de las instancias EC2 y RDS. Si la utilización es consistentemente baja, considerar el 'downsizing' a instancias aún más pequeñas (ej. %%INLINE42%% o %%INLINE43%% para EC2) o explorar planes de ahorro como Reserved Instances (RI) o Savings Plans una vez que la carga de trabajo sea predecible y estable a largo plazo.