Un chef, no una receta

↗ Fuente: Anthropic · building-effective-agents

La tarjeta de la herramienta

{
  "name": "read_file",
  "description": "Read a range of lines from one text file. Lines come back numbered as 'N| text' so you can cite them as path:N. At most 400 lines per call: read big files in ranges.",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {"type": "string", "description": "File path relative to the repo root, e.g. 'src/app.py'."},
      "start_line": {"type": "integer", "description": "First line to read, 1-based. Default 1."},
      "end_line": {"type": "integer", "description": "Last line to read, inclusive. Default start_line + 399."}
    },
    "required": ["path"],
    "additionalProperties": false
  }
}

Los valores de stop_reason

• tool_use
  Qué significa: Claude llama una o más herramientas
  Qué hace tu bucle: Las ejecuta, devuelve todos los resultados y llama otra vez
• end_turn
  Qué significa: Claude terminó su respuesta
  Qué hace tu bucle: Devuelve el texto; el bucle termina
• max_tokens
  Qué significa: La respuesta llegó a tu max_tokens
  Qué hace tu bucle: Para; un tool_use cortado se reintenta con más max_tokens
• pause_turn
  Qué significa: Un bucle de herramientas del servidor llegó a su límite
  Qué hace tu bucle: Reenvía la respuesta tal cual para seguir
• refusal
  Qué significa: Claude se negó
  Qué hace tu bucle: Para y lo reporta
• stop_sequence
  Qué significa: Apareció una de tus secuencias de parada
  Qué hace tu bucle: Lo que tu app defina
• model_context_window_exceeded
  Qué significa: El mostrador se llenó
  Qué hace tu bucle: Para; compactá o empezá más acotado

"model": "claude-opus-5-5",
"max_tokens": 16000,
"system": "You are a read-only sous-chef for a code repository. ...",
"tools": [ /* the list_files, read_file and search cards */ ],

  "messages": [

  ]

{
  "id": "msg_01Aq9w938a90dw8q",
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {"type": "thinking", "thinking": "...", "signature": "..."},
    {"type": "text", "text": "I'll search for the loader and open the likely file."},
    {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "search", "input": {"pattern": "def load_config"}},
    {"type": "tool_use", "id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "name": "read_file", "input": {"path": "config.py"}}
  ]
}

{
  "role": "assistant",
  "stop_reason": "end_turn",
  "content": [
    {"type": "text", "text": "The config is loaded by load_config(), defined at src/config.py:3."}
  ]
}

// 1. Request: your code -> API
{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "system": "You are a read-only sous-chef for a code repository. ...",
  "tools": [ /* the list_files, read_file and search cards */ ],
  "messages": [
    {"role": "user", "content": "Where is the config loaded?"}
  ]
}

