Entregue uma subtarefa a um filho, e devolva uma parada

Cerca de 26 minutos min de leitura, com 4 exemplos em 7 seções.

Edição 2026.11.2 Exemplos aprovados em 20 de nov de 2026 64 de 64 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.2. Leia o original

Ao final deste capítulo, você será capaz de entregar uma subtarefa a um loop filho, com um orçamento de passos próprio, e receber de volta um resumo e um motivo de parada, no lugar de toda a transcrição do filho. Você também fará com que uma parada chegue a uma pessoa: uma execução que as regras de parada encerram como travada vai para um pai, que faz a pergunta da parada ao mantenedor que abriu a issue.

Considere a tarefa T-02 do caso: em unitcraft, uma pequena biblioteca de unidades, uma quantia negativa perde seu separador de milhares, e o agente de manutenção precisa corrigir isso. A execução lê unitcraft/format.py e faz duas edições nele. Ambas falham, porque o texto antigo que elas indicam não está no arquivo como escrito, e por isso o resultado do teste permanece como estava. O Capítulo 2 encerra uma execução assim quando as regras percebem que não há progresso. O harness v1 executou a T-02 até o limite de passos, na gravação task-set. Reproduzidas com as duas regras de parada do Capítulo 2, as mesmas respostas encerram esta execução como no_progress at step 5 of 16. A parada cumpre sua função, mas deixa ao mantenedor um registro e nenhuma explicação do que o agente estava tentando. Alguém precisa ler o registro para descobrir.

O tamanho é o segundo problema. Descobrir onde está uma regra de arredondamento exige ler vários arquivos, e cada arquivo lido permanece no contexto que o próximo passo carrega. Uma tarefa lateral desse tipo é mais bem feita em um contexto próprio, que devolve apenas o que o pai precisa. A documentação de subagentes da Anthropic descreve essa divisão para o produto dela: o subagente faz o trabalho no próprio contexto e devolve apenas o resumo.

Este capítulo constrói o filho para esse caso. Um filho é o mesmo loop, com um orçamento próprio. Neste livro, um handoff é o fim de uma execução com uma pergunta devolvida a uma pessoa, em vez de uma conclusão: seja a chamada ask_user do próprio modelo, seja o handoff estruturado do harness após uma parada, que carrega o motivo da parada, o que a execução tentou e uma pergunta. Um filho devolve seu handoff ao pai: como terminou, o que tentou, quais arquivos leu e alterou, e então ou seu resumo ou a pergunta em que parou. Ele nunca devolve sua transcrição. Uma parada que encerra um filho chega ao mantenedor como uma pergunta.

Um filho é um loop com orçamento próprio

Uma tarefa paralela no caso, como descobrir onde fica uma regra de arredondamento, pode dar passos que o orçamento do pai não deveria pagar. Um filho é o loop do capítulo 1, iniciado por um pai no meio da própria execução. Ele tem as mesmas ferramentas e as mesmas regras de parada, e mantém uma transcrição própria. O que muda é a contagem. O orçamento do filho conta as chamadas de modelo do próprio filho, desde a primeira chamada, de modo que os passos do pai não pagam pelo trabalho do filho, e um filho que entra em loop esgota o próprio orçamento. Essa é a contagem que o capítulo 5 prometeu a um filho: os passos dele, não os do pai. O run_tests de um filho passa pelo mesmo executor de testes em sandbox que a do pai, com os limites, o ambiente limpo e a ausência de arquivos conftest que o capítulo 7 descreve, porque o filho recebe o mesmo conjunto de ferramentas. O caminho é run_tests em lib/tools.py, depois run_pytest e run_command ali, e então run_sandboxed em lib/sandbox.py. Nenhum exemplo executa o comando de um filho de outra maneira.

Dê ao filho 4 passos e execute-o no T-01. Os primeiros passos gravados da execução de task-set, a partir do modelo do capítulo 1, são reproduzidos para ele, de modo que o filho faça no início o que a execução gravada fez.

