Dê ao modelo ferramentas que ele não consiga usar de forma indevida
Cerca de 24 minutos min de leitura, com 5 exemplos em 6 seções.
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 dar a um modelo ferramentas cujos argumentos o harness verifica antes de qualquer ferramenta ser executada, e de escrever recusas que o modelo consiga aproveitar.
O trabalho do agente é corrigir unitcraft, uma pequena biblioteca em Python que formata e converte grandezas. Suas edições são onde o problema deste capítulo aparece, já que uma única aspa faltando faz uma delas falhar. O agente trabalha em uma cópia de rascunho da biblioteca. No capítulo 1, sua primeira execução registrada falhou em uma única chamada. O modelo aberto, Qwen3-4B reproduzido a partir de sua gravação, leu o arquivo correto, interpretou mal o problema como se pedisse para remover os zeros e, em seguida, escreveu cada alteração como um arquivo inteiro, em aspas triplas do Python, dentro do JSON de uma chamada de finish. Aspas triplas não são válidas dentro de uma string JSON, então esses argumentos nunca foram analisados. Nenhuma ferramenta foi executada, e a execução terminou no limite de passos.
Este capítulo compara dois conjuntos de ferramentas. Conjunto de ferramentas v1 são as sete ferramentas com as quais a gravação do conjunto de tarefas foi feita: list_files, read_file, run_tests, write_file, edit_file, ask_user e finish. Conjunto de ferramentas v2 tem as mesmas ferramentas, com as mesmas frases e o mesmo prompt de sistema, e três mudanças: modelos de argumentos estritos, o tipo de erro nomeado em cada recusa e erros de linha mais próxima para uma edição que falhou.
O erro de interpretação é do modelo, e nenhum desenho de ferramenta o corrige. As chamadas malformadas têm duas partes. A chamada tinha uma forma que o harness não conseguia ler, e a alteração viajava dentro de uma string que o modelo precisava escapar corretamente. Este capítulo trata das duas coisas. Cada ferramenta recebe um esquema de argumentos que o harness verifica antes de executá-la, e uma recusa volta ao modelo como texto que ele pode usar. No conjunto de ferramentas v1, a alteração também fica de fora de finish: o modelo edita sua cópia com edit_file e write_file, e finish traz apenas um resumo. Pequenas edições trazem problemas próprios de aspas, que a última seção aborda.
Um esquema diz o que é permitido
Um modelo escreve uma chamada de ferramenta a partir do que lhe foi dito sobre a ferramenta, e o harness só pode recusar uma chamada incorreta verificando-a contra essa mesma descrição. Cada ferramenta do conjunto tem três partes: um nome, uma frase de descrição e um modelo de argumentos, uma pequena classe pydantic que lista os campos que a ferramenta recebe. O harness envia o esquema de cada ferramenta junto com a requisição, e o esquema é construído a partir dessa classe; assim, o texto que o modelo lê e a verificação que o harness executa vêm de um único lugar.
Esse lugar único importa, porque um esquema guarda mais do que nomes de campos. Pense nele como o formulário que o modelo preenche antes de fazer uma chamada. Cada linha do formulário nomeia um campo, indica que tipo de resposta ele espera e pode indicar qual o tamanho que uma resposta pode ter. Um formulário pode orientar quem o preenche, mas não pode impedir que uma resposta errada seja escrita. É aí que o formulário deixa de ser útil como proteção, e o harness precisa fazer a verificação que o formulário não consegue fazer.
O pydantic escreve no esquema o tipo de cada campo, sua descrição, seu padrão e seus limites. As ferramentas do caso recebem apenas caminhos e strings, então esta seção usa outra leitura, uma com um limite de linhas que nenhuma ferramenta do conjunto usa. É um modelo didático, escolhido para mostrar como é um limite. Imprimir o esquema dele é o modo mais rápido de ver o que é dito ao modelo, e os limites e o padrão são as linhas a ler.
1"""The JSON schema pydantic makes for a read with a line limit: its bounds, its default and the descriptions the2model reads before it calls. The point of the prose rests on the max_lines lines: the bounds, the default and the3description."""4from lib.tools import LinesArgs56schema = LinesArgs.model_json_schema()7limit = schema["properties"]["max_lines"] # the schema of the one field with a bound8print("required:", ", ".join(schema["required"]))9print("max_lines minimum:", limit["minimum"])10print("max_lines maximum:", limit["maximum"])11print("max_lines default:", limit["default"])12print("max_lines description:", limit["description"])13print("path description:", schema["properties"]["path"]["description"])14# LinesArgs has no extra="forbid", so its schema says nothing about other keys. The tool classes do forbid them.15assert "additionalProperties" not in schema
python schema-from-model.pyrequired: path
max_lines minimum: 1
max_lines maximum: 1000
max_lines default: 200
max_lines description: The most lines to return, from 1 to 1000; the default is 200.
path description: A file path relative to the case root, with / as the separator.
Leia a saída como o modelo a lê. O único argumento obrigatório é path. max_lines aceita valores de 1 a 1000.
O padrão é a outra metade do campo. Quando o modelo deixa max_lines de fora, o valor é 200. Esses limites estão no esquema que o modelo lê, e não apenas no código que os verifica, e a própria descrição do campo diz o mesmo em palavras: "The most lines to return, from 1 to 1000; the default is 200."
Um padrão em um esquema é uma nota, não uma regra. A especificação de validação do JSON Schema trata default como uma anotação: ele fornece um valor e não verifica nada. Se o harness preenche o padrão é escolha do harness, e o esquema sozinho não faz isso acontecer.
A outra metade do que o modelo lê é a frase de cada ferramenta. Essas frases ficam ao lado dos seus esquemas em cada requisição, por isso o exemplo abaixo as imprime. Vale a pena conferir duas linhas: a que diz quais ferramentas do capítulo 1 compartilham uma frase com este conjunto, e a que diz que finish não compartilha.
1"""The one-sentence description of each tool in the v1 set, the text the model reads beside each schema. The point2rests on the last two printed lines: which chapter 1 tools carry the same sentence in v1, and that finish does not."""3from lib.tools import CH1, V145print("v1 tools:", len(V1.tools))6for tool in V1.tools:7 print(f"v1 {tool.name}: {tool.description}")8# The chapter 1 tools whose sentence is exactly the one v1 gives the same tool.9shared = [t.name for t in CH1.tools if V1.get(t.name) and V1.get(t.name).description == t.description]10print("ch1 tools with the same sentence in v1:", ", ".join(shared))11print("ch1 finish has the same sentence in v1:", V1.get("finish").description == CH1.get("finish").description)12assert shared == ["read_file", "run_tests"]
python tool-descriptions.pyv1 tools: 7
v1 list_files: List the files in the case, by their case-relative paths.
v1 read_file: Read one file in the case, given by its case-relative path.
v1 run_tests: Run the visible test suite on your copy and return the counts of passed and failed tests.
v1 write_file: Create a new file in your copy with this text; it is refused when the file already exists.
v1 edit_file: Replace the one occurrence of old text with new text in a file in your copy.
v1 ask_user: Ask the person a question and end the run; use it when the task needs their decision.
v1 finish: End the run with a summary of what you changed and why.
ch1 tools with the same sentence in v1: read_file, run_tests
ch1 finish has the same sentence in v1: False
O conjunto de ferramentas v1 tem 7 ferramentas, cada uma com uma frase. A impressão confirma que as ferramentas do capítulo 1 mantêm suas frases neste conjunto, e mantêm para read_file, run_tests. A ferramenta finish é a que mudou, porque a sua função mudou. Uma frase diz para que serve uma ferramenta. Ela não pode carregar uma regra que o harness não verifica.
Regra prática: Escreva cada limite, tipo e padrão no modelo de argumentos, onde o harness os verifica, e dê a cada campo uma descrição que o modelo possa ler. Mantenha a frase da ferramenta restrita ao propósito da ferramenta. Uma regra que vive apenas na frase é uma dica que o harness nunca vai aplicar.
Lax por padrão, strict de propósito
Um modelo que recebe o pedido de um número pode escrever "50", e uma flag pode chegar como true. O harness precisa decidir se aceita esses valores como foram pretendidos, e o pydantic responde conforme o modo. No modo padrão, o modo lax, um valor é convertido quando a conversão é clara e recusado quando não é. No modo strict, o valor precisa já ter o tipo declarado. Os modelos de argumentos do conjunto de ferramentas v1 usam o padrão, e as cópias do conjunto v2 são strict.
O schema é uma dica, não uma garantia. O guia de chamada de funções da OpenAI descreve uma configuração também chamada strict, que restringe o que o modelo gera: com ela ativada, as chamadas seguem o schema de forma confiável, e sem ela são feitas da melhor forma possível. O modo strict do pydantic é um mecanismo diferente. Ele verifica uma chamada depois que ela chega e não restringe a geração. Este harness não restringe o que o modelo escreve enquanto escreve, então toda chamada é verificada depois que chega, qualquer que seja o schema.
Um modelo que escreve "50" como limite de linhas provavelmente quer dizer cinquenta, então recusá-lo de imediato desperdiçaria uma etapa numa chamada quase correta. Um modelo que envia true para o mesmo campo quis dizer outra coisa por completo, e convertê-lo em número esconderia isso. Nenhuma das respostas está certa para todo campo, então o modo precisa ser escolhido para cada modelo de argumentos que contém esses campos. Este capítulo define o modo em cada modelo e não em cada campo.
O próximo exemplo envia os mesmos valores pelos dois modos. Compare o que cada modo faz com cada valor.
1"""Pydantic's default (lax) mode and strict mode, given the same values for an int field: lax takes the string "50"2and the bool True as ints, strict refuses both, and each refusal names its error type. The point of the prose rests3on the last lines: on a string field the two modes refuse the same values, and the two tool sets' schemas differ4only in their titles."""5from lib.tools import LinesArgs, PathArg, StrictLinesArgs, StrictPathArg, V1, V26from pydantic import ValidationError78values = [("str 50", "50"), ("int 50", 50), ("bool True", True), ("float 2.0", 2.0), ("float 2.5", 2.5)]9outcomes = {}10for label, value in values:11 for mode, model in (("lax", LinesArgs), ("strict", StrictLinesArgs)):12 try:13 model.model_validate({"path": "unitcraft/format.py", "max_lines": value})14 outcomes[mode, label] = "accepted"15 except ValidationError as exc:16 outcomes[mode, label] = exc.errors()[0]["type"] # the first error's type, which a refusal names17 print(f"{mode}, max_lines {label}: {outcomes[mode, label]}")18assert outcomes["lax", "str 50"] == "accepted" and outcomes["strict", "str 50"] == "int_type"1920# The case's tools take only strings. On a string field the modes agree, because lax mode does not turn a number,21# a flag or nothing into a string.22for label, value in [("str a.py", "a.py"), ("int 3", 3), ("float 3.5", 3.5), ("bool True", True), ("None", None),23 ("list", []), ("object", {})]:24 results = {}25 for mode, model in (("lax", PathArg), ("strict", StrictPathArg)):26 try:27 model.model_validate({"path": value})28 results[mode] = "accepted"29 except ValidationError as exc:30 results[mode] = exc.errors()[0]["type"] # the first error's type, which a refusal names31 print(f"{mode}, path {label}: {results[mode]}")32 assert results["lax"] == results["strict"]333435def untitled(node):36 """A schema with its titles removed, so the two tool sets can be compared on everything else."""37 if isinstance(node, dict):38 return {key: untitled(value) for key, value in node.items() if key != "title"}39 if isinstance(node, list):40 return [untitled(item) for item in node]41 return node424344same = [untitled(a.schema()) == untitled(b.schema()) for a, b in zip(V1.tools, V2.tools)]45print("v1 and v2 schemas differ before titles are removed:", any(a.schema() != b.schema() for a, b in zip(V1.tools, V2.tools)))46print("v1 and v2 schemas equal once titles are removed:", all(same))47assert all(same)
python lax-and-strict.pylax, max_lines str 50: accepted
strict, max_lines str 50: int_type
lax, max_lines int 50: accepted
strict, max_lines int 50: accepted
lax, max_lines bool True: accepted
strict, max_lines bool True: int_type
lax, max_lines float 2.0: accepted
strict, max_lines float 2.0: int_type
lax, max_lines float 2.5: int_from_float
strict, max_lines float 2.5: int_type
lax, path str a.py: accepted
strict, path str a.py: accepted
lax, path int 3: string_type
strict, path int 3: string_type
lax, path float 3.5: string_type
strict, path float 3.5: string_type
lax, path bool True: string_type
strict, path bool True: string_type
lax, path None: string_type
strict, path None: string_type
lax, path list: string_type
strict, path list: string_type
lax, path object: string_type
strict, path object: string_type
v1 and v2 schemas differ before titles are removed: True
v1 and v2 schemas equal once titles are removed: True
O que o modo strict muda são as conversões, e nada mais do que o exemplo mostra. Um valor do tipo declarado passa nos dois modos. A string "50" é aceita no modo lax e recusada no modo strict, com int_type. Uma flag é tratada da mesma forma: True é aceito no modo lax, e o modo strict o recusa com int_type. O modo lax também aceita 2.0 para um int, porque nada se perde na conversão. Ele recusa 2.5, porque a parte fracionária seria perdida, e a recusa diz int_from_float.
As cópias do conjunto de ferramentas v2 são escritas como subclasses das classes do conjunto v1. Cada uma mantém todos os campos de sua classe-mãe e altera apenas o modo, então o conjunto v1 mantém as classes que tinha e imprime o que imprimia antes. Acrescentar uma configuração ao lado da antiga, em vez de no lugar dela, permite que um conjunto de ferramentas mude sem mudar o que uma execução anterior imprimiu. O modo não aparece no schema que o modelo lê. O exemplo mostra que os schemas dos dois conjuntos diferem apenas no título de cada classe: StrictPathArg onde o conjunto v1 tem PathArg. O nome da classe é a única coisa do modo strict que um modelo poderia ver.
O modo strict não é gratuito. Ele transforma uma chamada utilizável em uma recusa, e o modelo então precisa tentar de novo. O que ele proporciona é que uma contagem recebida pela ferramenta seja uma contagem, e que uma flag nunca seja lida como número por acaso. Se essa troca vale a pena depende do campo, e nas ferramentas do caso ela não muda nada. Todo argumento das ferramentas do caso é uma string. Em um campo string, lax e strict recusam os mesmos valores. As últimas linhas da impressão tentam uma string, um número, um float, uma flag, nada, uma lista e um objeto, e o número, por exemplo, é recusado nos dois modos com string_type. Assim, a configuração strict do conjunto de ferramentas v2 não muda nenhuma recusa que uma chamada JSON possa causar nessas ferramentas. Ela protege um campo que uma ferramenta posterior possa adicionar como número. Só a leitura limitada converte, e nenhuma ferramenta a usa.
Regra prática: Use o modo lax quando a conversão é o que o modelo quis dizer, e o modo strict quando uma conversão silenciosa mudaria o que a ferramenta faz. Teste cada modelo com um valor do tipo errado antes de confiar nele, e leia o tipo de erro que a recusa indica, pois é isso que o modelo vai ver.
Erros que o modelo consegue ler
A recusa só ajuda quando o modelo consegue ler o que estava errado na sua chamada. Uma execução que para na primeira chamada ruim não ensina nada ao modelo, e um harness que descarta uma chamada ruim em silêncio deixa o modelo adivinhando o próximo passo. Por isso, cada recusa volta como o texto de um resultado de ferramenta, do mesmo tipo que qualquer outro resultado, o qual o modelo lê no passo seguinte.
Chamadas ruins falham em pontos diferentes, e o harness precisa verificá-las na ordem. Uma recusa que chega durante um passo é mais um resultado de ferramenta na transcrição. A execução continua, a próxima resposta do modelo pode reagir a ela, e o limite de passos ainda se aplica. Assim, uma chamada ruim custa ao modelo um passo, e a recusa decide se esse passo foi bem aproveitado.
Cada uma das chamadas ruins deste exemplo está errada de um jeito diferente. Elas passam pelo conjunto de ferramentas v2 e depois pelo conjunto v1, e a saída impressa mostra o que cada conjunto devolve:
1"""Five bad calls, sent by a ScriptedModel. Each parsed call is run through the v2 tool set and through v1, and each2refusal is the text the model reads on its next step. The point of the prose rests on the v2 lines and the v1 lines3for calls 2 to 5. A call whose JSON is cut off never reaches a schema, so neither set runs it."""4import shutil56from lib.case import scratch_copy7from lib.models import ScriptedModel8from lib.tools import V1, V2, Workspace910CALLS = [11 '<tool_call>{"name": "read_file", "arguments": {"path": "unitcraft/format.py"</tool_call>',12 '<tool_call>{"name": "read_file", "arguments": {}}</tool_call>',13 '<tool_call>{"name": "read_file", "arguments": {"path": "unitcraft/format.py", "lines": 5}}</tool_call>',14 '<tool_call>{"name": "read_file", "arguments": {"path": 3}}</tool_call>',15 '<tool_call>{"name": "read_files", "arguments": {"path": "unitcraft/format.py"}}</tool_call>',16]17scratch = scratch_copy()18ws = Workspace(scratch)19model = ScriptedModel(CALLS)20for number in range(1, len(CALLS) + 1):21 reply = model.reply([], V2.schemas()) # the schemas are sent with each request; a scripted model ignores them22 if reply.malformed: # the reply parser's reason for a call whose JSON it cannot read23 print(f"call {number}, not run, the JSON is not read: {reply.malformed[0]}")24 continue25 call = reply.tool_calls[0]26 print(f"call {number}, {call['name']}, v2: {V2.call(ws, call['name'], call['arguments']).text}")27 print(f"call {number}, {call['name']}, v1: {V1.call(ws, call['name'], call['arguments']).text}")28shutil.rmtree(scratch, ignore_errors=True)
python bad-arguments-handed-back.pycall 1, not run, the JSON is not read: not JSON (Expecting ',' delimiter)
call 2, read_file, v2: error: invalid arguments: path (missing): Field required
call 2, read_file, v1: error: invalid arguments: path: Field required
call 3, read_file, v2: error: invalid arguments: lines (extra_forbidden): Extra inputs are not permitted
call 3, read_file, v1: error: invalid arguments: lines: Extra inputs are not permitted
call 4, read_file, v2: error: invalid arguments: path (string_type): Input should be a valid string
call 4, read_file, v1: error: invalid arguments: path: Input should be a valid string
call 5, read_files, v2: error: invalid arguments: name (literal_error): Input should be 'list_files', 'read_file', 'run_tests', 'write_file', 'edit_file', 'ask_user' or 'finish'
call 5, read_files, v1: error: unknown tool: read_files
A primeira falha acontece antes de qualquer esquema ser consultado. A chamada cujo JSON está cortado nunca chega a uma ferramenta, porque o analisador da resposta não consegue lê-la. O motivo é not JSON, seguido da mensagem do próprio analisador JSON. Essa mensagem vem da biblioteca padrão do Python, não do pydantic, e a chamada não tem campo a nomear, já que seus argumentos nunca foram analisados.
As demais chamadas são analisadas e chegam ao esquema, e cada uma recebe a sua própria recusa. Uma chamada sem argumentos para read_file é recusada por causa de path, com o tipo de erro missing. Uma chave que a ferramenta não aceita, neste caso lines, é recusada como extra_forbidden, mesmo que o restante da chamada esteja correto. Um path passado como número é recusado como string_type. Toda recusa nomeia o campo, o tipo de erro e a mensagem, para que a próxima chamada do modelo possa mudar a única coisa que estava errada. O campo é citado com as palavras do esquema, path, e não com o nome de uma classe Python, porque são essas as palavras com que o modelo está trabalhando.
O conjunto de ferramentas v1 usa os mesmos campos sem o modo estrito, então, para as chamadas 2 a 4, recusa as mesmas chamadas, com os mesmos campos e mensagens, como mostram as linhas da v1 na saída impressa. Seu texto deixa de fora o tipo de erro, e nomear esse tipo é a única adição que o conjunto v2 faz a essas recusas. Compare o path ausente na chamada 2. O conjunto v1 diz error: invalid arguments: path: Field required, e o conjunto v2 diz error: invalid arguments: path (missing): Field required.
Cada uma dessas recusas pede um reparo diferente, e o texto é o que indica ao modelo qual deles fazer. Um campo ausente pede que o campo seja acrescentado. Uma chave extra pede que ela seja removida, e um tipo errado pede que o valor seja escrito do jeito que o esquema determina. Um modelo que recebe apenas "invalid arguments" precisa adivinhar qual dos três deve fazer, e cada palpite custa um passo. Nomear o campo e o tipo de erro transforma o palpite em uma única edição na chamada.
Regra prática: Devolva cada recusa como um resultado de ferramenta que nomeie o campo, o tipo de erro e a mensagem. Nunca encerre a execução por causa de uma chamada ruim, exceto pelas regras de parada do capítulo 2, quando estiverem ativas e a mesma chamada ruim continuar voltando. Uma chamada que o analisador não consegue ler recebe como recusa o motivo do analisador, e nenhuma ferramenta é executada com ela.
Um nome por ferramenta
O nome é a primeira coisa que uma chamada entrega ao harness, e o harness pode verificá-lo antes de ler qualquer argumento. Um modelo que inventa uma ferramenta, ou que a lembra de forma errada, faz uma chamada sem nada por trás, e o harness precisa dizer isso em termos que o modelo consiga usar.
A última chamada do exemplo da seção anterior pede read_files, uma ferramenta que o conjunto não tem, com um path que serviria para read_file. A recusa dela lista os nomes que o conjunto tem, para que a próxima chamada do modelo possa usar um deles. A recusa do conjunto de ferramentas v2 começa com invalid arguments, porque o harness verifica o nome como um campo da chamada, e o campo se chama name. O harness constrói um tipo Literal a partir dos nomes das ferramentas do conjunto e verifica o nome contra ele. Um nome errado falha como literal_error, e a mensagem informa os nomes permitidos. O conjunto de ferramentas v1 dá um texto mais curto para a mesma chamada: error: unknown tool: read_files. Ele diz que a ferramenta é desconhecida, e nada sobre quais ferramentas existem.
O nome fica fora dos parâmetros de cada ferramenta, então nenhum esquema de parâmetros impede um nome errado. A verificação acontece quando o harness procura o nome, e por isso ela pertence ao harness, e não apenas ao prompt.
O harness não adivinha, e essa diferença importa. Um nome parecido com uma ferramenta real, como read_files no lugar de read_file, ainda é recusado, porque o harness despacha por nomes exatos, e um palpite executaria uma ferramenta que o modelo não pediu. A recusa é que ajuda: ela lista o que existe, e o modelo escolhe de novo.
O nome importa mais para a ferramenta de parada. O loop encerra uma execução quando uma chamada a finish ou a ask_user é executada e o resultado traz a sinalização de fim. Uma ferramenta de parada escrita com erro não traz essa sinalização. Ela é recusada como qualquer outro nome desconhecido, e a execução continua até o limite de passos ou até que uma regra de parada a encerre. A mesma verificação de nome exato que recusa read_files é o que faz finish significar finish. Um modelo que continua pedindo uma ferramenta que o conjunto não tem é o tipo de execução para o qual as regras de parada do capítulo 2 existem.
Regra prática: Tire os nomes permitidos das ferramentas que o loop de fato executa, nunca de uma lista mantida ao lado delas, e inclua-os em toda recusa de um nome desconhecido. Um nome que o conjunto não tem recebe uma recusa, e o prompt não a promete. Aceite um apelido somente por meio de um mapa de apelidos explícito, mantido pelo harness, nunca por palpite.
Erros de edição que nomeiam as linhas mais próximas
Uma edição nomeia o texto que substitui. A ferramenta edit_file do conjunto de ferramentas v1 altera o único lugar em que old aparece no arquivo, e recusa a chamada quando old não existe ou aparece mais de uma vez. Por isso, uma edição pode falhar por causa de poucos caracteres citados (aspas). Um modelo que copia código a partir da sua própria leitura de um arquivo pode errar essas aspas, e então a edição é recusada.
A primeira versão da ferramenta de alteração, no capítulo 1, colocava o arquivo inteiro dentro de uma única string JSON, de modo que cada aspa e cada quebra de linha do arquivo precisavam ser escapadas na resposta do modelo. Uma edição é menor. Ela copia apenas as linhas que mudam, de modo que há menos caracteres para errar. O problema do escape, porém, não desaparece, pois a cópia ainda precisa coincidir exatamente com o arquivo.
O registro do conjunto de tarefas mostra a cópia dando errado. Ele guarda as respostas do mesmo modelo aberto, Qwen3-4B-Instruct-2507, ao longo de vinte tarefas, executadas com o conjunto de ferramentas v1, um limite de 16 passos e temperatura 0; o capítulo 1 explica a configuração do modelo. Na terceira resposta da T-01, o modelo copiou algumas linhas para old e deixou de fora as aspas em torno de duas f-strings e a aspa de fechamento de separator = ".". O arquivo tem essas aspas. O texto armazenado de old é mostrado primeiro, e depois essa única resposta é reexecutada pelos dois conjuntos de ferramentas, para que a diferença apareça:
1"""The edit_file call from step 3 of the task-set recording's T-01 run, read from its stored reply. Its old text drops2the quotes around the f-strings and the closing quote of separator = "."; the printed old text shows it. The point of3the prose rests on the two results: the v2 error names the nearest lines of the file, with their quotes, and the v14error only says the text is missing."""5import json6import shutil78from lib.case import DATA, scratch_copy9from lib.models import ScriptedModel10from lib.tools import V1, V2, Workspace1112rows = [json.loads(line) for line in (DATA / "recorded" / "task-set" / "replies.jsonl").read_text().splitlines()]13stored = next(row for row in rows if row["run"] == "T-01" and row["step"] == 3) # steps count from 114call = ScriptedModel([stored["text"]]).reply([], V2.schemas()).tool_calls[0] # the recorded reply, read back15scratch = scratch_copy()16ws = Workspace(scratch)17print("call:", call["name"], call["arguments"]["path"])18print("old text:")19print(call["arguments"]["old"])20print("v1 result:", V1.call(ws, call["name"], call["arguments"]).text)21v2 = V2.call(ws, call["name"], call["arguments"]).text22print("v2 result:")23print(v2)24assert 'text = f"{whole}{separator}{frac}"' in v225shutil.rmtree(scratch, ignore_errors=True)
python edit-error-nearest-lines.pycall: edit_file unitcraft/format.py
old text:
frac = frac.rstrip("0")
separator = ".
text = f{whole}{separator}{frac}
return f{sign}{text} {q.unit}
v1 result: error: old text not found in unitcraft/format.py
v2 result:
error: old text not found in unitcraft/format.py. The nearest lines of the file, numbered as in the file:
18 | frac = frac.rstrip("0")
19 | separator = "."
20 |
21 | text = f"{whole}{separator}{frac}"
22 |
23 | return f"{sign}{text} {q.unit}"
Copy old from those lines exactly, quotes included, and call edit_file again.
O texto do conjunto de ferramentas v1 diz apenas que o texto antigo não está no arquivo, e nomeia o arquivo. O texto do conjunto de ferramentas v2 faz mais. Ele traz as linhas mais próximas do arquivo, numeradas como o arquivo as numera e com suas aspas como estão, e termina dizendo o que fazer em seguida: copiar old dessas linhas, com as aspas, e chamar de novo. A recusa traz uma janela de linhas, e não o arquivo inteiro. Um arquivo inteiro responderia à pergunta do modelo com um custo de muitos tokens, e cada resultado de ferramenta conta contra o mesmo contexto que contém a tarefa, como o capítulo 5 mostra. As linhas são encontradas por semelhança. O harness desliza uma janela do mesmo comprimento de old pelo arquivo, mantém a janela que melhor coincide e, em caso de empate, prefere a janela anterior, de modo que a resposta é a mesma em todas as execuções. Aqui, a melhor janela contém a linha da f-string que o modelo copiava, com suas aspas, e o exemplo verifica que essa linha aparece no erro.
Se o modelo repetir a mesma edição com falha, as regras de parada do capítulo 2 encerram a execução, desde que estejam ativadas. Elas vêm desativadas por padrão, e o registro do conjunto de tarefas não as ativou. As linhas mais próximas servem para tornar essa repetição menos provável. O texto do conjunto de ferramentas v1 deixa ao modelo um segundo passo a gastar: ele precisa chamar read_file para ver as linhas que deveria ter copiado, e a resposta seguinte pode ainda copiá-las de forma errada. O texto do conjunto de ferramentas v2 coloca essas linhas na própria recusa, de modo que o modelo pode tentar de novo imediatamente. A impressão mostra o texto que o harness devolve, e não se a edição seguinte tem sucesso. Isso exige uma execução, e o capítulo 10 conta as execuções. Este capítulo não relata contagem de nenhum dos dois tipos.
Regra prática: Quando o texto de uma edição não está no arquivo, devolva as linhas mais próximas do arquivo com seus números e diga o que fazer em seguida. Não devolva apenas que o texto está ausente, pois isso deixa o modelo adivinhar qual aspa está errada. Um arquivo curto o bastante para ser devolvido inteiro pode ser devolvido inteiro, numerado, no lugar delas.
Decisões deste capítulo
Os esquemas e os textos de erro fazem parte da entrada do modelo. Alterar uma frase, um campo ou um texto de erro altera a requisição, e as reexecuções deste livro comparam cada requisição com a gravada e se recusam a responder quando elas diferem. Por isso, um conjunto de ferramentas muda sempre junto com a sua gravação, e nunca no lugar.
As promessas deste capítulo se mantêm adiante. Adaptadores de modelo usa estes mesmos esquemas em todos os adaptadores. Orçamentos de contexto conta cada recusa como um resultado de ferramenta, como qualquer outro. Testando o agente compara duas versões do harness por meio de contagens. Os conjuntos de ferramentas delas são estes dois; a versão no conjunto de ferramentas v2 também acrescenta as outras mudanças que o capítulo 10 lista.
As decisões são estas:
- Todo modelo de argumentos no conjunto de ferramentas proíbe chaves que ele não declara, de modo que uma chave inventada é recusada e não ignorada.
- Os modelos de argumentos do conjunto de ferramentas v1 mantêm o padrão permissivo (lax) do pydantic, já que as execuções gravadas do conjunto de tarefas o utilizaram. As cópias do conjunto de ferramentas v2 são estritas. Nas ferramentas do caso, elas recusam os mesmos valores JSON que as cópias permissivas recusam, de modo que a estrita não altera nenhuma recusa ali.
- As ferramentas do caso não têm nenhum campo que não seja uma string. A leitura limitada é o único lugar em que o modo aparece, e nenhuma ferramenta o utiliza.
- Uma recusa nomeia o campo, o tipo de erro e a sua mensagem. O conjunto de ferramentas v1 omite o tipo de erro.
- Os nomes de ferramentas permitidos vêm das ferramentas que o loop executa, e um nome desconhecido é recusado com eles.
- No conjunto de ferramentas v1,
finishcarrega um resumo, e as alterações são feitas comedit_fileewrite_filena cópia. - Uma edição cujo texto está ausente retorna as linhas mais próximas do arquivo, numeradas. Essa é uma mudança do conjunto de ferramentas v2.
- Os textos de erro discutidos neste capítulo são impressos pelos seus exemplos, de modo que uma alteração em um deles aparece na impressão antes de aparecer em uma execução. As outras recusas no código das ferramentas, como um caminho fora do caso, não são impressas aqui.
Este capítulo, nesta edição
Edição 2026.11.2Exemplos aprovados em 20 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.2.