CogniFlow AI Core — MVP Explainer

Concept

CogniFlow AI is a headless AI agent orchestration microservice targeting CTOs and Lead Engineers who need to embed autonomous agent capabilities into their existing products via a clean API — without adopting heavy, monolithic platforms like Dify or writing brittle "glue code" themselves.

The value proposition: a lightweight, API-first execution engine that manages the full lifecycle of reasoning, planning, and tool invocation for AI agents, exposing everything as composable REST endpoints.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      REST Layer (JWT Auth)                  │
│  AgentController  ExecutionController  ToolController       │
│  AuthController                                             │
└──────────────┬──────────────────────┬───────────────────────┘
               │                      │
┌──────────────▼──────────────────────▼───────────────────────┐
│                       Service Layer                         │
│  AgentService   AgentExecutionService   ToolRegistry        │
│  MemoryService  SimplePlanner           ExecutionEngine      │
└──────────────┬──────────────────────┬───────────────────────┘
               │                      │
┌──────────────▼──────────────────────▼───────────────────────┐
│                    Persistence Layer (JPA)                  │
│  AgentRepository  AgentExecutionRepository                  │
│  ToolDefinitionRepository  ExecutionStepRepository          │
│  AgentMemoryRepository                                      │
└──────────────────────────────┬──────────────────────────────┘
                               │
                        ┌──────▼──────┐
                        │ PostgreSQL  │
                        └─────────────┘

Virtual Threads (Java 25) ──────► External Tool HTTP Calls

Key Modules

Module	Responsibility
AgentController	CRUD for agents, trigger executions, manage memory
ExecutionController	Read-only trace viewer
ToolController	Secure tool registration and management
AgentExecutionService	Coordinates planning → execution lifecycle
SimplePlanner	Keyword-heuristic plan generator (LLM stub)
ExecutionEngine	Step-by-step tool invoker, virtual-thread I/O
ToolRegistry	Persistent + ephemeral tool store
MemoryService	Per-agent key-value working memory
JwtService	HS256 JWT signing and validation (HMAC-SHA256)
%%INLINE9%%	Servlet filter — validates Bearer tokens on %%INLINE10%%

---

Execution FSM

PENDING ──► PLANNING ──► EXECUTING ──► AWAITING_TOOL ──► EXECUTING (next step)
                                   └──► COMPLETED
                                   └──► FAILED

Each state transition is persisted immediately, so the trace viewer reflects live progress as steps complete.

---

API Endpoints

All endpoints under %%INLINE11%% require %%INLINE12%%. Obtain a token first from the public /v1/auth/token endpoint.

Authentication

Method	Path	Description
%%INLINE14%%	%%INLINE15%%	Issue a signed JWT (public, no auth required)

Request:

{ "subject": "my-client", "secret": "my-shared-secret" }

Response:

{ "token": "eyJ...", "expiresIn": 3600, "tokenType": "Bearer" }

---

Agents — Lifecycle Management

Method	Path	Description
%%INLINE16%%	%%INLINE17%%	Register a new agent
%%INLINE18%%	%%INLINE19%%	List all agents (?status=IDLE\|ACTIVE\|DISABLED)
%%INLINE21%%	%%INLINE22%%	Get agent by ID
%%INLINE23%%	%%INLINE24%%	Soft-delete (transitions to DISABLED)

Create Agent Request:

{
  "name": "research-agent",
  "description": "Searches and summarises information",
  "systemPrompt": "You are a concise research assistant."
}

---

Executions — Declarative Planning & Execution

Method	Path	Description
%%INLINE25%%	%%INLINE26%%	Start a new execution run
%%INLINE27%%	%%INLINE28%%	List executions for an agent
%%INLINE29%%	%%INLINE30%%	Full trace viewer (steps, I/O, timing)

Start Execution Request:

