Loop de herramientas en paralelo, memoria y frameworks de agentes

Un agente de depósito responde lento cuando el usuario pregunta por tres productos, y cada tanto la API devuelve un 400 que habla de un tool_use sin su tool_result. Otro agente, de tutorías, arranca cada sesión pegando las veinte conversaciones anteriores del alumno. Y un tercer equipo quiere pasar una llamada simple a un framework de grafos “para estar preparados”. Son tres patrones de agentes mal aplicados.

Varias herramientas en una misma respuesta

Claude puede pedir más de una herramienta en una sola respuesta: es el uso de herramientas en paralelo (parallel tool use). El harness tiene que:

1. Recorrer todos los bloques tool_use de la respuesta, no solo el primero.
2. Devolver un tool_result por cada uno, con su tool_use_id, todos juntos en el siguiente mensaje de usuario y antes de cualquier texto.
3. Ejecutar a la vez las que son independientes y de solo lectura (en Python, por ejemplo, con asyncio.gather), y en orden las que dependen una de otra o tienen efectos.

Si procesás solo el primer bloque, la API responde 400 porque quedaron pedidos sin resultado; si los ejecutás uno tras otro sin necesidad, la respuesta tarda la suma de todas las consultas.

Memoria: qué dura y dónde se guarda

Hay que separar dos cosas:

• Memoria de corto plazo: la conversación actual, dentro de la ventana de contexto (context window). Se pierde al terminar la sesión y ocupa lugar mientras dura.
• Memoria de largo plazo: lo que tiene que sobrevivir entre sesiones (preferencias del alumno, decisiones, avances). Va afuera del contexto.

Para la de largo plazo, la API tiene la herramienta de memoria (memory tool): Claude pide crear, leer, editar o borrar archivos dentro de un directorio /memories, y tu aplicación ejecuta cada operación sobre el almacenamiento que vos controlás (archivos, una base, un bucket por usuario). Es una herramienta del cliente, así que te toca validar cada ruta para que nunca salga de ese directorio. Así el agente lee solo las notas relevantes en lugar de cargar todo el historial en cada pedido.

Que la ventana no se llene

En un agente largo, las salidas de herramientas se acumulan. Las formas de contenerlo, que se ven en detalle en el dominio de contexto, son tres: delegar en subagentes que devuelven resúmenes, sacar o compactar las salidas viejas (recorte de contexto (context editing) y compactación) y mandar a memoria externa lo que tiene que durar. Ojo con un distractor frecuente: la caché de prompts abarata y acelera, pero no libera ni un token de la ventana.

Frameworks de agentes

Un framework de agentes (agentic framework) te da piezas ya armadas encima de la API:

Framework	Qué aporta
LangGraph	Modela el flujo como un grafo de nodos con estado persistente y puntos de control: ramas, reintentos y pausas para aprobación humana
PydanticAI	Agentes en Python con entradas y salidas tipadas y validadas con modelos de Pydantic
Strands Agents	Un SDK centrado en el modelo: definís prompt y herramientas y el framework corre el loop

La recomendación es empezar con la API directa y sumar un framework cuando resuelve una necesidad concreta, como estado que tiene que persistir entre pasos o un flujo con muchas ramas. Cada capa de abstracción esconde el prompt y la respuesta real, y eso complica la depuración. Si lo adoptás, conviene entender qué hace por debajo.

Las trampas típicas

• Procesar solo el primer tool_use, o mandar los resultados en mensajes separados.
• Ejecutar en serie consultas independientes de solo lectura.
• Pegar el historial completo en cada sesión en lugar de usar memoria con notas cortas.
• Implementar la herramienta de memoria sin validar rutas.
• Creer que la caché de prompts resuelve una ventana que se llena.
• Adoptar un framework “por las dudas” para una llamada con una herramienta.

En el examen

Si aparece un 400 que nombra un tool_use sin resultado, la respuesta es devolver un tool_result por cada bloque, todos juntos. Si además el agente es lento con varias consultas independientes, sumá la ejecución concurrente. Si el agente tiene que recordar entre sesiones, buscá la herramienta de memoria con almacenamiento propio. Y si alguien propone un framework sin un problema que lo pida, quedate con la API directa.