TheBotCompany para começar: uma nova forma de desenvolver times de IA com zero intervenção manual

Início em 30 minutos｜Colaboração autônoma com 3 papéis｜Fallback com múltiplos Providers｜Automatização ponta a ponta do requisito até o PR

---

Visão geral do projeto

TheBotCompany é uma plataforma de equipe para desenvolvimento de IA que faz você “realmente largar o volante”. A ideia central é bem direta: em vez de você sozinho conversar com a IA e escrever código, você monta uma equipe composta por múltiplos AI Agents — alguém planeja, alguém escreve código, alguém verifica. Eles próprios discutem, próprios atribuem tarefas e próprios gerenciam o progresso. Tudo o que você precisa fazer é intervir quando eles se depararem com situações que realmente exigem julgamento humano.

A equipe tem três papéis de gestão fixos: Athena faz o planejamento estratégico, definindo marcos e orçamento de ciclos; Ares lidera a execução, quebrando os marcos em tarefas específicas para os agents trabalhadores; Apollo cuida da aceitação, avaliando com um padrão alto a entrega do Ares — se não estiver aprovado, retorna. Esse ciclo não exige que você fique acompanhando: o Dashboard mostra em tempo real o que cada agent está fazendo, quanto está custando e quais problemas surgiram.

---

Para quem este artigo é

Este artigo é para desenvolvedores que:

• Têm alguma experiência de desenvolvimento e querem delegar tarefas repetitivas de codificação a uma equipe de AI Agents, ficando focados em decisões e arquitetura
• Se interessam pelos conceitos de colaboração Multi-Agent e times autogeridos, e querem exemplos práticos
• Já usam um single Agent para ajudar no desenvolvimento, mas querem evoluir para múltiplos agents em paralelo tratando direções diferentes

Se o que você quer é uma ferramenta de “instale e relaxe completamente”, ajuste a expectativa primeiro: o TheBotCompany reduz bastante a intervenção manual, mas não elimina totalmente a sua necessidade.

---

Dependências principais e ambiente

---

Estrutura completa em árvore do projeto

Após instalar e iniciar, a estrutura será gerada em ~/.thebotcompany/:

~/.thebotcompany/
├── keys.json              # API Keys armazenadas com criptografia
├── db.sqlite              # Banco de dados do Issue tracker
├── config.yaml            # Configuração global
└── logs/                  # Logs de execução

Seu diretório de projeto/
├── workers/               # Definições de habilidades dos agents trabalhadores
│   ├── leo.md             # Frontmatter: reports_to, role, model
│   └── maya.md
├── workspace/             # Espaços de trabalho de cada agent
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # Configuração no nível do projeto (gerada ao criar o projeto)

---

Passo a passo da instalação

Passo 1: instalar TheBotCompany

npm install -g thebotcompany

Verificação da instalação:

tbc --version

Passo 2: iniciar o serviço

tbc start

Na primeira execução, você será solicitado a configurar, em sequência:

1. Senha de acesso ao Dashboard — para proteger operações de escrita (pausar, retomar, modificar configuração)
2. Porta — padrão 3100; basta pressionar Enter para aceitar o padrão

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

Depois de iniciado com sucesso, o Dashboard fica acessível em http://localhost:3100. Por padrão, é somente leitura; para operar, é necessário fazer login.

Passo 3: configurar a API Key

