INTERMEDIO Bloque 2 — Sube de nivel con Claude Code · 20 min

Crea tu primer agente de IA desde cero

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.

📋 Antes de esta guía, completa: Guía 05 — Instala Claude Code · Guía 06 — MCP Servers

"Un agente no espera instrucciones. Toma decisiones, ejecuta pasos y te entrega resultados."

3
herramientas
20
minutos
1
agente funcional
1

Qué es un agente y en qué se diferencia de un prompt

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.

  • Un prompt: tú escribes → Claude responde → listo. Una sola interacción. Tú decides qué hacer con la respuesta y cuándo actuar.
  • Un agente: tú das un objetivo → él planifica → ejecuta paso 1 → evalúa el resultado → ejecuta paso 2 → repite hasta completar el objetivo. Opera de forma autónoma.

El loop de un agente en la práctica:

INPUT Tu objetivo CLAUDE Decide qué hacer HERRAMIENTA Ejecuta acción OUTPUT Resultado final

El loop de un agente: hasta completar el objetivo

Casos de uso reales donde un agente supera a un prompt:

  • Agente investigador: busca en internet, sintetiza múltiples fuentes y escribe un reporte completo
  • Agente de contenido: lee un brief, genera 5 formatos diferentes y los guarda en Notion
  • Agente de datos: lee un CSV, lo limpia, genera análisis y crea visualizaciones
2

Los componentes de un agente básico

Todo agente, sin importar su complejidad, tiene los mismos cuatro componentes. Entender cada uno te ayuda a diseñar mejores agentes desde el principio.

1
Objetivo
Qué debe lograr el agente. Cuanto más específico, mejor. "Investigar IA" es vago. "Buscar las 5 noticias más importantes sobre IA esta semana y resumirlas en 3 líneas cada una" es accionable.
2
Herramientas
Qué puede hacer el agente. Son funciones que tú defines: buscar_web, leer_archivo, escribir_archivo, enviar_email. Claude decide cuándo y cómo usarlas según el contexto.
3
Memoria
Qué sabe y recuerda el agente. Puede ser el historial de la conversación, datos de contexto que le das al inicio, o información que va acumulando durante la ejecución.
4
Output
Qué produce al finalizar. Un archivo, un mensaje, una serie de acciones completadas, datos estructurados. Define el output esperado antes de escribir el agente.

En código, el concepto se ve así (pseudocódigo para entender la estructura):

python
# 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.

3

Tu primer agente — el investigador de temas

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.

python
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)
g07-agent-running
4

Cómo probarlo y ajustarlo

Setup rápido: necesitas Python instalado y la biblioteca de Anthropic.

bash
# 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:

Error
AuthenticationError: API key not found
Solución
La variable de entorno no está configurada en la sesión actual. Vuelve a correr el comando export ANTHROPIC_API_KEY="..." en la misma terminal donde corres el script.
Error
El agente usa una herramienta pero dice "Tool not found" o falla silenciosamente
Solución
El nombre en la definición de la herramienta (campo "name") debe coincidir exactamente con el nombre en la función ejecutar_herramienta. Revisa mayúsculas y guiones bajos.
Error
El agente llega a las 10 iteraciones sin completar el objetivo
Solución
Sube el límite de iteraciones en el 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:

Prompt — Mejorar el agente con Claude Code

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?

5

Ideas para tu propio agente

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:

💼
FREELANCER / CONSULTOR
Agente que revisa tu inbox cada mañana, identifica emails de potenciales clientes, descarta los no relevantes, y te presenta un resumen con los 3 leads más calientes del día y un borrador de respuesta para cada uno.
🛒
E-COMMERCE
Agente que monitorea los precios de tus principales competidores, los compara con los tuyos, y genera un reporte semanal con alertas cuando hay cambios significativos o cuando un competidor lanza una promoción.
✍️
CREADOR DE CONTENIDO
Agente que toma un tema o keyword, investiga las tendencias actuales sobre ese tema, y genera automáticamente 5 borradores en diferentes formatos: hilo de Twitter, post de LinkedIn, guión de Reels, newsletter y artículo largo.
🎧
SERVICIO AL CLIENTE
Agente que lee los nuevos tickets de soporte, los clasifica por urgencia y tipo de problema, sugiere una respuesta basada en tu base de conocimiento, y escala automáticamente los casos que requieren atención humana.
📊
MARKETING
Agente que revisa tus métricas semanales (tráfico, conversiones, redes sociales), identifica tendencias positivas y negativas, y genera automáticamente el informe ejecutivo para el equipo con conclusiones y próximos pasos recomendados.

Usa este prompt directamente en Claude Code para que construya tu agente personalizado:

Prompt — Generar 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.

🚀
Siguiente nivel: En la próxima guía aprenderás a agregar memoria persistente a tu agente — para que recuerde contexto entre sesiones, aprenda de interacciones pasadas y mejore con el uso.

¿Cómo aplicarlo según tu negocio?

🏢 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.

¿QUIERES IR MÁS PROFUNDO?

Esta guía es el punto de partida.

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 →
SIGUIENTE GUÍA

Sistema de memoria para tus agentes de IA

Aprende a darle memoria persistente a tu agente para que recuerde contexto entre sesiones y mejore con cada interacción.

VER GUÍA 08 →
EXPERTOS AI BUILDER

¿Y si en vez de leer
lo ejecutas?

Te enseñamos a construir tu propio sistema de contenido con IA desde cero.

VER LA COMUNIDAD →