Quando um agente é o design errado

Cerca de 23 minutos min de leitura, com 2 exemplos em 6 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 tomar qualquer tarefa do caso, classificá-la como um pipeline fixo, uma única chamada de modelo ou um agente com portões, e dizer o que as execuções registradas mostram para ela. O caso oferece o primeiro teste. A tarefa T-02 é uma correção de uma linha em unitcraft, a biblioteca cujas tarefas este capítulo classifica por design: valores negativos perdem o separador de milhares, de modo que -1234.5 m deveria imprimir -1,234.50 m. A execução registrada com o conjunto de ferramentas v1 do capítulo 3, o conjunto com que a gravação da tarefa foi feita, nunca a concluiu. Ela usou todos os 16 passos e nunca chamou finish. A mudança é uma única substituição em uma única função, então a pergunta é se um agente chegou a ser o design certo para ela.

Comece pelo pipeline fixo

A primeira pergunta para o T-02 é quais passos ele precisa quando nada na execução tem de ser decidido. Leia o módulo de formatação, substitua a linha que monta o texto do número para que valores negativos mantenham o separador, rode os testes visíveis e termine com uma frase descrevendo a mudança. Nenhum desses passos depende do que um modelo pensa sobre o arquivo, então nenhum precisa de modelo. Um pipeline fixo é essa lista, escrita como código antes de a execução começar.

A publicação de engenharia da Anthropic sobre a construção de agentes traça uma linha semelhante. Ela chama de workflow um sistema em que LLMs e ferramentas são orquestrados por caminhos de código predefinidos, e de agente um sistema em que um LLM direciona dinamicamente seus próprios processos e o uso de ferramentas (Anthropic, "Building effective agents", publicado em 19 de dezembro de 2024). Um workflow, nesse sentido, ainda executa um modelo em seus passos. O pipeline deste capítulo vai um passo além, porque nenhum de seus passos precisa de modelo. A mesma publicação recomenda encontrar a solução mais simples possível e acrescentar complexidade só quando ela for necessária. A regra que este capítulo tira desse conselho é uma regra empírica, não uma medição: se os passos podem ser escritos antes da execução, escreva-os primeiro.

Cada pipeline é uma lista de edições exatas e um resumo, mantida em lib/pipeline.py. Uma edição nomeia o texto que substitui e o texto que o substitui, e falha quando o texto antigo não aparece exatamente uma vez no arquivo. O pipeline executa sua lista pelo conjunto de ferramentas v1, de modo que cada chamada se comporta como para o agente, e pontua o resultado com a mesma regra de conclusão. Somente três pipelines são escritos, para T-02, T-04 e T-05. O exemplo os executa e exibe cada um ao lado da execução armazenada do agente na mesma tarefa.

