Como Auto-Hospedar o AgentGPT com Docker e Conectar Endpoints LLM Locais ou Privados

A auto-hospedagem do AgentGPT em infraestrutura própria permite que equipes de engenharia e segurança executem agentes autônomos de IA sem expor prompts internos, metas confidenciais ou dados estratégicos a APIs de nuvem pública. Como os agentes autônomos operam por meio de ciclos recursivos — decompondo objetivos em subtarefas, avaliando saídas intermediárias e consultando o modelo de linguagem dezenas de vezes por execução —, utilizar endpoints locais ou privados de inferência elimina também custos recorrentes com tokens e limitações de requisição.

O AgentGPT (desenvolvido como software de código aberto pela Reworkd) oferece uma plataforma web para orquestração de agentes autônomos, estruturada em um frontend em Next.js, uma plataforma backend em FastAPI e um banco de dados relacional MySQL. Embora venha configurado para utilizar a infraestrutura da OpenAI, ajustes nas redes do Docker, nas variáveis de ambiente e em servidores de inferência compatíveis com a API OpenAI (como Ollama, LocalAI ou vLLM) viabilizam um ambiente totalmente privado e isolado da internet.

Visão Geral da Arquitetura e a Fronteira de Rede do Docker

A execução do AgentGPT via Docker Compose distribui as funções em três contêineres principais:

1. Frontend (next): Porta 3000, interface web para criação de agentes e monitoramento das etapas de execução em tempo real.
2. Plataforma Backend (platform): Porta 8000, serviço em FastAPI responsável pelo ciclo de decisão autônoma, fila de tarefas e conexões com modelos LLM.
3. Banco de Dados (db): Porta 3306, instância MySQL que armazena históricos de sessões, estados de tarefas e configurações.

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

O Desafio de Conectar o Contêiner ao Sistema Host

O erro mais frequente na configuração de modelos locais é apontar a URL da API para http://localhost:11434 ou http://127.0.0.1:11434. Dentro de um contêiner Docker, localhost faz referência ao ambiente de rede isolado do próprio contêiner, e não ao sistema operacional hospedeiro onde o servidor de inferência está em execução.

Para estabelecer a comunicação correta:

