Quantos agentes dá para rodar em paralelo sem estourar o limite da API?

Disparar trinta agentes de uma vez parece produtividade

na prática costuma voltar erro no lugar de resultado 😅

Quando a gente começa a brincar com agentes em paralelo, a tentação é sempre a mesma: se um agente resolve, dez resolvem dez vezes mais rápido, né? Só que existem DOIS tetos independentes ali no meio do caminho

Um é do provedor: o limite de uso da API, medido por minuto

O outro é da sua máquina e do seu contexto, que ninguém mede antes de dar o go

Ignorar qualquer um dos dois derruba a rodada inteira, e o pior é que os sintomas se parecem. Bora separar os dois e ver como raciocinar em fila em vez de tudo de uma vez?

Teto 1: o limite da API da Claude é por minuto, não por agente

O primeiro erro de raciocínio é achar que o limite conta agentes

Ele não conta

Segundo a documentação de limites da API, o uso é medido em três dimensões por classe de modelo:

• RPM: requisições por minuto
• ITPM: tokens de entrada por minuto
• OTPM: tokens de saída por minuto

Ou seja: dez agentes tagarelas podem estourar antes de trinta agentes discretos. O que pesa é o volume que eles empurram por minuto, não a quantidade de processos abertos

Os níveis de uso são três: Start, Build e Scale, cada um com limites maiores que o anterior. No Start, o teto é de 1.000 RPM, 2.000.000 ITPM e 400.000 OTPM

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Token bucket? Que negócio é esse?

É o algoritmo que controla essa conta. A ideia é que a capacidade seja reposta CONTINUAMENTE, e não que zere de minuto em minuto

Se você conhece aquele balde furado da física do ensino médio, é bem parecido: entra água o tempo todo, e você tira do balde conforme precisa

Na prática isso muda o seu jeito de disparar: não adianta segurar tudo pra mandar de uma vez achando que o balde esvazia e enche de novo em bloco, porque a reposição vai acontecendo aos poucos

O cache não conta no ITPM (e ainda sai mais barato)

Esse detalhe é ouro pra quem roda muitos agentes com o mesmo prompt base

Na maioria dos modelos Claude, só os tokens de entrada NÃO cacheados contam pro limite de ITPM. Os tokens de entrada em cache não entram nessa conta, e ainda são cobrados a 10% do preço base de entrada

Traduzindo: prompt base repetido e cacheado te dá mais espaço de paralelismo pelo mesmo teto

E o gasto do mês?

Cada nível tem um teto de gasto mensal também. Atingiu o teto, o uso da API pausa até o mês seguinte, a menos que você peça aumento

Pra conferir onde você está, o caminho é a página de limites do Console da Claude, em Settings > Limits

Tome cuidado com informação velha: em 26 de junho de 2026 a Anthropic reestruturou os limites da API. Os níveis antigos foram consolidados em Start, Build e Scale, e Claude Sonnet e Haiku passaram a ter os mesmos RPM, ITPM e OTPM do Opus em todos os níveis. Tutorial de antes disso te dá conta errada

Erro 429 e erro 529: qual é limite seu e qual é sobrecarga da API

O sintoma: você sobe a concorrência, a rodada anda um pouco e começa a devolver erro em série

Aí bate a dúvida: fui eu que passei do ponto ou a API que engasgou?

A causa está no código do erro:

• 429: você estourou um dos limites. A resposta informa QUAL limite foi excedido e vem com o cabeçalho retry-after, dizendo quantos segundos esperar
• 529 (overloaded_error): sobrecarga temporária da API, situação diferente de limite estourado

São coisas distintas, e confundir as duas leva a decisão errada: você desce a concorrência achando que é seu teto, quando na verdade era só esperar um pouco

A solução é tratar os dois como transitórios. A doc de erros lista 429, 500 (sem x-should-retry: false), 502, 503, 504 e 529 como respostas que devem ser repetidas com backoff exponencial, começando em 1 segundo e dobrando até 60 segundos

Repetir na hora, sem espera, é o clássico jeito de transformar um engasgo em uma avalanche de 429

Como prevenir antes de bater no teto

A resposta te entrega o orçamento restante em cabeçalho, se liga:

• anthropic-ratelimit-requests-remaining: quanto sobrou na janela
• anthropic-ratelimit-requests-reset: o timestamp RFC 3339 da reposição

Quem lê esses dois valores ajusta a concorrência ANTES de tomar erro, em vez de descobrir o teto na porrada

Teto 2: a sua máquina e o seu contexto

Agora a parte que quase ninguém mede

Nos workflows dinâmicos do Claude Code, o teto é de até 16 agentes simultâneos, e MENOS em máquinas de poucos núcleos de CPU. É esse teto que limita o uso de recurso local nesse mecanismo

