Subagentes no Claude Code — quem chamou quem, recados e rodadas (parte 3 de 3)
Como o painel CSR Lens mostra os subagentes de uma sessão do Claude Code: a origem, o grafo de quem chamou quem, os recados, as rodadas, o custo repartido e o parar.
TL;DR · o artigo em 5 pontos
- Um subagente é um ajudante que o Claude Code cria para uma parte da tarefa, com contexto próprio. Ele vem de um de quatro lugares: global (
~/.claude/agents), do projeto (.claude/agents), de um plugin ou embutido (Explore, Plan, general-purpose). - O grafo quem chamou quem do CSR Lens desenha a conversa principal como um cérebro e cada agente como um robô: os fios dizem quem criou quem, e as curvas tracejadas, os recados (
SendMessage) trocados entre eles. - Um recado pode acordar um agente que já terminou: cada vez que ele trabalha é uma rodada, com os próprios números. É diferente de chamar o mesmo agente instalado duas vezes, que são duas execuções separadas.
- O custo por agente e por rodada é uma repartição feita pelo Lens, não um número oficial: o Claude Code informa só o custo da sessão. Parar agente pede para o agente parar e nega as ferramentas dele; a API não o encerra à força.
- Um mod se testa em três camadas:
claude plugin validate,claude plugin test(o Lens tem 99 testes) e uma sessão de verdade com--plugin-dir. O painel e a instalação estão na parte 2.
Neste artigo
Uma sessão do Claude Code pode ter vários subagentes trabalhando ao mesmo tempo: ajudantes que o Claude Code cria para uma parte da tarefa, cada um com o próprio contexto e o próprio gasto. A conversa principal mostra só o resumo que volta de cada um. Quem chamou quem, o que eles conversaram entre si, quantas vezes cada um rodou e quanto cada um custou ficam fora da tela, e é isso que falta para entender uma sessão com agentes.
Este post mostra como o CSR Lens, um mod do Claude Code com um painel ao lado da conversa, desenha essa parte da sessão: de onde vêm os agentes, o grafo de quem chamou quem, a linha do tempo, o detalhe de um agente, as rodadas, o caminho que recorta o que se vê, o custo repartido, o botão Parar agente e os agentes de um workflow. No fim, como se testa um mod e os limites da API de mods. É para quem já usa agentes ou quer começar; as telas são as do README do CSR Lens, que o próprio mod desenha a partir de uma sessão encenada no claude-code-kit (4 turnos, 10 agentes, números de exemplo), e a clara ou a escura acompanha o tema deste site.
Subagentes e de onde eles vêm
Um subagente roda numa janela de contexto só dele, com instruções, ferramentas e permissões próprias, faz a tarefa e devolve um resumo à conversa que o criou. A documentação o chama de agente, e o Lens também. Quem o cria é a conversa principal (ou outro agente), pela ferramenta Agent, e cada chamada dessa ferramenta é uma execução nova, com um cartão próprio no painel.
A definição de um agente (o papel, o modelo, as ferramentas) é um arquivo Markdown, e ele pode morar em quatro lugares, que a documentação ordena por prioridade quando dois têm o mesmo nome:
| Origem | Onde fica | Vale em | No Lens |
|---|---|---|---|
| Global | ~/. | todos os seus projetos | roxo |
| Do projeto | . | o repositório, para quem o clona | laranja |
| De plugin | a pasta agents/ do plugin | onde o plugin está habilitado | azul |
| Embutido | dentro do Claude Code (Explore, Plan, general-purpose) | sempre | cinza |
A origem é a cor da borda do robô e do tipo em todo o painel. Na Visão geral e no fim da aba Agentes ficam os agentes disponíveis: um cartão por agente instalado, global, do projeto ou de plugin, desde o começo da sessão, mesmo os que ninguém chamou. O que ninguém chamou fica apagado, de borda tracejada; o chamado acende, com quantas vezes e há quanto tempo, e o clique abre a execução mais recente. É o jeito de ver, numa olhada, que agentes você tem e quais o Claude usou de fato (na Visão geral da parte 2, o code-reviewer global está apagado, e o conferente-de-readme do projeto e o revisor de plugin, acesos; a origem, em detalhe no README).
Quem chamou quem: o grafo
A aba Agentes abre com as contagens (quantos rodam, quantos terminaram, quantos falharam) e o grafo Quem chamou quem. A conversa principal é um cérebro; cada agente, um robô, com a tarefa e, menor embaixo, o tipo. O grafo tem duas formas e escolhe sozinho: radial, com poucos agentes todos criados pela conversa principal (o cérebro no centro e os robôs em volta), e árvore, quando há agentes criando agentes ou muitos agentes, com um nível por coluna.
Na tela, a aba inteira na sessão de exemplo: 1 agente rodando e 9 concluídos, o grafo em árvore (três agentes criados por Coordenar a leitura), a linha do tempo, com uma linha por rodada, e os cartões (em detalhe no README):
No grafo, três coisas se leem de uma vez:
- O estado é a cor do robô: azul enquanto roda (ele balança, digita e pisca a antena), verde e sorrindo quando termina, vermelho e caído de olhos em X quando falha. Enquanto a conversa principal trabalha, o cérebro solta ondas e mostra “pensando…”.
- A origem é a borda, nas cores da tabela acima.
- Os fios e os recados. O fio cinza vai de quem criou a quem foi criado, com um selo no meio:
↓ …a tarefa foi e ele trabalha,↓ ✓o resultado voltou,↓ ✕falhou. Os recados são as mensagens que a conversa principal e os agentes trocam pela ferramentaSendMessage: curvas roxas tracejadas com quantos foram (na tela,✉ 2entre a conversa principal eRevisar o formato.); ida e volta entre os mesmos dois viram uma curva só, com seta nas duas pontas. Um recado que não chegou a ninguém aparece em vermelho (nota: recado perdido), comts ✕1no agente que mandou. Passando o mouse numa linha, aparece o que passou por ela.
Os controles ajudam numa sessão cheia: Ampliar transforma a aba numa vista só do grafo, com até 40 agentes; Zoom aumenta o desenho inteiro; Mostrar Todos, Rodando ou Com falha apaga os outros agentes para destacar os que importam agora. Clicar num agente abre o detalhe dele.
A linha do tempo com a conversa principal
Abaixo do grafo, a linha do tempo põe os agentes mais recentes na mesma régua, uma barra do começo ao fim de cada um, e no alto a linha da conversa principal, com um trecho para cada vez que ela pensou e o total. O título diz quando a sessão começou. É onde se vê quem rodou em paralelo, quem demorou e quanto tempo a conversa principal passou pensando entre um agente e outro. Com o mouse no nome, o agente acende no grafo; o clique abre o agente.
Um agente que rodou mais de uma vez tem uma linha por rodada, cada uma no horário dela (na tela acima, Revisar o formato. e Coordenar a leitura têm duas). As rodadas têm uma seção própria mais abaixo.
O detalhe de um agente
Clicar num robô, num nome da linha do tempo ou em Ver detalhes num cartão abre o detalhe do agente. No alto, o Voltar e o caminho por onde você chegou; embaixo, Reler mensagens, porque o que o agente escreveu vem da transcrição dele, lida ao abrir o detalhe e de novo no botão, não ao vivo. Enquanto ele roda, ao lado fica o Parar agente. Na tela, Ler os testes, um Explore criado por Coordenar a leitura na rodada 1 dele, como diz o caminho: 6,7 segundos, US$ 0,08 e duas chamadas (em detalhe no README):
Depois vêm o cabeçalho (o nome, o estado, o tipo, quem o criou, o horário de começo e fim e os quadrinhos com o modelo, a duração, o custo, o contexto, as chamadas e os tokens de entrada, do cache e de saída), as ferramentas que ele chamou em barras, o pedido que recebeu, inteiro, as últimas chamadas, todas em ordem (clicar numa abre a entrada e a saída dela), e a resposta, formatada. Quando ele criou agentes ou trocou recados, entra também o grafo Agentes que ele criou e com quem conversou, com ele num anel: ficam acesos ele, quem o criou, os que ele criou e os que trocaram recado com ele; os outros nós, que só ligam a árvore até a conversa principal, ficam fracos. Embaixo vêm os cartões desses agentes, a lista dos recados que ele mandou e recebeu e, num agente instalado chamado mais de uma vez, Outras execuções do mesmo agente.
As rodadas: o mesmo agente acordado por um recado
Até aqui, cada agente rodou uma vez. Mas um agente que terminou pode voltar a trabalhar: a documentação explica que, quando o Claude manda um recado a um subagente concluído pela SendMessage, ele retoma em segundo plano, sem uma nova chamada da ferramenta Agent, com o contexto de antes. Cada vez que ele trabalha é uma rodada. É diferente de chamar o mesmo agente instalado duas vezes: aí são duas execuções separadas, cada uma com o seu cartão (e as duas se apontam em Outras execuções). A figura segue um agente que roda duas vezes; em Passo a passo, ela se monta um passo por vez:
- A conversa principal cria o agente pela ferramenta Agent: começa a rodada 1.
- Ele trabalha (3 chamadas, 31 s), entrega o relatório e termina: US$ 0,19.
- Um recado (SendMessage) da conversa principal o acorda: começa a rodada 2, com o contexto de antes.
- Na rodada 2, ele cria um Explore, que conta os SVGs e volta.
- Ele manda um recado ao revisor e recebe a resposta.
- A rodada 2 termina (16 s, US$ 0,08). O agente inteiro soma 2 rodadas: 47 s, US$ 0,27.
Cada tela do Lens mostra as rodadas de um jeito, e a regra é não misturar o que é de uma com o que é de outra:
- O agente inteiro (o cartão na aba Agentes e o detalhe aberto de lá) mostra os totais de todas as rodadas (duração, custo, chamadas, tokens) e a lista de rodadas: número, horário, duração, custo, estado, quem a acordou e o começo da resposta. Nada do pedido ou da resposta de uma rodada se mistura com outra.
- Cada rodada abre a sua tela, igual ao detalhe de um agente de uma rodada só, com os números dela; o pedido (na primeira) ou o recado que a acordou, inteiro; o grafo dos agentes que ela criou e os recados que trocou; as ferramentas e as chamadas dela; e a resposta. Os botões
‹ Rodada 1,Rodada 3 ›e Agente inteiro andam entre elas. - Onde ele aparece, aparecem só as rodadas daquele lugar. No cartão de um turno, no detalhe de um turno e no último turno da Visão geral, cada rodada que aconteceu naquele turno é um item próprio (
Revisar o formato.), que abre direto a tela dela. Dentro de outro agente, só as rodadas que esse agente criou ou acordou. A contagem diz quantos agentes e quantas rodadas (ts · rodada 2 de 2 Agentes · 2 · 4 rodadas). - Na linha do tempo, uma barra por rodada, no horário dela.
- Uma rodada é do turno em que a conversa principal (ou um agente daquele mesmo turno) a acordou (nota: quem acorda define o turno). Dois agentes antigos trocando recados enquanto você faz outro pedido não entram nesse pedido: aparecem dentro do agente que acordou o outro.
Nas telas, o agente da figura, Coordenar a leitura, aberto pela aba Agentes: o agente inteiro soma as duas rodadas (47 segundos, US$ 0,27) e lista cada uma, com o botão Ver rodada (em detalhe no README):
E a rodada 2 aberta: só os números dela (16 segundos, US$ 0,08), o recado que a acordou, o grafo com o agente num anel e o Explore que ela criou, os três recados trocados e a resposta; ‹ Rodada 1 e Agente inteiro andam entre as telas:
Dois limites vêm da API: o que o agente escreveu na transcrição só aparece na rodada mais recente, porque a transcrição não separa as rodadas; e os agentes de um workflow não ganham rodadas.
O caminho e o Voltar
O mesmo agente aberto por caminhos diferentes mostra coisas diferentes, e é o caminho, na linha logo abaixo das abas, que diz de onde você veio: por exemplo, Visão geral › Turno 2 › Coordenar a leitura ou Agentes › Coordenar a leitura. Cada parte é um botão que leva àquele nível; a última, na cor da aba, é onde você está. O caminho recorta o detalhe: entrando no agente por um turno, ele lista só as rodadas daquele turno; por outro agente, só as dele; pela aba Agentes, a Visão geral, o grafo ou a linha do tempo, todas. Uma linha diz o recorte (Rodadas deste turno: 1 de 2 · ver todas as rodadas) e oferece o resto.
É o que se vê entre a tela do agente inteiro, acima, com as duas rodadas, e o detalhe do turno 2, abaixo: dois dos três agentes dele são a rodada 2 de agentes que já tinham rodado no turno 1, e cada cartão traz só o recado e a resposta daquela rodada, com o botão Ver rodada (em detalhe no README):
O Voltar (ou a tecla v) sobe um nível: do detalhe para onde ele foi aberto. O painel rola inteiro, com as abas e o caminho junto, porque a API de mods não tem como fixar um cabeçalho fora da rolagem.
O custo por agente e por rodada
O Claude Code informa o custo da sessão inteira, calculado a preço de tabela a partir dos tokens, e o /usage mostra, nos planos pagos, que fatia do uso foi para subagentes, em percentual. Quanto custou cada agente, ou cada rodada, ele não diz. O Lens reparte esse custo: ao fim de cada resposta do modelo, o que o custo da sessão subiu vai para quem fez a resposta, um agente ou a conversa principal. O custo de uma rodada é o que o agente gastou entre o começo e o fim dela (em detalhe no README, O custo de cada agente):
O custo por agente não é um número oficial. Cada aumento do custo da sessão vai para um dono só, então nada é contado duas vezes, e a soma dos agentes nunca passa do total; mas, se duas respostas terminam no mesmo instante, uma fração pode cair no agente vizinho. O valor em dólar não é cobrança para quem paga assinatura: serve para comparar um agente com outro.
Na aba Contexto da parte 2, a sessão de exemplo mostra o resultado: US$ 1,12 da conversa e US$ 1,62 dos dez agentes, de US$ 2,74. O contexto de um agente, nos quadrinhos, é o tamanho do contexto dele na última resposta: ele tem uma janela própria, que não ocupa a da conversa principal.
Parar agente
No detalhe de um agente que está rodando, Parar agente pede para ele parar. A API de mods não tem como encerrar um agente à força, então o Lens faz duas coisas, e a figura mostra a ordem:
- No detalhe do agente, você clica em Parar agente; o botão vira Parando…
- O Lens manda um recado ao agente: pare agora e entregue o relatório.
- Cada ferramenta que o agente tenta depois é negada, com o pedido como motivo.
- Só a SubagentHandback passa: ele entrega o relatório e termina.
- O cartão passa a dizer parado antes de terminar. A API não encerra um agente à força.
O recado pede para o agente parar já e entregar o relatório; cada ferramenta que ele tentar depois é negada, com o mesmo pedido como motivo. A única que passa é a de entregar o relatório (SubagentHandback), para ele conseguir dizer o que fez e terminar. O cabeçalho mostra parando…, com o tempo, o custo e as chamadas até ali, e o cartão dele passa a dizer parado antes de terminar. O limite: se ele estiver no meio de uma resposta longa do modelo, só para quando ela acabar. É a única vez em que um hook do Lens responde a um evento no lugar do Claude Code; fora isso, ele só observa.
Na tela, um Explore logo depois do clique: o botão virou Parando…, o aviso diz o que acontece agora e o cabeçalho mostra parando…, com 41 segundos, US$ 0,30 e 7 chamadas até ali (em detalhe no README):
Os agentes de um workflow
Um workflow é um script que o Claude escreve para orquestrar muitos subagentes de uma vez, em fases, enquanto a sessão fica livre. Esses agentes não passam pela ferramenta Agent, e o Claude Code não entrega ao mod o nome nem o pedido deles. O Lens lê isso dos arquivos da execução, que ficam na pasta da sessão, em ~/., e os mostra como o painel de tarefas do próprio Claude Code: no grafo, cada fase é um nó, desenhado como uma pilha de cartões, entre a conversa principal e os agentes dela, com quantos terminaram; embaixo, o cartão do workflow (o nome, quantos agentes, quantos rodam, os tokens e o tempo) e as fases, cada uma com uma linha por agente, com o nome, o modelo, os tokens, o custo e o tempo. O nome abre o detalhe.
Na tela, o workflow pesquisa-de-plugins rodando: as fases Pesquisa (1 de 2) e Crítica (0 de 1) como nós do grafo e, embaixo, o cartão do workflow (3 agentes, 2 rodando, 76,4k tokens) com uma linha por agente (em detalhe no README):
Como se testa um mod
Um mod se testa em três camadas, da mais barata para a mais cara.
claude plugin validate. Num mod, além de conferir o manifesto, ele lista os eventos que o mod escuta e as chamadas que ele faz à API dos mods, sem executar nada. Serve também para auditar o mod de outra pessoa antes de instalar. No Lens, a lista não tem chamada de rede; os processos são só os comandos de leitura do git, e as gravações, só os dois arquivos de registro.
claude plugin test. Roda os testes do mod contra um Claude Code de mentira, sem sessão, sem login e sem rede: o teste dispara os eventos, monta o painel, aperta os botões e confere o que foi desenhado. O Lens tem 99 testes: eles rodam cada aba e cada detalhe no terminal e no aplicativo de desktop, a linha de resumo, as rodadas de um agente, o botão de parar, os agentes de workflow, os arquivos que o Bash lê e escreve, uma sessão longa e bagunçada e o tempo de desenho de cada aba.
Carimbo: rodado em 06/10/2026: 99 de 99
Uma sessão de verdade. O Claude Code aberto num projeto de exemplo, com o mod carregado por claude --plugin-dir ./plugins/csr-lens. Carregada assim, a pasta fica vigiada: o Claude Code recarrega o mod a cada arquivo salvo. É a única das três camadas que mostra o painel desenhado na tela, e a única em que os robôs do grafo balançam e as pílulas pulsam.
Os limites da API
Os limites desta parte vêm quase todos do que a API de mods entrega, ou não entrega, ao mod. Na versão 1.0.0 do Lens, em 06/10/2026 (a lista completa está no README, em Limites conhecidos):
conferido em out/2026
- Custo por agente, por rodada e por turno. É uma repartição do custo da sessão, não um valor informado pelo Claude Code.
- Parar um agente não é um encerramento à força: ele termina na resposta seguinte.
- Rodadas. O que o agente escreveu não se separa por rodada; rodadas gravadas por versões antigas do Lens não têm os tokens, o custo e a hora das chamadas.
- O raciocínio interno de um agente não aparece. O Claude Code não o expõe; o detalhe mostra só o texto que o agente escreveu, e ele é relido ao abrir o detalhe e no botão, não ao vivo.
- Cliques nos gráficos do aplicativo de desktop. Os nós do grafo, os indicadores e as pílulas são clicáveis por botões invisíveis postos em cima deles; a posição é calculada, e pode sair um pouco deslocada (nota: a posição é calculada) num tamanho de fonte diferente.
- Tamanho. 100 agentes, 200 recados e 10 rodadas por agente, além dos limites da parte 2.
- A API de mods ainda pode mudar de uma versão para outra do Claude Code; o
READMEdo plugin diz com qual versão ele foi testado.
Fontes
- Claude Code — Create custom subagents (o que é um subagente, o contexto próprio, de onde vêm as definições e a prioridade, a
SendMessageque retoma um subagente concluído e o que acontece com um agente parado) - Claude Code — Orchestrate subagents at scale with dynamic workflows (o que é um workflow, as fases e onde ficam os arquivos da execução)
- Claude Code — Manage costs effectively (o custo da sessão a preço de tabela e a fatia dos subagentes no
/usage) - Claude Code — Mods overview (o que um mod alcança), Create a mod (o
--plugin-dir, a recarga e a API em evolução) e Test a mod - Cesar Schutz — claude-code-kit e o README do CSR Lens (as telas deste post, numeradas e comentadas item a item): a aba Agentes, o detalhe de um agente, as rodadas de um agente, parar um agente, os agentes de um workflow e o custo de cada agente
tagclaudecode tagplugins