A maioria dos desenvolvedores que executam múltiplos agentes de IA enfrenta o mesmo problema depois do quinto agente: Claude Code reescrevendo um serviço de backend num terminal, Codex gerando testes em outro, Cursor editando um componente e mais três abas esquecidas. Ninguém monitora o trabalho do outro, custos aumentam, tarefas são duplicadas, e agentes ficam horas rodando sem direção clara.
O Paperclip resolve isso. É uma plataforma de orquestração open source que transforma seus agentes de IA dispersos em uma empresa estruturada, com organogramas, funções, gestão de tarefas, limites de orçamento e logs de auditoria. Com mais de 35.000 estrelas no GitHub em menos de três semanas, fica claro que muitos desenvolvedores sentiam essa dor.
Este guia mostra como configurar, estruturar sua primeira empresa de agentes e rodar tudo para o trabalho fluir sem precisar vigiar cada terminal.
O que é (e o que não é) o Paperclip
Antes de instalar, entenda o produto.
Paperclip é uma camada de orquestração: coordena agentes, rastreia trabalho, controla orçamentos e fornece contexto sobre os objetivos da empresa. Não cria agentes, não substitui seu provedor de IA e não adiciona chat UI.
- Agentes têm funções, não só prompts
- Tarefas têm proprietários, não só terminais abertos
- Orçamentos têm limites rígidos
- Tudo é registrado em logs de auditoria
Funciona com Claude Code, OpenAI Codex, Cursor, Gemini CLI e qualquer agente que aceite webhook ou heartbeat. Você traz os agentes, o Paperclip orquestra.
Não é:
- Chatbot UI
- Construtor drag-and-drop de fluxos tipo n8n ou Zapier
- Framework para programar agentes
- Indicado para uso com apenas um agente
Se só roda um agente IA ocasionalmente, Paperclip é overkill. Com três ou mais agentes, é a peça que faltava.
Instalando o Paperclip
Pré-requisitos: Node.js 20+, pnpm 9.15+. O Paperclip já vem com banco PostgreSQL embutido, sem configuração extra.
Comece rápido:
npx paperclipai onboard --yes
Baixa a CLI, integra com padrões e inicia o servidor na porta 3100. Acesse http://127.0.0.1:3100 para abrir o dashboard.
Para contribuir/desenvolver:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Usando Docker:
docker compose -f docker-compose.quickstart.yml up --build
Arquivos criados em disco:
~/.paperclip/instances/default/
config.json — configs do servidor/armazenamento
db/ — dados PostgreSQL interno
secrets/master.key — chave de criptografia (auto-gerada)
logs/ — logs do servidor
data/storage/ — anexos de arquivos
workspaces/<agent>/ — workspace por agente
No modo local, usa autenticação local_trusted (sem login, usuário "Board"). Dashboard pronto para uso, sem criar conta.
Cheque se está tudo OK:
paperclipai doctor
Se houver problemas, use:
paperclipai doctor --repair
Configurando sua primeira empresa
No Paperclip, "empresa" é o container principal de agentes, tarefas, objetivos e orçamentos. Pense como um projeto onde cada membro é um agente IA com função e reporte.
No dashboard, crie uma nova empresa e defina a missão. Isso serve de contexto para todas as tarefas dos agentes e é essencial para boas decisões em execuções longas.
Exemplo de missão:
"Construir e manter uma API REST para gerenciamento de pedidos de clientes. Priorizar a correção em detrimento da velocidade. Documentar todos os endpoints públicos."
Essa missão já orienta decisões dos agentes.
Adicionando seus primeiros agentes
Cada agente usa um adaptador que define qual IA usar e como se comunicar.
| Agente | Tipo de adaptador | Pacote |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP webhooks | Adaptador HTTP | endpoint personalizado |
Para adicionar um agente Claude Code via CLI:
paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
Isso inicializa o agente, instala habilidades em ~/.claude/skills e gera credenciais de API. O agente entra no organograma e já pode receber tarefas.
Principais opções para agente Claude:
| Campo | Função |
|---|---|
model |
Modelo Claude (ex: claude-sonnet-4-6) |
cwd |
Diretório de trabalho do agente |
promptTemplate |
Prompt de sistema com {{variáveis}}
|
maxTurnsPerRun |
Máximo de turns por pulso (padrão: 300) |
timeoutSec |
Timeout da execução (0 = sem limite) |
Alocação de modelo por função: Não rode Opus em todos os agentes. Sugestão:
- CEO / Orquestração: Sonnet
- Gerentes: Haiku
- ICs criativos/código: Sonnet
- ICs boilerplate/testes: Haiku
Isso reduz custos mensais com agentes em 40-60% sem perda real de qualidade em tarefas rotineiras.
Estruturando sua organização de agentes
Exemplo para projeto de software:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── Engenheiro de Backend (Sonnet)
│ ├── Engenheiro de Frontend (Sonnet)
│ └── Engenheiro de QA (Haiku)
└── Redator Técnico (Haiku)
CEO mantém missão e distribui objetivos. CTO encaminha para engenheiros. Engenheiros executam. QA valida. Redator documenta.
Cada agente tem um intervalo de pulso (heartbeat): frequência que acorda, verifica tarefas, executa e dorme. Isso controla custos.
Intervalos recomendados:
- Código: 600s (10 min)
- Sob demanda: 86400s (1 vez/dia) + ativação sob demanda
- Mínimo seguro: 30s
Como funciona o pulso (heartbeat)
Entenda o pulso para confiabilidade:
- Confirma identidade via
GET /api/agents/me - Processa aprovações pendentes
- Busca tarefas em
GET /api/companies/{companyId}/issues - Prioriza: em andamento > a fazer; ignora bloqueadas
- Faz
POST /api/issues/{issueId}/checkout(bloqueia para outros agentes) - Lê contexto e comentários
- Executa a tarefa
- Atualiza status e comentários
- Delega subtarefas se necessário
O checkout (passo 5) previne duplicação de trabalho. Só um agente pega cada tarefa por vez.
O Paperclip injeta contexto via variáveis de ambiente:
PAPERCLIP_TASK_ID
PAPERCLIP_WAKE_REASON
PAPERCLIP_AGENT_ID
PAPERCLIP_API_URL
Agentes usam essas variáveis para interagir com a API, criar subtarefas, pedir aprovação, etc.
Atribuindo tarefas e rastreando o trabalho
Tarefas funcionam como issues GitHub + gestão de projetos. Crie por UI ou CLI:
paperclipai issue create \
--company-id <id> \
--title "Adicionar paginação ao endpoint de pedidos" \
--assignee-agent-id <backend-engineer-id>
Tarefas incluem:
- Subtarefas (parent/child)
- Links de objetivo
- Comentários
- Menções (@) para ativação imediata
Veja tarefas abertas na CLI:
paperclipai issue list
Ou no dashboard, com proprietário, status e histórico de execução.
Controle de orçamento que realmente funciona
Cada agente recebe um orçamento mensal de tokens. Ao atingir 80%, só faz tarefas críticas. Aos 100%, pausa.
Defina o orçamento na configuração do agente. Comece com US$20-50/mês por agente. O dashboard mostra consumo por agente, custo por pulso e gasto mensal total.
Se o custo por pulso de um agente subir, ajuste prompts e escopo das tarefas antes de aumentar orçamento.
Sem controle, um agente mal configurado pode gastar centenas de dólares rapidamente. O Paperclip impede isso.
Habilidades em tempo de execução: ensinando novos fluxos de trabalho a agentes sem retreinamento
O Paperclip permite injeção de habilidades: arquivos SKILL.md adicionados ao contexto do agente via --add-dir. O agente lê o arquivo e segue o fluxo definido.
Exemplo: ensinar migrações de banco ao agente de backend:
# HABILIDADE: Migrações de banco de dados
Ao criar uma migração:
1. Nunca modifique arquivos de migração existentes
2. Use nomes descritivos: AAAAAMMDD_descricao.sql
3. Inclua SQL "up" e "down"
4. Teste localmente antes de commitar
5. Adicione um comentário explicando a razão de negócio para a mudança
Salve no diretório de habilidades do agente e ele seguirá esse processo automaticamente nos próximos pulsos.
Se você estiver testando APIs construídas por seus agentes
Se seus agentes estão criando APIs, teste rápido é essencial. Use Apidog: gerencie design, mock e testes automatizados de API em um só lugar. Quando o agente entrega um endpoint, valide imediatamente sem alternar entre Swagger, Postman, etc.
Gere suites de teste da OpenAPI, execute na saída do agente e envie resultados de volta como comentário de tarefa. O agente coleta no próximo pulso e corrige falhas sozinho.
O Apidog suporta REST, GraphQL, gRPC e é grátis para começar.
Gerenciando múltiplas instâncias
Paperclip suporta múltiplas instâncias isoladas usando a env PAPERCLIP_INSTANCE_ID ou flag --instance. Cada uma tem configs, banco, portas e workspaces próprios.
Para dev local, use worktree para criar instância isolada por branch git:
paperclipai worktree:make feature/orders-pagination
Você ganha ambiente separado para a branch. Ao terminar, exclua e tudo é limpo.
Configurações multiagente que funcionam
Padrões recomendados:
- Cascata de objetivos: Escreva um objetivo top-down, CEO divide para projetos, gerentes dividem em tarefas. Agentes entendem o propósito em cadeia.
- Portões de aprovação: Para ações críticas (produção, billing), configure gates. O agente pausa e espera aprovação manual.
- Ativação sob demanda via @-menção: Intervalo de pulso lento + @-menção ativa agente imediatamente quando necessário.
- Workspace isolado por agente: Cada agente tem seu diretório. Não compartilhe, evite interferência.
Começar leva cerca de 15 minutos
Primeira integração: menos de 15 minutos. Instale, rode, adicione agente e crie tarefa em minutos no dashboard.
O essencial é estruturar bem sua empresa: missão clara, modelos certos por função, limites de orçamento. Invista 30 minutos nisso antes de distribuir tarefas—o resultado dos agentes será muito melhor do que se só conectar tudo às pressas.
Se já executa mais de dois agentes IA em um projeto contínuo, vale reservar uma tarde para configurar. A diferença entre cada agente em um terminal e uma empresa estruturada, com orçamentos e logs, é o que separa um projeto paralelo de algo que funciona sem vigilância manual.
Top comments (0)