Cómo autoalojar AgentGPT con Docker y conectar endpoints LLM locales o privados

El autoalojamiento de AgentGPT en infraestructura propia permite a los equipos de ingeniería y ciberseguridad ejecutar flujos de trabajo con agentes autónomos de IA sin exponer indicaciones confidenciales, objetivos estratégicos ni datos corporativos a APIs públicas en la nube. Dado que los agentes autónomos operan mediante ciclos recursivos donde descomponen tareas, evalúan resultados intermedios y consultan al modelo de lenguaje decenas de veces por ejecución, utilizar endpoints locales o privados de inferencia elimina por completo las costosas facturas de tokens y las limitaciones de cuota.

AgentGPT (desarrollado de forma abierta por Reworkd) ofrece una plataforma web para la orquestación de agentes autónomos, compuesta por un frontend en Next.js, un backend de plataforma en FastAPI y una base de datos MySQL. Aunque viene preconfigurado para consultar la nube de OpenAI, una configuración adecuada de la red de Docker, las variables de entorno y motores de inferencia compatibles con la API de OpenAI (como Ollama, LocalAI o vLLM) permite disponer de un entorno totalmente aislado y bajo estricto control de privacidad.

Arquitectura y la trampa de red en contenedores Docker

La arquitectura autoalojada de AgentGPT se coordina mediante Docker Compose a través de tres servicios principales:

1. Frontend (next): Puerto 3000, interfaz de usuario para crear agentes y monitorizar la ejecución de tareas en tiempo real.
2. Plataforma Backend (platform): Puerto 8000, motor en FastAPI que gestiona los bucles de decisión, la planificación y las llamadas a los modelos LLM.
3. Base de Datos (db): Puerto 3306, instancia de MySQL para almacenar historiales de ejecución, estados de tareas y configuraciones.

+-------------------------------------------------------------------------+
| Red interna de Docker (agentgpt-network)                                |
|                                                                         |
|  [ Frontend: Next.js ] <---> [ Backend: FastAPI Platform ] <---> [ DB ] |
|         (:3000)                         (:8000)                (:3306)  |
+--------------------------------------------|----------------------------+
                                             | (REWORKD_PLATFORM_OPENAI_API_BASE)
                                             v
                     +--------------------------------------------+
                     | Máquina Host / Red Privada                 |
                     | host.docker.internal:11434/v1              |
                     | [ Ollama / vLLM / LocalAI Endpoint ]       |
                     +--------------------------------------------+

El límite de red entre el contenedor y el sistema anfitrión

El error más común al conectar modelos locales consiste en definir la dirección base de la API como http://localhost:11434 o http://127.0.0.1:11434. Dentro de un contenedor Docker, localhost apunta a su propio espacio de nombres de red aislado, no al sistema operativo anfitrión donde se ejecuta el servidor de inferencia.

Para resolver este enlace correctamente:

