AgentForge API — EXPLAINER

Concepto

AgentForge es un AI Agent Service Toolkit API-first que resuelve el problema más doloroso en el espacio de IA actual: la complejidad de construir, desplegar y operar agentes de IA fiables y con estado en producción.

Mientras que los LLMs se están convirtiendo en una commodity, el valor real reside en la capa de orquestación: gestión de estado, integración segura de herramientas, resiliencia ante fallos y observabilidad completa del razonamiento. AgentForge proporciona esa capa como un SaaS API-first, funcionando como los "picos y palas" de la fiebre del oro de la IA.

---

Arquitectura

┌──────────────────────────────────────────────────────────────────────┐
│                        REST API Layer (Spring MVC)                    │
│  AuthController  AgentController  ExecutionController  Observability  │
│  ToolConnectorController                                              │
└──────────────────────┬───────────────────────────────────────────────┘
                       │ Constructor injection (no @Autowired)
┌──────────────────────▼───────────────────────────────────────────────┐
│                        Service Layer                                  │
│  AuthService     AgentDefinitionService    ToolConnectorService       │
│  AgentOrchestrationService ←── Virtual Threads (Java 25)             │
│  ObservabilityService      JwtService  AppUserDetailsService         │
└──────────────────────┬───────────────────────────────────────────────┘
                       │ Spring Data JPA
┌──────────────────────▼───────────────────────────────────────────────┐
│                        Repository Layer                               │
│  AppUserRepository  AgentDefinitionRepository  AgentExecutionRepo     │
│  ExecutionLogRepository  ToolConnectorRepository                      │
└──────────────────────┬───────────────────────────────────────────────┘
                       │ H2 (dev) / PostgreSQL (prod)
┌──────────────────────▼───────────────────────────────────────────────┐
│                        Data Model                                     │
│  AppUser · AgentDefinition · AgentExecution · ExecutionLog            │
│  ToolConnector                                                        │
└──────────────────────────────────────────────────────────────────────┘

External Clients (Feign + Resilience4j):
  ExternalApiClient ──→ Slack / Jira / Stripe / Webhooks

Decisiones técnicas clave

Decisión	Justificación
Java Records para todos los DTOs	Inmutabilidad, compacidad, menos boilerplate
Virtual Threads (Executors.newVirtualThreadPerTaskExecutor())	Ejecuciones de agentes son I/O-bound (LLM calls, API calls). VTs permiten miles de ejecuciones concurrentes sin bloquear platform threads
FSM persistida (%%INLINE1%%)	%%INLINE2%% escrita en DB tras cada transición — resistente a crashes y reinicios
JWT stateless (JJWT 0.12.6)	Sin estado en servidor, escala horizontalmente
Credenciales cifradas (Base64 en MVP / KMS en prod)	Las credenciales nunca se exponen en ninguna respuesta HTTP
OpenFeign + Resilience4j	%%INLINE3%% + %%INLINE4%% en llamadas a herramientas externas — degradación elegante cuando APIs de terceros fallan
H2 embebida (dev) / PostgreSQL (prod)	Cero configuración para desarrollo local, producción real con PostgreSQL

---

MVP Features implementadas

Feature	Implementación
API declarativa para definir agentes	%%INLINE5%% acepta JSON + campo %%INLINE6%% para overrides en YAML
Motor de ejecución gestionado con estado	AgentOrchestrationService — ReAct loop en virtual threads, FSM persistida, reintentos automáticos
Dashboard de observabilidad	GET /api/observability/traces/{id} devuelve el trace completo con todos los pasos de razonamiento/tool-call
Conector seguro de herramientas	%%INLINE9%% — credenciales cifradas, %%INLINE10%% con circuit breaker

---

Endpoints

Auth (público — sin JWT)

POST /api/auth/register
Content-Type: application/json

{
  "username": "alice",
  "email": "alice@example.com",
  "password": "supersecret123"
}

POST /api/auth/login
Content-Type: application/json

{
  "username": "alice",
  "password": "supersecret123"
}

Respuesta:

{
  "accessToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 86400000,
  "userId": "uuid-...",
  "apiKey": "ak_..."
}

---

Agents (requiere Authorization: Bearer <token>)

POST   /api/agents              # Crear agente
GET    /api/agents              # Listar mis agentes
GET    /api/agents/{id}         # Obtener agente
DELETE /api/agents/{id}         # Eliminar agente

Ejemplo — crear agente:

{
  "name": "Slack Notifier",
  "goal": "Monitor Jira for critical bugs and notify the #alerts Slack channel",
  "model": "gpt-4o",
  "toolConnectorIds": ["connector-uuid-1", "connector-uuid-2"],
  "configYaml": "retryPolicy:\n  maxAttempts: 3\n  backoffMs: 500",
  "maxSteps": 10
}

