Dale a un modelo herramientas que no pueda usar mal
Unos 20 minutos de lectura, con 5 ejemplos en 6 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.2. Lee el original
Al terminar este capítulo podrás dar a un modelo herramientas cuyos argumentos el arnés verifica antes de ejecutar cualquier herramienta, y escribir rechazos sobre los que el modelo pueda actuar.
La tarea del agente es corregir unitcraft, una pequeña biblioteca de Python que formatea y convierte cantidades. Sus ediciones son donde se ve el problema de este capítulo, ya que basta con que falte una comilla para que una edición falle. El agente trabaja sobre una copia de prueba de la biblioteca. En el capítulo 1, su primera ejecución grabada se rompió en una sola llamada. El modelo abierto, Qwen3-4B reproducido desde su grabación, leyó el archivo correcto, interpretó mal el problema como si pidiera eliminar los ceros y luego escribió cada cambio como un archivo completo, entre triples comillas de Python, dentro del JSON de una llamada a finish. Las triples comillas no son válidas dentro de una cadena JSON, así que esos argumentos nunca se analizaron. Ninguna herramienta se ejecutó y la ejecución terminó al llegar a su límite de pasos.
Este capítulo compara dos conjuntos de herramientas. El conjunto de herramientas v1 son las siete herramientas con las que se hizo la grabación del conjunto de tareas: list_files, read_file, run_tests, write_file, edit_file, ask_user y finish. El conjunto de herramientas v2 tiene las mismas herramientas, con las mismas frases y el mismo mensaje de sistema, y tres cambios: modelos de argumentos estrictos, el tipo de error nombrado en cada rechazo y errores con la línea más cercana para una edición fallida.
El error de interpretación es del propio modelo, y ningún diseño de herramientas lo corrige. Las llamadas mal formadas tienen dos partes. La llamada tenía una forma que el arnés no podía leer, y el cambio viajaba dentro de una cadena que el modelo tenía que escapar correctamente. Este capítulo trata ambas cosas. A cada herramienta se le asigna un esquema de argumentos que el arnés comprueba antes de ejecutarla, y un rechazo vuelve al modelo como texto con el que puede actuar. En el conjunto de herramientas v1 el cambio también deja finish: el modelo edita su copia con edit_file y write_file, y finish lleva solo un resumen. Las ediciones pequeñas traen sus propios problemas de comillas, que la última sección aborda.
Un esquema dice lo que está permitido
Un modelo escribe una llamada a una herramienta a partir de lo que se le ha dicho sobre la herramienta, y el arnés solo puede rechazar una llamada incorrecta comprobándola con esa misma descripción. Cada herramienta del conjunto tiene tres partes: un nombre, una frase de descripción y un modelo de argumentos, una pequeña clase de pydantic que enumera los campos que recibe la herramienta. El arnés envía el esquema de cada herramienta junto con la solicitud, y el esquema se construye a partir de esa clase, de modo que el texto que lee el modelo y la comprobación que ejecuta el arnés proceden de un mismo lugar.
Ese lugar único importa porque un esquema contiene más que nombres de campos. Piensa en él como el formulario que el modelo rellena antes de hacer una llamada. Cada línea del formulario nombra un campo, indica qué tipo de respuesta se espera y puede indicar cuán grande puede ser una respuesta. Un formulario puede orientar a quien lo rellena, pero no puede impedir que se escriba una respuesta incorrecta. Ahí es donde el formulario deja de ser útil como protección, y el arnés tiene que hacer la comprobación que el formulario no puede hacer.
Pydantic escribe en el esquema el tipo de cada campo, su descripción, su valor por defecto y sus límites. Las herramientas del caso solo reciben rutas y cadenas, así que esta sección usa una lectura distinta, con un límite de líneas que ninguna herramienta del conjunto utiliza. Es un modelo didáctico, elegido para mostrar cómo es un límite. Imprimir su esquema es la forma más rápida de ver lo que se le dice al modelo, y las líneas que hay que leer son los límites y el valor por defecto.
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.
Lee la salida como la lee el modelo. El único argumento obligatorio es path. max_lines toma valores desde 1 hasta 1000.
Su valor por defecto es la otra mitad del campo. Cuando el modelo omite max_lines, el valor es 200. Esos límites están en el esquema que lee el modelo, no solo en el código que los comprueba, y la descripción del propio campo lo dice con palabras: "The most lines to return, from 1 to 1000; the default is 200."
Un valor por defecto en un esquema es una nota, no una regla. La especificación de validación de JSON Schema trata default como una anotación: proporciona un valor y no comprueba nada. Si un arnés rellena el valor por defecto es decisión del arnés, y el esquema por sí solo no hace que eso ocurra.
La otra mitad de lo que lee el modelo es la frase de cada herramienta. Esas frases acompañan a sus esquemas en cada solicitud, así que el ejemplo siguiente las imprime. Conviene comprobar dos líneas: la que indica qué herramientas del capítulo 1 comparten frase con este conjunto, y la que indica que finish no lo hace.
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
El conjunto de herramientas v1 tiene 7 herramientas, cada una con una frase. La impresión confirma que las herramientas del capítulo 1 conservan sus frases en este conjunto, y así es para read_file, run_tests. Su finish es la que cambió, porque cambió su función. Una frase dice para qué sirve una herramienta. No puede transportar una regla que el arnés no comprueba.
Regla práctica: Escribe cada límite, tipo y valor por defecto en el modelo de argumentos, donde el arnés los comprueba, y da a cada campo una descripción que el modelo pueda leer. Limita la frase de la herramienta a para qué sirve la herramienta. Una regla que vive solo en la frase es una pista que el arnés nunca hará cumplir.
Lax por defecto, estricto a propósito
Un modelo al que se le pide un número puede escribir "50", y una marca puede llegar como true. El harness tiene que decidir si toma esos valores tal como se pretendían, y pydantic responde según el modo. En su modo por defecto, el modo lax, un valor se convierte cuando la conversión es clara y se rechaza cuando no lo es. En el modo estricto, un valor debe tener ya el tipo declarado. Los modelos de argumentos del conjunto de herramientas v1 usan el modo por defecto, y las copias del conjunto v2 son estrictas.
El esquema es una pista, no una garantía. La guía de llamadas a funciones de OpenAI describe un ajuste llamado strict, que restringe lo que el modelo genera: con él activado, las llamadas siguen el esquema de forma fiable, y sin él son un mejor esfuerzo. El modo estricto de pydantic es un mecanismo distinto. Comprueba una llamada después de que llega y no restringe la generación. Este harness no restringe lo que el modelo escribe mientras lo escribe, así que cada llamada se comprueba después de llegar, independientemente de lo que dijera el esquema.
Un modelo que escribe "50" para un límite de líneas probablemente quiere decir cincuenta, así que rechazarlo sin más desperdiciaría un paso en una llamada casi correcta. Un modelo que envía true para el mismo campo ha querido decir algo completamente distinto, y convertirlo a número ocultaría eso. Ninguna de las dos respuestas es la correcta para todos los campos, así que el modo debe elegirse para cada modelo de argumentos que contenga esos campos. Este capítulo lo establece en cada modelo y no en cada campo.
El siguiente ejemplo envía los mismos valores por ambos modos. Compara lo que hace cada modo con 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
Lo que cambia el modo estricto son las conversiones, y nada más de lo que muestra el ejemplo. Un valor del tipo declarado pasa en ambos modos. La cadena "50" se acepta en modo lax y se rechaza en modo estricto, con int_type. Una marca se trata de la misma manera: True se acepta en modo lax, y el modo estricto la rechaza con int_type. El modo lax también acepta 2.0 para un int, porque en la conversión no se pierde nada. Rechaza 2.5, porque se perdería la parte fraccionaria, y su rechazo dice int_from_float.
Las copias del conjunto de herramientas v2 están escritas como subclases de las clases del conjunto v1. Cada una conserva todos los campos de su padre y solo cambia el modo, de modo que el conjunto v1 mantiene las clases que tenía e imprime lo que imprimía antes. Añadir un ajuste junto al antiguo, en lugar de sustituirlo, permite que un conjunto de herramientas cambie sin cambiar lo que imprimió una ejecución anterior. El modo no aparece en el esquema que lee el modelo. El ejemplo muestra que los esquemas de los dos conjuntos difieren solo en el título de cada clase, StrictPathArg donde el conjunto v1 tiene PathArg. El nombre de la clase es lo único que un modelo podría ver del modo estricto.
El modo estricto no es gratuito. Convierte una llamada utilizable en un rechazo, y el modelo tiene entonces que intentarlo de nuevo. Lo que aporta es que un recuento que recibe la herramienta es un recuento, y que una marca nunca se lee como un número por accidente. Si ese intercambio merece la pena depende del campo, y en las herramientas del caso no cambia nada. Cada argumento de las herramientas del caso es una cadena. En un campo de cadena, lax y estricto rechazan los mismos valores. Las últimas líneas de la salida prueban una cadena, un número, un float, una marca, nada, una lista y un objeto, y el número, por ejemplo, se rechaza en ambos modos con string_type. Así que el ajuste estricto del conjunto v2 no cambia ningún rechazo que una llamada JSON pueda provocar en estas herramientas. Protege un campo que una herramienta posterior podría añadir como número. Solo la lectura acotada convierte, y ninguna herramienta la usa.
Regla práctica: Usa el modo lax cuando una conversión es lo que quiso el modelo, y el modo estricto cuando una conversión silenciosa cambiaría lo que hace la herramienta. Prueba cada modelo con un valor del tipo equivocado antes de confiar en él, y lee el tipo de error que nombra el rechazo, porque eso es lo que verá el modelo.
Errores que el modelo puede leer
Una negativa solo ayuda cuando el modelo puede leer qué estuvo mal en su llamada. Una ejecución que se detiene en la primera llamada incorrecta no le enseña nada al modelo, y un arnés que descarta en silencio una llamada incorrecta deja al modelo adivinando su siguiente paso. Por eso cada negativa vuelve como el texto de un resultado de herramienta, del mismo tipo que cualquier otro resultado, que el modelo lee en su siguiente paso.
Las llamadas incorrectas fallan en puntos distintos, y el arnés tiene que comprobarlas en orden. Una negativa que llega durante un paso es un resultado de herramienta más en la transcripción. La ejecución sigue, la siguiente respuesta del modelo puede reaccionar a ella y el límite de pasos sigue vigente. Así, una llamada incorrecta le cuesta al modelo un paso, y la negativa decide si ese paso se aprovechó bien.
Cada una de las llamadas incorrectas de este ejemplo está mal de una forma distinta. Pasan primero por el conjunto de herramientas v2 y luego por el v1, y la salida muestra lo que devuelve cada conjunto:
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
El primer fallo ocurre antes de consultar ningún esquema. La llamada cuyo JSON está cortado nunca llega a una herramienta, porque el analizador de respuestas no puede leerla. Su motivo es not JSON, seguido del propio mensaje del analizador de JSON. Ese mensaje procede de la biblioteca estándar de Python, no de pydantic, y la llamada no tiene ningún campo que nombrar, ya que sus argumentos nunca llegaron a analizarse.
Las demás llamadas sí se analizan y llegan al esquema, y cada una recibe su propia negativa. Una llamada sin argumentos para read_file se rechaza por path, con el tipo de error missing. Una clave que la herramienta no admite, en este caso lines, se rechaza como extra_forbidden, aunque el resto de la llamada esté bien. Un path indicado como número se rechaza como string_type. Cada negativa nombra el campo, el tipo de error y el mensaje, de modo que la siguiente llamada del modelo pueda cambiar justo lo que estaba mal. El campo se nombra con las palabras del esquema, path, y no con el nombre de una clase de Python, porque esas son las palabras con las que trabaja el modelo.
El conjunto de herramientas v1 usa los mismos campos sin modo estricto, así que para las llamadas 2 a 4 rechaza las mismas llamadas, con los mismos campos y mensajes, como muestran las líneas de v1 en la salida. Su texto omite el tipo de error, y nombrar ese tipo es el único añadido que hace el conjunto de herramientas v2 a estas negativas. Compara el path que falta en la llamada 2. El conjunto v1 dice error: invalid arguments: path: Field required, y el conjunto v2 dice error: invalid arguments: path (missing): Field required.
Cada una de estas negativas pide una reparación distinta, y el texto es lo que le indica al modelo cuál. Un campo que falta pide añadir el campo. Una clave extra pide quitarla, y un tipo incorrecto pide escribir el valor como indica el esquema. Un modelo que solo recibe "argumentos no válidos" tiene que adivinar cuál de las tres debe corregir, y una suposición gasta un paso. Nombrar el campo y el tipo de error convierte la suposición en una sola edición de la llamada.
Regla práctica: Devuelve cada negativa como un resultado de herramienta que nombre el campo, el tipo de error y el mensaje. Nunca termines la ejecución por una llamada incorrecta, salvo mediante las reglas de parada del capítulo 2, cuando estén activas y la misma llamada incorrecta siga volviendo. Una llamada que el analizador no puede leer recibe como negativa el motivo del analizador, y ninguna herramienta se ejecuta con ella.
Un nombre por herramienta
El nombre es lo primero que una llamada entrega al arnés, y el arnés puede comprobarlo antes de leer cualquier argumento. Un modelo que inventa una herramienta, o que la recuerda mal, hace una llamada sin nada detrás, y el arnés tiene que decírselo en términos que el modelo pueda usar.
La última llamada del ejemplo de la sección anterior pide read_files, una herramienta que el conjunto no tiene, con un path que encajaría con read_file. Su rechazo enumera los nombres que el conjunto sí tiene, para que la siguiente llamada del modelo pueda usar uno de ellos. El rechazo del conjunto de herramientas v2 empieza por invalid arguments, porque el arnés comprueba el nombre como un campo de la llamada, y el campo se llama name. El arnés construye un tipo Literal a partir de los nombres de las herramientas del conjunto y compara el nombre con él. Un nombre incorrecto falla como literal_error, y el mensaje indica los nombres permitidos. El conjunto de herramientas v1 da un texto más corto para la misma llamada: error: unknown tool: read_files. Dice que la herramienta es desconocida, y nada sobre cuáles sí lo son.
El nombre está fuera de los parámetros de cada herramienta, así que ningún esquema de parámetros impide un nombre incorrecto. La comprobación ocurre cuando el arnés busca el nombre, por eso debe estar en el arnés y no solo en el prompt.
El arnés no adivina, y esa diferencia importa. Un nombre parecido a una herramienta real, como read_files en lugar de read_file, sigue siendo rechazado, porque el arnés despacha por nombres exactos y una suposición ejecutaría una herramienta que el modelo no pidió. El rechazo es lo que ayuda: enumera lo que existe, y el modelo vuelve a elegir.
El nombre importa sobre todo para la herramienta de parada. El bucle termina una ejecución cuando se ejecuta una llamada a finish o a ask_user y su resultado lleva la marca de fin. Una herramienta de parada mal escrita no lleva esa marca. Se rechaza como cualquier otro nombre desconocido, y la ejecución continúa hasta el límite de pasos o hasta que una regla de parada la termine. La misma comprobación de nombre exacto que rechaza read_files es la que hace que finish signifique finish. Un modelo que sigue pidiendo una herramienta que el conjunto no tiene es el tipo de ejecución para el que existen las reglas de parada del capítulo 2.
Regla práctica: Toma los nombres permitidos de las herramientas que el bucle realmente ejecuta, nunca de una lista guardada aparte, e inclúyelos en cada rechazo de un nombre desconocido. Un nombre que el conjunto no tiene recibe un rechazo, y el prompt no lo promete. Acepta un alias solo mediante un mapa de alias explícito que mantenga el arnés, nunca por suposición.
Mensajes de error de edición que señalan las líneas más cercanas
Una edición nombra el texto que reemplaza. La herramienta edit_file del conjunto de herramientas v1 cambia el único lugar donde aparece old en el archivo, y rechaza la llamada cuando old falta o aparece más de una vez. Por eso una edición puede fallar por unos pocos caracteres entre comillas. Un modelo que copia código a partir de su propia lectura de un archivo puede equivocarse en esas comillas, y entonces la edición se rechaza.
La primera versión del cambio, en el capítulo 1, metía el archivo entero dentro de una cadena JSON, así que cada comilla y cada salto de línea del archivo tenían que escaparse en la respuesta del modelo. Una edición es más pequeña. Copia solo las líneas que cambian, de modo que hay menos caracteres en los que equivocarse. Sin embargo, el problema del escape no desaparece, porque la copia aún tiene que coincidir exactamente con el archivo.
El registro del conjunto de tareas muestra cómo la copia sale mal. Recoge las respuestas del mismo modelo abierto, Qwen3-4B-Instruct-2507, a lo largo de veinte tareas, ejecutadas con el conjunto de herramientas v1, un límite de pasos de 16 y temperatura 0; el capítulo 1 explica la configuración del modelo. En la tercera respuesta de T-01, el modelo copió unas líneas en old y omitió las comillas de dos f-strings y la comilla de cierre de separator = ".". El archivo tiene esas comillas. El texto guardado de old se muestra primero, y después esa respuesta se reproduce con ambos conjuntos de herramientas, para que se vea la diferencia:
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.
El texto del conjunto v1 solo dice que el texto antiguo no está en el archivo, y nombra el archivo. El texto del conjunto v2 hace más. Da las líneas del archivo más cercanas, numeradas como las numera el archivo y con sus comillas tal como están, y termina diciendo qué hacer a continuación: copiar old de esas líneas, con las comillas incluidas, y volver a llamar. El rechazo lleva una ventana de líneas y no el archivo entero. Un archivo entero respondería a la pregunta del modelo a costa de muchos tokens, y cada resultado de herramienta cuenta contra el mismo contexto que contiene la tarea, como lo explica el capítulo 5. Las líneas se buscan por similitud. El arnés desliza por el archivo una ventana de la misma longitud que old, conserva la ventana que mejor coincide y, en caso de empate, se queda con la ventana anterior, de modo que la respuesta es la misma en cada ejecución. Aquí la mejor ventana contiene la línea del f-string que el modelo estaba copiando, con sus comillas, y el ejemplo afirma que esa línea aparece en el error.
Si el modelo repite la misma edición fallida, las reglas de parada del capítulo 2 terminan la ejecución, siempre que estén activadas. Están desactivadas por defecto, y el registro del conjunto de tareas no las activó. Las líneas más cercanas pretenden hacer menos probable esa repetición. El texto del conjunto v1 deja al modelo un segundo paso por gastar: tiene que llamar a read_file para ver las líneas que debería haber copiado, y la siguiente respuesta todavía puede copiarlas mal. El texto del conjunto de herramientas v2 pone esas líneas en el propio rechazo, para que el modelo pueda intentarlo de inmediato. La impresión muestra el texto que devuelve el arnés, no si la siguiente edición tiene éxito. Eso requiere una ejecución, y el capítulo 10 cuenta las ejecuciones. Este capítulo no informa de ningún recuento de ninguno de los dos tipos.
Regla práctica: Cuando el texto de una edición no está en el archivo, devuelve las líneas del archivo más cercanas con sus números, e indica qué hacer a continuación. No devuelvas solo que el texto falta, ya que eso deja al modelo adivinar qué comilla está mal. Un archivo lo bastante corto para devolverlo entero puede devolverse entero, numerado, en su lugar.
Decisiones en este capítulo
Los esquemas y los textos de error forman parte de la entrada del modelo. Cambiar una oración, un campo o un texto de error cambia la solicitud, y las repeticiones de este libro comparan cada solicitud con la grabada y se niegan a responder cuando difieren. Por eso un conjunto de herramientas cambia junto con su grabación, y nunca en su lugar.
Las promesas de este capítulo se mantienen. Adaptadores de modelo usa estos mismos esquemas para cada adaptador. Presupuestos de contexto cuenta cada rechazo como un resultado de herramienta, igual que cualquier otro. Probar el agente compara dos versiones del arnés mediante recuentos. Sus conjuntos de herramientas son estos dos; la versión con el conjunto de herramientas v2 añade además los otros cambios que enumera el capítulo 10.
Las decisiones son estas:
- Cada modelo de argumentos del conjunto de herramientas prohíbe las claves que no declara, de modo que una clave inventada se rechaza y no se ignora.
- Los modelos de argumentos del conjunto de herramientas v1 mantienen el valor predeterminado permisivo de pydantic, ya que las ejecuciones grabadas del conjunto de tareas lo usaron. Las copias del conjunto de herramientas v2 son estrictas. En las herramientas del caso rechazan los mismos valores JSON que las copias permisivas, de modo que la estrictez no cambia ningún rechazo allí.
- Las herramientas del caso no tienen ningún campo que no sea una cadena. La lectura acotada es el único lugar donde se muestra el modo, y ninguna herramienta lo usa.
- Un rechazo indica el campo, su tipo de error y su mensaje. El conjunto de herramientas v1 omite el tipo de error.
- Los nombres de herramienta permitidos provienen de las herramientas que ejecuta el bucle, y un nombre desconocido se rechaza mostrándolos.
- En el conjunto de herramientas v1,
finishlleva un resumen, y los cambios se hacen conedit_fileywrite_fileen la copia. - Una edición cuyo texto falta devuelve las líneas más cercanas del archivo, numeradas. Ese es un cambio del conjunto de herramientas v2.
- Los textos de error que trata este capítulo los imprimen sus ejemplos, así que un cambio en uno aparece en la impresión antes que en una ejecución. Los demás rechazos del código de herramientas, como una ruta fuera del caso, no se imprimen aquí.
Este capítulo, en esta edición
Edición 2026.11.2Ejemplos verificados el 20 de nov de 2026Superan la prueba 5 de 5 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.2.