Claude Agent SDK: Construye Agentes IA Autónomos

El Claude Agent SDK representa un cambio fundamental en cómo construimos software. No son solo asistentes de código que sugieren líneas—son agentes autónomos capaces de ejecutar tareas complejas, tomar decisiones y verificar su propio trabajo.

🤖 ¿Qué es el Claude Agent SDK?

El Claude Agent SDK es el conjunto de herramientas oficiales de Anthropic para construir agentes de IA autónomos. Evolucionó directamente desde Claude Code, la herramienta CLI que ya conoces, pero ahora disponible como SDK para integrar en tus propias aplicaciones.

Diferencia clave:

• Copilot/Cursor: Sugieren código mientras escribes
• Claude Code CLI: Ejecuta tareas completas en terminal
• Claude Agent SDK: Construye tus propios agentes autónomos

🔧 Características Principales

1. Búsqueda Agéntica

Los agentes pueden navegar y buscar en sistemas de archivos completos. No solo leen archivos—entienden la estructura del proyecto, encuentran patrones y localizan código relevante automáticamente.

// El agente puede buscar de forma inteligente
// Combina grep, búsqueda semántica y comprensión de código
const agent = await createAgent({
  model: 'claude-sonnet-4',
  tools: ['search', 'fileSystem', 'bash']
});

// Busca automáticamente en todo el proyecto
const result = await agent.query(
  "Encuentra todos los memory leaks en componentes React"
);

2. Subagentes Paralelos

Multiplica la capacidad de procesamiento ejecutando múltiples agentes simultáneamente. Cada subagente trabaja en su propia ventana de contexto aislada.

Sin Subagentes:

• 1 agente → 200K tokens contexto
• Procesa tareas secuencialmente

Con Subagentes:

• 5 subagentes → 1M tokens total
• Procesa tareas en paralelo

3. Gestión Automática de Contexto

El SDK incluye "compaction"—resumen automático de conversaciones largas para evitar quedarse sin contexto. El agente mantiene información relevante y descarta lo innecesario.

4. Model Context Protocol (MCP)

Integración estandarizada con servicios externos. Conecta tu agente con Slack, GitHub, Google Drive, bases de datos y más—todo con autenticación manejada automáticamente.

💻 Ejemplo Práctico: Agente de Facturación SAT

Vamos a construir un agente que procesa facturas CFDI 4.0 del SAT automáticamente. Valida XMLs, extrae información, calcula impuestos y genera reportes. Caso de uso real que le ahorra horas a cualquier contador o negocio mexicano.

Instalación

npm install @anthropic-ai/claude-agent-sdk
npm install zod xml2js  # Para validación y parseo de XML

Configuración Básica

import { createAgent } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';
import { parseString } from 'xml2js';

// Configurar el agente con conocimiento del SAT
const facturaAgent = await createAgent({
  model: 'claude-sonnet-4',
  apiKey: process.env.ANTHROPIC_API_KEY,

  tools: [
    'fileOperations',  // Leer XMLs
    'bash',            // Ejecutar comandos
    'webSearch'        // Consultar reglas SAT actualizadas
  ],

  // Contexto inicial con reglas del SAT
  systemPrompt: `Eres un experto en facturación electrónica mexicana.
    Conoces:
    - CFDI 4.0 (Comprobante Fiscal Digital por Internet)
    - Validaciones del SAT
    - Cálculo de IVA, ISR, retenciones
    - Complementos de pago
    - Catálogos SAT vigentes

    Valida facturas contra las reglas oficiales del SAT.`
});

Crear Herramientas Personalizadas

// Herramienta para validar estructura CFDI
const validarCFDI = {
  name: 'validar_cfdi',
  description: 'Valida estructura de factura CFDI 4.0',
  inputSchema: z.object({
    xmlPath: z.string().describe('Ruta al archivo XML')
  }),
  run: async (input) => {
    const fs = require('fs');
    const xml = fs.readFileSync(input.xmlPath, 'utf-8');

    const errores = [];

    // Validar versión CFDI
    if (!xml.includes('Version="4.0"')) {
      errores.push({
        tipo: 'VERSION',
        mensaje: 'No es CFDI 4.0',
        gravedad: 'alta'
      });
    }

    // Validar RFC emisor
    const rfcMatch = xml.match(/Rfc="([A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3})"/);
    if (!rfcMatch) {
      errores.push({
        tipo: 'RFC_EMISOR',
        mensaje: 'RFC emisor inválido o no encontrado',
        gravedad: 'alta'
      });
    }

    // Validar sello digital
    if (!xml.includes('Sello=')) {
      errores.push({
        tipo: 'SELLO',
        mensaje: 'Factura sin sello digital',
        gravedad: 'alta'
      });
    }

    // Validar UUID
    const uuidMatch = xml.match(/UUID="([A-F0-9-]{36})"/i);
    if (!uuidMatch) {
      errores.push({
        tipo: 'UUID',
        mensaje: 'Folio fiscal (UUID) inválido',
        gravedad: 'alta'
      });
    }

    return JSON.stringify({
      valido: errores.length === 0,
      errores,
      uuid: uuidMatch?.[1] || null
    }, null, 2);
  }
};

