Los administradores de sistemas y desarrolladores pueden autoalojar AgentGPT en su propia infraestructura mediante Docker y Docker Compose en cuestión de minutos. Al desplegar la aplicación de forma local o en una nube privada virtual (VPC), las organizaciones mantienen el control absoluto sobre la definición de objetivos, las trazas de razonamiento intermedio, el historial de prompts y los registros de la base de datos, evitando exponer el contexto operativo confidencial a plataformas SaaS públicas multiinquilino.
Esta guía detalla la arquitectura del sistema, los requisitos previos, los métodos de despliegue automatizado y manual en contenedores, las recomendaciones de securización y las consideraciones operativas para el ciclo de vida del proyecto.
Arquitectura del sistema y principios de funcionamiento
AgentGPT ejecuta flujos de agentes autónomos recursivos a través de una arquitectura multicapa en contenedores:
- Frontend (
frontend): Aplicación web desarrollada con Next.js 13, TypeScript, Tailwind CSS y HeadlessUI. Se expone en el puerto3000y permite a los usuarios configurar agentes, definir metas generales, supervisar en tiempo real la creación y ejecución de subtareas, y exportar resultados. - Motor Backend (
platform): Servicio Python basado en FastAPI que opera en el puerto8000. Coordina las cadenas de ejecución de modelos de lenguaje mediante LangChain, gestionando la descomposición de tareas, las colas de prioridad, los bucles de evaluación y el uso de herramientas. - Capa de persistencia de datos: Gestionada mediante Prisma ORM en la capa web y SQLModel en el backend, almacena configuraciones de agentes, sesiones y registros de auditoría en MySQL.
- Comunicaciones con APIs externas: Aunque el estado y la orquestación residen íntegramente en el host privado de Docker, la inferencia se realiza mediante llamadas salientes HTTPS a la API de OpenAI, con soporte opcional para Serper (búsqueda web) y Replicate (generación de imágenes).
Requisitos previos
Antes de comenzar el despliegue, compruebe que el servidor cumple con los siguientes requisitos:
- Docker y Docker Compose: Docker Engine 20.10+ o Docker Desktop con soporte para Compose v2 en funcionamiento.
- Git: Para clonar el repositorio de código fuente.
- Node.js 18+: Necesario si se utiliza el script interactivo de instalación rápida por línea de comandos.
- Credenciales de API:
- Clave de API de OpenAI activa y con cuota disponible (compatible con GPT-4 o GPT-3.5-turbo).
- (Opcional) Clave de API de Serper para habilitar búsquedas web autónomas.
- (Opcional) Token de Replicate para la generación de recursos visuales.
Método 1: Despliegue rápido mediante el script de configuración automática
El repositorio incluye un script interactivo que automatiza la configuración de variables de entorno, la instalación de dependencias y la compilación de imágenes Docker.
1. Clonar el repositorio
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
2. Ejecutar el script instalador
Ejecute el comando correspondiente según su sistema operativo:
- Linux / macOS:
./setup.sh - Windows (PowerShell o CMD):
setup.bat
3. Completar las preguntas interactivas
El instalador solicitará:
- La clave de API de OpenAI.
- Credenciales opcionales de Serper y Replicate.
- Preferencias de red y puertos de servicio.
Una vez finalizado el proceso de compilación, abra un navegador web y acceda a http://localhost:3000 para verificar la disponibilidad de la interfaz.
Método 2: Despliegue manual y operativo con Docker Compose
Para servidores de producción, flujos de integración continua (CI/CD) o entornos desatendidos, se recomienda utilizar el flujo estándar de Docker Compose.
1. Clonar e inspeccionar el repositorio
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
El archivo docker-compose.yml define los dos servicios primarios: frontend (basado en ./next/Dockerfile) y platform (basado en ./platform en fase prod).
2. Configurar las variables de entorno
Copie la plantilla de variables de entorno a la ruta requerida por Next.js:
cp .env.example ./next/.env
Edite ./next/.env con un editor de texto e introduzca los parámetros principales:
# Límite de bucles para evitar consumos descontrolados de tokens
NEXT_PUBLIC_MAX_LOOPS="50"
REWORKD_PLATFORM_MAX_LOOPS="50"
# Extremos de red internos
NODE_ENV="production"
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000"
# Seguridad de sesiones
NEXTAUTH_SECRET="genere-una-clave-secreta-aleatoria-de-al-menos-32-caracteres"
NEXTAUTH_URL="http://localhost:3000"
# Credenciales de modelos y herramientas
OPENAI_API_KEY="sk-su-clave-de-openai"
SERPER_API_KEY="su-clave-opcional-de-serper"
3. Compilar y levantar los contenedores en segundo plano
Ejecute la compilación de imágenes e inicie los servicios en modo desacoplado:
docker compose up --build -d
4. Verificar el estado de los servicios y los registros
Compruebe el estado de los contenedores:
docker compose ps
Revise los registros en tiempo real para verificar la inicialización del backend y la base de datos:
docker compose logs -f
Acceda a http://localhost:3000 para iniciar la ejecución de flujos de agentes en su entorno privado.
Buenas prácticas de seguridad para entornos corporativos
La configuración predeterminada está pensada para entornos de desarrollo local. Para implantaciones en redes empresariales compartidas, los administradores deben aplicar las siguientes medidas de refuerzo:
1. Restringir la exposición de puertos del host
Por defecto, Docker vincula los puertos 3000 y 8000 a todas las interfaces de red (0.0.0.0). Esto expone los servicios a accesos no autorizados dentro de la red local. Modifique docker-compose.yml para vincularlos exclusivamente a localhost (127.0.0.1):
services:
frontend:
ports:
- "127.0.0.1:3000:3000"
platform:
ports:
- "127.0.0.1:8000:8000"
2. Configurar un proxy inverso con cifrado TLS
Coloque un proxy inverso como Nginx, Traefik o Caddy por delante de la aplicación para gestionar certificados SSL/TLS y añadir autenticación corporativa (SSO / OAuth). Ejemplo de bloque en Nginx:
server {
listen 443 ssl http2;
server_name agent.internal.example.com;
ssl_certificate /etc/ssl/certs/internal.crt;
ssl_certificate_key /etc/ssl/private/internal.key;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}
3. Establecer límites estrictos de ejecución (bucles)
Ante objetivos ambiguos, los agentes autónomos pueden entrar en bucles recursivos continuos de descomposición de tareas. Fije siempre los parámetros NEXT_PUBLIC_MAX_LOOPS y REWORKD_PLATFORM_MAX_LOOPS en valores prudentes (entre 20 y 50) para proteger el presupuesto de API.
4. Comprender la frontera de privacidad de los datos
El autoalojamiento de AgentGPT garantiza que el software, las bases de datos locales y los registros de auditoría permanezcan dentro de su infraestructura privada. Sin embargo, las solicitudes enviadas a OpenAI se transmiten por Internet hacia los servidores del proveedor. Para casos que involucren información estrictamente confidencial, considere canalizar las peticiones a través de instancias privadas de Azure OpenAI o pasarelas intermedias con filtros de prevención de pérdida de datos (DLP).
Ciclo de vida del proyecto y consideraciones de mantenimiento
Antes de adoptar AgentGPT como estándar corporativo, los responsables de sistemas deben tener en cuenta el estado del proyecto:
- Estado de archivado: El repositorio oficial
reworkd/AgentGPTen GitHub fue archivado formalmente a principios de 2026. Aunque el código fuente es perfectamente funcional para pruebas de concepto, validaciones internas y flujos aislados, ya no recibe actualizaciones de seguridad ni correcciones activas. - Fijación de dependencias: Al construir imágenes Docker desde el código fuente, fije las versiones de las imágenes base y los paquetes de dependencias (npm y Python) para evitar roturas de compilación futuras.
- Evolución arquitectónica: Para arquitecturas complejas que exijan colaboración multiagente avanzada, integración continua de herramientas personalizadas o flujos estrictos con intervención humana (Human-in-the-loop), valore la evaluación paralela de marcos activos como CrewAI, AutoGen o LangGraph.