child-with-budget.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A child loop on T-01 with a budget of 4 steps. The budget counts the child's own model calls, and it ends the childas step_cap with no finish. The child's requests match the recording's first four steps, so they replay."""from lib.case import load_tasksfrom lib.models import ReplayModelfrom lib.subagents import run_childfrom lib.tools import V1from lib.trace import IdCounterBUDGET = 4task = load_tasks(only=["T-01"])[0]child = run_child(ReplayModel("task-set", "T-01"), task, V1, budget=BUDGET, ids=IdCounter())print("child budget, steps:", BUDGET)print("child steps:", child.handoff.steps)print("child result:", child.handoff.ended)print("child tools:", ", ".join(child.tool_names))print("child steps, in order:", *child.trace, sep="\n  ")child.run.close()assert child.handoff.ended == "step_cap" and child.handoff.steps == BUDGET
Saídapython child-with-budget.py
child budget, steps: 4
child steps: 4
child result: step_cap
child tools: list_files, read_file, run_tests, write_file, edit_file, ask_user, finish
child steps, in order:
  step 1: list_files: 25 files
  step 2: read_file: 23 lines
  step 3: edit_file: error: old text not found in unitcraft/format.py
  step 4: read_file: 23 lines

O orçamento, e não as ferramentas, encerrou este filho: ele usou todos os seus passos e nunca chamou finish. Seu orçamento conta chamadas de modelo, 4 delas aqui, contra um orçamento de 4, e o arcabouço encerra o filho como step_cap. As ferramentas são o conjunto completo da v1, list_files, read_file, run_tests, write_file, edit_file, ask_user, finish, de modo que é o orçamento que contém o filho, e não um conjunto de ferramentas menor.

Esses 4 passos são toda a execução do filho. Ele lista os arquivos, lê um, tenta uma edição que falha porque o texto antigo não está no arquivo como escrito, e lê o arquivo de novo. O orçamento não se importa com quais desses passos foram úteis. Ele os conta.

Um pai pode iniciar o mesmo filho por conta própria, por meio de uma ferramenta. No próximo exemplo, o pai é um loop com duas ferramentas, start_child e ask_user. Ele inicia o filho no T-02 sob as duas regras de parada, lê o repasse do filho como resultado da ferramenta e faz à pessoa a pergunta que o repasse traz.