• macOS y Windows (Docker Desktop): Utilice http://host.docker.internal:11434/v1.
• Entornos Linux: Añada extra_hosts: ["host.docker.internal:host-gateway"] en la definición del servicio platform dentro de docker-compose.yml, permitiendo la resolución del host anfitrión a través de la pasarela de red.
• Red Compose Compartida: Si ejecuta Ollama o LocalAI en el mismo archivo Docker Compose, utilice el nombre del servicio asignado (por ejemplo, http://ollama:11434/v1).

Paso 1: Preparar el endpoint LLM local o privado

El motor de inferencia debe exponer una API REST HTTP compatible con la especificación de OpenAI (particularmente los endpoints /v1/chat/completions y /v1/models).

Opción A: Ollama (Recomendado para estaciones de trabajo y desarrollo)

Inicie Ollama enlazando a todas las interfaces de red para permitir conexiones desde Docker:

# En Linux, configure el servicio o inicie mediante variable de entorno
OLLAMA_HOST=0.0.0.0:11434 ollama serve

Descargue un modelo optimizado para seguimiento de instrucciones y razonamiento estructurado:

ollama pull qwen2.5:14b
# o bien
ollama pull llama3.1:8b

Compruebe la disponibilidad del endpoint compatible mediante cURL:

curl http://localhost:11434/v1/models

Opción B: vLLM (Recomendado para servidores con GPU y entornos empresariales)

En un servidor dedicado con aceleración por GPU, inicie el servidor compatible de vLLM:

python3 -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000

Paso 2: Clonar AgentGPT y configurar variables de entorno

Clone el repositorio oficial del proyecto:

git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT

Genere el archivo de configuración a partir de la plantilla:

cp .env.example .env

Parámetros esenciales en .env

Edite el archivo .env en la raíz (y platform/.env si compila de forma modular):

# ----------------------------------------
# Configuración del Endpoint LLM
# ----------------------------------------
# Dirección del endpoint local resuelta mediante host.docker.internal
# ATENCIÓN: No añada una barra final (/v1 y no /v1/)
REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1

# Los clientes de OpenAI exigen un texto no vacío para validar la clave
# Los motores locales omiten esta comprobación; use cualquier valor
OPENAI_API_KEY=local-secret-key

# ----------------------------------------
# Configuración de Base de Datos
# ----------------------------------------
DATABASE_URL=mysql://root:password@db:3306/agentgpt
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=agentgpt

# ----------------------------------------
# Claves de Autenticación
# ----------------------------------------
NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
NEXTAUTH_URL=http://localhost:3000

Detalle crítico: La variable REWORKD_PLATFORM_OPENAI_API_BASE no debe terminar en /chat/completions ni incluir una barra inclinada adicional /. El backend concatena la ruta interna automáticamente; una barra adicional creará rutas inválidas como //chat/completions resultando en errores HTTP 404.

Paso 3: Ajustar docker-compose.yml para servidores Linux

En sistemas Linux, edite docker-compose.yml para habilitar la resolución del host en el servicio platform:

services:
  platform:
    build:
      context: ./platform
      dockerfile: Dockerfile
    environment:
      - REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1
      - OPENAI_API_KEY=local-secret-key
      - DATABASE_URL=mysql://root:password@db:3306/agentgpt
    ports:
      - "8000:8000"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - db

  frontend:
    build:
      context: ./next
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
    depends_on:
      - platform

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: agentgpt
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

Paso 4: Construir e iniciar los contenedores

Inicie el conjunto de servicios mediante Docker Compose:

docker compose up -d --build

Compruebe los registros de inicialización del backend para confirmar la conexión con la base de datos:

docker compose logs -f platform

Una vez que todos los contenedores reporten un estado saludable, abra el navegador en http://localhost:3000.

Paso 5: Configurar la interfaz y ejecutar agentes autónomos

1. Acceder a Ajustes: Haga clic en el icono de engranaje (Settings) en la esquina inferior izquierda de la interfaz de AgentGPT.
2. Definir el Modelo: Escriba el identificador exacto del modelo cargado en su motor local (por ejemplo, qwen2.5:14b o llama3.1:8b).
3. Ajustar Parámetros:
   • Temperature: Establézcala entre 0.2 y 0.4. La generación de tareas autónomas exige un cumplimiento estricto de estructuras JSON; temperaturas altas provocan errores sintácticos o bucles no deseados.
   • Límite de Bucles (Max Loops): Fije un tope inicial de 5 a 10 iteraciones para evitar saturar la capacidad de cómputo local.
4. Desplegar un Agente:
   • Agent Name: Local-Security-Auditor
   • Goal: Analizar los riesgos de fuga de información en despliegues internos de LLM y proponer tres medidas técnicas prioritarias de contención.
   • Pulse Deploy Agent.
5. Supervisión: Observe cómo el agente descompone el objetivo en subtareas, ejecuta cada una invocando al modelo local y sintetiza las conclusiones en un informe final.

Consideraciones prácticas y selección de modelos

1. Nivel de competencia requerido en el modelo local

Los agentes autónomos exigen una capacidad analítica sensiblemente mayor que los asistentes de chat convencionales:

• Deben interpretar fielmente las restricciones del prompt del sistema y emitir respuestas en formato JSON válido.
• Necesitan evaluar críticamente si el objetivo general ha concluido para evitar iteraciones redundantes.

Modelos con menos de 7.000 millones de parámetros (7B) o sin optimización para instrucciones estructuradas suelen fallar en el análisis sintáctico. Se recomiendan:

• Mínimo viable: Llama-3.1-8B-Instruct o Qwen-2.5-7B-Instruct.
• Línea base óptima para producción: Qwen-2.5-14B/32B o Llama-3.1-70B (cuantizados para equipos con soporte de GPU adecuado).

2. Ventana de contexto y prevención de truncamiento

Conforme el agente realiza múltiples tareas consecutivas, el historial de memoria se expande con rapidez:

• En Ollama, defina un Modelfile personalizado con PARAMETER num_ctx 16384 para evitar pérdidas silenciosas de contexto durante ejecuciones largas.

3. Estado de mantenimiento del proyecto

El repositorio oficial reworkd/AgentGPT en GitHub fue archivado en enero de 2026 y permanece en modo de solo lectura. Su arquitectura actual es sólida y plenamente funcional como base para despliegues privados; no obstante, los equipos de desarrollo deben fijar las versiones de las dependencias, gestionar sus propias imágenes Docker y proteger sus credenciales locales de forma autónoma.

Referencias

• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• Docker Compose | Docker Docs
• GitHub - ollama/ollama: Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.