fixed-pipeline-same-task.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The fixed pipeline on the tasks where one known edit works (T-02, T-04, T-05), with no model, beside the recordedagent's run on the same task. The point rests on two lines per run: the pipeline's actions and its model calls (0), andthe agent's steps, which are its model calls. The edits are written by a person; the scoring is the same for both."""from lib.case import load_tasksfrom lib.models import load_recordingfrom lib.pipeline import PIPELINES, Edit, Pipeline, agent_edit_results, run_pipelinefrom lib.tasks import scoremanifest, _ = load_recording("task-set")stored = {row["task"]: row for row in manifest["tasks"]}for task in load_tasks(only=sorted(PIPELINES)):    run = run_pipeline(task, PIPELINES[task.id])    done = score(task, run)    run.close()    agent = stored[task.id]    print(f"{task.id} pipeline ended: {run.ended}")    print(f"{task.id} pipeline done: {'yes' if done else 'no'}")    print(f"{task.id} pipeline actions: {run.tool_calls}")    print(f"{task.id} pipeline model calls: {run.steps}")    print(f"{task.id} pipeline prompt tokens: {run.prompt_tokens}")    print(f"{task.id} agent ended: {agent['ended']}")    print(f"{task.id} agent done: {'yes' if agent['done'] else 'no'}")    print(f"{task.id} agent steps: {agent['steps']}")    print(f"{task.id} agent tool calls: {agent['tool_calls']}")    print(f"{task.id} agent prompt tokens: {agent['prompt_tokens']}")    assert done and run.steps == 0 and run.tool_calls < agent["tool_calls"], task.id# The agent's T-02 run, replayed from the recording: the result the tools gave each of its edits and test runs.edits, tests = agent_edit_results("T-02")print(f"T-02 agent edits failed: {sum(e.startswith('error') for e in edits)} of {len(edits)}")print(f"T-02 agent test runs: {len(tests)}")print(f"T-02 agent first edit result: {edits[0]}")assert all(e.startswith("error") for e in edits) and not tests# The pipeline's own failure: its one edit names text the file does not hold, so the run stops at that step.task = load_tasks(only=["T-04"])[0]run = run_pipeline(task, Pipeline((Edit("unitcraft/units.py", "no such line", "x"),), "not run"))print(f"T-04 missing anchor ended: {run.ended}")print(f"T-04 missing anchor actions: {run.tool_calls}")print(f"T-04 missing anchor done: {'yes' if score(task, run) else 'no'}")print(f"T-04 missing anchor result: {run.stop_detail}")run.close()assert run.ended == "pipeline_stop" and run.tool_calls == 2
Saídapython fixed-pipeline-same-task.py
T-02 pipeline ended: finish
T-02 pipeline done: yes
T-02 pipeline actions: 4
T-02 pipeline model calls: 0
T-02 pipeline prompt tokens: 0
T-02 agent ended: step_cap
T-02 agent done: no
T-02 agent steps: 16
T-02 agent tool calls: 16
T-02 agent prompt tokens: 43904
T-04 pipeline ended: finish
T-04 pipeline done: yes
T-04 pipeline actions: 4
T-04 pipeline model calls: 0
T-04 pipeline prompt tokens: 0
T-04 agent ended: finish
T-04 agent done: yes
T-04 agent steps: 5
T-04 agent tool calls: 5
T-04 agent prompt tokens: 8809
T-05 pipeline ended: finish
T-05 pipeline done: yes
T-05 pipeline actions: 4
T-05 pipeline model calls: 0
T-05 pipeline prompt tokens: 0
T-05 agent ended: finish
T-05 agent done: yes
T-05 agent steps: 5
T-05 agent tool calls: 5
T-05 agent prompt tokens: 8494
T-02 agent edits failed: 9 of 9
T-02 agent test runs: 0
T-02 agent first edit result: error: old text not found in unitcraft/format.py
T-04 missing anchor ended: pipeline_stop
T-04 missing anchor actions: 2
T-04 missing anchor done: no
T-04 missing anchor result: error: old text not found in unitcraft/units.py

O pipeline conclui as três tarefas e não faz nenhuma chamada ao modelo. Neste capítulo, um passo é uma chamada ao modelo, como em todo o livro, então o pipeline não tem passos. Ele tem ações, que são suas chamadas de ferramentas, e a linha que as conta é 4 para o T-02. O agente gravado no T-02 fez 16 chamadas ao modelo, uma para cada passo, e seus tokens de prompt somam 43904. O pipeline não enviou prompt algum. No T-04 e no T-05, onde o agente concluiu, o agente ainda fez mais chamadas ao modelo do que o pipeline fez ações, e o exemplo exibe as duas contagens para cada um. O Capítulo 11 explica por que o livro conta chamadas e tokens em vez de dinheiro (custo como contagens).

Repetir a execução gravada do agente no T-02 mostra o resultado de cada chamada. Suas edições falharam, 9 of 9, cada uma com a mesma mensagem: error: old text not found in unitcraft/format.py. O agente leu o arquivo novamente e tentou de novo, com o mesmo erro, e nunca executou os testes: a contagem de execuções de teste é 0. O limite de passos interrompeu uma execução que não conseguia fazer sua mudança coincidir com o arquivo. Nada na execução verificou se alguma mudança havia funcionado, então a contagem diz quanto tempo o agente ficou preso e nada sobre o motivo.

O pipeline também falha à sua maneira. Sua última execução lhe dá uma edição para o T-04 cujo texto antigo não ocorre no arquivo, o que acontece quando um arquivo muda sob uma lista fixa. A execução termina nesse passo, após 2 ações, com a mensagem da própria ferramenta: error: old text not found in unitcraft/units.py. O pipeline não tenta outra âncora, não relê o arquivo nem pergunta a ninguém. Para uma edição escrita por uma pessoa, parar é a resposta correta, porque o arquivo mudou e uma pessoa deve olhar.