parent-starts-child.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A parent loop starts the child on T-02 through a tool, reads the child's handoff and asks the person the child'squestion. The output counts the parent's steps apart from the child's, and shows that the child's file text stays out ofthe parent's context."""from lib.case import load_tasksfrom lib.loop import Stops, run_taskfrom lib.models import ReplayModelfrom lib.subagents import ParentReadsHandoff, characters, start_child_toolsfrom lib.tools import V1from lib.trace import IdCounterRULES = Stops(repeat_limit=3, no_progress_limit=2)task = load_tasks(only=["T-02"])[0]child_ids = IdCounter()child_ids.next("run")  # the recording numbers its runs in task order, so T-02 is run-0002: skip T-01's numberchildren = []tools = start_child_tools(task, lambda: ReplayModel("task-set", task.id), ids=child_ids, stops=RULES, children=children)parent_model = ParentReadsHandoff(task.id)parent = run_task(parent_model, task, tools, max_steps=tools.step_cap, ids=IdCounter())child = children[0]h = child.handoff# the child's longest tool result is its read of the library file, the text a parent must not receivefile_text = max((m["content"] for m in child.transcript if m["role"] == "tool"), key=len)parent_text = "\n".join(m["content"] for m in parent_model.messages)print("child budget, steps:", V1.step_cap)print("child steps:", h.steps)print("child result:", h.ended)print("parent steps:", parent.steps)print("parent result:", parent.ended)print("parent tools:", ", ".join(t.name for t in tools.tools))print("question asked matches the handoff:", "yes" if parent.question == h.question else "no")print("child transcript, characters:", characters(child.transcript))print("handoff in parent context, characters:", len(h.text))print("parent context at last step, characters:", characters(parent_model.messages))print("child file text in parent context:", "yes" if file_text in parent_text else "no")print("parent steps, in order:", *parent.trace.lines(), sep="\n  ")assert h.ended == "no_progress" and parent.ended == "ask_user" and parent.steps == 2assert parent.question == h.question and file_text not in parent_textparent.close()
Saídapython parent-starts-child.py
child budget, steps: 16
child steps: 5
child result: no_progress
parent steps: 2
parent result: ask_user
parent tools: start_child, ask_user
question asked matches the handoff: yes
child transcript, characters: 5408
handoff in parent context, characters: 436
parent context at last step, characters: 1041
child file text in parent context: no
parent steps, in order:
  step 1: start_child: child no_progress at step 5
  step 2: ask_user: ask_user

A pergunta do pai é a do filho, palavra por palavra, e o texto do arquivo do filho não está no contexto do pai. O filho consome 5 passos do próprio orçamento, e o pai consome 2, um para iniciar o filho e outro para perguntar. O pai recebe um repasse de 436 caracteres, enquanto a transcrição do filho tem 5408.

O fim é uma parada como qualquer outra. Um filho que atinge o orçamento termina sem uma chamada a finish, e o repasse na seção sobre paradas leva esse fim ao pai, que é onde a próxima decisão é tomada.

Regra prática: Dê a cada filho um orçamento próprio, contado nas chamadas de modelo do próprio filho e nunca compartilhado com o pai. Defina-o a partir de execuções que terminaram no conjunto de tarefas, e não por estimativa. Um orçamento abaixo do que as execuções concluídas precisam transforma trabalho concluído em paradas.

Um briefing com quatro partes

O briefing é o trabalho tal como o filho o recebe. Aqui o filho recebe apenas o texto da issue: o filho T-02 em summary-to-parent parte da issue da própria tarefa, e de nada que um pai tenha escrito. O relato da Anthropic sobre seu sistema de pesquisa multiagente nomeia quatro partes de que o briefing de cada subagente precisa: um objetivo, um formato de saída, orientação sobre as ferramentas e fontes a usar e limites claros para a tarefa. Escrito com essas quatro partes, um briefing para o filho T-02 pode ficar assim:

Objective: find out why the two edits to unitcraft/format.py left the test result where it was.
Output format: a short summary, then the files read and the files edited.
Tools and sources: read_file and run_tests on the scratch copy; edit_file only on unitcraft/format.py.
Boundaries: do not change a test or any file other than unitcraft/format.py. If the fix needs a public name changed, call ask_user instead of editing.

Cada parte protege contra uma falha que o caso T-02 torna provável. O objetivo mantém o filho nas duas edições, e fora do restante da biblioteca. O formato de saída permite que o pai leia o resultado de uma só vez, com os arquivos no final, onde ele os procura. A linha de ferramentas e fontes diz qual arquivo o filho pode editar. O filho nestes exemplos tem o conjunto completo de ferramentas v1, incluindo write_file, por isso essa linha é um texto que o pai escreve, e nada aqui a faz valer. A linha files changed da transferência mostra depois quais arquivos o filho alterou, e a linha edits failed quantas edições não foram aplicadas. Os limites são a parte que um mantenedor verifica primeiro, porque os testes visíveis são a verificação, e uma edição em um teste passaria sem que houvesse correção de fato.

O briefing é um texto que o pai escreve, e este capítulo não o mede. O mesmo relato registra, como observação e não como medição, que subagentes com tarefas vagas às vezes duplicavam as buscas uns dos outros, e que um briefing explícito foi a correção do fornecedor. Nenhum exemplo aqui testa um briefing vago. O que o briefing torna verificável é o limite. A transferência em a seção sobre o que retorna lista os arquivos que o filho leu e alterou, e eles podem ser confrontados com os limites linha por linha.

Regra prática: Escreva as quatro partes em um briefing antes de o filho começar, e escreva os limites como arquivos e ferramentas, não como intenções. Um briefing que não consegue dizer quando o filho terminou, ou quais arquivos ele pode editar, não está pronto para ser enviado.

O que volta

A execução de T-02 deixa uma transcrição de cada arquivo lido, cada edição que falhou e cada execução de testes, e isso é muito mais do que o agente pai precisa de volta. O pai precisa do resultado do filho e de caminho suficiente do filho para julgar o resultado. Não precisa das leituras. Um filho interrompido precisa do mesmo tratamento, com um motivo de parada e uma pergunta acrescentados.

Execute T-02 como filho sob as duas regras de parada, com o limite de passos do conjunto de tarefas, e imprima o que o pai recebe ao lado do tamanho da transcrição do filho.

summary-to-parent.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""T-02's recorded run as a child, with both stop rules and the task set's step cap. The parent gets thehandoff's fields and not the child's transcript; the example prints the size of each."""from lib.case import load_tasksfrom lib.loop import Stopsfrom lib.models import ReplayModelfrom lib.subagents import characters, run_child, tokensfrom lib.tools import V1from lib.trace import IdCounterRULES = Stops(repeat_limit=3, no_progress_limit=2)task = load_tasks(only=["T-02"])[0]ids = IdCounter()ids.next("run")  # the recording numbers its runs in task order, so T-02 is run-0002: skip T-01's numberchild = run_child(ReplayModel("task-set", "T-02"), task, V1, budget=V1.step_cap, ids=ids, stops=RULES)h = child.handoffprint("child result:", h.ended, "at step", h.steps, "of", h.budget)print("transcript messages:", len(child.transcript))print("child transcript, characters:", characters(child.transcript))print("child transcript, estimated tokens:", tokens(characters(child.transcript)))print("parent receives, characters:", len(h.text))print("parent receives, estimated tokens:", tokens(len(h.text)))print("saved by the handoff, characters:", characters(child.transcript) - len(h.text))print("what the parent receives:")print(h.text)child.run.close()assert task.issue not in h.text and len(h.text) < characters(child.transcript)
Saídapython summary-to-parent.py
child result: no_progress at step 5 of 16
transcript messages: 12
child transcript, characters: 5408
child transcript, estimated tokens: 1803
parent receives, characters: 436
parent receives, estimated tokens: 146
saved by the handoff, characters: 4972
what the parent receives:
child: child-0001
ended: no_progress
steps: 5 of 16
tried: edit_file 2, list_files 1, read_file 2
files read: unitcraft/format.py
files changed: none
edits failed: 2
stop: no_progress (edit_file, 2 edits in a row left the test result unchanged: 8 failed, 22 passed)
question: The last 2 edits left the test result unchanged (last result: 8 failed, 22 passed). Should a person look at unitcraft/format.py, or should the agent keep going?