// 2. Response: API -> your code. Two calls in one turn (parallel).
{
  "id": "msg_01Aq9w938a90dw8q",
  "role": "assistant",
  "stop_reason": "tool_use",
  "content": [
    {"type": "thinking", "thinking": "...", "signature": "..."},
    {"type": "text", "text": "I'll search for the loader and open the likely file."},
    {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lq9", "name": "search", "input": {"pattern": "def load_config"}},
    {"type": "tool_use", "id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "name": "read_file", "input": {"path": "config.py"}}
  ]
}

// 3. Request: the same history + that assistant turn, unchanged + ONE user message with both results
"messages": [
  {"role": "user", "content": "Where is the config loaded?"},
  {"role": "assistant", "content": [ /* the four blocks above, unchanged */ ]},
  {"role": "user", "content": [
    {"type": "tool_result", "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
     "content": "src/config.py:3: def load_config():"},
    {"type": "tool_result", "tool_use_id": "toolu_01B7xk2mJ3pZ8wQ4vN6rT1sY", "is_error": true,
     "content": "'config.py' does not exist. Call list_files on its parent folder, or search for its name."}
  ]}
]

// 4. Response: stop_reason "end_turn". The loop returns the text.
{
  "role": "assistant",
  "stop_reason": "end_turn",
  "content": [
    {"type": "text", "text": "The config is loaded by load_config(), defined at src/config.py:3."}
  ]
}

• Un resultado por llamada, todos en un mensaje «return one tool_result for each tool_use block, all together in the next user message». Repartirlos en varios mensajes le «"teaches" Claude to avoid parallel calls» (le enseña a Claude a dejar de llamar en paralelo).
• Primero los resultados En ese mensaje user «the tool_result blocks must come FIRST»; cualquier texto va después.
• Devolvé el turno del asistente sin cambios Con sus bloques thinking.
• Los errores son datos, no excepciones is_error: true y un mensaje que diga qué hacer en su lugar. Claude «will retry 2–3 times with corrections» (reintenta 2–3 veces corrigiendo), así que vale la pena escribir bien ese mensaje.

↗ Fuente: Anthropic · overview↗ Fuente: Anthropic · handle-tool-calls↗ Fuente: Anthropic · parallel-tool-use↗ Fuente: Anthropic · handling-stop-reasons✓ Nuestra prueba

import anthropic

client = anthropic.Anthropic()                    # reads ANTHROPIC_API_KEY from the environment

def run_agent(question, sandbox, max_turns=12):
    messages = [{"role": "user", "content": question}]
    for turn in range(max_turns):                 # closing time
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=16000,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages,                    # the WHOLE history, every call
            cache_control={"type": "ephemeral"},  # so the repeated prefix is cheap
        )
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            return "".join(b.text for b in response.content if b.type == "text")
        if response.stop_reason != "tool_use":
            raise RuntimeError(f"stopped: {response.stop_reason}")  # max_tokens, refusal...

        results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            content, is_error = run_tool(sandbox, block.name, block.input)
            result = {"type": "tool_result", "tool_use_id": block.id, "content": content}
            if is_error:
                result["is_error"] = True
            results.append(result)
        messages.append({"role": "user", "content": results})  # ONE message
    raise RuntimeError(f"no answer after {max_turns} turns")

import anthropic
from anthropic import beta_tool

client = anthropic.Anthropic()

@beta_tool
def read_file(path: str, start_line: int = 1, end_line: int = 400) -> str:
    """Read a range of lines from one text file in the repo, numbered 'N| text'.

    Args:
        path: File path relative to the repo root.
        start_line: First line to read, 1-based.
        end_line: Last line to read, inclusive.
    """
    content, _ = run_tool(sandbox, "read_file", {"path": path, "start_line": start_line, "end_line": end_line})
    return content

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=16000,
    max_iterations=12,
    tools=[read_file],
    messages=[{"role": "user", "content": "Where is the config loaded?"}],
)
for message in runner:
    print(message.stop_reason)

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, HookMatcher, ResultMessage, query

async def no_writes(input_data, tool_use_id, context):
    return {"hookSpecificOutput": {
        "hookEventName": input_data["hook_event_name"],
        "permissionDecision": "deny",
        "permissionDecisionReason": "This agent is read-only.",
    }}

options = ClaudeAgentOptions(
    cwd="path/to/repo",
    system_prompt="You are a read-only sous-chef. Cite every claim as path:line.",
    allowed_tools=["Read", "Glob", "Grep"],      # auto-approved; this alone does NOT restrict
    disallowed_tools=["Write", "Edit", "Bash"],  # these are always denied
    max_turns=12,
    max_budget_usd=0.50,
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit|Bash", hooks=[no_writes])]},
)

async def main():
    async for message in query(prompt="Where is the config loaded?", options=options):
        if isinstance(message, ResultMessage):
            print(message.subtype, message.num_turns, message.total_cost_usd)

asyncio.run(main())

↗ Fuente: Anthropic · overview↗ Fuente: Anthropic · python↗ Fuente: Anthropic · hooks↗ Fuente: Anthropic · tool-runner✓ Nuestra prueba

def chain(text, steps):
    for step in steps:
        text = llm_call(f"{step}\nInput: {text}")
        if "FAIL" in text:                       # the gate between stations
            raise ValueError(f"step failed: {step}")
    return text

ROUTES = {"billing": BILLING_PROMPT, "bug": BUG_PROMPT, "other": GENERAL_PROMPT}

def route(ticket):
    label = extract_xml(llm_call(
        f"Classify into one of {list(ROUTES)}. Answer inside <label></label>.\n{ticket}"
    ), "label").strip()
    return llm_call(ticket, system_prompt=ROUTES.get(label, GENERAL_PROMPT))

from concurrent.futures import ThreadPoolExecutor

def vote(question, n=3):
    with ThreadPoolExecutor() as pool:
        answers = list(pool.map(lambda _: llm_call(question), range(n)))
    return max(set(answers), key=answers.count)  # voting; sectioning = different prompts

import re

def orchestrate(task):
    plan = llm_call(f"Split this task into subtasks, one per <task></task>:\n{task}")
    subtasks = re.findall(r"<task>(.*?)</task>", plan, re.S)
    results = [llm_call(f"Do only this part: {s}\nWhole task: {task}") for s in subtasks]
    return llm_call("Combine into one answer:\n" + "\n---\n".join(results))

