Financial Analytics Agent

Financial Analytics Agent es un agente de IA analista financiero senior para una empresa ficticia ("Northwind Labs") que responde preguntas en lenguaje natural sobre ingresos, presupuestos y anomalías de gasto con gráficas reales renderizadas dentro de un chat web en Next.js, resolviendo el problema de "preguntarle a la hoja de cálculo" sin necesitar un dashboard de BI ni un analista de datos de por medio.

Arquitectura y Stack Tecnológico

Arquitectura Central

• Framework de agente: eve (framework de agentes duraderos basado en filesystem) — instrucciones, tools y skills son archivos que eve compila y ejecuta
• Modelo: Mistral (mistral-medium-2508) vía integración directa con @ai-sdk/mistral
• Frontend: Next.js 16 App Router + React 19, useEveAgent para el chat, mismo origen (sin CORS, sin variables de URL base)
• Base de datos: Postgres (Neon vía Vercel Marketplace), cliente postgres.js
• Validación: Zod en cada input de tool y parámetro de query REST
• UI: Tailwind CSS 4 + shadcn/ui + Vercel AI Elements (PromptInput, Conversation, Suggestion) + Recharts

Arquitectura en Capas

Cliente → agente + API REST → una única librería de análisis compartida → Postgres. Las tools del agente y las rutas REST públicas llaman exactamente a las mismas funciones en agent/lib/finance.ts — no hay salto HTTP entre el agente y sus propios datos, por lo que corre de forma independiente bajo eve dev --no-ui sin ningún proceso de Next.js.

Flujo de una Petición

Características Principales

Las Tools de un Vistazo

Preguntas financieras en lenguaje natural

Ocho análisis, cada uno respaldado por una tool tipada y una ruta REST documentada: tendencia de ingresos/gastos (por mes o departamento), presupuesto vs. real con varianza, detección de anomalías (outliers por desviación estándar relativa a la categoría), desglose de categoría/mezcla de gasto, flujo de caja con neto acumulado, rentabilidad por departamento (ingresos vs. gastos y neto/margen por equipo, contribuidores netos vs. centros de costo), un resumen de totales, y un endpoint de resumen del dataset para preguntas meta ("¿cuántas transacciones tenemos?").

Skill de análisis financiero bajo demanda

Más allá de los totales crudos, una skill de eve (cargada solo cuando una pregunta la necesita, no en cada turno) enseña al modelo fórmulas de margen, crecimiento MoM/YoY, CAGR y varianza de presupuesto — y le instruye explícitamente rechazar una estimación de runway en vez de inventarla, ya que el esquema no tiene una cifra de saldo de caja que la respalde.

Dataset sintético con historias reales, no ruido aleatorio

Tres años de datos deterministas en Postgres (semilla RNG fija, se reproduce idénticamente en cada reseed) construidos alrededor de historias reales: estacionalidad y crecimiento anual en ingresos, una línea de ingresos por suscripción que compone con una caída de churn recurrente, un pico de gasto publicitario recurrente, un salto de costo por migración de plataforma más dos incidentes de infraestructura, dos rampas de proyectos de contratistas, dos impulsos de contratación, y picos puntuales de oficina/viajes — para que cada tipo de gráfica tenga algo genuino que mostrar, y las anomalías no siempre estén en los mismos uno o dos departamentos.

Preguntas sugeridas basadas en datos reales

Los chips del estado vacío no son marcadores estáticos — se construyen a partir de una llamada en vivo a /api/finance/highlights (la anomalía más grande, el departamento más sobre-presupuesto, la categoría de ingresos de más rápido crecimiento) calculada con SQL real, así que lo primero que ve un visitante ya refleja los datos sembrados reales.

Pruebas de regresión a nivel de comportamiento, no solo unitarias

Una suite pnpm eval (defineEval de eve) hace pasar al agente real por conversaciones reales y verifica lo que realmente hizo — p. ej. que comparar dos departamentos nombrados acote la gráfica solo a esos dos, o que la lista de anomalías devuelta solo cubra las categorías pedidas — detectando regresiones de prompt/tool que un test de tipos no puede ver.

Elección de modelo validada por la suite de evals, no por intuición