O pai recebe apenas o repasse, e nada além disso. O filho terminou como no_progress at step 5 of 16, e a transcrição que ele guardou tem 5408 caracteres. O repasse que o pai lê tem 436 caracteres.

A linha de arquivos alterados do repasse mostra none, e a linha de edições que falharam mostra 2. As duas edições citaram unitcraft/format.py, mas os bytes do arquivo não mudaram; por isso a linha de alterados deixa esse arquivo de fora, e a contagem de falhas indica que as edições não foram aplicadas.

Em tokens, a mesma diferença aparece como 1803 contra 146. São estimativas feitas com a regra do capítulo 5, não contagens do tokenizador do modelo, e este capítulo as usa apenas para comparar tamanhos.

As linhas do repasse seguem uma ordem fixa: o ID do filho, como ele terminou, seus passos em relação ao orçamento, as ferramentas que tentou e com que frequência, os arquivos que leu, os arquivos que alterou, o número de edições que falharam, e depois o motivo de parada e a pergunta. Um filho que termina entrega o seu resumo no lugar da parada e da pergunta. Filhos concluídos são contados, mas os seus resumos não são impressos, de modo que essa linha não aparece em nenhuma saída. O exemplo verifica que o texto do problema não aparece literalmente no repasse, para que o pai trabalhe a partir do que o filho fez, e não a partir da redação da tarefa.

O que o pai faz com o repasse é escolha do pai, e este capítulo não a roteiriza. O código deste capítulo implementa uma escolha: o pai submete a pergunta ao mantenedor. A mesma ligação poderia iniciar um segundo filho com uma instrução mais restrita que nomeie um arquivo listado no repasse, ou responder apenas a partir dos campos. Nenhum exemplo implementa qualquer uma dessas opções. Cada uma delas mantém a transcrição do filho fora do contexto do pai, que é justamente a razão do repasse.

O registro próprio do filho é mantido, e é ele que o capítulo 11 rastreia. O pai não o abre.