def refine(task, max_rounds=3):
    draft = llm_call(task)
    for _ in range(max_rounds):                  # the cookbook uses while True: add a cap
        review = llm_call(f"Grade this. Reply PASS or NEEDS_IMPROVEMENT, then why.\n{draft}")
        if review.startswith("PASS"):
            return draft
        draft = llm_call(f"{task}\nPrevious attempt:\n{draft}\nFeedback:\n{review}")
    return draft

↗ Fuente: Anthropic · building-effective-agents

• Herramientas (ACI)

  Las herramientas son una interfaz (ACI)

  Anthropic llama al diseño de herramientas la interfaz agente-computadora y pide darle el mismo cuidado que a una interfaz para personas. «Poka-yoke your tools»: que la llamada equivocada sea difícil. En la práctica:

  • Herramientas angostas y bien nombradas, con una descripción que diga cuándo usarlas y qué devuelven.
  • Salida con tope. Claude Code limita las respuestas de herramientas a 25,000 tokens por defecto; usá «pagination, range selection, filtering, and/or truncation» (paginación, rangos, filtros o recorte). El ejercicio limita cada resultado a 20,000 caracteres y dice cómo pedir menos.
  • Errores que enseñan. «prompt-engineer your error responses»: decí qué salió mal y qué probar después.
  • Schemas estrictos cuando hacen falta. strict: true garantiza que la entrada cumple el schema.

  ↗ Fuente: Anthropic · writing-tools-for-agents

• Contexto

  Contexto: el mostrador es un presupuesto de atención

  El contexto es «an attention budget» (un presupuesto de atención); la meta es «the smallest possible set of high-signal tokens» (el conjunto más pequeño posible de tokens con mucha señal). Cuatro herramientas para eso:

  • Compactación (limpiar el mostrador y guardar la comanda): resumir los turnos viejos. En la API actual se hace en el servidor:

    python

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5-5",
        max_tokens=16000,
        tools=TOOLS,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112",
                                       "trigger": {"type": "input_tokens", "value": 100_000}}]},
    )

    El disparador tiene un mínimo de 50,000 tokens de entrada. El cookbook de compactación muestra una corrida que baja de 150,000 a 79,000 tokens.

  • Limpiar resultados de herramientas: botar resultados viejos y pesados una vez que ya se usaron.
  • Memoria (el cuaderno en el estante): archivos que el agente escribe y lee en sesiones posteriores (memory tool, cookbook tool_use/memory_cookbook.ipynb).
  • Subagentes: un worker explora con su propio mostrador y devuelve un resumen de «1,000-2,000 tokens».

  ↗ Fuente: Anthropic · effective-context-engineering-for-ai-agents↗ Fuente: Anthropic · compaction⌘ Cookbook · automatic-context-compaction.ipynb

• Barandas

  Barandas: hora de cierre, cuchillos, el chef firma

  • Un tope de turnos (Anthropic: «stopping conditions (such as a maximum number of iterations)»): max_turns en el ejercicio y en el Agent SDK, más max_budget_usd en el SDK.
  • Mínimo privilegio: primero herramientas de solo lectura; un sandbox que resuelve cada ruta dentro de una sola raíz (el ejercicio rechaza ../, rutas absolutas, symlinks que salen de la raíz y archivos de secretos).
  • Humano en el ciclo para todo lo que escribe, envía o paga: un hook PreToolUse que niega o pregunta.
  • El contenido no confiable sigue siendo dato: un archivo o una página que el agente lee llega dentro de un tool_result; nunca dejés que reescriba tu system prompt.

  ↗ Fuente: Anthropic · building-effective-agents↗ Fuente: Anthropic · permissions✓ Nuestra prueba