{
  "goal": "Find the latest AI research papers on agent systems",
  "tools": [
    {
      "name": "arxiv-search",
      "description": "Search arxiv for research papers",
      "baseUrl": "https://export.arxiv.org",
      "httpMethod": "GET",
      "pathTemplate": "/api/query?search_query=ai+agents&max_results=5"
    }
  ]
}

Tools can be supplied inline (ephemeral, per-execution) or omitted to use the globally registered tools from the Tool Registry.

Execution Response:

{
  "id": "uuid",
  "agentId": "uuid",
  "status": "EXECUTING",
  "goal": "Find the latest AI research papers...",
  "plan": "[{\"stepNumber\":1,\"toolName\":\"arxiv-search\",...}]",
  "createdAt": "2026-04-02T10:00:00Z",
  "completedAt": null,
  "steps": [
    {
      "id": "uuid",
      "stepNumber": 1,
      "toolName": "arxiv-search",
      "reasoning": "Step 1/1: Invoke 'arxiv-search' to search arxiv...",
      "input": "{\"query\":\"Find the latest...\",\"tool\":\"arxiv-search\"}",
      "output": null,
      "status": "AWAITING_TOOL",
      "startedAt": "2026-04-02T10:00:01Z",
      "completedAt": null,
      "errorMessage": null
    }
  ]
}

---

Tools — Secure Tool Connector

Method	Path	Description
%%INLINE31%%	%%INLINE32%%	Register a persistent tool
%%INLINE33%%	%%INLINE34%%	List all tools (API key values redacted)
%%INLINE35%%	%%INLINE36%%	Get tool by ID (API key value redacted)
%%INLINE37%%	%%INLINE38%%	Remove a tool

Register Tool Request:

{
  "name": "weather-api",
  "description": "Get current weather data",
  "baseUrl": "https://api.openweathermap.org",
  "httpMethod": "GET",
  "pathTemplate": "/data/2.5/weather",
  "apiKeyHeader": "X-API-Key",
  "apiKeyValue": "your-secret-api-key"
}

---

Memory — Per-Agent Working Memory

Method	Path	Description
%%INLINE39%%	%%INLINE40%%	List all memory entries
%%INLINE41%%	%%INLINE42%%	Upsert a memory entry
%%INLINE43%%	%%INLINE44%%	Delete a memory entry

The ExecutionEngine automatically persists each step's output to memory under the key step_{N}_output, enabling subsequent executions to build on previous results.

---

Technical Highlights

Java 25 Virtual Threads

Tool HTTP calls run on virtual threads via Thread.ofVirtual(), allowing thousands of concurrent external API calls without exhausting platform threads:

Thread.ofVirtual()
    .name("cogniflow-exec-" + execId)
    .start(() -> executionEngine.run(execId));

The %%INLINE48%% inside %%INLINE49%% is also backed by a virtual-thread executor, making blocked I/O calls cheap.

Records for DTOs

All request/response objects are immutable Java Records:

public record CreateExecutionRequest(
    @NotBlank String goal,
    @Valid List<ToolDefinitionRequest> tools
) {}

Declarative Planning Engine

SimplePlanner implements a keyword-scoring heuristic that matches goal tokens against tool names and descriptions to produce an ordered plan. In production, replace with an LLM call (e.g. OpenAI function-calling, Spring AI).

JWT Security

%%INLINE51%% implements HS256 signing/validation manually using %%INLINE52%% and %%INLINE53%% — no runtime dependency on %%INLINE54%%. %%INLINE55%% extends Spring's %%INLINE56%% (no Spring Security needed).

JPA Execution State Machine

%%INLINE57%% and %%INLINE58%% entities persist every FSM transition. The @OrderBy("stepNumber ASC") annotation guarantees chronological step ordering in the trace viewer.

---

How to Run

Prerequisites

• Java 25+
• Maven 3.9+
• PostgreSQL 15+ (running locally or via Docker)

1. Start PostgreSQL

