Skip to content

Arquitectura

AgentCrew esta compuesto por varios sistemas interconectados que trabajan juntos para orquestar equipos de agentes IA multi-agente. Esta pagina describe cada componente, como se comunican y como estan estructurados los entornos de ejecucion.

Vision General del Sistema

La arquitectura de alto nivel sigue un diseno dirigido por mensajes donde el frontend, la API y los contenedores de agentes se comunican a traves de NATS: 

┌─────────────────────────────────────────────────────────────────┐
│                        Host Machine                             │
│                                                                 │
│  ┌──────────────┐    ┌──────────────────┐    ┌───────────────┐  │
│  │   Frontend    │    │    API Server     │    │     NATS      │  │
│  │  (React SPA)  │───▶│   (Go / Fiber)   │───▶│   (Messaging) │  │
│  │  :8080        │    │   :3000           │    │   :4222       │  │
│  └──────────────┘    └──────────────────┘    └───────┬───────┘  │
│                                                       │         │
│                              ┌────────────────────────┘         │
│                              ▼                                  │
│                    ┌───────────────────┐                        │
│                    │  Agent Container   │                        │
│                    │  ┌─────────────┐  │                        │
│                    │  │   Sidecar    │  │                        │
│                    │  │  (NATS ↔    │  │                        │
│                    │  │  stdin/out)  │  │                        │
│                    │  └──────┬──────┘  │                        │
│                    │         │         │                        │
│                    │  ┌──────▼──────┐  │                        │
│                    │  │ AI Provider  │  │                        │
│                    │  │    CLI       │  │                        │
│                    │  └─────────────┘  │                        │
│                    │                   │                        │
│                    │  /workspace ──────┼─── Host directory      │
│                    └───────────────────┘    or Docker volume    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Componentes

Frontend (React SPA)

El frontend es una aplicacion de pagina unica construida con React. Proporciona la interfaz de usuario para gestionar equipos, configurar agentes, instalar habilidades y chatear con equipos en tiempo real. Se comunica con el servidor API a traves de endpoints HTTP y conexiones WebSocket para la transmision de mensajes en vivo.

Servidor API (Go / Fiber)

El servidor API esta construido con Go usando el framework Fiber. Se encarga de:

  • Autenticacion y autorizacion: Capa de autenticacion integrada con tokens JWT, gestion de usuarios, organizaciones y control de acceso basado en roles (admin/miembro). Ver Autenticacion.
  • Endpoints de API REST para operaciones CRUD en equipos, agentes y habilidades.
  • Gestion de ajustes de la aplicacion (claves API, configuracion).
  • Gestion del runtime de Docker, incluyendo la creacion de redes, volumenes y contenedores para cada equipo.
  • Enrutamiento de mensajes NATS entre el frontend y los contenedores de agentes.
  • Aislamiento de datos multi-tenant: todas las consultas estan limitadas a la organizacion del usuario.
  • Acceso a la base de datos SQLite para almacenamiento persistente.

NATS (Mensajeria)

NATS proporciona la capa de mensajeria en tiempo real. Cada equipo obtiene su propia instancia de NATS ejecutandose en un contenedor. Los mensajes fluyen bidireccionalmente:

  • Usuario → Agente: Los mensajes de chat se publican en NATS por el servidor API y son recibidos por el proceso sidecar del agente.
  • Agente → Usuario: Las respuestas del agente se publican en NATS por el sidecar y se reenvian al frontend a traves del servidor API.

La autenticacion de NATS se maneja a traves de la variable de entorno NATS_AUTH_TOKEN, asegurando que solo los componentes autorizados puedan conectarse.

Internos del Contenedor de Agentes

El lider de cada equipo se ejecuta dentro de un contenedor Docker basado en una imagen especifica del proveedor (agent_crew_agent para Claude Code, agent_crew_opencode_agent para OpenCode). El contenedor incluye varios componentes:

Proceso Sidecar