---

Executions

POST /api/executions                    # Lanzar ejecución (202 Accepted)
GET  /api/executions/{id}               # Polling de estado
POST /api/executions/{id}/cancel        # Cancelar

Ejemplo — lanzar:

{
  "agentDefinitionId": "agent-uuid",
  "inputParameters": {
    "severity": "CRITICAL",
    "project": "FORGE"
  }
}

---

Observabilidad

GET /api/observability/traces/{executionId}         # Trace completo
GET /api/observability/traces/{executionId}/steps   # Sólo los pasos
GET /api/observability/executions?status=RUNNING    # Listado filtrado

Respuesta traces/{id} (resumen):

{
  "executionId": "...",
  "agentName": "Slack Notifier",
  "status": "SUCCESS",
  "totalSteps": 7,
  "startedAt": "...",
  "completedAt": "...",
  "steps": [
    { "stepNumber": 1, "stepType": "REASONING", "content": "..." },
    { "stepNumber": 2, "stepType": "TOOL_CALL",  "content": "..." },
    { "stepNumber": 3, "stepType": "TOOL_RESPONSE", "content": "..." },
    { "stepNumber": 4, "stepType": "FINAL_ANSWER",  "content": "..." }
  ]
}

---

Tool Connectors

POST   /api/connectors          # Registrar conector (credencial cifrada)
GET    /api/connectors          # Listar mis conectores
GET    /api/connectors/{id}     # Detalle (sin credencial)
DELETE /api/connectors/{id}     # Eliminar

Ejemplo:

{
  "name": "Slack Workspace",
  "toolType": "SLACK",
  "baseUrl": "https://hooks.slack.com/services",
  "authType": "BEARER_TOKEN",
  "credential": "xoxb-..."
}

---

Modelo de Estado (FSM)

        ┌─────────┐
  start │         │
   ─────► PENDING │
        │         │
        └────┬────┘
             │ virtual thread picks up
        ┌────▼────┐
        │         │
        │ RUNNING │
        │         │
        └────┬────┘
    ┌────────┼────────┐
    │        │        │
┌───▼──┐ ┌──▼───┐ ┌──▼────────┐
│      │ │      │ │           │
│ SUC- │ │FAIL- │ │CANCELLED  │
│ CESS │ │ ED   │ │(user req.)│
│      │ │      │ │           │
└──────┘ └──────┘ └───────────┘

Cada transición es persistida inmediatamente en la BD antes de continuar, garantizando que el sistema puede auditarse o recuperarse tras un reinicio.

---

Cómo ejecutar

Requisitos

• Java 25+
• Maven 3.9+

Inicio rápido (H2 embebida — cero configuración)

cd solutions/2026-04-12-agent-forge-api
mvn spring-boot:run

La aplicación arranca en http://localhost:8080 con H2 en memoria. El esquema se crea automáticamente (ddl-auto=create-drop).

Producción (PostgreSQL)

Añadir en application.yml o como variables de entorno:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/agentforge
    username: postgres
    password: secret
  jpa:
    hibernate:
      ddl-auto: update

forge:
  jwt:
    secret: <base64-encoded-256-bit-key>
    expiration: 86400000   # 24h en ms

Variables de configuración

Variable	Defecto	Descripción
forge.jwt.secret	clave de desarrollo	Secret HMAC-SHA256 en Base64
%%INLINE17%%	%%INLINE18%% (24h)	TTL del JWT en ms
%%INLINE19%%	%%INLINE20%%	URL base del cliente Feign

---

Análisis de Negocio

Modelo SaaS API-first

Tier	Límite	Precio objetivo
Free	50 ejecuciones/mes, 1 conector	$0
Starter	1.000 ejecuciones/mes, 5 conectores	$49/mes
Growth	20.000 ejecuciones/mes, conectores ilimitados	$249/mes
Enterprise	Ilimitado, SLA, soporte dedicado	$1.500+/mes

Ventajas competitivas

1. Durabilidad por diseño — estado FSM persistido en cada transición: cero pérdida de trabajo ante fallos.
2. Virtual Threads — escalado masivo sin infrastructure cost extra; misma instancia gestiona miles de agentes concurrentes.
3. Observabilidad de primera clase — cada decisión LLM y tool-call queda registrada; no más debugging a ciegas.
4. Seguridad de credenciales — conector seguro con cifrado en reposo; las API keys de terceros nunca viajan al cliente.

TAM / Oportunidad

El mercado de AI infrastructure / orchestration se estima en $4B+ para 2027, creciendo al 40% anual. AgentForge apunta al segmento de equipos de 5-200 ingenieros que no quieren construir su propia plataforma de orquestación.

---

Referencias