Regra prática: Devolva ao pai o ID de um filho, como ele terminou, suas contagens, seus arquivos e sua parada ou seu resumo, e nada mais. Mantenha a transcrição no registro próprio do filho, onde um rastreamento possa lê-la.

Uma parada devolvida

A execução T-02 termina travada, e uma parada, por si só, não diz ao mantenedor o que decidir. O Capítulo 2 deu um nome e um motivo a cada parada, mas alguém ainda precisa escolher entre tirar a tarefa do agente, dar-lhe mais passos ou tentar outra abordagem. Esse alguém é o mantenedor que abriu a issue. Assim, uma parada que o harness não consegue resolver torna-se um repasse para um pai, e o pai pergunta ao mantenedor.

A alternativa é registrar a parada e descartar a execução. Isso mantém pequeno o contexto do pai, mas não deixa a decisão com ninguém. O repasse mantém a decisão com o mantenedor e custa ao pai um passo curto nas execuções abaixo.

Para as três paradas que deixam um filho travado, step_cap, repeated_call e no_progress, o harness monta o repasse a partir do próprio registro da execução: seu rastro, sua sequência de chamadas repetidas e suas contagens de testes. O motivo da parada, as contagens e a pergunta vêm todos desse registro. Nenhum modelo os escreve, então uma execução reproduzida gera sempre o mesmo repasse. O pai é um laço próprio, com um orçamento pequeno de passos e duas ferramentas, ask_user e finish. Em um desenho real, o pai seria um modelo que formularia a pergunta ao mantenedor. Aqui, um pai roteirizado repassa a pergunta exatamente como o repasse a traz, de modo que a execução mostra a fiação e não o julgamento de um modelo.

Um filho que termina de outra forma não é devolvido. Uma execução que termina como no_tool_call, por exemplo, gera um repasse sem motivo de parada e sem pergunta, então o pai não tem o que levar à pessoa. Nenhuma execução aqui terminou assim (0 das execuções), então nenhum exemplo a mostra.

Execute cada execução do conjunto de tarefas como filho sob as duas regras de parada. Cada filho que termina travado vai a um pai, que faz à pessoa a pergunta do repasse.

handoff-on-stuck.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The 20 task-set runs as children, with both stop rules. Each child that ended stuck is handed to a parent, whichputs the stop's question to the person with ask_user. Counts only: how the children ended, and what the parents got."""from collections import Counterfrom lib.loop import Stopsfrom lib.models import ScriptedModelfrom lib.subagents import STUCK, asks, characters, hand_to_parent, task_set_childrenfrom lib.trace import IdCounterRULES = Stops(repeat_limit=3, no_progress_limit=2)ENDS = ("finish", "ask_user", "step_cap", "repeated_call", "no_progress", "no_tool_call")children = task_set_children(RULES)stuck = [(task, h, transcript) for task, h, _, transcript in children if h.stuck]ends = Counter(h.ended for _, h, _, _ in children)print("child runs:", len(children))for ended in ENDS:    print(f"  {ended}: {ends[ended]}")print("done with the rules:", sum(1 for _, _, ok, _ in children if ok))print("ended with finish or ask_user:", sum(1 for _, h, _, _ in children if h.ended in ("finish", "ask_user")))print("done among the handed back:", sum(1 for _, h, ok, _ in children if h.stuck and ok))print("handed back to a parent:", len(stuck))handed = Counter(h.ended for _, h, _ in stuck)for ended in STUCK:    print(f"  {ended}: {handed[ended]}")print("handed back, tasks:", ", ".join(task.id for task, _, _ in stuck))parent_ids = IdCounter()  # the parents number their runs apart, so the children's run IDs stay the recording'sparents = [(h, hand_to_parent(ScriptedModel([asks(h.question)]), h, parent_ids)) for _, h, _ in stuck]print("parent asked the person, with the handoff's question:",      sum(1 for h, r in parents if r.ended == "ask_user" and r.question == h.question))print("child steps, all handed back:", sum(h.steps for _, h, _ in stuck))print("parent steps, all handed back:", sum(r.steps for _, r in parents))print("child transcripts, characters:", sum(characters(t) for _, _, t in stuck))print("handoffs the parents read, characters:", sum(len(h.text) for _, h, _ in stuck))print("saved by the handoffs, characters:",      sum(characters(t) for _, _, t in stuck) - sum(len(h.text) for _, h, _ in stuck))assert all(h.stop and h.question for _, h, _ in stuck), "every stuck child gives a stop reason and a question"assert not any(ok for _, h, ok, _ in children if h.stuck), "a done task must not be handed back"
Saídapython handoff-on-stuck.py
child runs: 20
  finish: 6
  ask_user: 1
  step_cap: 1
  repeated_call: 1
  no_progress: 11
  no_tool_call: 0