El sidecar es un proceso ligero que conecta los mensajes NATS con la interfaz del proveedor de IA. Este:

  1. Se suscribe al subject NATS del equipo para mensajes entrantes.
  2. Reenvia los mensajes entrantes al proveedor de IA (stdin para Claude Code, API HTTP para OpenCode).
  3. Lee la salida del proveedor y publica las respuestas de vuelta a NATS.

Este diseno mantiene al proveedor de IA sin conocimiento de la infraestructura de mensajeria. El sidecar maneja toda la comunicacion de red, abstrayendo las diferencias entre proveedores detras de una interfaz unificada.

CLI de Skills

Antes de que el proveedor de IA inicie, el contenedor ejecuta el paso de instalacion de habilidades. Itera sobre las habilidades configuradas para el equipo e instala cada una usando el comando npx skills add. Las habilidades se colocan en .agents/skills/ con enlaces simbolicos creados en .claude/skills/.

Espacio de Trabajo

El directorio /workspace dentro del contenedor es:

  • Un bind mount de un directorio del host (cuando se configura una ruta de espacio de trabajo), o
  • Un volumen Docker (cuando no se especifica ruta de espacio de trabajo).

Aqui es donde los agentes leen y escriben archivos del proyecto. El directorio .claude/ dentro del espacio de trabajo contiene las instrucciones del lider, definiciones de agentes y habilidades.

Estructura del Directorio .claude/

/workspace/.claude/
  CLAUDE.md              # Leader agent instructions and team context
  agents/
    frontend-dev.md      # Worker: Frontend Developer definition
    backend-dev.md       # Worker: Backend Developer definition
    devops-engineer.md   # Worker: DevOps Engineer definition
  skills/
    skill-name → ../../.agents/skills/skill-name   # Symlinks to installed skills

Lider vs Trabajadores

Lider

El lider es el unico agente que se ejecuta dentro de un contenedor. Recibe mensajes del usuario, interpreta la solicitud y coordina el trabajo delegando tareas a los trabajadores. Las instrucciones del lider se definen en /workspace/.claude/CLAUDE.md.

Trabajadores

Los trabajadores no se ejecutan en contenedores separados. En su lugar, se definen como archivos Markdown en /workspace/.claude/agents/. Claude Code lee estos archivos y genera trabajadores como sub-agentes dentro del mismo proceso. El archivo .md de cada trabajador contiene su nombre, rol e instrucciones detalladas.

Este diseno mantiene el uso de recursos eficiente. Solo un contenedor se ejecuta por equipo, sin importar cuantos trabajadores esten definidos.

Runtime de Docker

Cuando se crea un equipo, el servidor API aprovisiona los siguientes recursos de Docker:

Recurso Descripcion
Red Una red Docker aislada para el equipo, conectando el contenedor NATS y el contenedor del agente.
Contenedor NATS Una instancia de servidor NATS dedicada al equipo, configurada con el token de autenticacion compartido.
Volumen de Espacio de Trabajo Un volumen Docker (o bind mount) para el directorio /workspace.
Contenedor del Lider El contenedor del agente ejecutando el proceso sidecar y el CLI del proveedor de IA.

Todos los recursos estan organizados por ID de equipo para evitar conflictos entre multiples equipos en ejecucion.

Runtime de Kubernetes (Proximamente)

Un runtime de Kubernetes esta planificado para despliegues en produccion. El diseno sigue la misma arquitectura logica con recursos nativos de Kubernetes:

  • Namespace por equipo: Aislamiento entre equipos usando namespaces de Kubernetes.
  • PersistentVolumeClaims: Para almacenamiento del espacio de trabajo y persistencia de la base de datos.
  • Pods: Contenedores NATS y de agentes ejecutandose como pods con limites de recursos apropiados.
  • Services: Red interna entre pods NATS y de agentes.

El runtime de Kubernetes soportara escalado horizontal, mejor gestion de recursos e integracion con infraestructura de cluster existente.

Modelo de Procesamiento de Tareas

Cada equipo de agentes ejecuta un unico proceso de agente IA dentro de su contenedor. El agente atiende una solicitud a la vez, en el orden recibido.

Cola FIFO