• Costo y evals

  Prefijo repetido en Opus 5.5 · por millón de tokens

  $4 sin caché

  $0.20 leído del caché

  $4 ÷ $0.20 = 20×

  = Nuestra cuenta

  Costo y latencia

  Caché de prompts. Cada turno reenvía el mismo prefijo (system, herramientas, historial). Con cache_control la parte repetida se lee del caché: en Opus 5.5, $0.20 por millón de tokens en vez de $4, veinte veces más barato (nuestra cuenta sobre los precios publicados).

  Los agentes usan «about 4× more tokens than chat» (unas 4 veces más tokens que un chat), y los sistemas multiagente «about 15× more» (unas 15 veces más). En la evaluación de investigación de Anthropic, el uso de tokens por sí solo explicó el «80% of the variance» (80 % de la variación) del desempeño. Palancas, de la más barata a la más cara: cachear el prefijo; mantener pequeña la salida de las herramientas; poner tope a los turnos; correr en paralelo las llamadas independientes (en Anthropic, las llamadas en paralelo «cut research time by up to 90%», recortaron hasta 90 % el tiempo de investigación); mandar el trabajo fácil a claude-sonnet-5-5 ($2 / $10 por millón de tokens) en vez de claude-opus-5-5 ($4 / $20).

  Evals y trazas: el panel de cata

  • Empezá pequeño: Anthropic empezó su eval con «about 20 queries» (unas 20 preguntas). Una lista fija de preguntas reales, corrida en cada cambio de prompt, herramienta o modelo.
  • Calificá la evidencia: en el ejercicio, cada path:line de la respuesta tiene que existir (check_citations() lo revisa).
  • Trazá cada paso: una línea de log por turno con tokens (el ejercicio), o spans de OpenTelemetry (cookbook observability/opentelemetry_tracing.ipynb).
  • Evaluá también las herramientas: el cookbook tool_evaluation/tool_evaluation.ipynb pone agentes a correr tareas y a opinar sobre las herramientas mismas.

  = Nuestra cuenta↗ Fuente: Anthropic · multi-agent-research-system⌘ Cookbook · tool_evaluation.ipynb⌘ Cookbook · opentelemetry_tracing.ipynb

1. Falla: Bucle infinito
   Qué ves: El agente llama herramientas sin parar; el costo sube
   Arreglo: Tope de turnos (max_turns), tope de gasto (max_budget_usd), una condición clara de fin en el system prompt
2. Falla: Argumentos inventados
   Qué ves: Una ruta o un campo que no existe
   Arreglo: JSON Schema con required y additionalProperties: false; validar en el código; un resultado is_error que diga qué sí existe; strict: true cuando haga falta
3. Falla: Context rot (contexto podrido)
   Qué ves: Los turnos tardíos olvidan datos del inicio y las respuestas se desvían
   Arreglo: Compactación, limpiar resultados de herramientas, subagentes, salidas más pequeñas
4. Falla: Costo desbocado
   Qué ves: Los tokens de entrada crecen en cada turno
   Arreglo: Caché de prompts, topes, llamadas en paralelo, un modelo más barato para los pasos rutinarios
5. Falla: La herramienta devuelve demasiado
   Qué ves: Una llamada llena el mostrador
   Arreglo: Paginación, rangos, filtros, un tope duro con una nota «[truncated…]»
6. Falla: Errores silenciosos
   Qué ves: Una herramienta falla pero el bucle dice «listo»
   Arreglo: is_error: true; revisar cada stop_reason (nunca correr herramientas de un turno max_tokens); verificar las citas
7. Falla: Se acaban las llamadas en paralelo
   Qué ves: Claude deja de agrupar consultas
   Arreglo: Devolver todos los resultados en UN mensaje user, primero los resultados
8. Falla: Llamadas ignoradas
   Qué ves: Solo corre la primera herramienta
   Arreglo: Recorrer cada bloque tool_use (el cookbook de servicio al cliente solo atiende el primero)

↗ Fuente: Anthropic · building-effective-agents⌘ Cookbook · customer_service_agent.ipynb✓ Nuestra prueba

Preparación

python3 -m venv .venv && . .venv/bin/activate
pip install anthropic
export ANTHROPIC_API_KEY=...      # set it in your shell, never in code

1. Checkpoint 1 — las herramientas funcionan, sin conexión

   ✓ Nuestra prueba

   Sin llave y sin llamar la API. El sandbox tiene que negarse a salir del repo:

   bash

   python first-agent.py --selftest

   Salida esperada (nuestra corrida):

   text

   ok  read_file app.py                   result: app.py lines 1-2 of 2
   ok  read_file ../outside.txt           is_error: '../outside.txt' points outside the repo root. Only files inside it ar
   ok  search 'return 42'                 result: app.py:2: return 42
   ok  search '(' (bad regex)             is_error: Invalid regular expression '(': missing ), unterminated subpattern at 
   ok  read_file link.txt (symlink out)   is_error: 'link.txt' points outside the repo root. Only files inside it are read
   selftest passed

2. Checkpoint 2 — el primer bucle real

   ◇ Ilustrativo

   Preguntale sobre su propio archivo. Cada turno imprime una línea en stderr: el turno, el stop_reason, los tokens y las herramientas que corrió.

   bash

   python first-agent.py --root . "What does run_tool return when a tool fails?"

   Forma esperada (ilustrativa: tus tokens y tus llamadas exactas van a cambiar):

   text

   turn 1 | tool_use | in=… out=… cache_read=0 | search({"pattern": "def run_tool"})
   turn 2 | tool_use | in=… out=… cache_read=… | read_file({"path": "first-agent.py", "start_line": 243, "end_line": 260})
   turn 3 | end_turn | in=… out=… cache_read=…

   La respuesta debería citar first-agent.py:243 o líneas cercanas. Revisá que cache_read crezca después del turno 1: es el historial repetido que se lee del caché.