done with the rules: 5
ended with finish or ask_user: 7
done among the handed back: 0
handed back to a parent: 13
  step_cap: 1
  repeated_call: 1
  no_progress: 11
handed back, tasks: T-01, T-02, T-03, T-06, T-10, T-11, T-12, T-13, T-15, T-16, T-17, T-19, T-20
parent asked the person, with the handoff's question: 13
child steps, all handed back: 83
parent steps, all handed back: 13
child transcripts, characters: 95252
handoffs the parents read, characters: 5874
saved by the handoffs, characters: 89378

Nenhuma das execuções devolvidas por uma parada foi concluída. As regras devolvem 13 das 20 execuções, e nenhuma delas está concluída. Cada uma chega a um pai, e os pais fazem a pergunta à pessoa 13 vezes, uma para cada. A parada que mais aparece é no_progress, a mesma em que a T-02 terminou.

As regras de parada não custam trabalho concluído. 7 execuções terminaram com finish (6) ou com ask_user (1), e todas as 5 execuções concluídas estão entre elas, porque nenhuma das execuções devolvidas foi concluída. As outras execuções desse grupo não estão concluídas, e nenhuma delas terminou em uma regra de parada, então nenhum repasse as cobre. Uma execução que termina com finish ou ask_user nunca chega a um pai sob estas regras, esteja ou não certo ter terminado ali.

As execuções devolvidas são T-01, T-02, T-03, T-06, T-10, T-11, T-12, T-13, T-15, T-16, T-17, T-19, T-20. Juntas, seus filhos levaram 83 passos, e seus pais levaram 13 passos, um cada, a chamada que pergunta à pessoa.

Os rastros dos filhos somaram 95252 caracteres, e os pais leram 5874 caracteres de repasse no total. Cada filho devolvido é verificado para trazer um motivo de parada e uma pergunta. Isso verifica a forma do repasse, e não verifica que a pergunta é a certa a fazer.

A pergunta da execução T-02 termina assim: "Uma pessoa deve olhar unitcraft/format.py, ou o agente deve continuar?" Ela nomeia o arquivo que as duas edições falhas citavam, de modo que o mantenedor sabe onde olhar sem abrir o rastro. A linha de arquivos alterados do repasse diz que nenhum arquivo foi alterado, então a pergunta aponta para um arquivo que as edições citaram mas nunca alteraram.

Uma ressalva, dita uma vez: um repasse diz que uma execução parou e por quê. Ele não diz que a tarefa não pôde ser concluída. Este livro conta uma execução devolvida como não concluída, como faz o exemplo.

Regra prática: Entregue a uma pessoa, como pergunta, toda parada travada (step_cap, repeated_call, no_progress), com seu motivo de parada, suas contagens e seus arquivos. Um pai trabalha a partir do repasse. O registro do filho fica com o filho, onde um rastro pode lê-lo.

Dois designs, e de quem são os números

Qual design uma divisão deve usar depende do que o agente pai precisa fazer com o resultado do filho. Dois designs são amplamente usados, e eles diferem no que acontece com a conversa. No design deste capítulo, o agente filho devolve um resultado e para. Em um handoff do SDK, a conversa passa para outro agente. O SDK usa a palavra handoff para o segundo design, que não é o sentido que este capítulo lhe dá. Nada nesta seção foi executado aqui, e seus números pertencem às suas fontes.

A documentação do OpenAI Agents SDK sobre handoffs, para o SDK 0.24.0 conforme obtida em novembro de 2026, descreve o segundo. Um handoff é uma ferramenta que o modelo chama, com o nome do seu destino; seu exemplo é transfer_to_refund_agent. O agente receptor vê toda a conversa anterior, a menos que um filtro de entrada altere o que ele vê. Para um especialista que deve devolver um resultado sem assumir a conversa, a mesma página recomenda encapsular o agente como ferramenta, com Agent.as_tool. Seu histórico aninhado, que resume a conversa anterior, é um recurso beta opcional e vem desativado por padrão.