A parada ainda precisa ir para algum lugar, e um pipeline não pode entregá-la a um filho, pois não tem nenhum. Ele pode entregar a parada a uma pessoa, que lê o passo que falhou e decide o que fazer. Ou pode entregar a tarefa a um agente, dado o passo que falhou e o arquivo como está agora. O híbrido, um pipeline primeiro e um agente somente em um pipeline_stop, é o natural. O pipeline faz os passos que não exigem julgamento, e o agente vê apenas a parte que quebrou. Isso inicia o agente a partir de um estado parcial, então a execução do agente precisa dos mesmos controles de qualquer outra. Recomendamos uma pessoa quando o passo quebrado toca em uma decisão que o caso atribui a uma pessoa. Recomendamos o agente quando o passo é uma edição conhecida que parou em uma âncora alterada. Este capítulo não mede o híbrido.

Três coisas limitam o que o pipeline mostra. Uma pessoa escreveu cada edição, então a comparação mede o custo do design, não o que um pipeline encontraria sozinho. As três tarefas são aquelas cujas edições podiam ser nomeadas antes da execução, e nada aqui mostra como as outras se sairiam. O pipeline também compara os identificadores de testes que falham antes e depois de sua edição, porque a suíte visível já falha antes de qualquer edição.

Regra prática: Antes de dar ao modelo o laço, escreva os passos, com a verificação que segue cada um. Se todos os passos são conhecidos e uma verificação decide o resultado sem modelo, construa o pipeline e meça-o. Decida para onde vai a sua parada antes da primeira execução: para uma pessoa, ou para um agente que recebe o passo que falhou.

Quando dividir o trabalho ajuda

Assim que um agente tem dificuldade, o próximo passo que as pessoas costumam tomar é acrescentar um segundo agente. Dividir o trabalho pode parecer mais cuidado, por isso a pergunta útil é quando isso realmente ajuda. Dois estudos apresentam condições, e não um veredito.

Tran e Kiela compararam um agente com vários em raciocínio de múltiplos saltos, mantendo iguais os tokens de raciocínio (Tran and Kiela, arXiv:2604.02460). O agente único igualou ou superou os sistemas multiagente. O resumo deles prevê que os sistemas multiagente se tornam competitivos sob duas condições: quando o uso efetivo do contexto por um agente único está degradado, e quando se gasta mais computação.

Kim et al. realizaram uma comparação controlada com 260 configurações e seis benchmarks agênticos (Kim et al., arXiv:2512.08296). O resumo deles afirma que o alinhamento entre arquitetura e tarefa determina o sucesso da colaboração, e que a coordenação incompatível degrada o desempenho. A leitura útil é condicional: um padrão de coordenação que ajuda em uma tarefa pode prejudicar em outra. Ambos os estudos são artigos isolados. Seu escopo são raciocínio e benchmarks, não uma biblioteca de manutenção; por isso, leia-os como razões para testar um projeto, e não como resultados definitivos.

O caso pode ser verificado pela primeira condição, um contexto que o agente único não consegue conter. A janela de contexto do registro é 8192 tokens. Sua maior requisição isolada continha 6556 tokens de prompt, o que deixa espaço dentro da janela e dentro do orçamento de prompt que o capítulo 5 define para ela. Nenhuma requisição do conjunto atingiu a janela; portanto, nenhuma tarefa do caso tem um contexto que force uma divisão. O capítulo 8 compara dois tipos de divisão e afirma que este livro não mede uma divisão contra um único ciclo. Assim, o caso também não fornece nenhum número para uma divisão. A tabela de decisão abaixo adota a primeira condição como teste para dividir, e nenhuma linha a satisfaz.

Regra prática: Divida uma tarefa somente quando você puder nomear a condição que torna a divisão útil, como um contexto que o agente único não consegue conter, e quando cada parte tiver uma verificação que não dependa das outras partes. Caso contrário, mantenha um único agente, ou nenhum.

O que dá errado quando você usa um agente

Um agente acrescenta pontos em que uma execução pode dar errado, e a maioria deles só aparece no registro da execução.

