Rodar agentes de IA diretamente no terminal funciona bem, mas quando voce precisa de ambientes isolados, dependencias especificas ou colaboracao em equipe, a abordagem "roda tudo no mesmo lugar" mostra suas limitacoes. E ai que o Docker Compose para ambientes multi-agente se torna uma ferramenta indispensavel.
Com Docker Compose, voce define em um arquivo YAML todo o ecossistema dos seus agentes: qual versao do Node.js cada um usa, quais variaveis de ambiente estao disponiveis, quais portas estao expostas e como eles se comunicam. Cada agente roda em seu proprio container, isolado mas conectado — exatamente como equipes de desenvolvimento trabalham com microservicos.
Neste guia, voce vai aprender a configurar Docker Desktop com WSL 2 no Windows e criar ambientes multi-agente com Docker Compose, integrados ao Orquestra.
Instalando Docker Desktop com WSL 2 no Windows
Antes de criar ambientes multi-agente, voce precisa do Docker configurado corretamente no Windows. A instalacao padrao do Docker Desktop ja inclui suporte ao WSL 2:
- Baixe o Docker Desktop:Acesse o site oficial e baixe a versao estavel para Windows. Durante a instalacao, marque a opcao "Use WSL 2 instead of Hyper-V".
- Ative a integracao WSL:Apos instalar, va em Settings > Resources > WSL Integration e ative a integracao com sua distribuicao (Ubuntu-24.04).
- Teste a instalacao: Abra o terminal WSL e execute
docker ps. Deve funcionar sem erros.
Com o Docker funcionando no WSL, voce tem o ambiente pronto para criar multiplos containers para seus agentes de IA.
Criando um docker-compose.yml para agentes de IA
O arquivo docker-compose.yml define os servicos (agentes) que vao rodar. Aqui esta um exemplo para tres agentes que compartilham a mesma rede e um volume de codigo:
Este arquivo define tres servicos que compartilham o mesmo volume de codigo (./projeto). Cada agente tem sua propria imagem base, variaveis de ambiente e ponto de entrada.
Docker Compose avancado para cenarios multi-agente
Para cenarios mais complexos, voce pode adicionar servicos de infraestrutura que os agentes utilizam:
Adicionando banco de dados e cache
Agora seus agentes tem um banco de dados PostgreSQL e um cache Redis disponiveis. Claude Code pode armazenar contexto, Codex pode buscar dados, e OpenCode pode executar testes que dependem desses servicos.
Perfis de execucao
Use perfis do Docker Compose para ativar/desativar agentes conforme necessidade:
Integrando Docker Compose com o Orquestra
O Orquestra foi projetado para gerenciar agentes em ambientes conteinerizados. A integracao funciona de duas formas:
1. Agentes dentro de containers
Configure cada terminal do Orquestra para executar comandos dentro de um container especifico. Em vez de abrir um terminal WSL comum, use:
Cada terminal no Orquestra aponta para um container diferente, e voce ve todos os agentes trabalhando em paralelo no mesmo canvas.
2. Volumes compartilhados
Como todos os containers compartilham o mesmo volume de codigo, as alteracoes feitas por um agente sao imediatamente visiveis para os outros. O Claude Code pode modificar um arquivo, e o Codex pode revisa-lo em seguida — tudo via Docker Compose.
Sugestao de imagem: Diagrama mostrando tres containers (Claude Code, Codex, OpenCode) conectados a um volume compartilhado e a servicos de banco de dados, com o Orquestra como interface central.
Boas praticas para ambientes multi-agente com Docker
- Use .dockerignore: Evite que node_modules, .git e caches sejam copiados para o contexto do build. Isso acelera a inicializacao dos containers.
- Variaveis de ambiente via .env: Nunca coloque chaves de API no docker-compose.yml. Use um arquivo .env referenciado com${VARIAVEL}.
- Limite de recursos por container: Adicione deps, memory e cpus no docker-compose.yml para evitar que um agente monopolize recursos.
- Volumes nomeados para cache: Use volumes nomeados (como claude-cache no exemplo) em vez de bind mounts para dados de cache, que sao mais rapidos e persistem entre execucoes.
- Healthcheck nos servicos: Configure healthcheck nos containers para que o Orquestra possa identificar quando um agente esta pronto ou com problemas.
Perguntas frequentes
Vale a pena usar Docker para agentes de IA em vez de rodar direto no WSL?
Para ambientes isolados, multiplas versoes de dependencias ou colaboracao em equipe, o Docker Compose e superior pela reproducibilidade. Para desenvolvimento rapido com poucos agentes, rodar direto no WSL e mais simples.
Docker Desktop e necessario para usar Docker Compose com agentes?
Sim, o Docker Desktop com backend WSL 2 e a forma mais simples. Instale, ative a integracao WSL nas configuracoes e pronto.
Como agentes de IA acessam o codigo dentro dos containers?
Via volumes montados. O codigo fica no sistema de arquivos do WSL e e montado como volume no container. O agente enxerga como se fosse local.
Docker Compose funciona com o Orquestra?
Sim. O Orquestra executa comandos Docker dentro dos terminais dos agentes, permitindo visualizar todos os containers trabalhando em paralelo no canvas.
Posso orquestrar agentes em containers diferentes?
Sim. Cada agente em seu proprio container com dependencias isoladas. Eles se comunicam via rede interna do Docker Compose.
Posts relacionados
Ambientes multi-agente com Docker
Baixe o Orquestra para Windows 11 e gerencie seus agentes de IA em containers Docker Compose. Visualize tudo em um canvas infinito. 7 dias gratis.