Un agente de IA es un programa que usa Claude como cerebro para tomar decisiones y ejecutar tareas de forma autónoma. Esta guía te enseña a construir uno desde cero.
"Un agente no espera instrucciones. Toma decisiones, ejecuta pasos y te entrega resultados."
Si alguna vez imaginaste tener un asistente de IA que trabaja solo — busca información, toma decisiones y entrega resultados sin que tengas que guiarlo paso a paso, esta guía es para ti.
Hay una diferencia fundamental entre usar Claude con un prompt y construir un agente. Entenderla es clave para saber cuándo necesitas uno.
El loop de un agente en la práctica:
El loop de un agente: hasta completar el objetivo
Casos de uso reales donde un agente supera a un prompt:
Todo agente, sin importar su complejidad, tiene los mismos cuatro componentes. Entender cada uno te ayuda a diseñar mejores agentes desde el principio.
En código, el concepto se ve así (pseudocódigo para entender la estructura):
# Pseudocódigo de un agente básico
agente = Agente(
objetivo="Investigar competidores y crear reporte",
herramientas=[buscar_web, leer_archivo, escribir_archivo],
memoria="Empresa: MiSaaS, Industria: CRM, Mercado: LATAM"
)
resultado = agente.ejecutar()
# Claude decide: buscar → leer resultados → sintetizar → escribir reporte
💡 En Expertos AI Builder usamos esto para automatizar la generación de reportes semanales. El agente busca los datos en Notion, los analiza, redacta el resumen ejecutivo y lo guarda listo para enviar. Cero intervención manual.
Aquí está el código completo de un agente funcional. Tiene dos herramientas: buscar_informacion y guardar_reporte. Claude decide cuándo usar cada una según el objetivo que le des. Cada línea está comentada en español para que entiendas exactamente qué hace.
import anthropic
import json
client = anthropic.Anthropic()
# Definición de herramientas que el agente puede usar
tools = [
{
"name": "buscar_informacion",
"description": "Busca información sobre un tema. Úsala cuando necesites datos actuales o información específica que no tengas.",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "La búsqueda a realizar"
}
},
"required": ["query"]
}
},
{
"name": "guardar_reporte",
"description": "Guarda el reporte final en un archivo. Úsala cuando hayas completado la investigación.",
"input_schema": {
"type": "object",
"properties": {
"nombre_archivo": {
"type": "string",
"description": "Nombre del archivo (sin extensión)"
},
"contenido": {
"type": "string",
"description": "El contenido del reporte"
}
},
"required": ["nombre_archivo", "contenido"]
}
}
]
def ejecutar_herramienta(nombre, argumentos):
"""Simula la ejecución de herramientas."""
if nombre == "buscar_informacion":
# En producción: conectar a API de búsqueda real (ej. Brave Search MCP)
query = argumentos["query"]
print(f" Buscando: {query}")
return f"Resultados de búsqueda para '{query}': [aquí irían los resultados reales]"
elif nombre == "guardar_reporte":
nombre_archivo = argumentos["nombre_archivo"]
contenido = argumentos["contenido"]
# Escribe el archivo en el directorio actual
with open(f"{nombre_archivo}.md", "w", encoding="utf-8") as f:
f.write(contenido)
print(f" Reporte guardado: {nombre_archivo}.md")
return f"Reporte guardado exitosamente como {nombre_archivo}.md"
return "Herramienta no encontrada"
def correr_agente(objetivo):
"""Loop principal del agente."""
print(f"\nAgente iniciado\nObjetivo: {objetivo}\n{'─'*50}")
# El historial de mensajes es la memoria del agente
mensajes = [{"role": "user", "content": objetivo}]
for iteracion in range(10): # máximo 10 iteraciones para evitar loops infinitos
print(f"\n[Iteración {iteracion + 1}]")
# Llamada a Claude con las herramientas disponibles
respuesta = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
tools=tools,
messages=mensajes
)
# Si Claude terminó (no hay más herramientas que usar), mostrar resultado
if respuesta.stop_reason == "end_turn":
for bloque in respuesta.content:
if hasattr(bloque, 'text'):
print(f"\nAgente completado:\n{bloque.text}")
break
# Agregar la respuesta de Claude al historial
mensajes.append({"role": "assistant", "content": respuesta.content})
resultados_herramientas = []
# Procesar cada herramienta que Claude decidió usar
for bloque in respuesta.content:
if bloque.type == "tool_use":
print(f" → Usando herramienta: {bloque.name}")
resultado = ejecutar_herramienta(bloque.name, bloque.input)
# Devolver el resultado de la herramienta a Claude
resultados_herramientas.append({
"type": "tool_result",
"tool_use_id": bloque.id,
"content": resultado
})
# Agregar resultados al historial para que Claude continúe
if resultados_herramientas:
mensajes.append({"role": "user", "content": resultados_herramientas})
# Ejecutar el agente con un objetivo real
if __name__ == "__main__":
objetivo = """
Investiga el tema: "tendencias de marketing digital en 2026".
Busca al menos 3 subtemas diferentes.
Crea un reporte estructurado con:
- Resumen ejecutivo
- 5 tendencias principales con explicación
- Implicaciones para negocios pequeños
Guarda el reporte como 'reporte-marketing-2026'.
"""
correr_agente(objetivo)
Setup rápido: necesitas Python instalado y la biblioteca de Anthropic.
# Instalar la biblioteca de Anthropic
pip install anthropic
# Configurar tu API key (Mac/Linux)
export ANTHROPIC_API_KEY="sk-ant-..."
# Configurar tu API key (Windows - Command Prompt)
set ANTHROPIC_API_KEY=sk-ant-...
# Guardar el código como agente.py y ejecutarlo
python agente.py
Tu API key la encuentras en console.anthropic.com → API Keys. Es un texto que empieza con sk-ant-.
Errores comunes y cómo resolverlos:
AuthenticationError: API key not foundexport ANTHROPIC_API_KEY="..." en la misma terminal donde corres el script."name") debe coincidir exactamente con el nombre en la función ejecutar_herramienta. Revisa mayúsculas y guiones bajos.for iteracion in range(10), o simplifica el objetivo para que requiera menos pasos. Objetivos muy amplios necesitan más iteraciones.Usa este prompt con Claude Code para mejorar el agente automáticamente:
Tengo este agente de Python [pega el código].
Quiero que mejores:
1. El manejo de errores (que no falle si una herramienta falla)
2. Que imprima el progreso de forma más clara
3. Que guarde un log de todas las iteraciones en un archivo
Mantén la estructura básica del loop.
Ejemplo de resultado
He analizado tu agente. Aquí están las mejoras implementadas:
✓ Manejo de errores: cada llamada a herramienta ahora tiene try/except con mensajes claros
✓ Progreso visual: agregué barra de estado con [■■■□□] y tiempo transcurrido
✓ Log completo: cada iteración se guarda en agent_log_2026-04-21.txt con timestamp
El agente mejorado está listo. ¿Quieres que también agregue reintentos automáticos si una herramienta falla?
Ahora que entiendes la estructura, el siguiente paso es construir un agente para tu caso de uso específico. Aquí hay 5 ideas concretas por tipo de negocio:
Usa este prompt directamente en Claude Code para que construya tu agente personalizado:
Quiero crear un agente de Python que [DESCRIBE LO QUE DEBE HACER].
El agente necesita las siguientes herramientas: [LISTA LAS HERRAMIENTAS].
El input será: [QUÉ INFORMACIÓN LE DOY AL INICIO].
El output esperado es: [QUÉ DEBE PRODUCIR].
Usa la biblioteca anthropic con el modelo claude-sonnet-4-6.
Sigue el patrón del loop agentic con tool_use.
Comenta el código línea por línea en español.
Ejemplo de resultado
Agente iniciado
Objetivo: Revisar inbox y clasificar leads del día
──────────────────────────────────────────────────
[Iteración 1]
→ Usando herramienta: leer_emails
Leyendo 14 emails nuevos...
[Iteración 2]
→ Usando herramienta: clasificar_leads
3 leads calientes identificados: María García (presupuesto alto), Carlos López (urgente), Ana Torres (referido)
[Iteración 3]
→ Usando herramienta: guardar_reporte
Reporte guardado: leads-2026-04-21.md ✓
Agente completado: Encontré 3 leads prioritarios hoy. El reporte está en tu carpeta con borradores de respuesta para cada uno.
🏢 Agencia o consultor
Construye un agente de investigación que analice el sitio del competidor del cliente, extraiga su propuesta de valor y genere un análisis de diferenciación en 3 minutos.
🛍️ Producto o servicio
Crea un agente de soporte que responda FAQs desde tu base de conocimiento. Maneja el 70% de las consultas sin intervención humana.
🎬 Creador de contenido
Agente que monitorea trending topics en tu nicho, los filtra por relevancia para tu audiencia y te entrega 5 ideas de contenido cada lunes.
En la comunidad Expertos AI Builder tienes el workshop completo en video, plantillas listas y soporte directo para implementarlo en tu negocio.
Ver la comunidad →Aprende a darle memoria persistente a tu agente para que recuerde contexto entre sesiones y mejore con cada interacción.
VER GUÍA 08 →