Cemri et al. construíram a sua taxonomia a partir de 150 rastros que anotadores especialistas leram com atenção. Depois, usaram um pipeline de LLM-as-a-judge, conferido contra esses anotadores, para rotular os mais de 1,600 rastros do seu conjunto de dados, provenientes de sete frameworks multiagente (Cemri et al., arXiv:2503.13657, v3). O resultado são 14 modos de falha em três categorias: problemas de design do sistema, desalinhamento entre agentes e verificação da tarefa. A taxonomia foi feita para sistemas multiagente, por isso se aplica a um único agente apenas de forma limitada. Este capítulo não relaciona nenhum dos seus modos ao caso. As chamadas de ferramenta malformadas na execução reproduzida do capítulo 1 são falhas do que o modelo envia a uma ferramenta, e elas são visíveis no registro daquela execução.

A execução T-02 falhou por repetição. Os seus 16 passos foram uma listagem e uma série de edições, a maioria depois de uma leitura do mesmo arquivo, e cada edição retornou o mesmo erro, porque o texto antigo que ela citava não estava no arquivo. O limite de passos encerrou a execução, que é para isso que serve o orçamento do capítulo 2, mas o limite apenas interrompeu a execução. O registro mostra por que ela nunca terminou: o agente nunca fez uma alteração que correspondesse, e nunca verificou uma alteração que não tinha feito.

As tarefas de parada falham de outro modo. Em T-17 e T-19 o agente fez uma pergunta a uma pessoa, e nenhuma das execuções foi contada como concluída. O avaliador só conta um ask_user quando a pergunta nomeia o motivo da parada, e procura palavras como half ou truncat em T-17, e dimension, length ou mass em T-19. T-17 pergunta qual é o arredondamento correto para dinheiro, e a pergunta final propõe uma mudança no arredondamento baseado em float e pergunta se deve seguir em frente. T-19 pede que metros sejam convertidos em quilogramas, e a pergunta final oferece um caso especial que assume uma densidade de 1 e pergunta qual abordagem a pessoa prefere. Nenhuma das perguntas nomeia o motivo que o avaliador procura. As duas execuções também tentaram editar antes de perguntar. Cada edição retornou um erro, porque o texto antigo não estava no arquivo, e uma gravação no arquivo existente foi recusada, de modo que as cópias nunca mudaram. O registro mostra que as perguntas não nomearam o motivo e que as edições falharam primeiro. Ele não mostra o que uma pessoa teria respondido, e este capítulo não faz suposições sobre isso.

T-18 é a outra tarefa de parada, e o seu registro é um alerta sobre o avaliador. O avaliador conta a sua execução como concluída por meio de uma palavra dentro de um caminho de arquivo, e o capítulo 10 explica como. Este livro mantém o avaliador como está e relata T-18 como um limite do avaliador, não como um bom encerramento.

A confiabilidade é a falha que uma única execução esconde. O tau-bench define pass^k como a chance de que todas as k tentativas independentes de uma tarefa tenham sucesso, em média sobre as tarefas (Yao et al., arXiv:2406.12045). Na sua configuração de 2024, agentes com chamada de função, entre eles o gpt-4o, tiveram sucesso em menos da metade das suas tarefas, e o pass^8 em seu domínio de varejo ficou abaixo de 25%. Uma execução bem-sucedida é uma tentativa. Este livro executa cada tarefa uma única vez, por isso não pode relatar pass^k, e o capítulo 10 descreve o que ele relata no lugar disso.

Regra prática: Antes de confiar no design de um agente, classifique as suas execuções interrompidas pelo modo como terminaram e leia o registro de cada tipo. Uma contagem de falhas sem os seus tipos não diz qual parte corrigir, e uma única execução bem-sucedida não prevê a próxima.

A verificação fica fora do agente

Uma execução que o agente julga concluída ainda não é uma tarefa concluída.

Kim et al. constataram que arquiteturas sem verificação centralizada tendem a propagar mais erros do que as que têm coordenação centralizada. Na medição do próprio artigo, agentes independentes amplificaram erros em nível de rastro 17.2 vezes, e um orquestrador centralizado conteve esse valor em 4.4 vezes (Kim et al., Seção 1 e Tabela 5). O artigo trata de vários agentes. A lógica se aplica também a um único agente: quem decide que o trabalho está correto não deve ser a parte que realizou o trabalho.