Repara que esse 16 é do workflow dinâmico, não uma régua geral do Claude Code: cada mecanismo de paralelismo tem o seu próprio número, e a gente compara todos numa tabela mais pra frente

Ou seja: não é só sobre a API topar. É sobre a sua máquina aguentar

Se você não tem um PC da Nasa, a conta cai sozinha 😀

Contexto é gargalo antes do que você imagina

Rodar muitos subagentes que devolvem resultados detalhados consome bastante contexto. Cada retorno gordo volta pra alguém ler

Pra paralelismo sustentado, ou pra trabalho que passa da janela de contexto, os times de agentes dão a cada worker um contexto próprio e independente

Recurso experimental, e ele vem desativado por padrão. A ativação é pela variável CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS igual a 1, no ambiente do shell ou no settings.json:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

E se dois agentes editarem o mesmo arquivo?

Essa é a dor clássica de quem roda sessões paralelas no mesmo repo

As worktrees do Git dão a cada sessão um checkout separado, então sessões paralelas não editam os mesmos arquivos. Isolamento de disco resolve o que isolamento de contexto não resolve

Esse raciocínio de isolar por projeto também aparece em outras ferramentas, como quando você precisa rodar vários agentes no mesmo projeto sem que um pise no trabalho do outro

Os quatro jeitos de paralelizar no Claude Code e o teto de cada um

A doc lista quatro mecanismos diferentes de paralelizar trabalho: subagentes, agent view, times de agentes e workflows dinâmicos

Não são sinônimos, e cada um tem um teto diferente:

Repara numa sutileza do teto de subagentes: quem leva o bloqueio é só a chamada feita pela ferramenta Agent, só que outras execuções também ocupam essas mesmas vagas. A vaga só volta quando a contagem de rodando cai abaixo do limite

É exatamente isso que faz o "tenho 20, então posso 20" dar errado na prática

No caso do workflow dinâmico ainda tem um aviso antes do teto: passando de 25 agentes agendados, ou de 1,5 milhão de tokens projetados, a linha de progresso no painel de tarefas mostra Large workflow

Como raciocinar em fila com concorrência limitada

Não existe prompt mágico nem número universal aqui, sinto muito 😛

O que existe é um raciocínio de fila: você escolhe um número de vagas, e cada agente que termina libera a vaga pro próximo. Assim o pico fica controlado em vez de tudo bater na API no mesmo segundo

1. Descubra seu nível e seus limites

Abra a página de limites do Console (Settings > Limits) e anote RPM, ITPM e OTPM do seu nível

O erro comum deste passo: assumir número de tutorial antigo, sendo que os níveis foram reestruturados em 26 de junho de 2026

2. Estime tokens por agente e cheque contra ITPM e OTPM

Um agente que lê muito arquivo pesa no ITPM. Um agente que escreve relatório longo pesa no OTPM

O erro comum deste passo: olhar só RPM. Dá pra estar folgado em requisições e estourado em tokens tranquilamente

E lembra: só entrada NÃO cacheada conta no ITPM

3. Escolha um número de vagas em vez de disparar tudo

Separe o total de trabalho da quantidade que roda AO MESMO TEMPO. Cem tarefas com oito vagas é uma operação saudável, cem tarefas de uma vez é um 429 esperando pra acontecer

O erro comum deste passo: esquecer que outras execuções ocupam as mesmas vagas do teto da ferramenta Agent

4. Ajuste o teto de subagentes conscientemente

A variável aceita qualquer número inteiro positivo, então dá pra subir E pra descer:

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=8

O erro comum deste passo: mexer só pra cima. Em máquina modesta, descer o número costuma entregar mais resultado que subir

5. Trate 429 e 529 com backoff exponencial

Começa em 1 segundo e dobra até 60 segundos, em vez de reenviar na hora

O erro comum deste passo: retry imediato em loop, que empilha requisição e piora o quadro que você está tentando resolver

6. Preste atenção no aviso Large workflow

Quando um workflow agenda mais de 25 agentes, ou quando a projeção de tokens passa de 1,5 milhão, a linha de progresso no painel de tarefas mostra o aviso Large workflow

O erro comum deste passo: ignorar o aviso e só descobrir o tamanho da brincadeira quando ela já rodou

Ter um lugar pra olhar o que cada agente está fazendo muda o jogo, e vale pra qualquer stack: é a mesma lógica de acompanhar os agentes num painel em vez de ficar alternando entre janelas e se perdendo

Quando paralelizar, quando enfileirar e quando usar a API de lotes

Nem todo trabalho quer paralelismo alto, e essa é a parte que a galera pula

Cenário 1: trabalho curto e independente