docker run -d \
  --name cogniflow-pg \
  -e POSTGRES_DB=cogniflow \
  -e POSTGRES_USER=cogniflow \
  -e POSTGRES_PASSWORD=cogniflow \
  -p 5432:5432 \
  postgres:16

2. Configure the Application

Add to src/main/resources/application.yml (or use environment variables):

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cogniflow
    username: cogniflow
    password: cogniflow
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: false

cogniflow:
  jwt:
    secret: "change-me-in-production-use-32-chars-minimum"

3. Build & Run

mvn clean compile          # verify compilation
mvn spring-boot:run        # start the application

4. Quick API Smoke Test

# 1. Get a token
TOKEN=$(curl -s -X POST http://localhost:8080/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"subject":"dev","secret":"my-secret"}' | jq -r '.token')

# 2. Register an agent
AGENT_ID=$(curl -s -X POST http://localhost:8080/v1/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo-agent","description":"Demo agent"}' | jq -r '.id')

# 3. Start an execution with an inline tool
EXEC_ID=$(curl -s -X POST http://localhost:8080/v1/agents/$AGENT_ID/executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Search for AI agent research",
    "tools": [{
      "name": "httpbin",
      "description": "Test HTTP endpoint",
      "baseUrl": "https://httpbin.org",
      "httpMethod": "GET",
      "pathTemplate": "/get"
    }]
  }' | jq -r '.id')

# 4. Poll the execution trace
curl -s http://localhost:8080/v1/executions/$EXEC_ID \
  -H "Authorization: Bearer $TOKEN" | jq .

---

Business Analysis

Market Opportunity

The "AI agent orchestration" market is in the infrastructure layer of the AI stack — the layer every AI-powered application must traverse but no one wants to build from scratch. This positions CogniFlow as infrastructure (high switching cost, recurring revenue) rather than a feature (easily copied).

Monetisation (API-First SaaS)

Tier	Inclusions	Price Signal
Hobby	1 agent, 100 executions/month	Free
Startup	10 agents, 5 000 executions/month	~$49/month
Scale	Unlimited agents, per-step billing	Usage-based

Billing levers: execution count + step count (captures complexity).

Moat

1. Developer experience — dead-simple API, instant trace visibility.
2. Memory persistence — agents that remember across runs create stickiness.
3. Open tool connector — any REST API becomes a first-class citizen.
4. Extensible planner — easy LLM swap (replace SimplePlanner with GPT-4

function-calling, Spring AI, or Anthropic Claude for richer plans).

---

References

• ReAct: Synergising Reasoning and Acting in Language Models — arXiv:2210.03629
• Original source URL: arXiv:2601.01743
• Spring AI Documentation: https://docs.spring.io/spring-ai/reference/
• Java Virtual Threads (JEP 444): https://openjdk.org/jeps/444
• Jakarta Persistence 3.2: https://jakarta.ee/specifications/persistence/3.2/

---

FinOps Analysis para CogniFlow AI

Estimación de Costos Operativos Mensuales

Para una micro-startup como CogniFlow AI, la optimización de costos desde el día uno es crucial. Hemos estimado los siguientes costos operativos mensuales basados en un escenario inicial de adopción y uso:

• Tokens LLM: ~62.5M tokens/mes

* Detalle: Asumiendo un modelo de lenguaje eficiente como OpenAI gpt-4o-mini. Este volumen se calcula para soportar aproximadamente 12,500 ejecuciones de agentes al mes (e.g., 20 clientes x 625 ejecuciones/mes), donde cada ejecución implica 2 llamadas al LLM con prompts y respuestas de tamaño moderado (ej. 2000 input tokens, 500 output tokens por llamada). Esto resulta en un costo de $15/mes.

• Infraestructura Cloud: $25/mes

* Detalle: Una configuración lean en AWS que podría incluir una instancia AWS Lightsail de 2GB (aproximadamente $10/mes) para la aplicación Spring Boot, y una instancia de AWS RDS PostgreSQL db.t3.micro (aproximadamente $15/mes) para la persistencia de datos. Esta combinación proporciona un balance entre rendimiento y costo para una fase inicial.

• Base de Datos: Incluida en la infraestructura cloud (ver arriba).
• Monitoring/Logging: $5/mes

* Detalle: Costos mínimos asociados a servicios básicos de logging y métricas (e.g., AWS CloudWatch Logs y Metrics) para asegurar la observabilidad del sistema.

Desglose de Costos Mensuales:

• LLM (OpenAI gpt-4o-mini): $15
• Cloud (Compute - Lightsail): $10
• Base de Datos (RDS PostgreSQL): $15
• Monitoring/Logging: $5
• Costo Operativo Total Estimado: $45/mes

Estimación de Ingresos Mensuales

Basado en el modelo de monetización API-first y el público objetivo (CTOs y Lead Engineers), proyectamos un ingreso inicial conservador pero escalable:

• Ingreso Mensual Estimado: $500/mes

* Detalle: Esto podría lograrse con aproximadamente 20 clientes de adopción temprana, cada uno pagando un promedio de $25/mes. Este precio podría ser una suscripción base con un nivel de uso incluido, o un modelo puramente basado en el uso de ejecuciones de agentes y pasos del planificador.

Cálculo del Margen de Beneficio

Con los costos e ingresos estimados, el margen de beneficio inicial de CogniFlow AI es:

• Margen de Beneficio: 91%

Cálculo: (($500 de Ingresos - $45 de Costos) / $500 de Ingresos) 100 = 91%

Este alto margen refleja la naturaleza API-first y de bajo coste operativo de la micro-startup, donde la mayor inversión inicial es en desarrollo y no en infraestructura escalada. A medida que el uso y los ingresos crezcan, los costos de LLM e infraestructura escalarán, pero el modelo de negocio debería permitir mantener un margen saludable.

Optimizaciones Concretas para Reducir Costos

Para mantener este margen y asegurar la viabilidad a largo plazo, CogniFlow AI debería implementar las siguientes estrategias FinOps:

1. Optimización de Prompts y Selección de Modelos LLM por Tarea:

* Detalle: Implementar lógica para identificar la complejidad de cada paso del agente. Utilizar modelos de lenguaje más económicos (e.g., gpt-3.5-turbo o incluso modelos open-source ligeros auto-hospedados para tareas muy específicas) para tareas sencillas como parsing de JSON, validación de entrada o reformateo de datos. Reservar el gpt-4o-mini o modelos más potentes exclusivamente para la planificación compleja, el razonamiento crítico y la toma de decisiones, donde la precisión es primordial. Esto reducirá drásticamente el consumo de tokens de modelos caros y el costo por token promedio.

1. Caché de Planes de Agente y Resultados de Herramientas:

* Detalle: Desarrollar un sistema de caché robusto a nivel de aplicación (ej. usando Redis o Caffeine). Almacenar planes de ejecución de agentes generados previamente para objetivos idénticos o muy similares, así como los resultados de llamadas a herramientas externas que sean idempotentes y no cambien frecuentemente. Esto evitará llamadas redundantes a LLM y a APIs de herramientas, reduciendo tanto los costos de LLM como la latencia general del sistema.

1. Uso de Infraestructura Serverless (AWS Fargate/Lambda) para Escalabilidad y Costo-Eficiencia:

* Detalle: A medida que la demanda crezca, migrar la capa de ejecución de agentes y la API principal de una VM dedicada a contenedores serverless (como AWS Fargate o Google Cloud Run) o funciones sin servidor (AWS Lambda). Esto permitirá pagar solo por los recursos consumidos durante el procesamiento activo de las peticiones, escalando automáticamente a cero cuando no haya tráfico y eliminando los costos de recursos ociosos de las VMs dedicadas. Para la base de datos, considerar opciones serverless como Amazon Aurora Serverless v2 para que también escale automáticamente con la demanda.