Se corrieron cuatro modelos de Mistral contra la misma suite de evals antes de elegir uno: el modelo original fallaba directamente el eval de seguridad aritmética, un modelo más grande chocaba con límites de tasa persistentes en esta API key, un modelo más barato pasaba —pero fallaba el mismo eval de anomalías en aproximadamente la mitad de las corridas repetidas—, y el modelo que quedó en producción es el único que pasó de forma consistente y dio una respuesta notablemente mejor en una pregunta de razonamiento abierta. La misma suite de evals detectaría una regresión si un futuro cambio de modelo empeora las cosas de nuevo.

Destacados Técnicos

Tooltips de gráficas con colores exactos y orden consciente

Un renderizador de tooltip personalizado para Recharts empareja cada valor con el color exacto de la serie que lo dibuja (el tooltip por defecto de la librería permite que un estilo de contenido temático elimine esa codificación de color), y ordena las filas ya sea por valor (para líneas que se cruzan, así el orden de arriba a abajo en el tooltip coincide con el de la pantalla) o por orden declarado (para barras/apilados agrupados, donde reordenar rompería la correspondencia visual).

Vista de gráficas expandible casi a pantalla completa

Cada gráfica se renderiza dos veces — compacta en línea, y a escala de diálogo (96vw × 92vh) detrás de un botón de expandir — desde el mismo componente puro basado en datos, sin lógica de gráfica duplicada entre los dos tamaños.

Contexto del agente siempre actualizado, nunca una fecha fija

Un resolver defineDynamic se dispara en session.started y calcula "hoy" más el rango de cobertura de datos en vivo en cada sesión, en vez de una fecha literal horneada en las instrucciones compiladas en tiempo de build (el fallo clásico de un agente que cree que sigue siendo el día en que se desplegó).

Una librería de análisis compartida, dos puertas de entrada

agent/lib/finance.ts es llamada tanto por las tools autoradas del agente como por las rutas REST (vía un helper parseQuery de Zod compartido) — un solo conjunto de queries SQL, dos formas de llegar a él: lenguaje natural para personas, HTTP plano para máquinas/scripts.

Estructura del Proyecto

agent/
├── agent.ts                  # Configuración del modelo (Mistral)
├── instructions.md            # Persona y reglas estáticas, sin fechas literales
├── instructions/dates.ts      # Resolver dinámico de "hoy" + rango de datos
├── skills/financial-analysis/ # Skill de ratios/fórmulas bajo demanda
├── hooks/log-action-failures.ts # Loguea cualquier tool/skill que falle
├── lib/
│   ├── finance.ts             # Queries de análisis compartidas
│   ├── finance.types.ts
│   ├── api-route.ts           # Helper de parseo de queries REST
│   ├── db.ts / stats.ts / rng.ts
└── tools/
    ├── get_summary.ts
    ├── get_trend.ts
    ├── get_budget_status.ts
    ├── get_anomalies.ts
    ├── get_category_breakdown.ts
    ├── get_cashflow.ts
    ├── get_profitability.ts
    └── get_data_overview.ts

app/
├── _components/
│   ├── agent-chat.tsx          # Orquestación del chat
│   ├── agent-chat/             # Nav, estado vacío, hook de highlights
│   └── tool-result/            # Un archivo por tipo de gráfica
└── api/finance/*/route.ts      # Endpoints REST, delgados sobre la librería compartida

evals/
├── evals.config.ts
└── *.eval.ts                  # Pruebas de regresión de comportamiento (pnpm eval)

db/
├── schema.sql
├── migrate.ts
└── seed.ts                     # Datos sintéticos deterministas de 3 años

Impacto y Escalabilidad

• Código abierto: disponible en GitHub
• API REST documentada: los mismos análisis son consumibles fuera del chat — por un script, un dashboard u otro servicio — sin código de backend extra
• Determinista y reproducible: reseedear la base de datos siempre produce números de demo idénticos byte a byte, así que la demo nunca se desalinea
• Extensible por diseño: agregar un nuevo análisis toca exactamente cuatro archivos (tipo, query, tool, ruta REST) más un componente de gráfica — un patrón documentado y repetible en vez de adiciones ad-hoc
• No es solo un juguete de chat: la lógica financiera, la superficie REST y las tools del agente son tres vistas sobre una única capa de análisis real, la forma que tomaría una integración de producción de verdad

Notas

El proyecto está construido sobre eve (un framework de agentes duraderos basado en filesystem) y el sistema de diseño Vercel AI Elements / shadcn. El código es público en GitHub. Para un análisis técnico más detallado, consulta la wiki de documentación completa.