Administradores de sistemas e desenvolvedores podem hospedar o AgentGPT em infraestrutura própria em poucos minutos utilizando Docker e Docker Compose. Ao executar a aplicação localmente ou em uma nuvem privada virtual (VPC), as organizações mantêm controle absoluto sobre a definição de metas, rastros intermediários de raciocínio, histórico de prompts e registros de banco de dados, eliminando o risco de exposição de contextos corporativos confidenciais a plataformas SaaS públicas multi-inquilino.
Este guia detalha a arquitetura do sistema, os pré-requisitos essenciais, os procedimentos de implantação automatizada e manual em contêineres, práticas recomendadas de endurecimento de segurança e considerações sobre o ciclo de vida da solução.
Visão Geral da Arquitetura
O AgentGPT orquestra o ciclo de vida de agentes autônomos recursivos por meio de uma pilha multicontêiner modular:
- Frontend (
frontend): Uma aplicação web desenvolvida em Next.js 13, TypeScript, Tailwind CSS e HeadlessUI. Opera na porta3000, permitindo aos usuários configurar identidades de agentes, estabelecer metas principais, acompanhar em tempo real a criação e resolução de subtarefas e exportar os artefatos finais. - Motor Backend (
platform): Um serviço em Python FastAPI na porta8000. Coordena cadeias de ferramentas de modelos de linguagem via LangChain, gerenciando decomposição de tarefas, filas de prioridade, iterações de reflexão e acionamento de ferramentas externas. - Camada de Dados: Gerenciada pelo Prisma ORM na camada web e SQLModel no backend, persistindo configurações, sessões de usuários e logs operacionais em MySQL.
- Integrações com APIs Externas: Enquanto o estado do sistema e os registros operacionais permanecem no host privado, a inferência é realizada por chamadas HTTPS externas para a API da OpenAI, com suporte opcional à API Serper (pesquisa na web) e Replicate (geração de imagens).
Pré-requisitos do Sistema
Antes de iniciar a instalação, certifique-se de que o host atende aos seguintes requisitos:
- Docker e Docker Compose: Docker Engine 20.10+ ou Docker Desktop em execução, com suporte ao comando Compose v2.
- Git: Necessário para clonar o repositório oficial do projeto.
- Node.js 18+: Exigido caso utilize o script interativo de configuração automática via CLI.
- Credenciais de API:
- Chave de API da OpenAI ativa e com limites adequados de tokens (modelos GPT-4 ou GPT-3.5-turbo).
- (Opcional) Chave de API Serper para permitir que o agente realize pesquisas na web.
- (Opcional) Token da API Replicate para geração automatizada de imagens.
Método 1: Implantação Rápida via Script de Configuração
O repositório do AgentGPT inclui um assistente interativo em linha de comando que automatiza a geração do arquivo de variáveis de ambiente, a instalação de dependências e a compilação dos contêineres.
1. Clonar o Repositório
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
2. Executar o Script de Inicialização
Execute o inicializador correspondente ao seu sistema operacional:
- Linux / macOS:
./setup.sh - Windows (PowerShell ou Prompt de Comando):
setup.bat
3. Responder às Etapas Interativas
O assistente solicitará:
- Sua chave da API da OpenAI.
- Chaves opcionais da Serper e da Replicate.
- Configurações de portas e preferências de execução.
Ao término da compilação e inicialização dos contêineres, acesse http://localhost:3000 no navegador para verificar a interface.
Método 2: Implantação Manual com Docker Compose
Para servidores de produção, pipelines de integração contínua (CI/CD) ou ambientes sem suporte a scripts interativos, o uso direto do Docker Compose é a abordagem mais robusta e previsível.
1. Clonar o Repositório e Inspecionar Arquivos
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
O arquivo docker-compose.yml define os serviços principais: frontend (apontando para ./next/Dockerfile) e platform (apontando para ./platform no estágio prod).
2. Configurar as Variáveis de Ambiente
Copie o modelo de variáveis de ambiente para a raiz de execução do Next.js:
cp .env.example ./next/.env
Abra o arquivo ./next/.env em um editor e ajuste as configurações essenciais:
# Limite máximo de loops para evitar consumo desenfreado de tokens
NEXT_PUBLIC_MAX_LOOPS="50"
REWORKD_PLATFORM_MAX_LOOPS="50"
# Endpoints de rede interna
NODE_ENV="production"
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000"
# Segurança de sessões e autenticação
NEXTAUTH_SECRET="defina-aqui-uma-chave-secreta-aleatoria-de-32-caracteres"
NEXTAUTH_URL="http://localhost:3000"
# Credenciais de modelos e ferramentas
OPENAI_API_KEY="sk-sua-chave-openai"
SERPER_API_KEY="sua-chave-opcional-serper"
3. Compilar e Iniciar os Contêineres em Segundo Plano
Compile as imagens e suba a infraestrutura em modo desacoplado:
docker compose up --build -d
4. Validar o Status dos Contêineres e Logs
Confira se os contêineres estão ativos:
docker compose ps
Acompanhe os logs em tempo real para verificar a integridade da inicialização:
docker compose logs -f
Acesse http://localhost:3000 para iniciar seus primeiros fluxos de trabalho autônomos.
Práticas de Segurança para Ambientes Corporativos Privados
A configuração padrão do Docker Compose é voltada ao desenvolvimento local. Em ambientes de rede interna ou servidores compartilhados, aplique as seguintes medidas de segurança:
1. Restringir a Vinculação de Portas no Host
Por padrão, as portas 3000 e 8000 são vinculadas a todas as interfaces de rede (0.0.0.0), o que pode permitir acesso não autorizado de outros nós da rede. Altere o docker-compose.yml para vincular exclusivamente ao localhost (127.0.0.1):
services:
frontend:
ports:
- "127.0.0.1:3000:3000"
platform:
ports:
- "127.0.0.1:8000:8000"
2. Implementar Proxy Reverso com Terminação TLS
Adicione um proxy reverso (Nginx, Traefik ou Caddy) à frente dos serviços para fornecer criptografia HTTPS e autenticação unificada (SSO/OAuth). Exemplo de configuração no 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. Impor Limites Rígidos de Ciclos de Execução (Loops)
Agentes autônomos podem entrar em loops repetitivos de planejamento ao lidar com metas ambíguas. Mantenha os parâmetros NEXT_PUBLIC_MAX_LOOPS e REWORKD_PLATFORM_MAX_LOOPS restritos (valores entre 20 e 50 são recomendados) para proteger o orçamento financeiro de consumo da API.
4. Definir Limites de Privacidade de Dados
A implantação autônoma garante que o código, o banco de dados, os artefatos e o histórico do fluxo residam na sua infraestrutura. Entretanto, o conteúdo dos prompts e do raciocínio ainda é enviado pela internet para os servidores da OpenAI. Para casos de alta confidencialidade, avalie rotear chamadas através de instâncias empresariais do Azure OpenAI ou proxies de filtragem contra vazamento de dados (DLP).
Ciclo de Vida do Projeto e Recomendações de Manutenção
Antes de adotar o AgentGPT para operações críticas contínuas, é importante atentar para o estado atual do projeto:
- Status de Arquivamento: O repositório
reworkd/AgentGPTno GitHub foi formalmente arquivado em modo somente leitura no início de 2026. A base de código permanece funcional e prática para prototipagem e validações internas, mas não receberá mais atualizações de segurança ou correções de falhas pelo mantenedor original. - Fixação de Versões de Dependências: Ao compilar imagens a partir do código-fonte, fixe as versões das imagens base e pacotes npm/Python para evitar quebras de build futuras causadas por bibliotecas externas desatualizadas.
- Evolução de Arquitetura: Para fluxos corporativos complexos que demandem pipelines multiagente, integração contínua de ferramentas customizadas ou fluxos com aprovação humana obrigatória (Human-in-the-loop), recomenda-se avaliar frameworks ativamente mantidos como CrewAI, AutoGen ou LangGraph.