Arquitectura de AI Workforce OS

Componentes#

Todo el estado de negocio vive en el backend; el runtime no guarda estado entre llamadas. Postgres, Redis, el almacenamiento de objetos y el sandbox son opcionales en desarrollo y tienen un modo de reserva.

Fronteras entre backend y runtime#

La regla central: el runtime nunca habla con Postgres, Redis ni sistemas externos. Recibe una tarea con su contexto y devuelve un resultado, solicitudes de herramientas y consumo; solo contacta al proveedor del modelo. El backend decide permisos, autonomía y presupuesto, y es el único que ejecuta herramientas.

El backend llama al runtime por HTTP con JSON en RUNTIME_URL. Si RUNTIME_TOKEN está definido en ambos lados, cada llamada lleva ese secreto como token bearer. El motor de IA queda detrás de una interfaz propia (AgentEngine), de modo que CrewAI puede reemplazarse sin tocar el backend.

Flujo de una petición#

La solicitud del usuario llega al orquestador, que pide un plan al runtime, lo valida y crea tareas. Cada tarea la ejecuta un agente que puede pedir herramientas; las acciones sensibles esperan aprobación humana y al final se sintetiza un reporte.

1. El usuario envía el texto con POST /api/v1/requests (o por el chat, que lo enruta). El backend responde 202 con request_id y emite request.received.
2. El orquestador pide el plan al runtime y lo valida antes de aceptarlo: claves duplicadas, dependencias desconocidas o circulares y profundidad máxima. Luego emite plan.created y task.created.
3. Las tareas se ejecutan respetando depends_on. Cada una cambia el estado del agente (agent.state_changed) y puede generar consultas entre agentes (message.sent) y una revisión de calidad (task.reviewed).
4. Las herramientas que pide el runtime pasan por la política de autonomía y los permisos. Si hace falta aprobación, se crea un registro pendiente (approval.requested) y la tarea queda en awaiting_approval.
5. Un usuario con permiso decide con POST /api/v1/approvals/{id}/decision. La tarea continúa o se bloquea.
6. Cuando todas las tareas terminan, el runtime sintetiza el reporte y el backend emite report.created y request.completed.
7. En paralelo se registra el costo de cada llamada y se aplica el presupuesto: budget.warning avisa y budget.exceeded pausa la ejecución.

POST /api/v1/requests {"text": "..."}      -> 202 {"request_id": "..."}
  orchestrator -> runtime POST /v1/plan          -> tasks + depends_on
  backend validates the plan                     -> plan.created, task.created*
  per task: runtime POST /v1/run-task            -> output, consults, tool_requests, usage
  tool_requests -> policy/autonomy check         -> approval.requested (if needed)
  POST /api/v1/approvals/{id}/decision           -> approval.resolved, task resumes
  runtime POST /v1/synthesize                    -> report.created, request.completed

Canal en tiempo real#

GET /ws abre un WebSocket por organización. El backend publica cada evento en Redis (canal aiworkforce:events) y un hub reenvía el cuadro solo a los clientes cuyo org_id coincide; un cuadro sin org_id se descarta. Un cuadro con audience llega solo a esos usuarios.

Al conectar llega un evento hello con la lista de agentes y después los eventos de dominio. El cliente debe recargar el estado por REST tras reconectar, porque no hay replay.

• El servidor envía ping cada 30 s y cierra si no recibe pong en 60 s.
• Un cliente lento, con 256 cuadros en cola, se desconecta.
• Con autenticación activa, el socket se cierra con el código 4401 a los 15 minutos (la vida por defecto del token de acceso) para que el cliente reconecte con un token nuevo.

{
  "id": "<uuid>",
  "type": "task.completed",
  "ts": "2026-01-01T12:03:22Z",
  "org_id": "<org id>",
  "agent_id": "sales",
  "payload": { "task": { "id": "...", "status": "done" } }
}

Modelo de datos#

Las tablas viven en Postgres y todas las de negocio llevan org_id. Esta es la vista resumida; el esquema completo está en las migraciones numeradas de backend/internal/infrastructure/postgres/migrations/.

Multi-tenencia#

El org_id viaja dentro del token de acceso y nunca se toma de la entrada del cliente. La capa HTTP lo coloca en el contexto de la petición y todas las consultas se filtran por él. Un usuario puede pertenecer a varias organizaciones y cambia de una a otra abriendo una sesión nueva.

Como defensa en profundidad, Postgres aplica row-level security:

• Cada transacción fija app.org_id con set_config(..., true), local a la transacción; las políticas comparan org_id con app_current_org().
• Si el valor falta, la consulta no ve ni escribe filas: falla cerrado.
• La aplicación hace SET ROLE a un rol sin privilegios de propietario (DB_APP_ROLE, por defecto app_user, sin BYPASSRLS); las migraciones usan MIGRATE_DATABASE_URL.
• El hub del WebSocket también filtra por organización.

Simulación frente a IA real#

El contrato HTTP del runtime es el mismo en ambos modos; cambia el motor. En simulación (con SIMULATION=true o sin ningún proveedor configurado) el runtime devuelve resultados guionados con latencias simuladas, sin red y sin costo. En modo real usa los proveedores configurados y su GET /healthz informa mode: live y el proveedor.

Si hay un proveedor configurado pero el motor real no arranca, el runtime responde en simulación con status: degraded y un aviso; no hay fallback silencioso. El backend refleja el modo en su propio GET /healthz como runtime_mode.

curl http://localhost:8080/healthz
# {"status":"ok","runtime":"up","runtime_mode":"simulation"}

Despliegue y borde#

Hay tres archivos de Compose:

• docker-compose.yml: desarrollo con cuentas. Levanta postgres, redis, objects (almacenamiento S3), agent-runtime, backend y frontend; el sandbox runner está en el perfil sandbox.
• docker-compose.demo.yml: se combina con el anterior para el modo demo abierto (AUTH_ENABLED=false).
• docker-compose.prod.yml: producción. caddy, postgres, redis, agent-runtime, backend y frontend; solo Caddy publica puertos (80 y 443).

Estructura del repositorio#

El backend sigue capas: api depende de application, que depende de domain; infrastructure implementa los puertos.

backend/            Go (chi)
  cmd/server/       main.go: composition root (wires every service)
  cmd/sandbox-runner/  code-execution runner
  internal/         domain/ application/ api/ auth/ events/ projects/ drive/
                    skills/ memory/ rewards/ connections/ controls/ audit/ ...
  internal/infrastructure/{postgres,redis,runtime,memory}
  internal/infrastructure/postgres/migrations/   numbered SQL migrations
agent-runtime/      Python FastAPI (CrewAI engine, simulation engine)
  app/              main.py, engine.py, simulation.py, crewai_engine.py, providers.py ...
frontend/           Next.js + React Three Fiber (src/app, src/components, src/lib)
e2e/                Playwright
sandbox/            sandbox container images
Caddyfile           production edge (TLS, reverse proxy)
docker-compose.yml  dev stack; docker-compose.demo.yml, docker-compose.prod.yml
docs/               SPEC.md and architecture/*.md
landing/            this public site