A documentação de subagentes do Claude Code, conforme obtida em novembro de 2026, descreve o primeiro tipo. Um subagente tem um limite de turnos agênticos, que este livro chamaria de passos, definido como maxTurns. Quando um subagente atinge o limite, sua saída volta marcada como parcial, e o pai pode retomá-lo. A página diz que a marcação parcial "requer o Claude Code v2.1.246 ou posterior"; nada aqui foi executado nessa versão. Os subagentes embutidos herdam as regras de permissão do pai, e a maioria roda com um conjunto restrito de ferramentas. Um subagente personalizado tem suas próprias ferramentas e permissões independentes. O formato corresponde ao orçamento deste capítulo, com o handoff fazendo o papel do resultado parcial.

A medição que esta seção cita vem da empresa que construiu o sistema que ela mede. Em junho de 2025, o relato da Anthropic sobre seu sistema de pesquisa informou que "um sistema multiagente com o Claude Opus 4 como agente líder e subagentes Claude Sonnet 4 superou o Claude Opus 4 de agente único em 90.2% na nossa avaliação interna de pesquisa". Essa comparação coloca um sistema multiagente contra um único agente, com um modelo diferente nos subagentes, em uma avaliação cuja métrica o post não nomeia. O post diz que suas avaliações favorecem consultas de busca em largura, nas quais muitas direções independentes podem ser exploradas ao mesmo tempo.

O mesmo post apresenta uma segunda medição, na avaliação BrowseComp: "o uso de tokens, por si só, explica 80% da variância". Ele diz que sistemas multiagente funcionam sobretudo porque gastam tokens suficientes para resolver o problema. Seus próprios dados colocam os agentes em cerca de quatro vezes os tokens de um chat, e os sistemas multiagente em cerca de quinze vezes. Diz também que alguns domínios em que os agentes precisam compartilhar um mesmo contexto, ou dependem uns dos outros de muitas formas, não se adequam bem, e que seu agente líder executava subagentes em lotes, esperando que cada conjunto terminasse. Uma divisão não é paralela só porque tem vários agentes.

Um argumento muito lido contra divisões vem do ensaio de Walden Yan, "Não construa multiagentes", publicado pela Cognition em 2025. Seu primeiro princípio é: "Compartilhe o contexto e compartilhe os rastros completos dos agentes, não apenas mensagens individuais." O handoff quebra esse princípio: ele passa os campos de um filho e seu resumo ou sua parada, e nunca seu rastro completo. O segundo princípio do ensaio é que ações carregam decisões implícitas, de modo que agentes que trabalham separados podem agir com base em decisões conflitantes. Trata-se de um ensaio, o juízo de um praticante.

A forma mais simples de seguir os princípios do ensaio é um agente linear único com um contexto contínuo. Para tarefas muito longas, ele propõe um modelo que comprime o histórico em detalhes-chave, eventos e decisões, e diz que isso é difícil de acertar. Isso está próximo da compactação do capítulo 5 e do handoff deste capítulo. O ensaio também aceita um subagente que responde a uma pergunta bem definida, geralmente sem escrever nenhum código.

O filho-exemplo deste capítulo escreve código: o filho do T-02 edita unitcraft/format.py, justamente o caso contra o qual o ensaio argumenta. Aqui, um filho edita e o pai não edita esse arquivo, de modo que o conflito descrito no segundo princípio não surge nestes exemplos. Os motivos das edições do filho ainda não chegam ao pai, e a objeção do ensaio a isso se mantém. O livro constrói o filho mesmo assim, porque o caso do T-02 exige um filho capaz de alterar a biblioteca. A divisão compensa quando um resultado pode ser usado sem os motivos por trás dele, que é o caso que a documentação do produto descreve.

Recomendamos um filho para uma tarefa secundária cujo resultado se sustenta sozinho, e um único laço para trabalho em que o pai e o filho editariam os mesmos arquivos.

