Agent Zero com Ollama: instalação Docker e limites

#O que é o Agent Zero

Agent Zero (repositório agent0ai/agent-zero) se apresenta como um framework que dá ao agente um computador Linux completo: desktop XFCE em um contêiner Docker, navegador com anotação do DOM, trabalho colaborativo em tempo real em arquivos Markdown, planilhas e apresentações, e um hub com mais de 100 plugins comunitários. O projeto contava com mais de 19.000 estrelas no GitHub em 28 de setembro de 2026, com a versão mais recente identificada pela tag v2.13 publicada em 23 de setembro de 2026.

Não se trata de um agente especializado em programação como OpenCode ou Cline: o Agent Zero se destina a tarefas transversais (pesquisa, controle de aplicativos de desktop, revisão de interfaces web, análise), ao custo de uma infraestrutura mais pesada do que um simples binário no terminal.

O projeto também destaca “perfis de agente” (especialistas criados na hora, por exemplo para uma análise financeira prudente com entregas em planilhas), uma gestão de projetos que isola arquivos, segredos, memórias e repositórios por contexto, e uma cooperação entre múltiplos agentes em que um agente principal delega pesquisa, código, análise ou revisão a subagentes dedicados. Cada uma dessas funcionalidades consome contexto e capacidade de seguir instruções, o que pesa diretamente na escolha do modelo quando se vai além de uma simples conversa.

#Instalar o contêiner Docker

Com Docker já instalado, a via mais direta é um único comando que monta os dados da instância em um volume persistente. O projeto também oferece um instalador em script (A0 Install) para servidores e modo headless, além de um launcher gráfico (A0 Launcher) que gerencia Docker, instâncias e portas no lugar do usuário.

docker run -p 80:80 -v a0_usr:/a0/usr agent0ai/agent-zero

Após o contêiner ser iniciado, a interface web abre na porta escolhida (80 por padrão, ou a passada como parâmetro) para configurar o fornecedor do modelo antes da primeira tarefa. Em um servidor sem interface gráfica, o instalador em script aceita um modo silencioso que cria uma instância e uma porta especificadas sem abrir um menu, útil para uma implantação automatizada ou uma máquina remota acessível apenas via SSH.

#Conectar uma instância local do Ollama

A documentação oficial de instalação detalha os passos a seguir: nos ajustes do modelo de conversa, do modelo utilitário ou do modelo de embedding, escolha Ollama como fornecedor, escreva o nome do modelo esperado por Ollama (por exemplo, llama3.2 ou qwen2.5:7b), depois preencha a URL da API, se ela for diferente do valor padrão.

Se o contêiner não conseguir acessar o Ollama, a documentação lembra que a porta 11434 deve estar acessível a partir do contêiner; o arquivo Docker Compose fornecido associa host.docker.internal ao gateway do host no Docker sob Linux e, se os dois serviços compartilharem a mesma rede Docker, o endereço também pode ser http://(nom du conteneur):11434.

#Qual modelo escolher e para qual papel?

O Agent Zero distingue três campos de modelo: chat (conversa principal), utilitário (organização da memória, resumo) e embedding (busca na memória). O formato do nome do modelo depende do provedor: com o Ollama, é apenas o nome do modelo (gpt-oss:20b), sem prefixo do provedor, ao contrário do OpenRouter.

O ponto mais frequentemente negligenciado: um modelo de conversa razoável pode falhar na função utilitária se for muito pequeno, o que degrada silenciosamente a qualidade da memória sem que o usuário entenda por que o agente “esquece” ou confunde fatos de uma sessão para outra.

#Chamada de ferramentas com um pequeno modelo local

O próprio Agent Zero documenta um problema comum nos modelos locais leves: o modelo explica o comando em vez de chamar a ferramenta que o executaria. O projeto propõe uma correção apenas por meio do prompt, sem alterar o código: o perfil "Tiny Local", que mantém o formato padrão de chamada de ferramenta, mas remove os campos de raciocínio visíveis do prompt de comunicação, para solicitar apenas um objeto JSON executável com tool_name e tool_args.

