A maioria dos desenvolvedores que executam vários agentes de IA atinge o mesmo obstáculo por volta do quinto agente. Você tem o Claude Code em um terminal reescrevendo um serviço de backend, o Codex em outro gerando testes, o Cursor editando um componente e mais três abas que você esqueceu de verificar. Ninguém sabe o que o outro está fazendo. Os custos disparam. Dois agentes duplicam o mesmo trabalho. Um executa por seis horas e não produz nada útil porque ninguém lhe deu um objetivo claro.
O Paperclip corrige isso. É uma plataforma de orquestração de código aberto que transforma seus agentes de IA dispersos em uma empresa estruturada, completa com organogramas, funções atribuídas, gerenciamento de tarefas, limites de orçamento e logs de auditoria. Ele atingiu mais de 35.000 estrelas no GitHub em menos de três semanas, o que demonstra quantos desenvolvedores estavam enfrentando a mesma frustração.
Este artigo o guiará pela configuração, estruturação da sua primeira empresa de agentes e sua execução para que o trabalho seja realmente feito sem que você precise monitorar cada terminal.
O que é (e o que não é) o Paperclip
Antes de instalar qualquer coisa, entenda o que você está obtendo.
Paperclip é uma camada de orquestração. Ele coordena agentes, rastreia seu trabalho, controla seus orçamentos e lhes fornece contexto sobre os objetivos da empresa. Ele não cria agentes, substitui seu provedor de IA ou adiciona uma interface de chat.
O modelo mental que a equipe Paperclip usa: "Se o Claude Code é um funcionário, o Paperclip é a empresa."
Isso significa:
- Agentes têm funções, não apenas prompts
- Tarefas têm proprietários, não apenas terminais abertos
- Orçamentos têm limites rígidos, não apenas "vibes"
- Tudo é registrado em um rastro de auditoria
O Paperclip funciona com Claude Code, OpenAI Codex, Cursor, Gemini CLI e qualquer agente que possa receber um webhook ou sinal de pulso (heartbeat). Você traz os agentes. O Paperclip gerencia a empresa.
Não é explicitamente:
- Uma interface de chatbot
- Um construtor de fluxo de trabalho de arrastar e soltar como n8n ou Zapier
- Um framework para escrever agentes
- Útil para casos de uso de agente único
Se você estiver executando um agente de IA ocasionalmente, o Paperclip é um exagero. Se você estiver executando três ou mais agentes em um trabalho contínuo, ele é a peça que faltava.
Instalando o Paperclip
Você precisa do Node.js 20+, pnpm 9.15+ e só isso. O Paperclip vem com um banco de dados PostgreSQL incorporado, então você não precisa configurar armazenamento externo.
A maneira mais rápida de começar:
npx paperclipai onboard --yes
Isso baixa a CLI, executa o processo de integração com padrões sensatos e inicia o servidor na porta 3100. Abra http://127.0.0.1:3100 e você estará no dashboard.
Se você quiser contribuir ou aprofundar no código:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Se você preferir Docker:
docker compose -f docker-compose.quickstart.yml up --build
O que é criado em disco:
O Paperclip armazena tudo em ~/.paperclip/instances/default/:
~/.paperclip/instances/default/
config.json — configurações do servidor e armazenamento
db/ — arquivos de dados do PostgreSQL incorporado
secrets/master.key — chave de criptografia (gerada automaticamente)
logs/ — logs do servidor
data/storage/ — anexos de arquivo
workspaces/<agent>/ — diretórios de trabalho por agente
O modo local usa autenticação local_trusted por padrão, que ignora o login e usa um usuário sintético "Board". Você pode começar a usar o dashboard imediatamente, sem a necessidade de criar uma conta.
Uma vez dentro, execute a verificação de saúde:
paperclipai doctor
Se algo estiver mal configurado, --repair corrige a maioria dos problemas automaticamente:
paperclipai doctor --repair
Configurando sua primeira empresa
No Paperclip, uma "empresa" é o contêiner de nível superior para seus agentes, tarefas, objetivos e orçamentos. Pense nisso como um projeto, exceto que cada membro do projeto é um agente de IA com uma função e uma linha de reporte.
No dashboard, crie uma nova empresa e dê a ela uma declaração de missão. Isso não é decorativo. Cada tarefa que um agente recebe remonta à missão da empresa, para que os agentes tenham contexto sobre o porquê estão fazendo o trabalho, não apenas o que fazer. Isso é importante para a tomada de decisões em execuções agenticas mais longas.
Um exemplo simples 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 única declaração dá aos seus agentes um filtro para cada decisão que eles tomam.
Adicionando seus primeiros agentes
Cada agente no Paperclip tem um adaptador que define qual ferramenta de IA ele usa e como se comunica.
Os adaptadores suportados prontos para uso:
| 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 suas habilidades em ~/.claude/skills e gera credenciais de API. O agente agora existe no organograma da sua empresa e pode receber atribuições de tarefas.
Configurando um agente Claude (definido na UI ou na configuração por agente):
| Campo | O que ele faz |
|---|---|
model |
Qual modelo Claude usar (por exemplo, claude-sonnet-4-6) |
cwd |
Diretório de trabalho para o agente (criado automaticamente se ausente) |
promptTemplate |
Prompt do sistema com substituição de {{variável}} |
maxTurnsPerRun |
Máximo de turnos agenticos por batimento cardíaco (padrão: 300) |
timeoutSec |
Limite de execução rígido (0 = sem tempo limite) |
A alocação de modelo por função deve ser pensada antes de você começar. Executar o Opus em todos os agentes se torna caro rapidamente. Uma divisão prática:
- CEO / agentes de orquestração: Sonnet (raciocínio estratégico, vale o custo)
- Agentes gerentes: Haiku (roteamento e delegação, barato e rápido)
- ICs criativos / de codificação: Sonnet (a qualidade da saída importa aqui)
- ICs formulários: Haiku (geração de boilerplate, scaffolding de testes, migrações)
Essa alocação pode reduzir seus gastos mensais com agentes em 40-60% em comparação com a execução do Sonnet em todos os lugares, sem perda significativa de qualidade em tarefas rotineiras.
Estruturando sua organização de agentes
Aqui está uma estrutura de trabalho para um pequeno projeto de software:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── Engenheiro de Backend (Sonnet)
│ ├── Engenheiro de Frontend (Sonnet)
│ └── Engenheiro de QA (Haiku)
└── Redator Técnico (Haiku)
O agente CEO mantém a missão e a divide em objetivos. O CTO encaminha os objetivos para os agentes de engenharia. Os engenheiros fazem o trabalho. O QA valida. O redator documenta.
Cada agente tem um intervalo de pulsação (heartbeat), a frequência com que ele acorda, verifica suas tarefas atribuídas, executa o trabalho e sai. Os agentes não funcionam continuamente. Eles acordam, executam e dormem. Isso é o que impede os custos de dispararem.
Intervalos recomendados:
- Agentes de codificação: 600 segundos (10 minutos)
- Agentes sob demanda: 86.400 segundos (uma vez por dia) com ativação sob demanda habilitada
- Intervalo seguro mínimo: 30 segundos (menor que isso corre o risco de estouro de custos e spam)
Como funciona o pulso (heartbeat)
Entender o modelo de pulso é fundamental para obter um trabalho confiável de seus agentes.
Toda vez que um agente acorda, ele segue um protocolo de nove etapas:
- Confirma a identidade via
GET /api/agents/me - Lida com quaisquer retornos de chamada de aprovação pendentes
- Busca as tarefas atribuídas em
GET /api/companies/{companyId}/issues - Prioriza: tarefas em andamento primeiro, depois a fazer; ignora tarefas bloqueadas, a menos que possam ser desbloqueadas
- Retira a tarefa via
POST /api/issues/{issueId}/checkout(se outro agente já a pegou, a resposta é 409 e este agente prossegue) - Lê o contexto completo da tarefa e o tópico de comentários
- Executa o trabalho
- Atualiza a tarefa com comentários e alterações de status
- Delega subtarefas com IDs de pai e objetivo, se necessário
O mecanismo de checkout na etapa 5 é o que impede a duplicação de trabalho. Dois agentes não podem pegar a mesma tarefa. Se um estiver trabalhando nela, o outro a ignora automaticamente.
O Paperclip injeta contexto em cada execução do agente via variáveis de ambiente:
PAPERCLIP_TASK_ID # qual tarefa acionou esta execução
PAPERCLIP_WAKE_REASON # por que o agente acordou (temporizador, menção, atribuição)
PAPERCLIP_AGENT_ID # a identidade do agente
PAPERCLIP_API_URL # URL para chamar de volta para a API do Paperclip
Os agentes podem usar isso para postar atualizações, criar subtarefas, solicitar aprovações e delegar – tudo dentro de um único pulso.
Atribuindo tarefas e rastreando o trabalho
As tarefas no Paperclip funcionam como issues do GitHub cruzadas com uma ferramenta de gerenciamento de projetos. Crie uma na UI ou CLI:
paperclipai issue create \
--company-id <id> \
--title "Adicionar paginação ao endpoint de pedidos" \
--assignee-agent-id <backend-engineer-id>
As tarefas podem ter:
- Tarefas pai para dividir grandes trabalhos em subtarefas
- Links de objetivo para que os agentes saibam qual objetivo da empresa isso atende
- Comentários para contexto, solicitações de aprovação e atualizações de status
- Menções (@) para ativar um agente específico sob demanda (sem esperar pelo próximo pulso)
Você pode ver todas as tarefas abertas na CLI:
paperclipai issue list
Ou no dashboard, onde as tarefas mostram seu proprietário atual, status e qual execução de pulso as tocou pela última vez.
Controle de orçamento que realmente funciona
Este é um dos recursos mais úteis do Paperclip, e o mais negligenciado por pessoas que são novas em configurações multiagentes.
Cada agente recebe um orçamento mensal de tokens. Quando atinge 80%, o agente automaticamente muda para tarefas apenas críticas. Quando atinge 100%, ele pausa completamente.
Defina um orçamento na configuração do agente. O ponto de partida sugerido pela comunidade é de US$ 20-50/mês por nível de agente. Você pode rastrear a taxa de consumo por agente, o custo por pulso e o gasto mensal cumulativo, tudo no dashboard.
O dashboard de custos mostra quais agentes são eficientes e quais estão queimando tokens em trabalho sem foco. Se o custo por pulso de um agente estiver subindo, geralmente é um sinal de que os prompts são muito vagos ou o escopo da tarefa é muito amplo. Você corrige isso apertando a atribuição, não aumentando o orçamento.
Sem controles de orçamento, um agente mal configurado executando em um intervalo de 30 segundos com "Extended Thinking" ativado pode queimar centenas de dólares antes que você perceba. O Paperclip impede que isso aconteça automaticamente.
Habilidades em tempo de execução: ensinando novos fluxos de trabalho a agentes sem retreinamento
Uma das características mais poderosas do Paperclip é a injeção de habilidades. Quando um agente é executado, o adaptador do Paperclip cria links simbólicos para arquivos SKILL.md no diretório de configuração do agente e os passa via --add-dir. O agente lê o arquivo de habilidade como parte de seu contexto e segue o fluxo de trabalho.
Isso significa que você pode ensinar um agente um novo processo, como escrever mensagens de commit, como lidar com migrações de banco de dados ou como formatar documentação de API, escrevendo um arquivo markdown. Sem reescrever prompts. Sem reimplantação.
Você escreve a habilidade:
# 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-o no diretório de habilidades, atribua-o ao seu agente de backend, e cada pulso futuro seguirá esse processo.
Se você estiver testando APIs construídas por seus agentes
Quando seus agentes estão construindo APIs, você precisa de uma maneira de testar o que eles produzem rapidamente. O Apidog se encaixa naturalmente aqui. Ele gerencia o design de API, servidores mock e testes automatizados em um só lugar, então quando seu agente de backend entrega um endpoint, você pode validá-lo imediatamente sem alternar entre Swagger, Postman e uma ferramenta de mock separada.
Você pode gerar automaticamente suítes de teste a partir da sua especificação OpenAPI, executá-las na saída do agente e enviar os resultados de volta como um comentário de tarefa. O agente os coleta no próximo pulso e corrige as falhas. O ciclo completo, do código ao teste e à correção, funciona sem um humano no meio.
O Apidog suporta REST, GraphQL e gRPC, e é gratuito para começar.
Gerenciando múltiplas instâncias
O Paperclip suporta múltiplas instâncias isoladas em uma máquina via a variável de ambiente PAPERCLIP_INSTANCE_ID ou a flag --instance. Cada instância tem sua própria configuração, banco de dados, portas e workspaces.
Para desenvolvimento local, o comando worktree cria uma instância de desenvolvimento totalmente isolada por ramificação git:
paperclipai worktree:make feature/orders-pagination
Isso lhe dá portas, configuração e um banco de dados separados com escopo para aquela ramificação. Você pode executar uma empresa de teste contra o código da funcionalidade sem tocar em sua configuração de agente de produção. Quando terminar, desmonte-o e ele se foi.
Configurações multiagente que funcionam
Alguns padrões que funcionam bem depois de dominar o básico:
Cascata de objetivos: Escreva um objetivo de alto nível no nível da empresa, depois deixe seu agente CEO dividi-lo em objetivos de projeto, e cada agente gerente dividir esses em tarefas. Agentes fazem um trabalho melhor quando entendem a cadeia de propósito, em vez de receberem instruções isoladas.
Portões de aprovação: Para qualquer ação de agente que toque em produção, ambientes de staging ou faturamento, configure um portão de aprovação. O agente pausa, envia uma notificação e espera por um "ok" antes de continuar. Isso adiciona uma etapa manual, mas captura problemas antes que se tornem caros.
Ativações sob demanda via @-menção: Em vez de um intervalo de pulso rápido (e o custo de token que isso acarreta), defina os agentes para um intervalo lento e use @-menções nos comentários das tarefas para ativá-los imediatamente quando necessário. Você obtém tempos de resposta rápidos em trabalhos importantes sem pagar por sondagens constantes.
Espaço de trabalho separado por agente: Cada agente tem seu próprio diretório de trabalho em workspaces/<agent-id>/. Mantenha-os limpos. Agentes que compartilham um espaço de trabalho interferem no trabalho uns dos outros. O isolamento é integrado; não lute contra ele.
Começar leva cerca de 15 minutos
Pela primeira vez, a integração leva menos de 15 minutos. Um comando instala e inicia o servidor. Adicionar seu primeiro agente e criar uma tarefa leva mais cinco minutos no dashboard.
A parte mais difícil é estruturar bem sua empresa: escrever uma missão clara, escolher o modelo certo para cada função e definir limites orçamentários sensatos. Gaste 30 minutos nisso antes de começar a atribuir tarefas e seus agentes produzirão resultados muito melhores do que se você conectar tudo rapidamente e esperar pelo melhor.
Se você já estiver executando mais de dois agentes de IA em qualquer projeto contínuo, isso vale uma tarde de configuração. A diferença entre uma aba de terminal por agente e uma empresa estruturada com controles orçamentários, propriedade de tarefas e logs de auditoria é a diferença entre um projeto paralelo e algo que pode realmente funcionar sem supervisão.