Introducción: más allá del chat
Cuando usas Claude en una conversación, estás aprovechando solo una fracción de su potencial. Los agentes IA son diferentes: son sistemas que toman decisiones, ejecutan código, consultan fuentes externas y se adaptan según los resultados. Para programadores, esto abre un mundo de posibilidades.
En este tutorial, te mostraremos cómo construir agentes prácticos usando Claude Code, el protocolo MCP (Model Context Protocol) y una orquestación efectiva. No es magia; es ingeniería aplicada.
Qué son los agentes IA y por qué importan
Un agente IA es un sistema que:
- Recibe una tarea de alto nivel
- Desglosa el problema en pasos
- Ejecuta código o consulta herramientas
- Evalúa los resultados
- Se ajusta y repite hasta alcanzar el objetivo
A diferencia de un chatbot que responde preguntas, un agente es proactivo. Puede validar datos, llamar a APIs, analizar archivos y tomar decisiones sin intervención humana constante.
Caso real: procesar y validar pedidos
Imagina que recibes cientos de pedidos en JSON. Un agente podría:
- Leer el archivo de pedidos
- Validar esquema y datos (cantidad, precios, cliente)
- Consultar un inventario (vía API)
- Crear reportes de disponibilidad
- Actualizar una base de datos
- Enviar notificaciones
Todo sin que tú ejecutes cada paso manualmente.
Claude Code: tu aliado para código ejecutable
Claude Code es la capacidad de Claude para escribir, analizar y ejecutar código Python directamente en la conversación. Aquí no solo genera snippets; el código se ejecuta y tú ves los resultados en tiempo real.
Cómo usar Claude Code en un agente
Cuando activas Claude Code, puedes:
- Escribir funciones que procesen datos
- Importar librerías (pandas, requests, json, etc.)
- Debuggear en vivo observando outputs
- Iterar rápidamente sin copiar código a tu editor local
Ejemplo básico:
import json
import requests
# Función para validar un pedido
def validar_pedido(pedido):
errores = []
if not pedido.get('id'):
errores.append('Falta ID de pedido')
if pedido.get('cantidad', 0) <= 0:
errores.append('Cantidad debe ser mayor a 0')
if pedido.get('precio', 0) < 0:
errores.append('Precio no puede ser negativo')
return {
'valido': len(errores) == 0,
'errores': errores
}
# Prueba
pedido_test = {'id': '001', 'cantidad': 5, 'precio': 29.99}
print(validar_pedido(pedido_test))Este código ejecutable te permite ver el resultado inmediatamente. Si hay errores, Claude te ayuda a corregirlos en la misma conversación.
MCP: conectando tu agente al mundo exterior
El Protocolo de Contexto de Modelo (MCP) es el puente entre Claude y herramientas externas. Piensa en ello como un API estandarizado que permite que Claude acceda a recursos sin necesidad de integraciones custom complejas.
Recursos típicos en MCP
- Bases de datos: consultar y actualizar registros
- APIs externas: llamadas a servicios web
- Sistemas de archivos: lectura y escritura estructurada
- Herramientas especializadas: análisis, transformación, búsqueda
Para crear un agente con MCP:
- Define los recursos que necesita acceder
- Especifica qué operaciones puede hacer (lectura, escritura, análisis)
- Dale a Claude las instrucciones sobre cuándo usar cada recurso
- Monitorea las llamadas para auditoría y debugging
Un agente sin límites es un caos. Siempre define permisos explícitos en MCP: qué tablas puede tocar, qué endpoints llamar, qué archivos leer. La seguridad y la lógica van juntas.
Construyendo tu primer agente: validador de datos
Te presentamos un agente práctico para validar un dataset de contactos.
Prompt de orquestación
Este es el prompt que le darías a Claude para que maneje todo el flujo:
Eres un agente de validación de datos. Tu tarea es:
1. Recibir un archivo JSON con contactos (nombre, email, teléfono, empresa)
2. Validar cada campo según estas reglas:
- nombre: no vacío, máx 100 caracteres
- email: formato válido (contiene @, punto)
- teléfono: solo dígitos y símbolos +- permitidos
- empresa: no vacío si el contacto es B2B
3. Generar un reporte con:
- Contactos válidos (con ID)
- Contactos rechazados (motivo del error)
- Estadísticas (% validación, errores más frecuentes)
4. Guardar el resultado en un JSON limpio
Si encuentras ambigüedades, pregunta al usuario antes de proceder.Flujo de ejecución
- Recepción: el agente recibe el archivo
- Análisis: ejecuta código Python para validar cada contacto
- Consulta (si aplica): vía MCP, verifica dominios de email en una lista de permitidos
- Decisión: marca cada registro como válido o rechazado
- Salida: genera el reporte estructurado
Errores comunes y cómo evitarlos
1. No definir límites al agente
Si le dices “valida y actualiza lo que necesites”, puede hacer cambios inesperados. Sé específico: “valida y reporta, pero NO actualices nada sin confirmación”.
2. Olvidar el logging
Siempre que tu agente ejecute código o llame a recursos, guarda qué hizo. Te salvará en debugging.
3. Asumir que una pasada es suficiente
Los agentes son iterativos. Si el 10% de datos falla, el agente debe reportarlo y preguntar si reintentar con reglas más flexibles.
4. No versionar el agente
Cuando mejoras las reglas de validación o añades nuevos recursos MCP, documenta qué cambió. Luego puedes replicar resultados.
Pasos siguientes
- Experimenta con Claude Code: crea funciones simples, pruébalas en vivo
- Mapea tus recursos MCP: qué datos necesita tocar tu agente
- Define reglas claras: escribe el prompt de orquestación de forma exhaustiva
- Prueba con datos pequeños: antes de lanzar a producción
- Monitorea y ajusta: los agentes mejoran con feedback
Los agentes IA no son el futuro lejano. Son herramientas que puedes construir hoy, con Claude, sin necesidad de frameworks complejos. Empieza pequeño, prueba en vivo con Claude Code, y escala cuando tengas confianza en el comportamiento del agente.