O caso aplica essa lógica à sua própria pontuação. Para uma correção, a verificação oculta é executada após o fim da execução, em uma cópia que o agente nunca vê. O agente não pode editar um teste para fazê-lo passar, e o capítulo 10 descreve a verificação oculta.

A verificação de parada é mais fraca. Uma tarefa de parada é pontuada a partir da pergunta que o agente escreveu, de modo que as próprias palavras do agente decidem se a execução conta. A T-18 mostra o pouco que isso vale (capítulo 10). Uma verificação que lê o relato do agente sobre o seu trabalho é uma verificação com a qual o agente pode argumentar. Um teste visível que o agente pode editar mostra o que o agente pensa da sua própria mudança, e não o que o código faz.

Regra prática: Coloque a verificação que decide o resultado de uma tarefa onde o agente não possa editá-la nem vê-la antes do fim da execução. Se uma conclusão ou uma parada depende do relato do próprio agente sobre o seu trabalho, acrescente uma verificação que o agente não escreveu.

A tabela de decisão

A tabela classifica cada tarefa por três leituras: se os seus passos são conhecidos antes da execução, se uma verificação pode decidir o resultado sem uma pessoa e se uma pessoa precisa dizer sim. Uma quarta questão vem antes das três, que é saber se o harness recusa a alteração de imediato. As leituras são o juízo do autor sobre cada tarefa, não medições, e as regras são regras práticas. Cada linha fica ao lado do fim registrado da execução daquela tarefa, e nenhum modelo é chamado.

As regras são aplicadas em uma ordem, e a ordem é o ponto central. Primeiro, uma alteração que o harness proíbe não é uma questão de design. O gate do capítulo 6 recusa qualquer alteração em .github/, e recusa uma renomeação que remove um nome público, porque nenhum sim pode liberar uma regra desse tipo (alterações da classe nunca). Segundo, o sim de uma pessoa significa um agente atrás de um gate, porque o gate precisa perguntar antes de aplicar uma alteração. Terceiro, passos conhecidos significam um pipeline quando uma verificação decide o resultado, e uma única chamada de modelo quando nenhuma verificação decide. Passos abertos significam um agente. A ordem importa para T-16, que a segunda regra sozinha enviaria a um gate, e que a primeira regra recusa.

decision-table.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The decision table for chapter 12: every task in the set, with the author's readings (judgement, not measured), thedesign the rules give, and how the task's recorded run ended. The counts at the end are the ones the chapter quotes.No model is called."""import jsonfrom lib.models import RECORDED, load_recordingfrom lib.pipeline import ONE_CALL_SHAPE, REFUSED, TASK_SHAPES, designyes_no = {True: "yes", False: "no"}manifest, _ = load_recording("task-set")stored = {row["task"]: row for row in manifest["tasks"]}replies = [json.loads(line) for line in           (RECORDED / "task-set" / "replies.jsonl").read_text(encoding="utf-8").splitlines() if line.strip()]print("task | steps known | exploration | wrong change | auto check | person | design | recorded ended | recorded done")for task_id, s in TASK_SHAPES.items():    rec = stored[task_id]    print(f"{task_id} | {yes_no[s.steps_known]} | {yes_no[s.exploration]} | {s.wrong_change} | "          f"{yes_no[s.auto_check]} | {yes_no[s.person]} | {design(s)} | {rec['ended']} | {yes_no[rec['done']]}")pipelines = [t for t, s in TASK_SHAPES.items() if design(s) == "fixed pipeline"]agents = [t for t, s in TASK_SHAPES.items() if design(s) == "agent with gates"]refused = [t for t, s in TASK_SHAPES.items() if design(s) == REFUSED]print(f"rows with design 'fixed pipeline': {len(pipelines)}")print(f"rows with design 'agent with gates': {len(agents)}")print(f"rows with design 'one model call': {sum(design(s) == 'one model call' for s in TASK_SHAPES.values())}")print(f"rows the harness refuses: {len(refused)}")print(f"pipeline rows the recorded agent finished and passed: "      f"{sum(stored[t]['ended'] == 'finish' and stored[t]['done'] for t in pipelines)}")print(f"agent rows the recorded agent finished and passed: "      f"{sum(stored[t]['ended'] == 'finish' and stored[t]['done'] for t in agents)}")print(f"rows done in the recording: {sum(stored[t]['done'] for t in TASK_SHAPES)}")print(f"one-call shape, not in the set: {design(ONE_CALL_SHAPE)}")print(f"largest request in the recording, prompt tokens: {max(r['prompt_tokens'] for r in replies)}")print(f"context window in the recording, tokens: {manifest['n_ctx']}")assert pipelines == ["T-01", "T-02", "T-03", "T-04", "T-05", "T-10", "T-12", "T-14", "T-20"]assert design(ONE_CALL_SHAPE) == "one model call"assert refused == ["T-16", "T-18"]assert max(r["prompt_tokens"] for r in replies) < manifest["n_ctx"]
Saídapython decision-table.py
task | steps known | exploration | wrong change | auto check | person | design | recorded ended | recorded done
T-01 | yes | no | low | yes | no | fixed pipeline | step_cap | no
T-02 | yes | no | low | yes | no | fixed pipeline | step_cap | no
T-03 | yes | no | low | yes | no | fixed pipeline | ask_user | no
T-04 | yes | no | low | yes | no | fixed pipeline | finish | yes
T-05 | yes | no | low | yes | no | fixed pipeline | finish | yes
T-06 | no | yes | low | yes | no | agent with gates | step_cap | no
T-07 | no | yes | low | yes | no | agent with gates | finish | no
T-08 | no | yes | low | yes | no | agent with gates | finish | no
T-09 | no | yes | low | yes | no | agent with gates | finish | yes
T-10 | yes | no | low | yes | no | fixed pipeline | step_cap | no
T-11 | no | yes | high | yes | no | agent with gates | step_cap | no
T-12 | yes | no | low | yes | no | fixed pipeline | ask_user | no
T-13 | no | yes | low | yes | no | agent with gates | step_cap | no
T-14 | yes | no | low | yes | no | fixed pipeline | finish | yes
T-15 | no | yes | low | yes | no | agent with gates | ask_user | no
T-16 | yes | no | high | yes | yes | not a design choice: the harness refuses | step_cap | no
T-17 | no | no | high | no | yes | agent with gates | ask_user | no
T-18 | yes | no | high | yes | no | not a design choice: the harness refuses | ask_user | yes
T-19 | no | no | high | no | yes | agent with gates | ask_user | no
T-20 | yes | no | low | yes | no | fixed pipeline | ask_user | no
rows with design 'fixed pipeline': 9
rows with design 'agent with gates': 9
rows with design 'one model call': 0
rows the harness refuses: 2
pipeline rows the recorded agent finished and passed: 3
agent rows the recorded agent finished and passed: 1
rows done in the recording: 5
one-call shape, not in the set: one model call
largest request in the recording, prompt tokens: 6556
context window in the recording, tokens: 8192

As regras dão 9 pipelines fixos, 9 agentes com gates e 2 recusas. Os pipelines são T-01 a T-05, T-10, T-12, T-14 e T-20: as edições que uma pessoa poderia escrever antes da execução, em que um teste então decide o resultado. Os agentes são as correções em aberto e as funções novas, T-06 a T-09, T-11, T-13 e T-15, e as duas tarefas de parada T-17 e T-19, em que os passos não são conhecidos e uma pessoa precisa decidir. A tabela indica onde olhar, não como a execução vai terminar.

O agente registrado confirma isso apenas em parte. Das nove linhas de pipeline, ele terminou e passou em 3 delas: T-04, T-05 e T-14. As outras seis atingiram o limite de passos ou pararam com uma pergunta. Das nove linhas de agente, ele terminou e passou em 1, T-09. Ao todo, 5 das vinte execuções foram concluídas. A regra indica pipeline para as nove linhas, e o pipeline foi construído e executado em apenas três delas. As outras seis são previsões, e o registro não lhes dá nenhum resultado de pipeline para comparar.

T-16 é a linha que mostra o que dá errado quando a ordem é ignorada. Sua tarefa renomeia parse_quantity para parse e remove o nome antigo. O gate do capítulo 6 recusa essa alteração, porque um nome público removido nunca cabe ao agente alterar, e o gate a recusaria ao ler o diff em finish. O agente registrado nunca perguntou. Ele tentou edições e gravações até o limite de passos, e todas falharam. Um agente atrás de um gate gastaria todo o seu orçamento em uma alteração que o harness não vai aplicar. Assim, T-16 é uma recusa como T-18, e o seu final correto é uma pergunta ao mantenedor que o convida a tratar a renomeação como uma decisão separada. Essa é a pergunta que a palavra de parada approv do avaliador procura. Colocar T-16 entre as linhas de agente faz a tabela estar certa no papel e errada na execução.

T-18 é a recusa vista pelo outro lado. Sua edição está em .github/, que o gate recusa sem perguntar, então o harness decide e o design não. A linha registra a decisão do harness, e a contagem do avaliador para esta execução é um limite (capítulo 10), não um bom final.

A linha de uma única chamada de modelo precisa de um caso, e o conjunto não tem nenhum. Uma única chamada de modelo serve a um passo que precisa do juízo de um modelo, sem ferramenta e sem laço, e cuja saída uma pessoa lê depois. Eis um que não está no conjunto: um resumo da alteração de T-02 para o pull request, escrito a partir do diff. Seus passos são conhecidos, já que o diff entra e sai um parágrafo. Nenhuma verificação decide se o parágrafo é bom, e não é preciso um sim, porque o mantenedor o lê depois da alteração. Um pipeline não pode escrevê-lo, porque a redação é um juízo que uma pessoa faz. Um agente acrescentaria passos que não verificam nada. O texto da Anthropic faz um ponto relacionado: "Para muitas aplicações, porém, otimizar chamadas únicas de LLM com recuperação e exemplos no contexto costuma ser suficiente" (Anthropic, "Building effective agents"). As regras dão one model call para esse resumo, e o exemplo o afirma. Nenhuma tarefa do conjunto chega a essa linha, e a razão é que cada tarefa tem uma verificação que a decide, um sim de uma pessoa que a envia a um gate, ou passos que ninguém consegue nomear antecipadamente. Toda linha do conjunto cai em uma dessas três, por isso a contagem é 0. Este capítulo não tem nenhuma resposta única registrada para a linha, e não executa nenhum modelo novo para produzir uma.

Regra prática: Classifique cada tarefa nesta ordem antes de escolher um design: uma recusa é uma pergunta a uma pessoa, não um design; o sim de uma pessoa é um agente atrás de um gate; passos conhecidos com verificação são um pipeline; passos conhecidos sem verificação são uma única chamada cuja saída uma pessoa lê. Passos abertos são um agente, e então você conta as suas paradas por tipo, como faz o capítulo 10, antes de acreditar que o design funciona.

Decisões tomadas neste capítulo

  • O padrão para etapas conhecidas que têm uma verificação é um pipeline, construído e medido antes de qualquer agente. Isso segue a recomendação de começar pelo design mais simples. É uma regra prática.
  • As ações do pipeline e as chamadas de modelo do agente são contadas separadamente e nunca precificadas, pelo motivo explicado no capítulo 11.
  • Uma recusa vem antes do sim de uma pessoa, porque um sim não pode liberar uma mudança proibida. O capítulo 6 apresenta o motivo.
  • As leituras são o juízo do autor. Um leitor que discorde altera uma leitura no exemplo e executa novamente, e as regras permanecem as mesmas.
  • As execuções registradas são relatadas como terminaram, e o registro do T-02 é uma falha repetida, não um quase acerto.
  • Nenhuma divisão é recomendada para este caso. Nenhuma tarefa atinge a condição de contexto, e o livro não mede uma divisão contra um único loop.
  • O design de uma única chamada tem um caso, mas ele não está no conjunto, e sua saída não é verificada por nenhum teste. Apenas a regra é mostrada.

O que foi aprendido é mais restrito do que as regras sugerem. A maioria das tarefas de etapas conhecidas do conjunto são pipelines no papel, e apenas três foram executadas como um. As tarefas de parada foram julgadas por suas perguntas, e o avaliador que fez esse julgamento é a parte mais fraca do caso.

Regra prática: Trate o pipeline de uma regra como uma previsão até que uma execução o tenha medido, e anote onde fica a sua parada antes de construí-lo.

Este capítulo, nesta edição

Edição 2026.11.2Exemplos aprovados em 20 de nov de 20262 de 2 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 12 de 12: Quando um agente é o design errado

  1. Comece pelo pipeline fixo
  2. Quando dividir o trabalho ajuda
  3. O que dá errado quando você usa um agente
  4. A verificação fica fora do agente
  5. A tabela de decisão
  6. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos