Reduce el costo de los flujos de trabajo con mucho uso de herramientas

La demostración de este video se grabó en septiembre de 2026. Se ejecutó en Claude Sonnet 5 (claude-sonnet-5). Los resultados pueden variar en modelos más recientes.

Un agente que usa herramientas envía todo de nuevo en cada solicitud, por lo que su costo crece con cada llamada a una herramienta. Cada solicitud lleva las definiciones de herramientas, la indicación del sistema, la pregunta y todos los resultados de herramientas hasta el momento. Esos son sus tokens de entrada, y cada uno se factura.

La llamada programática a herramientas y el almacenamiento en caché de prompts reducen ambos ese costo.

Meridian es una consultora de ingeniería ficticia con 40 ingenieros. Su agente recibió una sola pregunta: ¿Qué ingenieros estuvieron por debajo del 70% de utilización en junio de 2026? El agente tenía dos herramientas. list_employees devuelve la nómina, y get_employee_hours devuelve la hoja de horas de un ingeniero.

Responder esa pregunta le tomó al agente 42 solicitudes y 1,124,799 tokens de entrada. La ejecución completa costó $2.29 en tokens.

Mide los tokens de entrada en cada solicitud

Imprime usage.input_tokens cada vez que llega una respuesta, porque esos recuentos te muestran dónde está el costo.

resp = client.messages.create(...)
print(resp.usage.input_tokens, "input tokens")

El agente de Meridian ejecuta un bucle clásico, donde cada respuesta solicita una llamada a una herramienta. Aquí hay dos de sus recuentos.

La solicitud 1 lleva solo lo que envía cada solicitud. Las solicitudes posteriores agregan llamadas a herramientas y sus resultados. Compara los dos recuentos para ver qué parte creció.

Mantén los resultados de herramientas fuera de lo que lee Claude

Con la llamada programática a herramientas, Claude escribe un script que llama a tus herramientas, y la herramienta de ejecución de código lo ejecuta en un contenedor. Solo lo que imprime el script llega a Claude. Las 40 hojas de horas de Meridian permanecen con el script, y Claude recibe su breve impresión.

Revisa primero tus herramientas y tu modelo. A partir de octubre de 2026, la llamada programática a herramientas no admite herramientas marcadas con strict: true. Tampoco admite disable_parallel_tool_use, el ajuste de tool_choice que limita a Claude a una llamada a herramienta por respuesta. tool_choice no puede obligar a Claude a llamar a una herramienta desde el script.

Claude Haiku 4.5 no admite esta función. La función se ejecuta en la Claude API, Claude Platform on AWS y las implementaciones de Microsoft Foundry alojadas en Anthropic.

Activar la llamada programática a herramientas requiere cuatro cambios.

1. Agrega la herramienta de ejecución de código a tu lista tools.
2. Marca las herramientas que el script puede llamar. Dale a cada una un campo allowed_callers que nombre la herramienta de ejecución de código en la versión code_execution_20260120 o posterior.
3. Envía de vuelta el ID del contenedor. Léelo de cada respuesta que se detiene para una llamada a herramienta, y envíalo con la solicitud que devuelve tus resultados de herramientas.
4. Describe el resultado de cada herramienta. Indica en la descripción qué forma tiene, porque el script tiene que analizarlo. Aquí está la descripción de Meridian para get_employee_hours.

Returns one engineer's hours for the month as JSON: {"name": str, "billable_hours": float, "utilization": float 0-1}

Aquí está el bucle de Meridian después de estos cambios.

CODE_EXECUTION = "code_execution_20260120"
TOOLS = [
    {"type": CODE_EXECUTION, "name": "code_execution"},
    {**LIST_EMPLOYEES, "allowed_callers": [CODE_EXECUTION]},
    {**GET_EMPLOYEE_HOURS, "allowed_callers": [CODE_EXECUTION]},
]

messages = [{"role": "user", "content": QUESTION}]
container = None
while True:
    resp = client.messages.create(
        model="claude-sonnet-5", max_tokens=4096,
        tools=TOOLS, messages=messages, container=container,
    )
    print(resp.usage.input_tokens, "input tokens")
    if resp.stop_reason not in ("tool_use", "pause_turn"):
        break
    container = resp.container.id
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason == "tool_use":
        messages.append({"role": "user", "content": run_tools(resp)})
print("".join(b.text for b in resp.content if b.type == "text"))

• LIST_EMPLOYEES y GET_EMPLOYEE_HOURS son las definiciones de herramientas de Meridian.
• Tu propia run_tools ejecuta cada llamada a herramienta y devuelve los resultados.
• En pause_turn, el bucle envía la respuesta de vuelta y continúa.

Cuando el script llama a una herramienta, el stop_reason de la respuesta es "tool_use". Tu código ejecuta la herramienta, y el resultado va al script, no a Claude. El script puede ejecutar herramientas en paralelo, por lo que una respuesta puede contener más de una llamada a herramienta.

Aquí está la misma pregunta respondida de las dos maneras.

Ambas ejecuciones usaron la misma pregunta, las mismas herramientas y claude-sonnet-5. Los costos usan precios a partir de septiembre de 2026, y el tiempo de ejecución de código se factura por separado de los tokens.

La llamada programática a herramientas es adecuada para búsquedas que no dependen entre sí. Ayuda poco cuando Claude tiene que razonar sobre cada resultado antes de hacer la siguiente llamada a herramienta.

Almacena en caché las definiciones de herramientas que se repiten

Con el almacenamiento en caché de prompts, la API guarda el prefijo de tu solicitud, la parte hasta un punto de caché que marcas. Leer ese prefijo de nuevo cuesta mucho menos.

Un segundo agente de Meridian tiene 14 herramientas, y sus definiciones suman 3,305 tokens que cada solicitud envía de nuevo.

Marca el punto de caché colocando cache_control en la última herramienta, y toda la lista queda en caché. Eso toma una línea:

TOOLS[-1]["cache_control"] = {"type": "ephemeral"}

En Claude Sonnet 5, leer el prefijo cuesta una décima parte del precio normal de entrada. Escribirlo cuesta 1.25 veces el precio normal de entrada.

El prefijo en caché dura cinco minutos de forma predeterminada, y cada uso lo renueva. Para solicitudes más distanciadas, agrega "ttl": "1h" a cache_control para mantenerlo durante una hora. Escribir una caché de una hora cuesta el doble del precio normal de entrada.

Meridian ejecutó las mismas ocho preguntas con la caché y sin ella. Su costo total de entrada bajó de $0.0554 a $0.0154.

Con el almacenamiento en caché automático, colocas un campo cache_control en el nivel superior de la solicitud, y la API ubica el punto de caché por ti.

Ten en cuenta tres cosas una vez que la caché está activada:

1. Si cambias cualquier definición de herramienta, pierdes toda la caché.
2. En Sonnet 5, un prefijo en caché debe tener al menos 1,024 tokens. Cuando es más corto, no se almacena nada en caché y ningún error lo indica.
3. Con la caché activada, input_tokens no incluye el prefijo en caché, así que el total real de una solicitud es input_tokens, cache_read_input_tokens y cache_creation_input_tokens sumados.

Combina las funciones donde encajen

Agrégalas en este orden.

1. Comienza con la caché. Toma una línea.
2. Prueba la llamada programática a herramientas. Ejecuta parte de tu tráfico habitual con y sin allowed_callers, y luego compara los tokens de entrada facturados de cada ejecución.

Para cada una de las dos solicitudes de Meridian a continuación, encuentra la parte que contiene la mayoría de los tokens de entrada, y luego elige la función que la reduce.

Puntos clave

• Cada solicitud envía todo de nuevo, por lo que pagas una y otra vez por resultados de herramientas anteriores.
• Imprime usage.input_tokens cada vez que llega una respuesta, para saber qué parte de la solicitud cuesta más.
• Comienza con la caché. Agrega cache_control a la última herramienta de tu lista.
• Cuando tus llamadas a herramientas no dependen entre sí, configura la llamada programática a herramientas con la herramienta de ejecución de código y allowed_callers. Envía el ID del contenedor con cada solicitud posterior.