Cómo construir un agente de IA personalizado con el SDK de Anthropic
La primera vez que entendí lo que "agente" realmente significaba — no la versión de marketing, no el buzzword en la landing page de cada startup — llevaba tres horas metido en la documentación del Agent SDK de Anthropic a las 11 PM un martes. Mi café se había enfriado. Tenía diecisiete pestañas del navegador abiertas. Mi IDE tenía un entorno de Python a medio construir que aún no cooperaba.
Y no dejaba de pensar: esto es realmente diferente.
Había entrado con escepticismo. Había visto demasiadas demos de "agentes de IA" que eran chatbots glorificados con un wrapper de herramientas encima. Impresionantes en una demo controlada. Inútiles en producción. Pero la arquitectura que Anthropic construyó aquí — la forma en que gestiona el bucle de control, maneja el contexto de conversación automáticamente y da a los desarrolladores acceso al mismo conjunto de herramientas integradas que usa Claude Code — no era eso. Era algo significativamente diferente.
Pasé la semana siguiente construyendo un agente de IA personal al que llamaré Luna. Se integra con Slack, Gmail, Notion, Chartmogul y App Store Connect. Tiene un sistema de memoria de tres niveles. Ejecuta resúmenes matutinos programados y envía notificaciones push con elementos de acción a mi teléfono antes de que abra mi portátil. Es lenta — las consultas complejas toman de 1 a 2 minutos — pero es minuciosa de una manera que ninguna respuesta rápida de chatbot puede igualar.
Este artículo cubre todo lo que aprendí. Incluyendo el problema de costos que genuinamente me preocupó, el error arquitectónico que cometí al principio y que me costó cuatro días de retrabajo, y por qué creo que el Anthropic Agent SDK es lo más significativo que Anthropic ha lanzado para desarrolladores desde el propio Claude.
Antes de entrar en cómo construir esto, quiero dejar algo aquí: el mayor error que cometen la mayoría de los desarrolladores al construir agentes no es técnico. Es un error de diseño. Te explicaré exactamente cuál es — y por qué desperdicia semanas — una vez que tengamos las bases en su lugar.
Qué es realmente un agente (dejando de lado el buzzword)
Todas las empresas dicen que ahora tienen agentes. La mayoría está siendo muy generosa con la definición. Un agente real tiene exactamente tres componentes. Entenderlos con precisión es lo que separa a los agentes funcionales de los chatbots costosos.
Componente uno: un LLM. Claude, GPT-4, el que uses. El LLM es el motor de razonamiento. Lee el contexto, decide qué hacer a continuación y genera texto. Eso es todo. No puede ejecutar nada por sí solo. No puede llamar APIs. No puede leer archivos. Piensa. Nada más.
Componente dos: herramientas. Funciones que el LLM puede invocar. Una herramienta podría ser "leer este hilo de Gmail", "consultar esta base de datos de Notion" o "ejecutar este comando de bash". El LLM no las ejecuta — las solicita en un formato estructurado, tu sistema las ejecuta y los resultados regresan al LLM como nuevo contexto.
Componente tres: el bucle. Después de que el LLM llama a una herramienta y recibe resultados, evalúa esos resultados y decide qué hacer a continuación. ¿Otra llamada a herramienta? ¿Una consulta de seguimiento? ¿Una respuesta final? Este bucle continúa hasta que la tarea se completa. Esto es lo que convierte algo en un agente en lugar de un chatbot. Sin el bucle, tienes un invocador de herramientas de un solo uso. Con el bucle, tienes algo que puede razonar a lo largo de docenas de pasos.
Cometí el error temprano de equiparar "más herramientas" con "agente más inteligente". Es exactamente al revés. La inteligencia vive en el bucle. Un bucle bien estructurado con cinco herramientas enfocadas supera a un bucle caótico con cincuenta. Siempre. Reconstruí la configuración de herramientas de Luna dos veces antes de interiorizar esto.
Esta distinción importa para lo que viene a continuación — porque el Anthropic Agent SDK es fundamentalmente un gestor de bucles. Todo lo que hace sirve al bucle: hacerlo confiable, eficiente y más fácil de construir sin escribir cientos de líneas de código repetitivo.
Qué hace el SDK que nada más hace del todo bien
Antes de que existiera este SDK, construir el bucle significaba escribir código repetitivo a mano: gestión del historial de conversación, parseo de llamadas a herramientas, formateo de resultados, manejadores de streaming, lógica de reintentos. Nada de eso es complicado individualmente. Combinado, son varios cientos de líneas de código que cada desarrollador de agentes escribía de forma ligeramente diferente, lo que hacía que las bases de código de agentes fueran difíciles de mantener o extender.
El SDK condensa todo eso en una gestión basada en sesiones. Inicializas una sesión con un ID, el SDK rastrea la conversación y Claude recibe el contexto correcto automáticamente en cada turno. Cuando probé esto por primera vez, esperaba fragilidad — la gestión "automática" de estado en herramientas para desarrolladores generalmente significa que funciona hasta que misteriosamente deja de hacerlo. Pero después de ejecutar sesiones de varias horas con Luna ejecutando docenas de llamadas a herramientas secuenciales, no he encontrado un problema de consistencia de contexto.
La función de auto-compactación me convenció definitivamente. Cuando una conversación crece lo suficiente como para acercarse al límite de contexto de Claude, el SDK resume automáticamente las partes más antiguas de la conversación y las comprime. Sin errores. Sin truncamiento. Sin intervención manual. Para Luna, donde una sesión de flujo de trabajo individual puede involucrar leer veinte correos electrónicos, consultar tres bases de datos y extraer métricas de negocio — esto no es opcional. Sin ello, las tareas complejas fallarían a mitad de ejecución al alcanzar el límite. Con ello, el agente sigue razonando sin interrupción.
Pero esto es lo que no anticipé: el SDK le da a tu agente acceso al conjunto real de herramientas integradas de Claude Code. No una versión simplificada. Las mismas herramientas.
Las herramientas integradas: más poderosas de lo que sugiere la documentación
Las herramientas integradas de Claude Code son de nivel producción: ejecución de bash, lectura y escritura de archivos, grep y glob para coincidencia de patrones, búsqueda web optimizada y web scraping. Cuando usas el Anthropic Agent SDK, tu agente obtiene acceso a estas mismas herramientas de forma predeterminada.
Déjame ser específico sobre lo que eso significa: tu agente puede ejecutar comandos de shell, leer y escribir archivos en el sistema de archivos, buscar en la web información actual y extraer contenido de cualquier URL pública. Esto no es funcionalidad de juguete. Es el mismo conjunto de herramientas que Claude Code usa cuando ayuda a los desarrolladores a escribir software de producción.
Para Luna, esto eliminó tres integraciones personalizadas que había estado planeando construir. Solo la capacidad de web scraping reemplazó 200 líneas de código personalizado que había escrito para un proyecto anterior. Eliminé ese código dentro de las 24 horas posteriores a la configuración del SDK.
Aquí es donde necesito señalar la advertencia — porque me tomó un día completo aprenderlo correctamente. La ejecución de bash en un agente es un límite de confianza. Un agente con acceso irrestricto a bash puede hacer cualquier cosa que tu cuenta de usuario pueda hacer: borrar archivos, hacer solicitudes de red salientes, instalar paquetes a nivel de sistema, modificar la configuración del sistema. Mi primer prototipo de Luna, en una sesión de prueba, decidió instalar una biblioteca de Python faltante a través de pip install a nivel de sistema porque necesitaba esa biblioteca para completar una tarea que le había asignado. No estaba equivocada en que el enfoque funcionaría. Pero un agente automatizado ejecutándose en mi portátil no debería estar haciendo cambios de paquetes a nivel de sistema sin permiso explícito.
Ese es el error de diseño que mencioné en la apertura — y aplica mucho más allá del acceso a bash. La mayoría de los desarrolladores le dan a su agente permisos máximos porque es más simple de configurar. Luego se sorprenden cuando el agente hace cosas inesperadas. Limita tus herramientas exactamente a lo que el agente necesita para cumplir sus tareas definidas. Nada más. Esta decisión debería tomarse antes de escribir una sola línea de código de implementación.
El sistema de habilidades: cómo escalas sin romper todo
A medida que un agente acumula capacidades, encuentra un problema fundamental de escalabilidad: más herramientas en contexto significa mayor costo en tokens y razonamiento más lento. Un agente que conoce cincuenta herramientas es más costoso por solicitud que uno que conoce cinco — incluso si solo usa tres de ellas.
El sistema de habilidades resuelve esto de forma limpia. Una habilidad es una capacidad modular definida como una carpeta que contiene un archivo de metadatos e instrucciones en markdown. Los metadatos describen lo que hace la habilidad en lenguaje simple. El agente lee las descripciones de habilidades para determinar cuáles son relevantes para la tarea actual, y luego carga solo esas. Esto es revelación progresiva — el agente se revela capacidades a sí mismo selectivamente, basándose en el contexto de la tarea, en lugar de cargar todo desde el principio.
Para Luna, tengo ocho habilidades configuradas: Gmail, Slack, Notion, Chartmogul, App Store Connect, notificaciones push, gestión de archivos e investigación web. En una sesión típica de resumen matutino, tres habilidades se activan. Las otras cinco permanecen inactivas. Antes de cambiar a esta arquitectura, cada sesión cargaba los ocho contextos de habilidades. Después del cambio, la latencia de las solicitudes bajó un 30–40% y mi uso mensual de tokens disminuyó notablemente.
El archivo de metadatos de habilidades es simple pero importante de hacer bien:
# Gmail Skill
## Description
Search, read, and analyze Gmail messages. Use when the user needs to check email,
find specific messages, or review communication threads.
## When to activate
- User asks about emails or messages
- Task requires checking inbox for updates
- User mentions checking communication or correspondence
## Capabilities
- Search Gmail with query syntax
- Read full email threads
- Extract sender, subject, date, and body content
- Identify urgency signals in messages
La descripción es lo que el agente lee para decidir la relevancia. Escríbela desde la perspectiva del agente, no del desarrollador. Si la descripción no comunica claramente cuándo usar la habilidad, el agente la activará en exceso o la ignorará cuando se necesite.
Aquí es donde el sistema de habilidades se vuelve particularmente poderoso: se conecta directamente con la arquitectura de memoria. La combinación de habilidades ligeras y bajo demanda con una capa de memoria persistente es lo que hace que un agente personal se sienta genuinamente personalizado en lugar de genérico y reiniciado en cada sesión.
Construyendo tu primer agente: la implementación real
Permíteme guiarte por la estructura central. Esto está simplificado pero es arquitectónicamente preciso — suficiente para entender lo que estás construyendo antes de empezar.
import anthropic
from anthropic import Anthropic
client = Anthropic()
# Define your tools as structured schemas
tools = [
{
"name": "search_gmail",
"description": "Search Gmail for emails matching a query. Returns sender, subject, date, and body preview.",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Gmail search query (supports standard Gmail operators)"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return. Default: 10"
}
},
"required": ["query"]
}
},
{
"name": "get_slack_messages",
"description": "Retrieve recent messages from a specified Slack channel.",
"input_schema": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Slack channel name or ID"
},
"hours": {
"type": "integer",
"description": "How many hours back to retrieve messages"
}
},
"required": ["channel"]
}
}
]
def run_agent_loop(session_id: str, user_message: str, conversation_history: list):
"""Core agent loop: think → tool call → result → repeat until done."""
messages = conversation_history + [{"role": "user", "content": user_message}]
while True:
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
tools=tools,
messages=messages
)
# Agent has reached a final answer
if response.stop_reason == "end_turn":
final_text = next(
(block.text for block in response.content if hasattr(block, "text")),
""
)
return final_text, messages
# Agent wants to call one or more tools
if response.stop_reason == "tool_use":
tool_results = []
for block in response.content:
if block.type == "tool_use":
# Execute the requested tool
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# Append agent's response and tool results, continue loop
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
La función execute_tool es donde viven tus integraciones reales. Llamadas a la API de Gmail. Consultas a Notion. Extracción de métricas de Chartmogul. Al agente no le importa cómo funcionan internamente — solo ve los resultados.
Un consejo profesional que vale la pena destacar: devuelve datos estructurados y fáciles de procesar por el agente desde tus herramientas, no respuestas crudas de la API. Si tu herramienta de Gmail devuelve "Se encontraron 3 correos urgentes: (1) De: [email protected], Asunto: Problema de pago, Fecha: Hoy 9:14 AM, Vista previa: 'No hemos recibido la factura...'" — el agente razona sobre ello de inmediato. Si devuelve JSON crudo con 40 campos que el agente tiene que parsear, estás gastando tokens en parseo que la herramienta debería manejar. Tus herramientas deberían hacer el trabajo pesado para que el agente pueda concentrarse en razonar.
Bien — si has llegado hasta aquí, ya entiendes la arquitectura central mejor que la mayoría de los desarrolladores que empiezan a construir agentes. La siguiente parte es donde se vuelve genuinamente poderoso.
Memoria que realmente funciona: la arquitectura de tres niveles
Los agentes por defecto tienen memoria de pez. Cada sesión empieza de cero. El agente no sabe que prefieres listas de verificación de Notion en lugar de viñetas. No recuerda que siempre quieres que los mensajes urgentes de clientes se muestren primero. No conoce la convención de nombres que usas para los archivos de proyecto.
Para tareas puntuales, eso está bien. Para un asistente personal que se supone debe manejar tu flujo de trabajo matutino, es un factor decisivo.
La arquitectura de tres niveles que construí para Luna:
La memoria de sesión es el contexto de conversación actual — gestionado automáticamente por el SDK. Nada que construir aquí. Simplemente funciona.
La memoria persistente es la capa interesante. Almacena hechos que el agente decide que vale la pena guardar: tus preferencias, patrones recurrentes, correcciones a su propio comportamiento. "Mejba prefiere los resúmenes diarios formateados como listas de acciones priorizadas, no como resúmenes narrativos." "Siempre revisar el canal de App Store Connect en Slack antes de reportar problemas de la App Store — generalmente tiene contexto." "El informe estándar de Chartmogul debe incluir MRR, tasa de abandono y cantidad de nuevos clientes."
El comportamiento clave aquí: el agente guarda esto proactivamente. No espera a que digas "recuerda esto". Identifica información que vale la pena conservar durante las interacciones normales y la escribe en memoria con una nota sobre por qué. Después de dos semanas con Luna, tenía noventa y tres entradas de memoria persistente. Mis interacciones se sienten personalizadas porque realmente ha aprendido mis patrones.
La memoria de archivo maneja material de referencia masivo — documentación de proyectos, transcripciones de conversaciones pasadas, archivos de referencia demasiado grandes para cargar directamente en el contexto. Se recupera mediante búsqueda semántica: Luna consulta el archivo con una descripción de lo que necesita y regresan los fragmentos relevantes. Nunca se carga en su totalidad.
Para el backend de almacenamiento, evalué Firebase, Supabase y Convex. Me decidí por Convex por una razón específica: sincronización en tiempo real. Cuando Luna realiza una acción que aparece en mi iPhone — una notificación push, un resumen matutino — el flujo de datos es: acción del agente → Convex → servicio de notificaciones → teléfono. Con backends basados en polling, hay retrasos incómodos. Con las suscripciones en tiempo real de Convex, es instantáneo. Convex también maneja cron jobs de forma nativa, que es lo que alimenta el flujo de trabajo matutino programado de Luna.
Despliegue: la decisión que la mayoría de los tutoriales ignoran
¿Dónde vive realmente tu agente? Esta pregunta tiene más peso arquitectónico del que parece a primera vista.
El despliegue local te da acceso completo a tu máquina. Para la integración con iMessage — que no tiene API oficial y solo se puede acceder a través de AppleScript en macOS — la ejecución local es la única opción. La contrapartida: tu agente solo funciona cuando tu portátil está encendido y conectado. Los flujos de trabajo programados fallan en el momento en que cierras la tapa.
Un VPS funciona 24/7 y maneja cualquier integración accesible por la nube de forma limpia: Gmail, Slack, Notion, Chartmogul, App Store Connect. Pero un VPS no puede ejecutar AppleScript. No puede tocar iMessage ni otras herramientas exclusivas de Mac.
Luna usa una arquitectura dividida. Un VPS maneja los flujos de trabajo programados y todas las integraciones con plataformas en la nube. La ejecución local maneja todo lo específico de Mac. Convex sincroniza el estado entre ambos entornos en tiempo real, así que desde la perspectiva del usuario se siente como un único agente continuo independientemente de qué máquina está ejecutando la tarea actual.
La parte no resuelta — y quiero ser honesto sobre esto — es la autenticación para despliegue multiusuario. Almacenar claves de API para uso personal es sencillo: variables de entorno, cifradas en reposo, listo. Hacer que esas claves estén disponibles de forma segura para los usuarios de un producto que estás distribuyendo es un problema genuinamente difícil. El enfoque ingenuo (credenciales en una base de datos compartida) crea exposición de seguridad. El enfoque correcto (OAuth por usuario con aislamiento adecuado de credenciales) añade semanas de trabajo de ingeniería que la mayoría de los tutoriales de agentes no mencionan porque no están construyendo productos, están construyendo demos.
Cualquiera que planee lanzar un producto de agentes debería presupuestar 2–3 veces más tiempo para la arquitectura de autenticación de lo que estiman inicialmente.
La realidad de costos que nadie quiere calcular
Al precio actual de la API de Anthropic, un agente personal activo usando Claude Opus 4.6 con múltiples sesiones diarias y flujos de trabajo complejos con múltiples herramientas cuesta aproximadamente $200–$400 por mes en costos de API. Eso es antes de los costos de VPS, costos de base de datos y tarifas de APIs de terceros.
Compara eso con una suscripción a Claude Pro a $20/mes. Para un consumidor que obtiene resultados ligeramente mejores de un agente personalizado que de una suscripción a Claude Pro, las cuentas no cuadran. No cuadran en absoluto.
Esto no significa que los productos de agentes no sean viables. Significa que actualmente son productos B2B — casos donde el costo del agente es pequeño comparado con el valor que genera. Asesoré a un agente de auditoría de cumplimiento HIPAA que cuesta $50–$100 por informe en llamadas a la API, pero detecta brechas de cumplimiento que costarían $10,000–$50,000 en tiempo de ingeniería identificarlas manualmente. Esas cuentas sí cuadran. Un agente de atención al cliente que maneja el 80% de los tickets de nivel 1 de forma autónoma, reduciendo el costo de personal en $15,000/mes — esas cuentas sí cuadran.
Para uso personal con los planes de suscripción de Anthropic: la asignación de tokens cubre un uso razonable de agente personal. Luna, ejecutando mis flujos de trabajo diarios, se mantiene bien dentro de los límites de suscripción. El problema surge solo si quieres ofrecer tu agente como producto, ya que los beneficios de la suscripción no son transferibles a tus usuarios. En el momento en que quieres servir a usuarios externos, estás en la facturación de API.
Opinión honesta: construí Luna para uso personal, subsidiada por mi suscripción. La experiencia es genuinamente excelente. Si quisiera productizar Luna y cobrar a los consumidores $15/mes por acceso, la economía unitaria no funciona todavía. Lo revisaré en 18 meses a medida que la eficiencia de los modelos siga mejorando.
Los productos de agentes para consumidores requieren o bien LLMs locales (que aún consumen muchos recursos y no son lo suficientemente capaces para tareas complejas multiplataforma) o paciencia para que las curvas de precios bajen más. Ambas cosas están llegando. Ninguna es una estrategia de lanzamiento viable hoy.
Qué cambia realmente cuando construyes esto bien
Soy deliberadamente cuidadoso con las afirmaciones de productividad porque la mayoría están infladas. Así que déjame darte números específicos de mi propio flujo de trabajo.
Antes de Luna: 45–60 minutos cada mañana revisando Slack, escaneando Gmail, extrayendo métricas de Chartmogul y revisando notificaciones de App Store Connect. El tiempo no se gastaba en ninguna plataforma individual — se gastaba en el cambio de contexto entre todas ellas. Cada cambio conlleva sobrecarga cognitiva: reingresar al contexto mental de esa plataforma, descifrar qué necesita atención, decidir qué puede esperar.
Después de Luna: 8–12 minutos. El resumen matutino de Luna llega como notificación push antes de que abra mi portátil. Dos elementos necesitan atención inmediata. Cinco necesitan respuesta en el día. Todo lo demás está catalogado y disponible si lo necesito. Abro mi portátil sabiendo exactamente dónde invertir mi primera hora.
Eso son 35–50 minutos recuperados diariamente. En un mes laboral, aproximadamente 15 horas. Uso esas horas construyendo cosas.
El tiempo de respuesta de 1–2 minutos de Luna para consultas complejas es la verdadera contrapartida — y quiero dejar claro que es una contrapartida genuina, no una molestia menor. Para preguntas factuales rápidas, el tiempo de respuesta es frustrante. Pero para las tareas que Luna realmente maneja, la profundidad lo justifica. Cuando le pido que identifique comunicaciones urgentes en cinco plataformas, genuinamente revisa las cinco, aplica lógica de relevancia y sintetiza el resultado. Un agente más rápido pero más superficial requeriría que yo verificara sus conclusiones, lo cual anula el propósito.
El patrón que vale la pena interiorizar: construye agentes rápidos para tareas de alta frecuencia y baja complejidad. Construye agentes minuciosos para tareas de baja frecuencia y alta complejidad. Luna está optimizada para lo segundo. Intentar hacerla rápida la haría superficial, y superficial anula el propósito.
Qué viene después para esta arquitectura
Los sub-agentes son la siguiente iteración que estoy diseñando activamente. La arquitectura actual de Luna es un único agente con múltiples herramientas. La próxima versión ejecuta agentes especialistas — uno enfocado puramente en correo electrónico y comunicación, uno en métricas de negocio, uno en gestión de proyectos — coordinados por un agente orquestador principal que delega trabajo y sintetiza resultados.
Esto refleja cómo funcionan los equipos efectivos. Especialistas para dominios específicos. Un coordinador que es dueño de la síntesis y sabe a qué especialista consultar. Ninguna persona individual intentando ser experta en todo simultáneamente. El mismo principio escala limpiamente a los agentes.
El streaming es la mejora de experiencia que más me emociona implementar. Ahora mismo, Luna espera hasta tener una respuesta completa antes de devolver algo. El streaming mostraría su razonamiento en tiempo real — verías las llamadas a herramientas ocurriendo, los resultados intermedios acumulándose, el proceso de decisión desenvolviéndose. Para tareas de 2 minutos, ver a un agente trabajar activamente es dramáticamente mejor que ver un spinner de progreso.
El control directo del ordenador cierra la última brecha importante. Ahora mismo, cualquier plataforma sin API está fuera del alcance de Luna. Con el control del ordenador, esa restricción desaparece — el agente interactúa con cualquier interfaz, no solo con las que exponen acceso programático.
Aquí es donde te dejo — y esto es un desafío genuino, no un recurso retórico:
Piensa en un flujo de trabajo en tu rutina diaria actual que requiera tres o más pasos manuales en diferentes plataformas. No un flujo de trabajo hipotético futuro. Algo que hagas esta semana. Tal vez sea la rutina de preparación antes de tu standup del lunes. Tal vez sea un proceso de reporte semanal que implica extraer datos de dos herramientas y formatearlos para una tercera. Tal vez sea algo específico de tu industria.
Ese es tu primer agente. No una gran visión. No una jugada de plataforma. Un flujo de trabajo acotado y específico con entradas accesibles por API y una definición clara de "terminado".
Constrúyelo. Haz que funcione. Mide cuánto tiempo te ahorra. Luego expande.
El Anthropic Agent SDK está listo. La arquitectura que he descrito — el bucle, el sistema de habilidades, la memoria de tres niveles, el despliegue dividido — es construible por un solo desarrollador en dos a tres semanas enfocadas. La infraestructura existe. Las herramientas son reales.
¿Cuál es el flujo de trabajo que vas a construir primero?
Trabajemos juntos
¿Buscas construir sistemas de IA, automatizar flujos de trabajo o escalar tu infraestructura tecnológica? Me encantaría ayudar.
- Fiverr (proyectos personalizados e integraciones): fiverr.com/s/EgxYmWD
- Portfolio: mejba.me
- Ramlit Limited (soluciones empresariales): ramlit.com
- ColorPark (diseño y branding): colorpark.io
- xCyberSecurity (servicios de seguridad): xcybersecurity.io