// Herramienta para extraer datos fiscales
const extraerDatos = {
  name: 'extraer_datos_fiscales',
  description: 'Extrae información clave de la factura',
  inputSchema: z.object({
    xmlPath: z.string().describe('Ruta al archivo XML')
  }),
  run: async (input) => {
    const fs = require('fs');
    const xml = fs.readFileSync(input.xmlPath, 'utf-8');

    let datos = {};

    parseString(xml, (err, result) => {
      if (err) {
        datos = { error: 'XML mal formado' };
        return;
      }

      const cfdi = result['cfdi:Comprobante'];
      const emisor = cfdi['cfdi:Emisor'][0].$;
      const receptor = cfdi['cfdi:Receptor'][0].$;

      datos = {
        // Datos generales
        fecha: cfdi.$.Fecha,
        folio: cfdi.$.Folio || 'Sin folio',
        serie: cfdi.$.Serie || 'Sin serie',
        formaPago: cfdi.$.FormaPago,
        metodoPago: cfdi.$.MetodoPago,

        // Emisor
        emisor: {
          rfc: emisor.Rfc,
          nombre: emisor.Nombre,
          regimenFiscal: emisor.RegimenFiscal
        },

        // Receptor
        receptor: {
          rfc: receptor.Rfc,
          nombre: receptor.Nombre,
          usoCFDI: receptor.UsoCFDI
        },

        // Importes
        subtotal: parseFloat(cfdi.$.SubTotal),
        descuento: parseFloat(cfdi.$.Descuento || '0'),
        total: parseFloat(cfdi.$.Total),

        // Impuestos
        impuestos: this.calcularImpuestos(cfdi)
      };
    });

    return JSON.stringify(datos, null, 2);
  }
};

// Herramienta para calcular impuestos
const calcularImpuestos = {
  name: 'calcular_impuestos',
  description: 'Calcula desglose de impuestos',
  inputSchema: z.object({
    xmlPath: z.string().describe('Ruta al archivo XML')
  }),
  run: async (input) => {
    const fs = require('fs');
    const xml = fs.readFileSync(input.xmlPath, 'utf-8');

    let impuestos = {
      trasladados: [],
      retenidos: [],
      totalTrasladado: 0,
      totalRetenido: 0
    };

    parseString(xml, (err, result) => {
      const cfdi = result['cfdi:Comprobante'];
      const impuestosNode = cfdi['cfdi:Impuestos']?.[0];

      if (!impuestosNode) return;

      // IVA trasladado
      const trasladados = impuestosNode['cfdi:Traslados']?.[0]?.['cfdi:Traslado'] || [];
      trasladados.forEach(t => {
        const imp = t.$;
        impuestos.trasladados.push({
          impuesto: imp.Impuesto === '002' ? 'IVA' : 'IEPS',
          tasa: parseFloat(imp.TasaOCuota) * 100 + '%',
          importe: parseFloat(imp.Importe)
        });
        impuestos.totalTrasladado += parseFloat(imp.Importe);
      });

      // Retenciones
      const retenidos = impuestosNode['cfdi:Retenciones']?.[0]?.['cfdi:Retencion'] || [];
      retenidos.forEach(r => {
        const imp = r.$;
        impuestos.retenidos.push({
          impuesto: imp.Impuesto === '002' ? 'IVA' : 'ISR',
          importe: parseFloat(imp.Importe)
        });
        impuestos.totalRetenido += parseFloat(imp.Importe);
      });
    });

    return JSON.stringify(impuestos, null, 2);
  }
};

// Registrar herramientas en el agente
facturaAgent.addTools([validarCFDI, extraerDatos, calcularImpuestos]);

Procesar Factura Automáticamente

// Función principal de procesamiento
async function procesarFactura(xmlPath: string) {
  const fs = require('fs');

  // 1. Validar estructura CFDI
  console.log('📋 Validando factura...');

  const analisis = await facturaAgent.query(
    `Analiza esta factura del SAT: ${xmlPath}

    1. Valida que sea CFDI 4.0 correcto
    2. Extrae todos los datos fiscales
    3. Calcula el desglose de impuestos
    4. Genera un resumen ejecutivo en español
    5. Identifica cualquier irregularidad

    Usa las herramientas que te di para hacer el análisis completo.`,
    {
      stream: true,
      onProgress: (chunk) => {
        console.log(chunk); // Progreso en tiempo real
      }
    }
  );

  // 2. Generar reporte
  const reporte = `
# 🧾 Reporte de Factura

${analisis.response}

## ⚠️ Acciones Requeridas
- Verificar que el UUID esté en el portal del SAT
- Confirmar que los montos coincidan con el pedido
- Validar que el RFC del emisor esté activo

---
*Análisis generado con Claude Agent SDK*
`;

  // 3. Guardar reporte
  const reportPath = xmlPath.replace('.xml', '_reporte.md');
  fs.writeFileSync(reportPath, reporte);

  console.log(`✅ Reporte guardado en: ${reportPath}`);

  return analisis;
}