• macOS e Windows (Docker Desktop): Utilize http://host.docker.internal:11434/v1.
• Ambientes Linux: Inclua extra_hosts: ["host.docker.internal:host-gateway"] na definição do serviço platform no docker-compose.yml, permitindo resolver o IP do gateway do host.
• Mesma Rede Docker: Caso execute o Ollama ou LocalAI também via contêiner no mesmo Compose, utilize diretamente o nome do serviço (por exemplo, http://ollama:11434/v1).

Passo 1: Preparar o Endpoint LLM Local ou Privado

O servidor de inferência deve disponibilizar uma API HTTP REST compatível com o padrão OpenAI (especialmente as rotas /v1/chat/completions e /v1/models).

Opção A: Ollama (Recomendado para Estações de Trabalho e Desenvolvimento)

Inicie o Ollama vinculado a todas as interfaces de rede para permitir conexões provenientes de contêineres:

# No Linux, defina a variável no systemd ou execute diretamente
OLLAMA_HOST=0.0.0.0:11434 ollama serve

Baixe um modelo com boa capacidade de raciocínio lógico e adesão a formatos estruturados:

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

Valide a resposta do endpoint com cURL:

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

Opção B: vLLM (Recomendado para Servidores Dedicados com GPU)

Inicie o servidor compatível do vLLM em sua máquina dedicada:

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

Passo 2: Clonar o AgentGPT e Configurar Variáveis de Ambiente

Clone o repositório oficial:

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

Crie o arquivo de ambiente a partir do exemplo fornecido:

cp .env.example .env

Variáveis Essenciais no .env

Edite o arquivo .env na raiz do projeto (e também platform/.env se fizer builds individuais):

# ----------------------------------------
# Configuração do Endpoint LLM
# ----------------------------------------
# Aponta para o endpoint do host resolvido via host.docker.internal
# AVISO: Não inclua barra final no endereço (/v1 e não /v1/)
REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1

# O SDK da OpenAI exige uma chave não vazia para validação de formato
# Servidores locais não validam o valor; utilize uma string genérica
OPENAI_API_KEY=local-secret-key

# ----------------------------------------
# Banco de Dados
# ----------------------------------------
DATABASE_URL=mysql://root:password@db:3306/agentgpt
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=agentgpt

# ----------------------------------------
# Segurança e Sessão
# ----------------------------------------
NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
NEXTAUTH_URL=http://localhost:3000

Atenção à sintaxe: Não adicione /chat/completions nem barras adicionais ao final de REWORKD_PLATFORM_OPENAI_API_BASE. A plataforma concatena internamente os caminhos da API; a presença de barras extras resulta em rotas corrompidas (//chat/completions) e falhas HTTP 404.

Passo 3: Ajustar o docker-compose.yml para Hosts Linux

Em instalações Linux convencionais, atualize o docker-compose.yml na seção do serviço 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:

Passo 4: Construir e Iniciar os Serviços

Inicie a pilha de contêineres:

docker compose up -d --build

Acompanhe os logs da plataforma para certificar-se da comunicação estável com o banco MySQL:

docker compose logs -f platform

Assim que todos os contêineres estiverem em execução regular, acesse http://localhost:3000 pelo navegador.

Passo 5: Configurar e Testar o Agente na Interface Web

1. Abrir Configurações: Clique no ícone de engrenagem (Settings) na barra lateral inferior do AgentGPT.
2. Definir o Modelo: Digite a tag correspondente ao modelo carregado no seu servidor de inferência (por exemplo, qwen2.5:14b ou llama3.1:8b).
3. Parâmetros de Execução:
   • Temperature: Defina entre 0.2 e 0.4. O planejamento autônomo requer coerência estrutural e formatação JSON precisa; temperaturas altas aumentam o risco de erros de interpretação de formato.
   • Limite de Loops (Max Loops): Estabeleça um teto inicial de 5 a 10 ciclos para avaliar o tempo de resposta do hardware local.
4. Disparar um Agente:
   • Agent Name: Local-Infrastructure-Planner
   • Goal: Mapear os principais gargalos de rede na orquestração interna de agentes autônomos e listar três soluções práticas de mitigação.
   • Clique em Deploy Agent.
5. Acompanhar o Ciclo: Veja o agente criar a lista de tarefas, executar cada ação consultando o endpoint local e consolidar as conclusões em um relatório final.

Boas Práticas e Seleção de Modelos

1. Capacidade Exigida do Modelo Local

O fluxo de trabalho de agentes autônomos demanda muito mais consistência do modelo do que diálogos comuns de chat:

• Capacidade de interpretar prompts de sistema densos e produzir JSON semanticamente válido de forma contínua.
• Julgamento lógico para determinar a conclusão das tarefas sem entrar em repetições infinitas.

Modelos com menos de 7 bilhões de parâmetros (7B) ou modelos sem ajuste instrucional adequado tendem a gerar erros de sintaxe nas etapas intermediárias. Recomenda-se:

• Mínimo recomendado: Llama-3.1-8B-Instruct ou Qwen-2.5-7B-Instruct.
• Ideal para produção: Qwen-2.5-14B/32B ou Llama-3.1-70B (executado via quantização em GPUs compatíveis).

2. Gerenciamento da Janela de Contexto

Com a execução contínua de tarefas, a memória acumulada de mensagens cresce rapidamente:

• No Ollama, configure um Modelfile contendo PARAMETER num_ctx 16384 para assegurar que instruções anteriores não sejam truncadas silenciosamente.

3. Situação do Repositório Upstream

O repositório reworkd/AgentGPT no GitHub foi arquivado em janeiro de 2026 e tornou-se somente leitura. Sua arquitetura permanece totalmente válida e recomendada para implementações internas e prova de conceito; contudo, projetos que visem uso corporativo prolongado devem versionar suas próprias imagens Docker, congelar versões de bibliotecas e manter políticas internas de governança de chaves.

Referências

• 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.