Monitoriza el uso de tokens y el coste de tus agentes IA en Java con `sprout-monitoring`

Si construyes agentes de IA en Java, tarde o temprano tienes que responder a una pregunta de dinero: ¿cuántos tokens están gastando mis agentes y modelos, y cuánto me está costando? Sprout 1.3.0 trae un módulo nuevo — sprout-monitoring — que registra el uso de agentes y modelos, el recuento de tokens y el coste, desglosado por modelo, por agente y por herramienta. Lo mejor: se integra en tu app en una línea y tus agentes no cambian en absoluto.

TL;DR

Nuevo módulo sprout-monitoring en Maven Central (Sprout 1.3.0).

Registra uso de tokens, coste y número de llamadas por modelo, por agente y por herramienta.

Construido íntegramente sobre el bus de eventos de Sprout — sin sobrecoste en el bucle del agente.

Un nuevo componente @UsageStore con un store en memoria por defecto; cámbialo por una base de datos, Prometheus o StatsD.

Funciona automáticamente como bean de Spring con el starter de Spring Boot.

Qué registra `sprout-monitoring`

Añade el módulo, ejecuta tus agentes y lee un resumen de todo lo que han usado:

Models:
  WeatherStubModel: 6 calls, 297 in + 60 out tokens, $0.001791
Agents:
  WeatherAgent: 3 runs (3 ok / 0 failed), 6 iterations, 357 tokens
Tools:
  forecast: 3 calls
Totals: 6 model calls, 357 tokens, $0.001791

Esa es toda la propuesta: contabilidad de tokens y coste siempre activa, desglosada tal y como piensas tu sistema — por modelo, por agente, por herramienta y como total global. Sin dashboards que montar antes de ver los números.

Cómo funciona: construido sobre el bus de eventos de Sprout

Esta es la parte de la que estamos orgullosos: la monitorización no añade trabajo al bucle del agente. Está construida íntegramente sobre el bus de eventos que viene en el core de Sprout.

A medida que los agentes se ejecutan, el bucle ya publica un conjunto de eventos de ciclo de vida: AgentStartedEvent / AgentCompletedEvent / AgentFailedEvent, ModelRequestEvent / ModelResponseEvent y ToolCalledEvent. La monitorización no es más que un suscriptor bien educado. Un pequeño colector escucha los eventos que llevan la información de uso y los va acumulando en un store:

public void subscribe(AbstractEventBus bus) {
    bus.subscribe(ModelResponseEvent.class, this::onModelResponse);
    bus.subscribe(AgentCompletedEvent.class, this::onAgentCompleted);
    bus.subscribe(AgentFailedEvent.class, this::onAgentFailed);
    bus.subscribe(ToolCalledEvent.class, this::onToolCalled);
}

Como consume los mismos eventos tanto si el modelo se ejecuta dentro de un agente como por su cuenta, todo se cuenta exactamente una vez, y el código del agente permanece ajeno a todo ello. Es observabilidad como efecto secundario de eventos que ya estaban circulando — sin instrumentación, sin envoltorios, sin hooks repartidos por tu lógica de negocio.

Precios: convertir tokens en coste

El recuento de tokens es exacto; el coste depende de tus tarifas. Las configuras por modelo con propiedades sencillas — sprout.monitoring.pricing.<modelName>.input / .output, cada una un precio por millón de tokens:

sprout.monitoring.pricing.AnthropicModelExecutor.input=3.0
sprout.monitoring.pricing.AnthropicModelExecutor.output=15.0

Un modelo sin tarifa sigue registrando sus tokens, con coste cero, así que nunca pierdes datos mientras esperas a poner un precio.

Un nuevo componente `@UsageStore`, cableado como cualquier otro

Los datos aterrizan en un @UsageStore — un nuevo tipo de componente que se comporta exactamente como los stores y modelos que ya conoces en Sprout. Se cablea mediante su propio @Processor, el mismo punto de extensión que da vida a @Model y @ConversationStore: el processor registra el store (bajo el nombre usageStore) y suscribe el colector al bus. Y ya está.