Cuando llegan multiples mensajes de forma concurrente (por ejemplo, dos tareas programadas disparandose al mismo tiempo, o un mensaje de chat mientras una tarea programada esta en ejecucion), el sidecar encola los mensajes y los envia uno a la vez. El agente los procesa en orden FIFO: el primer mensaje en entrar es el primero en ser respondido.

El sidecar mantiene una cola de correlacion interna para asociar cada respuesta con la solicitud correcta. Esto asegura que la tarea programada A reciba la respuesta destinada a la tarea A, incluso si la tarea B fue enviada momentos despues. 

  Solicitudes concurrentes                Procesamiento secuencial
  ┌──────────────────┐                   ┌─────────────────────┐
  │ Tarea A ─────────┼──▶ stdin ──▶      │ Agente procesa A    │
  │ Tarea B ─────────┼──▶ (en cola)      │ Agente procesa B    │
  │ Mensaje chat ────┼──▶ (en cola)      │ Agente procesa C    │
  └──────────────────┘                   └─────────────────────┘

  Cola de correlacion: [A, B, Chat]
  Respuesta A → asociada a Tarea A
  Respuesta B → asociada a Tarea B
  Respuesta C → asociada a Chat

Implementacion de la Cola por Proveedor

Ambos proveedores logran el mismo comportamiento FIFO, pero el mecanismo de serializacion difiere segun como cada CLI acepta entrada:

Aspecto Claude Code OpenCode
Interfaz stdin/stdout HTTP REST + SSE
Comportamiento de SendInput Bloqueante — la llamada escribe en stdin y espera la respuesta completa en stdout antes de retornar. No bloqueante — el HTTP POST a /prompt_async retorna inmediatamente.
Serializacion Natural: como la llamada bloquea, el siguiente mensaje no puede enviarse hasta que el actual termine. Cola explicita: el sidecar mantiene un flag busy y una cola pendiente en memoria. Cuando un prompt esta en vuelo, los nuevos mensajes se encolan. Cuando el stream SSE emite un evento result, el siguiente mensaje encolado se drena y se envia.

En ambos casos, la capa bridge mantiene una cola de correlacion compartida (scheduledRunIDs) que asocia cada respuesta con la ejecucion programada correcta, independientemente del proveedor.

Por que Un Solo Proceso por Equipo?

El proveedor de IA mantiene contexto conversacional entre mensajes. Ejecutar un unico proceso por equipo significa que el agente conserva conocimiento de interacciones previas dentro de la misma sesion — una tarea programada puede aprovechar el contexto de mensajes anteriores. Un proceso, un hilo de conversacion.

Nota: El motor de programacion puede lanzar muchas ejecuciones en paralelo (controlado por SCHEDULER_MAX_CONCURRENT), pero dentro de cada equipo los mensajes se procesan secuencialmente. Si dos tareas programadas apuntan al mismo equipo, la segunda espera a que la primera termine.

Flujo de Datos: Enviar un Mensaje

Este es el flujo completo cuando un usuario envia un mensaje a un equipo:

  1. El usuario escribe un mensaje en la interfaz de chat del frontend.
  2. El frontend envia el mensaje al servidor API via HTTP/WebSocket.
  3. El servidor API publica el mensaje en el subject NATS del equipo.
  4. El proceso sidecar dentro del contenedor del agente recibe el mensaje NATS.
  5. El sidecar reenvia el mensaje al proveedor de IA.
  6. El agente de IA procesa la solicitud, potencialmente delegando a sub-agentes trabajadores.
  7. El agente produce la salida de respuesta.
  8. El sidecar lee la salida y publica fragmentos de respuesta en NATS.
  9. El servidor API recibe los mensajes NATS y los reenvia al frontend.
  10. El frontend renderiza la respuesta en tiempo real a medida que llegan los fragmentos.

Siguientes Pasos

  • Habilidades: Entiende como las habilidades extienden las capacidades de los agentes y se integran en el contenedor.
  • Configuracion: Revisa todas las opciones de configuracion para personalizar tu despliegue.
  • Inicio Rapido: Pon AgentCrew en marcha localmente en menos de 5 minutos.