Abra o Dashboard (http://localhost:3100), clique em Settings no canto superior direito e adicione sua API Key no painel de Keys. Também é possível detectar automaticamente na primeira execução via variáveis de ambiente:

# Adicione no .bashrc ou .zshrc:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Passo 4: criar um projeto via Dashboard

1. Abra http://localhost:3100
2. Clique em New Project e preencha:
   • Repository URL — o endereço do seu GitHub Repo (requer que o gh tenha permissão)
   • Provider — selecione qual LLM Provider usar
   • Model Tier — modelos usados em cada nível (high/mid/low)
3. Clique Create e entregue o controle à Athena para iniciar o trabalho

---

Arquitetura detalhada de colaboração com 3 papéis

Esta é a concepção mais central do TheBotCompany. Entendendo os três papéis, você entende como todo o sistema funciona.

Três papéis fixos de gestão

O ciclo completo (Cycle loop)

Fase PLANNING (Athena)
  → Athena + seus agents trabalhadores rodam
  → pesquisa, avaliação e brainstorming
  → define marcos → entra em IMPLEMENTATION

Fase IMPLEMENTATION (Ares)
  → Ares + seus agents trabalhadores rodam (até N ciclos)
  → Ares anuncia concluído → entra em VERIFICATION
  → excedeu o orçamento do ciclo → retorna para PLANNING para reavaliar

Fase VERIFICATION (Apollo)
  → Apollo + seus agents trabalhadores rodam
  → Apollo aceita → entra no próximo PLANNING
  → Apollo retorna → volta para IMPLEMENTATION para corrigir

Como os agents trabalhadores funcionam

Os Managers (Ares / Athena / Apollo) “contratam” agents trabalhadores criando arquivos .md dentro do diretório {project_dir}/workers/. Cada arquivo tem um YAML frontmatter fixo:

---
reports_to: ares          # Para quem reporta
role: Frontend Engineer   # Descrição de responsabilidades
model: mid                # Qual modelo usar
---

# Frontend Engineer

Você é um engenheiro de frontend. Sua responsabilidade é implementar componentes de UI e a lógica de interação.

Quando o Manager atribui tarefas aos trabalhadores, ele atribui uma tarefa por ciclo — não é permitido empilhar cinco tarefas de uma vez. Após a conclusão, o Manager lê o note.md no espaço de trabalho para entender o contexto e então decide o próximo passo.

Como ocorre a comunicação entre agents

Os agents não conversam diretamente; eles coordenam via o Issue Tracker embutido:

• Ares precisa da opinião da Athena → cria uma Issue no Issue Tracker, atribuindo à Athena
• O Worker encontra um problema → cria uma Issue, e o Manager fica sabendo e trata
• Necessita intervenção humana → cria uma GitHub Issue com título começando com HUMAN:; você faz login no GitHub para responder

---

Demonstração completa do fluxo de desenvolvimento

Step 1：Criar o projeto via Dashboard

Abra o Dashboard e clique em New Project:

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

Depois de criado o projeto, aparecerá um cartão correspondente no Dashboard, com status PLANNING, e a Athena começará a trabalhar.

Step 2：Observar o processo de planejamento da Athena

No painel Agent Reports do Dashboard, você consegue ver a saída da Athena. Ela está fazendo coisas como:

• Ler o README do projeto e o código existente para entender a situação atual
• Buscar soluções técnicas relacionadas e boas práticas
• Avaliar a viabilidade dos requisitos
• Definir o primeiro marco e o respectivo orçamento (quantos Cycle)

Quando a definição dos marcos é concluída, o sistema muda automaticamente para a fase IMPLEMENTATION, e o Ares entra em ação.

Step 3：Ares executa a implementação

O status do Dashboard muda para IMPLEMENTATION e o Ares começa:

1. Contratar trabalhadores — Ares cria arquivos como workers/leo.md e workers/maya.md
2. Atribuir tarefas — em cada Cycle, atribui apenas um trabalhador para executar uma tarefa específica
3. Revisar PR — após os workers enviarem PR, o Ares faz Code Review
4. Controle do Cycle — se não terminar dentro do ciclo, devolve para tentar novamente no próximo Cycle

Você pode enviar mensagens para o Ares diretamente no painel Chat do Dashboard para ajustar a direção ou adicionar contexto.

Step 4：Apollo valida

Quando o Ares anuncia que o marco foi concluído, o sistema troca para VERIFICATION e o Apollo entra:

→ Apollo lê as mudanças no código
→ Executa testes de validação (via GitHub Actions)
→ Verifica se atende aos requisitos do marco
→ Aprovado → entra no próximo PLANNING
→ Reprovado → volta para IMPLEMENTATION, explicando o que está errado

O padrão do Apollo é uma etapa acima do do Ares, então é comum acontecer “Ares acha que está pronto, mas Apollo retorna”. Isso é parte do design, não é bug.

Step 5：Intervenção humana (se necessário)

Quando um agent se depara com algo que realmente exige julgamento humano, ele cria uma GitHub Issue começando com HUMAN::

HUMAN: Para a página de login, usamos OAuth ou nome de usuário/senha?
Responda esta Issue no GitHub para que o Agent continue com base na sua resposta.

Depois que você responde, o Ares continua a execução. Se você achar que não precisa intervir, pode pausar o projeto diretamente no Dashboard.

---

Detalhes das funções do Dashboard

O Dashboard do TheBotCompany é o centro de controle de todo o sistema; você vê todos os estados de uma vez.

Visão geral dos projetos

A página inicial do Dashboard exibe todos os cards de projetos. Cada card mostra:

• A fase atual (PLANNING / IMPLEMENTATION / VERIFICATION)
• Contagem atual de Cycle / Epoch
• Barra de progresso do marco
• Resumo do último Agent Report

Agent Reports

O histórico das saídas de cada projeto. Suporta renderização em Markdown e resumo automático. Se a saída de algum Cycle for especialmente longa, o Dashboard comprime automaticamente e mostra apenas as conclusões-chave.

Issue Tracker

A coordenação entre agents acontece aqui:

• Filtrar por projeto
• Filtrar por status (Open / In Progress / Resolved)
• Filtrar por agent
• Painel dedicado Human Issues, listando todas as solicitações de escalonamento que exigem sua ação

Chat

Dentro do Dashboard há uma entrada de conversa direta: você pode escolher qualquer projeto, enviar mensagem para o Manager correspondente e adicionar contexto ou ajustar a direção. Suporta respostas em streaming e envio de imagens.

Rastreamento de custos (Cost Tracking)

Detalhamento do custo de cada projeto e de cada agent:

• Custo do Last Cycle
• Custo médio nas últimas 24 horas
• Custo total acumulado

Com Budget Controls, você pode configurar um limite de orçamento em rolagem de 24 horas; se exceder, os agents entram automaticamente em modo de descanso (sleep).

Controls

Botões de controle rápido no Dashboard:

• Pause / Resume — pausar e retomar o projeto (requer login)
• Skip Sleep — pular o intervalo de descanso pré-configurado e iniciar imediatamente o próximo Cycle
• Kill Run / Cycle / Epoch — forçar a interrupção da execução atual
• Bootstrap — reiniciar a partir do marco especificado

---

Gestão de múltiplos Providers e Key Pool

Lista de Providers suportados

O TheBotCompany já vem com suporte a 15+ tipos de LLM Provider:

Como funciona o Key Pool

No painel de Keys em Settings, você pode adicionar várias chaves para o mesmo Provider e definir uma ordem de prioridade. Durante a execução:

1. O sistema usa primeiro a Key com maior prioridade
2. Se essa Key atingir rate limit (429) ou faltar quota → alterna automaticamente para a próxima Key
3. Quando o tempo de resfriamento (cooldown) terminar, a Key volta a ficar disponível e entra novamente na rotação

Isso é especialmente útil para projetos que rodam por muito tempo, já que você não precisa se preocupar com a exaustão de uma única Key derrubar todo o time de agents.

Configuração de Model Tier

Cada projeto pode customizar quais modelos são usados em cada nível:

# config.yaml no nível do projeto .tbc/config.yaml
model_tiers:
  high: claude-opus-4       # Arquiteturas complexas, raciocínio profundo
  mid: claude-sonnet-4      # Padrão, equilíbrio entre capacidade e custo
  low: claude-haiku-3       # Tarefas simples e repetitivas, formatação

Também é possível alterar diretamente pela UI no painel Model Tier Overrides em Settings, sem precisar mexer no arquivo de configuração.

---

Solução de problemas (FAQ)

Q1：Depois de executar tbc start, o Dashboard não abre e aparece Connection Refused

Causa：a porta está ocupada, ou o serviço não iniciou corretamente.

Passos de verificação：

# 1. Verifique se o tbc está rodando
tbc status

# 2. Se não estiver rodando, inicie manualmente e observe a saída de erro
tbc dev

# 3. Se a porta estiver ocupada, use outra porta
TBC_PORT=3200 tbc start

---

Q2：O time de Agents fica preso no PLANNING e não entra em IMPLEMENTATION

Causa：Athena está fazendo pesquisa aprofundada ou aguardando o resultado dos agents trabalhadores, e ainda não definiu marcos.

Como resolver：

Abra o Dashboard → Agent Reports e veja a saída mais recente da Athena. Se ela estiver aguardando o resultado de algum worker, você pode usar /tbc logs para checar os logs do servidor e confirmar se está travada. Se realmente estiver travada, envie uma mensagem para a Athena no painel Chat do Dashboard: “Defina o primeiro marco com base nas informações existentes; não precisa esperar mais pesquisas.”

---

Q3：O PR do GitHub não é criado automaticamente e o Agent reporta erro de permissão no Issue Tracker

Causa：o CLI gh não está autenticado corretamente, ou o token não tem permissões suficientes.

Passos de verificação：

# 1. Verifique o status de login do gh
gh auth status

# 2. Se não estiver logado, autentique novamente (requer permissões do repo)
gh auth login --scopes repo

# 3. Confirme se a URL remote no diretório do projeto está correta
cd /path/to/your-project
git remote -v

---

Q4：Apollo retorna sempre a implementação do Ares, causando loop infinito de Cycle

Causa：a direção que o Ares corrige em cada tentativa não é consistente com o que o Apollo espera, ou a definição dos marcos não está clara o suficiente.

Como resolver：

No painel Chat do Dashboard, envie para o Ares: “Os motivos do retorno do Apollo são [cole as opiniões específicas do Apollo Report]. Antes de corrigir, confirme que entendeu os critérios do Apollo e confirme com o Apollo a direção da correção.”

Se os critérios do Apollo forem excessivamente rígidos, você pode pedir que a Athena ajuste as condições de aceitação do marco na fase PLANNING.

---

Q5：O custo ficou muito acima do esperado e você quer pausar todos os Agents imediatamente

Como resolver：

# Método 1：Ações no Dashboard
# Faça login no Dashboard → em cada card de projeto → Controls → Pause

# Método 2：Pausar via CLI
tbc stop

# Método 3：Definir limite de orçamento (vale na próxima inicialização)
# No Dashboard Settings → Budget Controls, configure limite de orçamento para 24h

---

Q6：Adicionou várias API Keys, mas o Agent continua usando a mesma Key e estoura o limite

Causa：a ordem de prioridade do Key Pool pode estar incorreta, ou o cooldown (resfriamento) das limitações de taxa ainda não terminou.

Como resolver：

No Dashboard Settings → painel de Keys, verifique o estado de cada Key:

• Active — em uso normal
• Cooldown — ativou rate-limit, em período de resfriamento
• Exhausted — cota esgotada

Se uma Key ficar em Cooldown por muito tempo, mova manualmente essa Key para o final da lista de Keys para que o sistema alterne para a próxima.

---

Leitura complementar e caminhos avançados

1. Customizar as habilidades dos agents trabalhadores

Crie novos arquivos .md dentro de workers/ para expandir as capacidades do time:

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

Você é um engenheiro DevOps, especialista em pipelines de CI/CD, containerização e infraestrutura como código.

O Manager detecta automaticamente os novos agents trabalhadores adicionados. Assim, no início do próximo Cycle, você já consegue escaloná-los.

2. Integrar um Provider customizado

Se você precisa integrar serviços internos de LLM da empresa (formato compatível com OpenAI ou Anthropic), em Settings → Keys → Add Custom Provider:

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. Integração profunda com GitHub Actions

A arquitetura de agents do TheBotCompany incentiva rodar testes e builds demorados dentro do GitHub Actions. Na habilidade dos agents trabalhadores, defina:

Nunca execute testes que durem mais de 5 minutos diretamente no terminal. Todos os suites de testes devem ser acionados pelo GitHub Actions.

Dessa forma, quando o agent é morto por timeout do Cycle, o código já enviado e os resultados do CI não se perdem.

4. Gerenciamento de múltiplos projetos e visão geral

Se você estiver rodando vários projetos ao mesmo tempo (manutenção open source, Side Project, projeto comercial), o Dashboard unificado do TheBotCompany permite ver em uma única página o status, os custos e a distribuição de problemas de todos os projetos. Use os Project Filters no topo para alternar rapidamente e o painel Human Issues para tratar todas as solicitações de escalonamento centralizadamente, sem deixar passar nenhum ponto que exija sua decisão.

5. Controle refinado de orçamento e custos

O limite padrão de orçamento em rolagem de 24 horas vale globalmente. Se você quiser configurar orçamentos diferentes para projetos diferentes, pode rodar múltiplas instâncias do TheBotCompany (com diretórios TBC_HOME diferentes). Cada instância gerencia independentemente seu conjunto de projetos e orçamento, sem interferir nas demais.