Construir un agente con Claude no es difícil; construirlo de forma que sea confiable en producción requiere exactamente el tipo de disciplina que distingue al AI-TDA del desarrollo serio. Este tutorial cubre el camino completo: desde la primera llamada a la API hasta un agente con herramientas reales, contexto persistente y una política de error que no deja el sistema en estado indefinido.
Estructura básica: tool_use en la API de Claude
Un agente con Claude es un loop donde tú controlas la ejecución y el modelo controla las decisiones. Cuatro pasos: envías un mensaje con una lista de herramientas disponibles; el modelo responde con una acción de tool_use especificando qué herramienta llamar y con qué parámetros; tú ejecutas esa herramienta y obtienes el resultado; devuelves ese resultado como tool_result y el ciclo continúa hasta que el modelo produce una respuesta de texto final. La descripción de cada herramienta no es documentación para humanos: es el contexto que Claude usa para decidir cuándo y cómo usarla. Escríbela como si estuvieras instruyendo a un junior.
Memoria y contexto persistente
Claude no tiene memoria entre llamadas. Si tu agente necesita recordar decisiones anteriores, esa memoria debe vivir en tu código y ser inyectada en el contexto de cada nueva llamada. La forma más pragmática: un JSON o estructura en memoria con las acciones tomadas en la sesión actual, los resultados obtenidos y el estado acumulado. Mantén este contexto compacto: resumir en lugar de acumular verbatim evita que la ventana de contexto se sature en sesiones largas.
«El agente es tan bueno como las herramientas que le das y tan confiable como la política de error que defines para cuando esas herramientas fallan.»
Reintentos, errores y cuándo detener el loop
Define antes de escribir una sola línea: ¿cuántos ciclos máximos puede ejecutar el agente? ¿Qué pasa si una herramienta falla dos veces consecutivas? El patrón recomendado: máximo N iteraciones configurables, reintento con backoff exponencial para errores transitorios, escalada inmediata para errores de autorización, y log completo de cada iteración antes de cualquier acción. Si el agente llega al límite sin completar el objetivo, produce un informe del estado actual y escala — nunca silencia el fallo.
De prototipo a producción
Un agente que funciona en local no es un agente de producción. Antes de desplegar: cada herramienta debe tener validación de inputs y manejo de excepciones propio, el agente debe tener un modo dry-run donde razona y registra pero no actúa, y debe existir observabilidad completa de cada llamada al modelo y cada invocación de herramienta. En SFD, ningún agente entra a producción sin al menos una semana de operación en modo observación con revisión diaria de logs. El agente que resiste la primera semana en producción no es el más inteligente, sino el mejor diseñado para fallar de forma segura.