El módulo trae un store en memoria por defecto, InMemoryUsageStore. ¿Quieres guardar el uso en algo persistente — una base de datos, Prometheus, StatsD? Implementa la interfaz, anótala y deja que se escanee en tu propio paquete:

@UsageStore
public class PrometheusUsageStore implements AbstractUsageStore {
    // registra llamadas a modelos, ejecuciones de agentes e invocaciones de herramientas como prefieras
}

Tu bean es ahora el store, sin que cambie nada más — el mismo modelo de "cambia el componente" que @EventBus y @ConversationStore. Este es el principio de diseño al que Sprout vuelve una y otra vez: eliges el comportamiento que quieres escogiendo un componente, no editando un framework.

Cómo añadir monitorización a tu app de Sprout (3 pasos)

1. Añade la dependencia desde Maven Central:

<dependency>
    <groupId>io.github.ivannavas</groupId>
    <artifactId>sprout-monitoring</artifactId>
    <version>1.3.0</version>
</dependency>

2. Pon el store en memoria en tu escaneo de componentes (igual que el ejemplo de RAG incorpora el vector store en memoria del core):

sprout.scan.base-packages=com.example.app,io.github.ivannavas.sprout.monitoring.impl

3. Lee los totales desde donde quieras:

AbstractUsageStore store = container.getSingleton("usageStore");
UsageSnapshot usage = store.snapshot();

System.out.println(usage.modelCalls() + " calls, "
        + usage.totalTokens() + " tokens, $" + usage.totalCost());

usage.byAgent().get("WeatherAgent");            // ejecuciones (ok/fallidas), iteraciones, tokens
usage.byModel().get("AnthropicModelExecutor");  // llamadas, tokens, coste
usage.byTool().get("forecast");                 // número de llamadas

Sin cambios en los agentes. Sin código pegamento.

Uso con Spring Boot

Como el store es un singleton gestionado llamado usageStore, si ejecutas Sprout dentro de Spring Boot con el starter, queda expuesto como un bean de Spring automáticamente. Inyecta AbstractUsageStore en un @RestController y sirve métricas de tokens y coste en vivo desde un endpoint — sin configuración extra.

Preguntas frecuentes

¿Cómo registro el uso de tokens de un LLM en Java?

Añade sprout-monitoring a una app de Sprout y pon su paquete de store en tu escaneo de componentes. Cada llamada a un modelo publica un ModelResponseEvent con su TokenUsage, que el colector registra — así el uso de tokens se contabiliza automáticamente, sin cambios en tus agentes.

¿Cómo calculo el coste de un agente de IA?

Configura una tarifa por modelo con sprout.monitoring.pricing.<model>.input/.output (precio por millón de tokens). La monitorización multiplica tus recuentos de tokens por esas tarifas y expone los totales de forma global y por modelo.

¿Funciona con modelos de OpenAI y Anthropic?

Sí. Funciona con cualquier @Model de Sprout, incluidos sprout-openai y sprout-anthropic, porque observa los eventos del modelo y no la API de un proveedor concreto.

¿Puedo guardar el uso en una base de datos o en Prometheus en vez de en memoria?

Sí. Implementa AbstractUsageStore, anótalo con @UsageStore y reemplaza al store en memoria por defecto — apuntando el uso a una base de datos, Prometheus, StatsD o donde quieras.

¿La monitorización ralentiza mis agentes?

No. Solo se suscribe a eventos que el bucle del agente ya publica; el store en memoria por defecto hace una agregación barata en proceso, así que no hay llamadas extra al modelo ni sobrecoste medible.

Consíguelo

sprout-monitoring está disponible en Maven Central como parte de Sprout 1.3.0, junto al resto de módulos (core, anthropic, openai, mcp, orchestration, spring-boot-starter). Hay un ejemplo ejecutable en sprout-examples (-Pmonitoring) que produce el informe de arriba, totalmente offline.

Construye agentes que puedas ver — entonces sabrás exactamente cuánto cuestan.

Monitoriza el uso de tokens y el coste de tus agentes IA en Java con sprout-monitoring

Qué registra sprout-monitoring