// Procesar una factura
procesarFactura('./facturas/factura_2024_001.xml');

// Procesar carpeta completa
async function procesarCarpeta(dir: string) {
  const fs = require('fs');
  const files = fs.readdirSync(dir)
    .filter(f => f.endsWith('.xml'));

  for (const file of files) {
    await procesarFactura(`${dir}/${file}`);
  }
}

procesarCarpeta('./facturas/octubre-2024');

🎯 Casos de Uso Reales para México

Contabilidad y Finanzas

• Procesamiento de Facturas SAT: El agente que acabamos de construir, valida CFDI 4.0 automáticamente
• Cálculo de Nómina: Procesa nómina con retenciones IMSS, Infonavit, ISR según LFT
• Conciliación Bancaria: Valida CLABE, procesa archivos SPEI, concilia pagos automáticamente
• Declaraciones SAT: Genera reportes mensuales listos para presentar

E-commerce y Ventas

• Bot WhatsApp Business: Responde consultas, genera cotizaciones, procesa pedidos vía WhatsApp
• Integración Mercado Libre: Sincroniza inventario, responde preguntas, ajusta precios según competencia
• Análisis de Competencia: Monitorea precios y estrategias de competidores en marketplaces mexicanos
• Facturación Automática: Genera facturas CFDI desde pedidos de tienda online

Legal y Compliance

• Análisis de Contratos: Revisa contratos de arrendamiento, compraventa, servicios contra código civil/comercio mexicano
• Avisos de Privacidad LFPD: Genera avisos de privacidad conforme a regulación mexicana
• Compliance Regulatorio: Verifica cumplimiento con SAT, IMSS, protección de datos
• Generación de Formatos Oficiales: Llena automáticamente formatos SAT, IMSS, Infonavit

Desarrollo de Software

• Code Review Automático: Revisa pull requests, verifica estándares, encuentra bugs
• Migración de Código: Moderniza proyectos legacy a tecnologías actuales
• Generación de Documentación: Crea docs técnicos y manuales de usuario automáticamente
• Debugging Inteligente: Encuentra y corrige bugs con análisis completo del codebase

⚡ Arquitectura del Agente

Los agentes del SDK operan en un ciclo de feedback continuo:

Ciclo de Ejecución:

1. Recopilar Contexto: Busca archivos relevantes, ejecuta comandos, obtiene información
2. Tomar Acción: Edita código, ejecuta herramientas, genera contenido
3. Verificar Trabajo: Ejecuta tests, valida resultados, verifica contra reglas
4. Repetir: Si hay errores o mejoras, vuelve al paso 1

🚀 Consideraciones de Producción

Permisos y Seguridad

const agent = await createAgent({
  model: 'claude-sonnet-4',

  // Limitar capacidades del agente
  permissions: {
    fileOperations: {
      read: ['./src/**'],        // Solo lectura en src
      write: ['./src/generated/**'], // Solo escritura en generated
      delete: []                 // Sin permisos de borrado
    },
    bash: {
      allowedCommands: [
        'npm test',
        'npx eslint',
        'git status'
      ]
    },
    network: {
      allowedDomains: [
        'api.github.com',
        'api.anthropic.com'
      ]
    }
  }
});

Costos y Performance

Claude Sonnet 4:

• $3 USD / 1M tokens input
• $15 USD / 1M tokens output
• Ideal para producción

Claude Haiku:

• $0.25 USD / 1M tokens input
• $1.25 USD / 1M tokens output
• Para tareas simples

Verificación de Calidad

// Usar otro modelo como judge
async function verifyAgentWork(agentOutput: string) {
  const judge = await createAgent({
    model: 'claude-opus-4',
    systemPrompt: `Verifica que el código generado:
      1. Cumple con estándares de TypeScript
      2. No tiene vulnerabilidades
      3. Está correctamente documentado`
  });

  const verification = await judge.query(
    `Revisa este código generado por un agente:

    ${agentOutput}

    ¿Es correcto y seguro? Detalla cualquier problema.`
  );

  return verification.response;
}

📚 Recursos y Próximos Pasos

Documentación Oficial:

• docs.claude.com/en/api/agent-sdk

Código Open Source:

• TypeScript SDK
• Python SDK

Comunidad:

• Únete a Discord de Anthropic para compartir experiencias y resolver dudas

🎯 Conclusión

El Claude Agent SDK democratiza la creación de agentes de IA autónomos. Ya no necesitas ser un experto en ML para construir herramientas que automatizan tareas complejas—solo necesitas entender el problema que quieres resolver.

Empieza Hoy:

1. Identifica un proceso manual: Code review, testing, análisis de datos
2. Define herramientas necesarias: ¿Qué necesita hacer el agente?
3. Construye un prototipo: Empieza simple, itera rápido
4. Verifica y mejora: Usa otro agente como judge

La era de los agentes autónomos ya está aquí. Los desarrolladores que aprendan a construirlos tendrán una ventaja competitiva significativa.

---

¿Quieres dominar Claude Code y el Agent SDK? Únete a nuestro taller práctico donde construirás agentes reales.