• AI Agent Service Toolkit Trend — Stackademic
• Spring Boot 4.0.4 Release Notes
• Virtual Threads — JEP 444 (Java 21+)
• ReAct: Reasoning + Acting in LLMs
• Resilience4j Documentation
• JJWT 0.12.x Reference

---

FinOps Analysis: AgentForge

Resumen Ejecutivo

AgentForge, una micro-startup de AI Agent Service Toolkit, proyecta un margen de beneficio del 70% durante su fase MVP inicial. Los costos operativos clave se dividen entre el consumo de tokens LLM y la infraestructura cloud. Con una estrategia de monetización API-first, el modelo es altamente escalable y rentable, siempre que se gestionen activamente los costos de LLM.

Desglose de Costos Mensuales (MVP)

• Estimación de Tokens LLM: ~60 millones de tokens/mes (mezcla de %%INLINE21%% para tareas generales y %%INLINE22%% para razonamiento complejo).
• Costos de APIs (LLM): $115/mes (principalmente OpenAI).

* gpt-4o-mini: ~54M tokens -> ~$15.39 * gpt-4-turbo: ~6M tokens -> ~$96.00

• Costos de Infraestructura Cloud: $35/mes (AWS t3.small EC2 para la aplicación Spring Boot, db.t3.micro RDS PostgreSQL para persistencia).
• Otros Costos: Mínimos para el MVP (monitoring básico, networking).
• Costo Total Mensual Estimado: $150

Ingresos Mensuales Estimados (MVP)

• Modelo de Monetización: SaaS API-first.
• Precio por Cliente: $50/mes (plan básico).
• Número de Clientes (MVP): 10 clientes.
• Ingreso Total Mensual Estimado: $500

Margen de Beneficio (MVP)

Cálculo: (($500 (Ingreso) - $150 (Costos)) / $500 (Ingreso)) 100 = 70%

Principales Drivers de Costo

El principal driver de costo variable son los tokens LLM. La complejidad de los agentes (número de pasos, tamaño del contexto, uso de herramientas) impactará directamente el volumen de tokens consumidos. La elección del modelo LLM (ej. %%INLINE25%% vs %%INLINE26%%) tiene un impacto significativo en el costo por token.

Estrategias de Optimización FinOps

Para mantener y mejorar este margen de beneficio a medida que la startup escala, se recomiendan las siguientes optimizaciones:

1. Optimización de Consumo de LLM:

* Caching Inteligente: Implementar un caché de respuestas para llamadas LLM con prompts determinísticos o resultados predecibles, reduciendo llamadas redundantes. * Prompt Engineering: Refinar los prompts para ser concisos y eficientes, minimizando el conteo de tokens de entrada. Utilizar resúmenes de contexto/historial cuando sea posible. * Selección Dinámica de Modelos: Utilizar modelos más económicos (%%INLINE27%%, %%INLINE28%%) para tareas de bajo valor o pasos de razonamiento más simples, reservando modelos más potentes (gpt-4-turbo) para decisiones críticas. * Exploración de Modelos Open-Source: Para tareas internas o componentes específicos del agente, investigar el auto-hospedaje de modelos open-source (ej. Llama 3, Mistral) para reducir la dependencia y el costo de APIs externas.

1. Optimización de Infraestructura Cloud:

* Auto-escalado: Configurar grupos de auto-escalado para las instancias EC2 (o migrar a AWS Fargate/GCP Cloud Run) para escalar recursos según la demanda y pagar solo por lo que se usa. * Instancias Reservadas/Savings Plans: Una vez que se establezca una carga base predecible, considerar planes de ahorro o instancias reservadas para reducir los costos de EC2 y RDS. * Optimización de Base de Datos: Asegurar que las consultas JPA sean eficientes y que la base de datos tenga los índices adecuados para evitar cuellos de botella y reducir la necesidad de escalar RDS prematuramente.

1. Monitoreo y Control de Costos:

* Etiquetado de Recursos: Implementar una estrategia de etiquetado (tagging) en los recursos cloud para una mejor visibilidad y asignación de costos. * Alertas de Presupuesto: Configurar alertas en la plataforma cloud (ej. AWS Budgets) para ser notificado si los costos se acercan a los límites predefinidos. * Dashboard de FinOps: Desarrollar un dashboard interno para monitorear el consumo de tokens por cliente/agente y los costos asociados, facilitando la identificación de ineficiencias y la implementación de políticas de uso justo.

Conclusión

AgentForge muestra un fuerte potencial de rentabilidad en su fase MVP. La clave del éxito a largo plazo residirá en una gestión proactiva y continua de los costos de LLM, combinada con una infraestructura cloud eficiente y escalable. Adoptar principios de FinOps desde el inicio permitirá a la startup crecer de manera sostenible.