Uma alternativa sem precisar mudar o perfil consiste em adicionar um arquivo de prompt dedicado (extensão .promptinclude.md) que repete a disciplina esperada: uma resposta visível que é exatamente um objeto JSON com exatamente os campos tool_name e tool_args, sem marcação markdown nem texto antes ou depois. A documentação é clara sobre a limitação desse ajuste: trata-se de uma modificação de prompt e de perfil, não de alteração no código de execução — se um modelo específico continuar falhando apesar dessa disciplina, a próxima etapa é mudar de modelo, não complicar ainda mais o prompt.

#O que a área de trabalho Linux realmente muda

O diferencial do Agent Zero em relação aos agentes que funcionam exclusivamente no terminal é esse ambiente de desktop XFCE completo dentro do contêiner: o agente pode abrir um programa com interface gráfica de verdade (Blender para modelar um objeto, um gerenciador de arquivos, um terminal visível), e o usuário acompanha cada ação compartilhando o mesmo mouse e o mesmo teclado virtuais, com a possibilidade de intervir a qualquer momento.

O navegador integrado vai além de um simples controle de página: o modo Annotate transforma qualquer página web em uma superfície de instruções clicáveis — alterar um elemento, inspecioná-lo, reutilizá-lo para outro projeto ou deixar um comentário específico que o agente então trata como uma tarefa.

#Conectar servidores MCP

Além das ferramentas integradas (navegador, terminal, arquivos), o Agent Zero pode se conectar a servidores MCP externos para acessar outros serviços: a documentação oficial descreve cada conexão MCP como uma ponte — uma pode conectar o Gmail, outra um banco de dados e outra ainda uma ferramenta de automação. Um servidor MCP é configurado como um comando executado localmente ou como uma URL remota, o que muda a questão da rede: um comando executado dentro do contêiner está sujeito às mesmas restrições que o acesso ao Ollama (host.docker.internal, rede Docker compartilhada), enquanto uma URL remota segue as regras normais de rede do contêiner.

A documentação recomenda limitar cada conexão ao estritamente necessário, em vez de adicionar mais conexões por precaução: cada servidor MCP conectado amplia a superfície que o modelo pode alcançar, inclusive com um modelo local cujo comportamento ao chamar ferramentas é menos previsível que o de um modelo de ponta na nuvem.

#Checklist de segurança antes de conectar modelo e ferramentas

Três pontos merecem uma verificação explícita antes de deixar o Agent Zero operar sem supervisão constante: o isolamento do contêiner, os segredos e as chaves de API e os servidores MCP conectados.

#Em comparação com outros agentes locais

• OpenCode com Ollama no terminal

#Limitações que você deve conhecer antes de começar

Volume de pesquisa enganoso

« Agent Zero » também abrange conteúdos de entretenimento nos mecanismos de busca; a demanda real pelo framework de desenvolvimento é mais restrita do que o volume bruto da palavra-chave sugere.

Uso de disco e RAM

O contêiner inclui um ambiente de desktop completo além do runtime do agente: prever mais recursos do que para um agente CLI mínimo, mesmo que a inferência em si rode em outro lugar via Ollama.

Modelo utilitário subdimensionado

Um modelo utilitário pequeno demais prejudica a memória sem uma mensagem de erro explícita; é a primeira coisa a verificar se o agente parece « perder o fio » entre uma sessão e outra.

Rede interna ao contêiner

host.docker.internal funciona com o Docker Desktop e a configuração Linux fornecida, mas uma implantação personalizada (rede Docker personalizada, hospedagem remota) exige que você insira novamente a URL da API manualmente.

• Implantar um LLM em produção com Docker Compose
• Instalar Ollama com Docker
• Agente de IA: definições e limites gerais
• Fonte: repositório oficial do Agent Zero no GitHub
• Fonte: guia oficial de instalação
• Fonte: guia oficial sobre chamadas de ferramentas em execução local