Várias tarefas pequenas, que não dependem uma da outra e devolvem pouca coisa

Aqui o paralelismo alto compensa mesmo: o gargalo tende a ser o limite por minuto da API, então a régua é RPM, ITPM e OTPM

Cenário 2: trabalho longo que devolve muito resultado

Agente que varre repositório inteiro e volta com relatório completão

Nesse caso o contexto vira o gargalo ANTES do limite da API. É onde faz sentido usar time de agentes, com contexto próprio por worker, ou isolar as sessões em worktrees do Git pra ninguém editar o arquivo do outro

Cenário 3: trabalho que não precisa de resposta imediata

Aqui tem um atalho que muita gente esquece: a API de lotes (Message Batches) custa 50% do preço padrão em todo o uso, valendo pra tokens de entrada, de saída e especiais

E tem limites próprios: o uso dela não afeta os limites da Messages API

Ou seja, processamento que pode esperar não deveria estar competindo por vaga com o que é interativo

O que aprendi rodando uma empresa inteira de agentes

Eu montei uma operação inteira de agentes pra valer, e o que mais me surpreendeu não foi a parte de IA, foi a parte de infra

Primeira decisão: não instalei o orquestrador no meu computador. Subi numa VPS

O motivo é bem prático: assim os agentes seguem rodando em paralelo sem depender do PC ligado, e eu consigo monitorar à distância. Instalar na própria máquina funciona, sem drama, mas pra mim esse tipo de operação com vários agentes tem que viver num servidor dedicado

Na escolha da máquina eu separei dois perfis: quem só está testando como as coisas funcionam fica no plano de entrada, e quem já toca um negócio e quer garantir escala vai pro plano acima, porque aquela máquina vai rodar o orquestrador MAIS o que a pessoa quiser

Onde eu travei (porque travei mesmo)

O primeiro start falhou por uma proteção do banco de dados, que não libera acesso com o usuário root. Resolvi criando um usuário não root pra ferramenta

Aí bati num segundo erro no mesmo setup: o gerenciador de pacotes ficou fora do PATH do usuário novo. Corrigi exportando o caminho e reinstalando o pacote pra aquele usuário

Depois disso, o teste de ambiente do meu primeiro agente falhou porque o CLI do modelo não estava instalado no servidor. Só passou quando abri outra conexão, instalei o CLI e fiz login

E eu evitei abrir porta no servidor: acessei o painel por túnel SSH, porque não quis deixar aquilo exposto pra qualquer um no navegador

O que eu faria diferente antes de subir o número de agentes

Definir orçamento de tokens ANTES de dar o go

Na configuração da empresa, esse orçamento é o que te dá previsibilidade de custo, em vez de descobrir o gasto na fatura. E o corte automático por orçamento foi a proteção principal: quando o agente atinge o limite definido, ele para

O painel de gastos e a auditoria fecham o ciclo, porque dá pra acompanhar o que cada agente consumiu enquanto tudo roda

Sobre quando isso vale a pena: o indício mais honesto que eu tenho é o seu próprio comportamento. Se você já mantém mais de um Claude Code aberto ao mesmo tempo gerenciando projetos diferentes, alternando janela e se perdendo, orquestrar faz sentido

Sinal de necessidade: vários objetivos rodando em paralelo e a necessidade de monitorar custo

Sinal de dispensa: você trabalha com um agente por vez, faz tarefas pontuais sem continuidade e usa de forma casual e exploratória. Nesse caso, setup simples resolve e ponto

No vídeo acima eu mostro esse setup do zero, incluindo os dois erros de instalação na VPS e o momento em que o teste de ambiente do primeiro agente falha ao vivo 🙂

Conclusão: o número certo é o que a sua fila aguenta

Recapitulando o que importa aqui

Teto da ferramenta e teto da API são coisas diferentes: o Claude Code tem 20 subagentes simultâneos por sessão no padrão e até 16 agentes simultâneos nos workflows dinâmicos, enquanto a API conta RPM, ITPM e OTPM por minuto, por classe de modelo

Estourar o primeiro te dá um bloqueio de ferramenta. Estourar o segundo te dá 429 com retry-after

E 529 não é limite seu, é sobrecarga temporária da API

O número saudável de agentes em paralelo nasce de medir, não de chutar: você olha o seu nível, estima o peso de cada agente, escolhe as vagas de propósito e deixa o backoff cuidar do resto

Próximo passo bem concreto: abre a página de limites do Console da Claude, anota RPM, ITPM e OTPM do seu nível e roda a próxima tarefa com uma concorrência escolhida a dedo, com backoff exponencial de 1 segundo até 60 segundos configurado

Depois disso você para de brigar com erro e começa a brigar com o problema certo 😀

até o próximo post!