Regra prática: Use um filho quando o resultado puder ser usado sem os seus motivos: um fato, uma lista de arquivos, ou uma parada com a sua pergunta. Mantenha um único laço quando o pai precisar agir sobre os arquivos que o filho editaria. Este livro não mede uma divisão contra um único laço, de modo que a regra se apoia no argumento acima, não em uma medição.

O que dá errado em produção

Dividir o trabalho traz falhas que um único laço não tem. A primeira é um orçamento na unidade errada. Um orçamento contado em segundos interrompe um agente filho por causa de uma execução lenta de testes com a mesma facilidade com que o interrompe por causa de um laço, e uma reexecução não consegue repeti-lo, porque a mesma execução leva tempos diferentes a cada vez. Por isso este capítulo conta chamadas ao modelo e não o tempo.

A segunda é um agente pai que decide pela pessoa. O pai em transferência ao travar tem finish e também ask_user entre as suas ferramentas, então um modelo que acha que sabe a resposta pode encerrar uma execução travada sem perguntar a ninguém. Em produção, um pai que recebe uma parada deve ter apenas os meios para perguntar, e uma parada que chega até ele deve sempre terminar em uma pergunta ao mantenedor.

A terceira é uma divisão que o pai não consegue conciliar. Dois filhos que editam o mesmo arquivo podem devolver, cada um, um resumo limpo, e o pai então precisa abrir os dois registros para ver que as edições deles divergem. A transferência não mostra essa divergência por si só, e é esse o ponto de a visão contrária.

A quarta é um custo que não aparece. Os tokens de um filho são dele, e o número do fornecedor coloca um sistema multiagente em cerca de quinze vezes os tokens de um chat. Registre os tokens de cada filho no seu próprio registro, como faz o capítulo 11, ou o custo de uma divisão nunca chega à contagem do pai.

Regra prática: Conte o orçamento de um filho em chamadas ao modelo, dê ao pai apenas os meios para perguntar, e confira as edições de cada divisão contra os arquivos que os outros filhos alteraram antes de uni-las. Registre os tokens de cada filho no seu próprio registro, para que o custo de uma divisão seja contado onde é gasto.

Decisões tomadas neste capítulo

Para o mantenedor, a mudança é que a parada T-02 agora chega como uma pergunta sobre um arquivo. Antes, ela terminava em um registro que o mantenedor precisava ler, sem nenhuma decisão associada. Com este design, ela chega ao mantenedor com os seus arquivos e com uma pergunta que indica o arquivo a ser consultado. Cada escolha abaixo pode ser revista, e cada uma altera o que o mantenedor vê quando uma execução dá errado. As três primeiras definem quanto um filho pode gastar, o que ele devolve e de onde vem o motivo de uma parada. As três últimas definem quando vale a pena separar um filho e quem responde quando ele não consegue terminar.

  • O orçamento de um filho conta as suas próprias chamadas ao modelo, e a contagem do pai não as inclui.
  • Um filho devolve campos e o seu resumo ou a sua parada, nunca a sua transcrição. A transcrição permanece no próprio registro.
  • O motivo de uma parada, as contagens e a pergunta vêm do registro da execução, construído por código, de modo que uma reexecução produza a mesma transferência.
  • Um filho travado é encaminhado a um pai com um orçamento pequeno de passos, que pergunta ao mantenedor que abriu o problema por meio de ask_user.
  • Um filho serve para uma tarefa secundária cujo resultado se sustenta sozinho. Trabalho em que o pai e o filho editam os mesmos arquivos permanece em um único ciclo.
  • Uma parada que chega a uma pessoa como pergunta é mais útil do que uma parada que termina em um registro. O Capítulo 12 trata do caso em que nenhuma divisão, e nenhum agente, vale o seu custo.

Este capítulo, nesta edição

Edição 2026.11.2Exemplos aprovados em 20 de nov de 20264 de 4 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.2.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 8 de 12: Entregue uma subtarefa a um filho, e devolva uma parada

  1. Um filho é um loop com orçamento próprio
  2. Um briefing com quatro partes
  3. O que volta
  4. Uma parada devolvida
  5. Dois designs, e de quem são os números
  6. O que dá errado em produção
  7. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos