En noviembre pasado le entregué a un cliente un agente impulsado por Claude que se suponía que debía clasificar tickets de soporte entrantes, enrutarlos al departamento correcto y redactar respuestas de primer paso. Me tomó tres semanas construirlo. Se veía brillante en staging. El primer día en producción alucinó una política de reembolso que no existe, enrutó diecisiete tickets a la cola equivocada y le dijo confiadamente a un cliente que su pedido llegaría "el jueves" sin acceso a datos de envío.
Así que. Aprendí algunas cosas.
Este post trata sobre lo que sé ahora, después de reconstruir ese agente correctamente y lanzar varios más desde entonces. No es teoría. Decisiones reales que tomé, herramientas que usé y errores que no repetiré. Si eres dueño de una agencia o freelancer intentando ir más allá de la etapa de demostración con el Claude Agent SDK, esto está escrito para ti.
---
Qué es Realmente el Claude Agent SDK (y Qué No Es)
Antes que nada: el SDK no es magia. Es una forma estructurada de darle a Claude acceso a herramientas, gestionar el contexto de la conversación a través de múltiples turnos y orquestar lo que equivale a un bucle de decisión. Claude razona sobre una tarea, decide si debe llamar una herramienta, obtiene un resultado, razona de nuevo y, o bien llama otra herramienta o produce una respuesta final.
Ese bucle suena simple. Es simple. La complejidad vive enteramente en lo que pones alrededor de él.
El SDK te proporciona la fontanería. Tú sigues siendo responsable de la presión del agua, el diámetro de las tuberías y de si recordaste cerrar la llave de paso antes de empezar a perforar. He visto dueños de agencias entregarle el SDK a un desarrollador junior, esperar un producto terminado en un sprint y recibir algo que técnicamente funciona pero se desmorona en cualquier entrada que no esté en el camino feliz.
Cómo Se Ve el Bucle en Práctica
Defines herramientas como esquemas JSON. Claude lee esos esquemas, decide cuándo usarlos, pasa argumentos estructurados y tu código ejecuta la lógica real. Claude nunca ejecuta código directamente. Pregunta. Tu sistema hace el trabajo. Luego Claude obtiene el resultado y continúa.
Esa separación importa más de lo que la mayoría de la gente se da cuenta. Significa que Claude es siempre un orquestador, no un ejecutor. Y ese enmarque debe guiar cada decisión arquitectónica que hagas.
---
Diseñar Herramientas que Claude Pueda Realmente Usar
Aquí es donde la mayoría de las construcciones fracasan. He revisado tal vez quince bases de código de agentes de otros desarrolladores durante el año pasado, y el problema más común no es la ingeniería de prompts ni la elección del modelo. Son herramientas mal diseñadas.
Aquí está lo que "mal diseñado" significa en la práctica:
- Una herramienta llamada
process_dataque hace cinco cosas no relacionadas dependiendo de qué parámetros pases - Descripciones de herramientas que leen como comentarios de código interno ("llama el endpoint v2 con headers de autenticación")
- Parámetros nombrados
typeomodeque aceptan strings arbitrarios en lugar de enumeraciones - Sin información de error en el valor de retorno, Claude no tiene forma de saber si la llamada fue exitosa
A principios de 2023, Seahawk tenía un proyecto de pipeline de contenido donde habíamos construido una herramienta manage_content que aceptaba un parámetro action: create, update, delete, publish, unpublish, archive. Claude seguía eligiendo la acción incorrecta porque las distinciones no eran obvias solo del schema. Las dividimos en seis herramientas separadas. La precisión en esa decisión específica pasó de alrededor del 60% al 94% en nuestras evaluaciones internas. Un solo cambio.
Las Reglas que Sigo Ahora
- Una herramienta, un trabajo. Si no puedes describir el propósito de la herramienta en una sola oración sin "y", divídela.
- Usa enums donde sea posible. No dejes que Claude adivine strings.
- Escribe la descripción para Claude, no para un desarrollador humano. Claude no conoce tu base de código. Solo conoce lo que le dices.
- Siempre retorna datos estructurados con un campo de éxito/fallo explícito. Nunca hagas que Claude infiera del silencio.
- Mantén los nombres de herramientas iniciando con verbo. search_orders, create_draft, fetch_customer_record. No orders, draft,
customer.
La documentación de Anthropic sobre tool use profundiza en la estructura del schema y vale la pena leerla cuidadosamente, no por encima.
---
La Gestión de Contexto Es el Costo Oculto
Hay algo de lo que nadie habla lo suficiente. Los tokens no son gratis, y los agentes tienen hambre.
Cada turno en el bucle incluye el historial completo de la conversación, todos los schemas de herramientas, el system prompt y los resultados de las herramientas. Un agente moderadamente complejo con diez herramientas y un system prompt detallado podría comenzar cada sesión de usuario en 3,000-4,000 tokens antes de que el usuario haya escrito un solo carácter. Suma cinco o seis llamadas a herramientas con resultados, y estás viendo 15,000-20,000 tokens por tarea resuelta. A los precios actuales de la API de Claude, esto suma rápidamente en cualquier volumen.
Ahora lo rastro obsesivamente. Para cada agente que lanzo, ejecuto un número de costo por resolución durante QA. Si está por encima de un umbral que he acordado con el cliente de antemano, vuelvo atrás y ajusto el system prompt, reduzco los schemas de herramientas, o veo si puedo cachear contexto estático usando prompt caching, que Anthropic agregó y que genuinamente uso en cada proyecto ahora. Los tokens elegibles para caché cuestan aproximadamente el 10% de la tasa de entrada estándar en un acierto de caché. En un agente ocupado que ejecuta el mismo system prompt miles de veces al día, esto no es un error de redondeo.
Ajustando Sin Romper las Cosas
La tentación es escribir un system prompt rico y detallado que cubra cada caso borde. Resístela. Cada línea que agregues cuesta tokens en cada turno. Escribe para el caso común. Maneja casos borde en los valores de retorno de herramientas o en instrucciones más cortas en contexto inyectadas en el momento correcto.
También corto despiadadamente las descripciones de herramientas una vez que un agente está funcionando. Si una descripción dice "Esta herramienta busca la base de datos de órdenes y retorna una lista de órdenes que coinciden con la consulta, incluyendo ID de orden, nombre del cliente, artículos de línea, estado de envío y timestamps" la condensaré a "Busca órdenes por cadena de consulta. Retorna registros de órdenes coincidentes." Claude es lo suficientemente inteligente. No necesita la lista de campos en la descripción de la herramienta si el schema de retorno documenta esos campos apropiadamente.
---
Orquestación Multi-Agente: Cuando un Agente No Es Suficiente
Los sistemas de agente único se rompen en cierto techo de complejidad. Alcancé ese techo en un proyecto para una empresa de gestión de propiedades la primavera pasada. El agente necesitaba manejar solicitudes de mantenimiento, comunicarse con contratistas, actualizar una base de datos de Notion, enviar correos electrónicos templados vía SendGrid y extraer datos de disponibilidad de una API de calendario construida a medida. Siete herramientas, varias de las cuales tenían sub-flujos.
Un agente tratando de coordinar todo eso se volvió poco confiable. El contexto se volvió desordenado. Claude ocasionalmente perdería la pista de en qué sub-tarea estaba trabajando a mitad del bucle.
La solución fue obvia en retrospectiva: orquestador más especialistas. Un agente Claude de nivel superior maneja la clasificación de intención y el enrutamiento. Sub-agentes especialistas manejan dominios específicos (comunicación, programación, actualizaciones de datos) y reportan resultados estructurados. El orquestador nunca ve los internos de lo que cada especialista hizo. Solo ve el resultado.
Este patrón se describe en la propia guía multi-agente de Anthropic y mapea estrechamente con cómo diseñarías un equipo humano. Un gerente de proyecto no escribe personalmente cada correo electrónico ni actualiza cada hoja de cálculo. Delega, espera confirmación y sigue adelante.
Notas Prácticas sobre el Diseño de Sub-Agentes
- Dale a cada sub-agente un prompt de sistema ajustado y específico. Sin instrucciones entre dominios.
- Los sub-agentes nunca deberían tener más herramientas de las que necesitan para su dominio. La sobrecarga de herramientas es tan peligrosa en sub-agentes como en el orquestador principal.
- Pasa el contexto explícitamente. No asumas que un sub-agente "sabe" qué pasó aguas arriba. Envíale exactamente lo que necesita, nada más.
---
Manejo de fallos con elegancia (porque sucederán)
Los agentes en producción fallan. Se agotan los tiempos de espera. Las APIs externas devuelven 500s. Los usuarios envían entradas que nunca anticipaste. Claude ocasionalmente malinterpreta un esquema de herramienta y pasa un argumento malformado.
La pregunta no es si tu agente fallará. Es si falla de forma segura.
Construyo tres cosas en cada agente ahora, sin excepción:
- Lógica de reintentos con backoff en todas las llamadas a herramientas externas. No solo en errores de límite de velocidad. En cualquier cosa que no sea 200.
- Una ruta alternativa cuando el agente ha realizado más de N llamadas a herramientas sin resolver la tarea. N varía, pero rara vez lo dejo por encima de ocho. En ese punto, algo está mal y un humano debería involucrarse.
- Manejo explícito de incertidumbre en el prompt del sistema. Le digo a Claude: si no tienes información suficiente para actuar con confianza, haz una pregunta aclaratoria en lugar de proceder sobre suposiciones.
Ese tercero salvó el agente de triaje de tickets que mencioné al principio. La versión reconstruida ahora hace una pregunta aclaratoria cuando está inseguro sobre el enrutamiento. A los usuarios no les importa. Prefieren responder una pregunta que tener su ticket en la cola equivocada.
---
Evals: No puedes lanzar sin ellas
No ejecuté evals adecuadas en la primera versión del agente de soporte de tickets. Ese fue el error, realmente. Todo lo demás fue un síntoma de eso.
Las evals no tienen que ser elaboradas. Lo que hago ahora es construir un conjunto de 40-60 entradas representativas antes de empezar a construir, cubriendo casos normales, casos extremos y entradas adversariales. Ejecuto el agente contra todas ellas después de cada cambio significativo. Sigo tres números: tasa de finalización de tareas, precisión de llamadas a herramientas (¿llamó a la herramienta correcta con los argumentos correctos?), y tasa de alucinación (¿aseveró algo que no está fundamentado en resultados de herramientas?).
Para un agente en producción, no lanzaré por debajo del 88% de finalización de tareas y tolerancia cero de alucinación en salidas de alto riesgo como mensajes dirigidos al cliente con afirmaciones específicas (fechas, precios, políticas).
El marco de evaluación HELM de Stanford vale la pena consultar para inspiración en el diseño de evals, incluso si no estás ejecutando a escala académica. Las categorías que prueban se mapean bien a requisitos reales de producción.
---
El prompt del sistema es estructural
He cambiado de opinión sobre esto en el último año. Solía tratar el prompt del sistema como texto de configuración, algo que escribes una vez y olvidas. Ahora lo trato como el archivo más importante del proyecto.
Un prompt de sistema bien escrito hace cuatro cosas:
- Define claramente la identidad y el alcance del agente (qué hace y, críticamente, qué explícitamente no hace)
- Establece expectativas de tono y formato de salida
- Maneja proactivamente los modos de fallo más comunes ("Si no puedes encontrar un pedido, dilo explícitamente en lugar de adivinar")
- Establece criterios de escalada
La definición del alcance es la que la mayoría de desarrolladores saltan. Sin ella, Claude intentará ser útil de formas que no pretendías. En el agente de gestión de propiedades, el primer prompt del sistema no excluía explícitamente asesoramiento financiero. Un inquilino le preguntó al agente si debería impugnar un cargo. Claude ayudosamente opinó. Eso no es lo que el cliente pagó, y no es lo que el agente fue construido para hacer.
Una frase lo arregló todo: "No estás autorizado para brindar asesoramiento sobre disputas financieras, asuntos legales o interpretación de contratos de arrendamiento. Dirige a los usuarios a comunicarse directamente con la oficina para estos temas."
Escribe esa frase para cada dominio que esté fuera del alcance. No asumas que Claude inferirá los límites.
---
FAQ
¿En qué se diferencia el Claude Agent SDK del uso directo de la Claude API?
La API te da una única solicitud-respuesta. El Agent SDK (y los patrones de agentes que documenta Anthropic) te da un bucle estructurado donde Claude puede tomar múltiples decisiones, llamar herramientas, recibir resultados y continuar razonando entre turnos. Se trata menos de un paquete de software distinto y más de un patrón: definiciones de herramientas, gestión de contexto multiturno y lógica de orquestación. Estás construyendo la estructura alrededor de la API para habilitar ese bucle.
¿Cuál es un cronograma realista para entregar un agente listo para producción?
Honestamente, cuatro a seis semanas para cualquier cosa no trivial. Dos semanas se van en construir e integrar herramientas. Una semana en ingeniería de prompts e iteración. Una a dos semanas en evaluaciones, manejo de casos extremos y QA. Cualquiera que te prometa un agente de producción en una semana o nunca ha entregado uno antes o te está vendiendo una demostración disfrazada de producto.
¿Debo usar Claude para todos los sumagentes en un sistema multiagente, o mezclar modelos?
Uso Claude para cualquier cosa que requiera razonamiento matizado o donde la calidad del resultado importe al usuario final. Para tareas simples de clasificación o enrutamiento de alto volumen y bajo riesgo, un modelo más pequeño y económico puede funcionar. Pero mezclar modelos añade sobrecarga de integración y dificulta la depuración. Comienza con Claude para todo, luego optimiza una vez tengas datos de producción reales mostrando dónde un modelo más ligero es suficiente.
¿Cómo evito que un agente se salga del guión?
Tres cosas trabajando juntas: un system prompt restrictivo con declaraciones explícitas de fuera del alcance, diseño de herramientas que impida físicamente ciertas acciones (no le des al agente una herramienta que no debería usar), y validación de salida en cualquier cosa orientada al cliente. No puedes confiar únicamente en el system prompt. Defensa en profundidad.
¿Cuál es el mayor error que cometen los desarrolladores con la memoria del agente?
Tratar la ventana de contexto como infinita. No lo es. La mayoría de los fallos que veo en agentes mal construidos vienen de un contexto hinchado de historial irrelevante, forzando a Claude a razonar entre ruido. Poda agresivamente. Resume donde puedas. Solo lleva adelante lo que el agente genuinamente necesita para completar la tarea actual.
---
El resumen honesto es este: el SDK no es la parte difícil. La parte difícil es lo mismo de siempre en software: pensar claramente sobre el alcance, diseñar para el fracaso y probar antes de entregar. Claude es una capa de razonamiento notablemente capaz, pero no compensará un sistema mal diseñado a su alrededor. Primero haz bien la plomería.