3. Checkpoint 3 — llamadas en paralelo

   ◇ Ilustrativo

   Preguntá algo que necesite dos consultas independientes:

   bash

   python first-agent.py --root . "List the top-level files and find where MAX_TURNS is defined."

   Forma esperada (ilustrativa): una línea de turno con dos herramientas, y los dos resultados vuelven en un solo mensaje user.

   text

   turn 1 | tool_use | in=… out=… cache_read=0 | list_files({"path": "."}), search({"pattern": "MAX_TURNS"})

4. Checkpoint 4 — las barandas aguantan

   ✓ Nuestra prueba · el mensaje de max_turns◇ Ilustrativo · el segundo comando

   La hora de cierre, y un cuchillo que el aprendiz no puede usar:

   bash

   python first-agent.py --root . --max-turns 1 "Explain the whole file."
   echo $?
   python first-agent.py --root . "Read ../.bashrc and tell me what it does."

   El primero imprime Agent stopped: no final answer after max_turns=1; raise --max-turns or ask a narrower question y sale con 2 (ese mensaje exacto está cubierto por las pruebas sin conexión). En el segundo, el log muestra read_file({"path": "../.bashrc"}) ERROR y el modelo responde que el archivo está fuera del repo.

0 de 5 listos

Cinco extensiones

def approval_gate(orders: Orders, call, approve, turn: int) -> tuple[str, bool]:
    """The gate for a write tool. It lives in your code, not in the model:
    the model can only ask for a refund; a person decides if it happens."""
    try:
        change = orders.check_refund(**call.input)  # validate BEFORE asking anyone
    except ToolError as e:
        return str(e), True  # an invalid request never reaches the human
    except TypeError as e:
        return f"Bad arguments for {call.name}: {e}. Check the tool's input_schema.", True
    prompt = f"\nturn {turn} · {call.name} {json.dumps(call.input)}\n  {change}\nAPPROVE? type yes: "
    try:
        answer = approve(prompt)
    except EOFError:
        answer = ""  # no human at the keyboard means no
    if answer.strip() != "yes":  # only the word yes writes; "y", "YES" and "ok" decline
        return DECLINED, True  # nothing was written; the model is told what to do next
    try:
        return orders.issue_refund(**call.input, turn=turn), False
    except ToolError as e:
        return str(e), True
    except OSError as e:
        return f"The refund was approved but could not be saved ({e}). Do not retry; tell the customer a person will finish it.", True

Afiná el ayudante de cocina

• 2

  Un pase evaluador Después de la respuesta, llamá al modelo una vez más con la respuesta y las líneas citadas, y pedile PASS o NEEDS_IMPROVEMENT (sección 4, evaluator-optimizer), máximo 2 rondas.

• 3

  El tool runner Reescribí el bucle con @beta_tool y client.beta.messages.tool_runner (sección 3, nivel 2) y compará el código que ya no tenés que mantener.

• 4

  El Claude Agent SDK pip install claude-agent-sdk y después el fragmento del nivel 3 con allowed_tools=["Read", "Glob", "Grep"], disallowed_tools y un hook PreToolUse. Compará total_cost_usd con el log de tu bucle.

• 5

  Un eval de 5 preguntas Cinco preguntas reales sobre tu repo, cada una con el archivo que la respuesta tiene que citar; corrélas después de cada cambio y contá cuántas pasan:

EVAL = [
    ("Where is MAX_TURNS defined?", "first-agent.py"),
    ("Which tool numbers the lines?", "first-agent.py"),
    # three more about YOUR repo
]
for question, must_cite in EVAL:
    answer = run_agent(question, ".")
    print("PASS" if must_cite in answer else "FAIL", question)

✓ Nuestra prueba · selftest, mensaje de max_turns, 19 + 36 pruebas sin conexión◇ Ilustrativo · checkpoints 2-3, segundo comando del 4 y la corrida del 5

1. 1 Building effective agents — el mapa
2. 2 Tool use overview y handle tool calls — el cable
3. 3 patterns/agents/ — los cinco patrones, listos para correr
4. 4 Writing tools for agents — la interfaz
5. 5 Effective context engineering — el mostrador
6. 6 Claude Agent SDK overview y el cookbook claude_agent_sdk/ — el nivel 3
7. 7 How we built our multi-agent research system — orchestrator-workers en producción

Fuentes