Um trecho de configuração está circulando esta semana: defina agents.max_concurrent_threads_per_session = 64 no seu config.toml do Codex e veja uma única sessão se ramificar em dezenas de subagentes. O post que deu início a isso afirma que o padrão é 3 e que a OpenAI testou 64. A configuração é real. Os dois números não estão na documentação, e a parte interessante não é o limite em si. É o que acontece com o trabalho quando você o aumenta.
Este post aborda o que a configuração realmente faz, segundo a referência do Codex, e as três coisas que falham em sequência quando uma única sessão passa a rodar mais agentes do que uma pessoa consegue ler.
TL;DR
agents.max_concurrent_threads_per_session limita quantas threads de agentes gerados o Codex mantém abertas ao mesmo tempo, sem contar a thread principal. A referência não publica um valor padrão; ela diz que o Codex escolhe um quando a chave não está definida. Os subagentes devolvem resumos para a thread principal, que espera por todos eles e responde uma única vez, e a documentação os recomenda para trabalho com muita leitura, ao mesmo tempo que alerta que fluxos de trabalho paralelos com muita escrita criam conflitos e sobrecarga de coordenação. Aumentar o limite para 64 estressa exatamente esses dois pontos: arquivos compartilhados e uma única resposta consolidada que ninguém consegue auditar. A Sharkly executa o Codex como um Runtime e eleva o paralelismo um nível acima, onde cada execução é uma Task com seu próprio worktree, seu próprio log e seu próprio revisor.
O que a configuração faz
Três chaves na seção [agents] do config.toml importam aqui. O texto abaixo vem da referência de configuração.
| Chave | O que a referência diz |
|---|---|
agents.max_concurrent_threads_per_session |
"Número máximo de threads de agentes gerados que podem ficar abertas simultaneamente, excluindo a thread principal. Quando não definido, o Codex escolhe o padrão." |
agents.max_threads |
"Alias legado de agents.max_concurrent_threads_per_session." |
agents.enabled |
"Ativa ou desativa as ferramentas multiagente (padrão: true)." |
Duas chaves relacionadas, agents.default_subagent_model e agents.default_subagent_reasoning_effort, definem em que os agentes gerados rodam, a menos que uma chamada de geração diga o contrário.
Portanto, o trecho funciona como está escrito:
[agents]
max_concurrent_threads_per_session = 64
O que a referência não diz é qual é o padrão, nem que algum valor foi testado. Trate "padrão 3" e "a OpenAI testou 64" como afirmações de um post, não do fornecedor, até que a documentação diga o contrário.
O guia de subagentes acrescenta as duas frases que decidem se aumentar o limite é uma boa ideia. Sobre os resultados: "Quando muitos agentes estão rodando, o Codex espera até que todos os resultados solicitados estejam disponíveis e, em seguida, retorna uma resposta consolidada." Sobre a adequação: os subagentes são indicados para "tarefas com muita leitura, como exploração, testes, triagem e sumarização", e o guia recomenda cautela com "fluxos de trabalho paralelos com muita escrita, porque agentes editando código ao mesmo tempo podem criar conflitos e aumentar a sobrecarga de coordenação".
Leia as duas juntas e a ordem das falhas se escreve sozinha.
O que quebra primeiro: o checkout compartilhado
Os subagentes em uma sessão compartilham o diretório de trabalho da sessão, a menos que você organize de outra forma. Isso não é problema para sessenta e quatro agentes lendo. É um problema de merge para quatro agentes escrevendo.
A falha não é dramática. Dois subagentes editam o mesmo arquivo, a segunda gravação prevalece, e o resumo consolidado informa que ambas as tarefas foram concluídas. Você descobre na revisão, se houver revisão, ou em produção se não houver. O alerta da documentação sobre conflitos e sobrecarga de coordenação está descrevendo exatamente isso.
A solução é a mesma para a qual toda configuração de agentes paralelos converge: uma cópia de trabalho por unidade de trabalho. Na Sharkly, cada execução de Task recebe um diretório isolado, e o trabalho respaldado por repositório usa um git worktree separado por execução, que é o mecanismo abordado em agentes paralelos em worktrees isolados. Dez Tasks contra um repositório, zero estado compartilhado. O Runtime que faz a edição ainda pode ser o Codex; o isolamento é fornecido ao redor dele.
O que quebra em segundo lugar: a resposta consolidada
O Codex espera por todos os subagentes e retorna uma única resposta. Com quatro subagentes, isso é uma conveniência. Com sessenta e quatro, é uma única mensagem resumindo sessenta e quatro unidades de trabalho, escrita pelo agente que as despachou, com a saída intermediária dobrada e escondida.
Esse é o formato errado para revisão. Um revisor precisa saber o que cada unidade de trabalho tocou, o que executou e onde parou, e precisa poder aceitar ou rejeitar cada uma individualmente. Um resumo de resumos não pode ser aceito parcialmente.
A Sharkly armazena a resposta final do Agent na Task e mantém um log de execução por execução, com o gatilho, início e fim, chamadas de ferramentas, eventos do Runtime e detalhes de falhas. As execuções ficam em sua própria aba, separadas da linha do tempo de comentários. Sessenta e quatro unidades de trabalho são sessenta e quatro Tasks com sessenta e quatro logs, cada uma revisável, cada uma devolvendo seu resultado ao lugar onde uma pessoa vai olhar.
O que quebra em terceiro lugar: o humano no circuito
O limite não diz nada sobre o que acontece quando um subagente precisa de uma pessoa. Dentro de uma sessão, um subagente bloqueado é uma thread que ficou em silêncio numa espera consolidada. A thread principal não pode responder por você, e você não consegue ver qual das sessenta e quatro threads é a que parou.
A Sharkly mantém o status da Task e o estado de trabalho do Agent separados: uma Task iniciada pode mostrar Working, Waiting for human reply, Waiting for human review ou Error. Os sinais de espera e de falha chegam à seção Primary do Inbox para a pessoa responsável, e uma resposta na Task inicia a execução de acompanhamento com a thread como contexto. A que travou avisa você, em vez de ficar pendurada numa espera que você não consegue inspecionar.
Subagentes ou Tasks? Um par de decisão
Use subagentes do Codex dentro de uma única sessão quando o trabalho envolve muita leitura e converge para uma única resposta: explorar uma base de código, fazer a triagem de um lote de falhas, resumir um conjunto de documentos, rodar uma suíte de testes. É para isso que o guia os recomenda, e um limite mais alto é barato quando nada está escrevendo.
Use Tasks separadas, cada uma atribuída a um Agent em um Computer, quando as unidades de trabalho escrevem código, quando pessoas diferentes vão revisar partes diferentes, ou quando uma pessoa pode precisar responder no meio da execução. A Sharkly não substitui o Codex; o Codex é o Runtime que executa cada Task. A diferença está em onde o paralelismo mora: dentro da espera consolidada de uma única sessão, ou ao longo de um quadro onde contexto, progresso, bloqueios, resultados e revisão humana permanecem visíveis da solicitação até a entrega.
Aumentar o limite com segurança
Se você for aumentar max_concurrent_threads_per_session, faça como a própria documentação de concorrência da Sharkly descreve para os Computers: aumente só depois que a configuração atual lidar com a carga de trabalho existente de forma confiável, porque mais concorrência consome mais CPU, memória, disco, capacidade do provedor e largura de banda do repositório. Um Computer na Sharkly tem seu próprio limite de concorrência de tarefas, e os Agents que usam diretórios temporários têm metade disso por padrão. A capacidade é limitada pelo Computer, pela concorrência do Agent e pela disponibilidade de diretórios, e um Agent online ainda pode ter trabalho enfileirado quando essa capacidade está cheia.
A capacidade do provedor é a que as pessoas esquecem. Sessenta e quatro threads contra uma única chave de API são sessenta e quatro maneiras de atingir um rate limit ao mesmo tempo, e um 429 que significa "cota esgotada" não se resolve tentando de novo. O log de execuções com falha da Sharkly mantém a resposta original do provedor ao lado de um título simples, para que a diferença fique visível antes de alguém tentar novamente.
Perguntas frequentes
Qual é o valor padrão de agents.max_concurrent_threads_per_session? A referência de configuração não informa nenhum. Ela diz que o Codex escolhe o padrão quando a chave não está definida. Os números que circulam nas redes sociais não vêm da referência.
Aumentar o limite deixa o Codex mais rápido? Para ramificações com muita leitura, mais threads terminam mais cedo. Para trabalho com muita escrita, a documentação alerta que edições simultâneas criam conflitos e sobrecarga de coordenação, o que custa mais tempo do que o paralelismo economiza.
Os subagentes do Codex rodam em git worktrees separados? O guia de subagentes não diz que sim. Planeje como se eles compartilhassem o diretório de trabalho, a menos que você mesmo tenha configurado o isolamento.
Como a Sharkly usa o Codex? Como um Runtime. Um Computer rodando o Codex o reporta como disponível, e as Tasks atribuídas a um Agent naquele Computer são executadas por meio dele, cada execução em seu próprio diretório ou worktree isolado.
Ainda posso usar subagentes dentro de uma Task da Sharkly? Sim. Tudo o que o Runtime consegue fazer sozinho continua funcionando dentro da execução. A Sharkly acrescenta a Task, o isolamento, o log e a revisão ao redor disso.
A versão curta
A configuração é real e o trecho funciona. O que ela não faz é tornar seguras sessenta e quatro edições simultâneas, tornar revisável uma única resposta consolidada, ou dizer qual thread está esperando por você. Essas são as três coisas que quebram, nessa ordem. Mantenha os subagentes para ramificações com muita leitura e coloque o trabalho paralelo com muita escrita em um quadro onde cada execução tenha seu próprio worktree e seu próprio revisor. Conecte um Computer com o Codex nele, crie um Agent e atribua a ele algo entediante. A documentação cobre cada conceito com mais profundidade: docs.sharkly.ai.
