Inicio

Fundamentos de SubAgentes

Capítulo 10: Fundamentos de SubAgentes

La Arquitectura de Inteligencia Distribuida

Los subagentes representan una de las capacidades más transformadoras y menos comprendidas de Claude Code. No son simplemente una forma de delegar tareas; representan un paradigma completamente nuevo de desarrollo donde múltiples instancias de inteligencia artificial colaboran, cada una especializada en diferentes aspectos del problema, creando soluciones que ninguna podría lograr individualmente.

Esta capacidad trasciende la simple automatización. Estamos hablando de orquestación inteligente donde cada subagente puede tener su propio contexto, sus propias herramientas, y su propia especialización, pero todos trabajan hacia un objetivo común. Es como tener un equipo completo de desarrolladores expertos, cada uno con su especialidad, trabajando en paralelo y coordinándose automáticamente.

La verdadera revolución de los subagentes no está en su capacidad individual, sino en las propiedades emergentes que surgen cuando múltiples agentes colaboran. Comportamientos complejos emergen de la interacción de agentes simples, soluciones creativas surgen de la combinación de diferentes perspectivas, y la robustez del sistema aumenta dramáticamente cuando cada componente puede compensar las debilidades de otros.

Anatomía de un SubAgente

El Concepto Fundamental

Un subagente es esencialmente una instancia separada de Claude que puede ser invocada con un contexto y objetivo específico. Cada subagente opera independientemente pero puede compartir información con el agente principal y otros subagentes através de mecanismos de comunicación estructurados.

1# Invocación básica de un subagente
2claude "necesito analizar este código en busca de vulnerabilidades de seguridad"
3
4# Claude puede decidir internamente invocar subagentes especializados:
5# - SubAgente de análisis estático
6# - SubAgente de revisión de dependencias
7# - SubAgente de verificación de mejores prácticas
8# - SubAgente de generación de reportes
9

Estructura y Componentes

Cada subagente tiene tres componentes fundamentales que determinan su comportamiento y capacidades:

1// Definición conceptual de un subagente con LlamaIndex
2import { agent } from "@llamaindex/workflow";
3import { tool } from "llamaindex";
4import { openai } from "@llamaindex/openai";
5
6interface SubAgentConfig {
7  contexto: Record<string, any>;     // Información específica del dominio
8  herramientas: any[];               // Tools disponibles para el agente
9  objetivo: string;                  // Misión específica del agente
10}
11
12// Crear un agente especializado
13const crearSubAgente = (config: SubAgentConfig) => {
14  return agent({
15    name: "SubAgente",
16    description: config.objetivo,
17    tools: config.herramientas,
18    llm: openai({ model: "gpt-4o-mini" })
19  });
20};
21

Tipos de SubAgentes Disponibles

Claude Code viene con varios tipos de subagentes predefinidos, cada uno optimizado para diferentes tipos de tareas:

  1. general-purpose: El agente más versátil, capaz de manejar tareas complejas de investigación y desarrollo
  2. code-reviewer: Especializado en análisis de código y sugerencias de mejora
  3. test-generator: Enfocado en crear tests comprehensivos
  4. documentation-writer: Optimizado para generar documentación técnica
  5. security-auditor: Especializado en identificar vulnerabilidades

Creando Tu Primer SubAgente

Ejemplo Básico: Refactoring Assistant

Vamos a crear un flujo simple que usa subagentes para refactorizar código de manera inteligente:

1# Prompt principal para invocar subagentes
2claude "quiero refactorizar el archivo src/components/UserDashboard.tsx"
3
4# Claude internamente puede hacer:
5# 1. Invocar un subagente para analizar el código actual
6# 2. Invocar otro subagente para proponer mejoras
7# 3. Invocar un tercer subagente para verificar que no se rompan tests
8

Implementación Práctica

Cuando trabajas con subagentes, es importante entender cómo estructurar las tareas para aprovechar sus capacidades:

1/**
2 * Ejemplo de orquestación básica de subagentes
3 * para refactorización de código con LlamaIndex
4 */
5
6import { multiAgent } from "@llamaindex/workflow";
7import { agent } from "@llamaindex/workflow";
8import { tool } from "llamaindex";
9import { z } from "zod";
10
11// Definir herramientas para análisis de código
12const readTool = tool({
13  name: "read_file",
14  description: "Lee el contenido de un archivo",
15  parameters: z.object({ path: z.string() }),
16  execute: async ({ path }) => {
17    // Implementación de lectura de archivo
18    return `Contenido del archivo ${path}`;
19  }
20});
21
22// Crear agentes especializados
23const agenteAnalisis = agent({
24  name: "AnalizadorCodigo",
25  description: "Analiza código para identificar mejoras",
26  tools: [readTool],
27  llm: openai({ model: "gpt-4o-mini" })
28});
29
30const agenteRefactor = agent({
31  name: "RefactorExpert",
32  description: "Genera propuestas de refactorización",
33  tools: [],
34  llm: openai({ model: "gpt-4o-mini" })
35});
36
37const agenteValidador = agent({
38  name: "ValidadorTests",
39  description: "Valida que las refactorizaciones no rompen tests",
40  tools: [],
41  llm: openai({ model: "gpt-4o-mini" })
42});
43
44// Orquestación de múltiples agentes
45const orquestarRefactorizacion = async (archivo: string) => {
46  const workflow = multiAgent({
47    agents: [agenteAnalisis, agenteRefactor, agenteValidador],
48    rootAgent: agenteAnalisis
49  });
50
51  const resultado = await workflow.run({
52    prompt: `Analiza y refactoriza el archivo ${archivo}`,
53    stream: true
54  });
55
56  return resultado;
57};
58

Patrones de Comunicación Entre Agentes

Comunicación Secuencial

El patrón más simple donde cada agente procesa y pasa información al siguiente:

1# Flujo secuencial de análisis de proyecto
2claude "analiza la arquitectura del proyecto y sugiere mejoras"
3
4# Flujo interno:
5# AgentA (análisis) → AgentB (evaluación) → AgentC (propuestas)
6

Comunicación Paralela

Múltiples agentes trabajando simultáneamente en diferentes aspectos:

1# Análisis paralelo de diferentes aspectos
2claude "necesito un análisis completo de rendimiento del sistema"
3
4# Ejecución paralela:
5# ├── Agente1: Análisis de queries de base de datos
6# ├── Agente2: Análisis de performance del frontend
7# ├── Agente3: Análisis de uso de memoria
8# └── Agente4: Análisis de latencia de red
9

Comunicación Jerárquica

Un agente maestro coordina múltiples subagentes especializados:

1// Estructura jerárquica de agentes con LlamaIndex
2import { multiAgent, agent } from "@llamaindex/workflow";
3
4interface ProyectoAnalisis {
5  seguridad: string;
6  rendimiento: string;
7  calidad: string;
8  documentacion: string;
9}
10
11// Crear agentes especializados
12const agenteSeguridad = agent({
13  name: "AgenteSeguridad",
14  description: "Analiza vulnerabilidades de seguridad",
15  tools: [],
16  llm: openai({ model: "gpt-4o-mini" })
17});
18
19const agenteRendimiento = agent({
20  name: "AgenteRendimiento",
21  description: "Evalúa métricas de performance",
22  tools: [],
23  llm: openai({ model: "gpt-4o-mini" })
24});
25
26const agenteCalidad = agent({
27  name: "AgenteCalidad",
28  description: "Revisa estándares de código",
29  tools: [],
30  llm: openai({ model: "gpt-4o-mini" })
31});
32
33const agenteDocumentacion = agent({
34  name: "AgenteDocumentacion",
35  description: "Verifica y genera documentación",
36  tools: [],
37  llm: openai({ model: "gpt-4o-mini" })
38});
39
40// Coordinador jerárquico
41const coordinadorWorkflow = multiAgent({
42  agents: [
43    agenteSeguridad,
44    agenteRendimiento,
45    agenteCalidad,
46    agenteDocumentacion
47  ],
48  rootAgent: agenteSeguridad // El coordinador principal
49});
50
51const procesarProyecto = async (proyecto: string): Promise<ProyectoAnalisis> => {
52  const resultado = await coordinadorWorkflow.run({
53    prompt: `Analiza el proyecto ${proyecto} en todas sus dimensiones`
54  });
55
56  return resultado as ProyectoAnalisis;
57};
58

Casos de Uso Prácticos

Debugging Inteligente

Los subagentes pueden colaborar para resolver bugs complejos:

1# Debugging colaborativo
2claude "hay un bug intermitente en el sistema de autenticación"
3
4# Orquestación de subagentes:
5# 1. Agente de logs: Analiza patrones en logs
6# 2. Agente de código: Revisa implementación
7# 3. Agente de tests: Crea tests para reproducir
8# 4. Agente de fixes: Propone soluciones
9

Migración de Código

Para proyectos de migración, los subagentes pueden dividir el trabajo:

1# Migración de JavaScript a TypeScript
2claude "migra el proyecto de JavaScript a TypeScript"
3
4# División del trabajo:
5# - Agente1: Analiza dependencias y compatibilidad
6# - Agente2: Genera tipos para funciones
7# - Agente3: Actualiza configuración del proyecto
8# - Agente4: Verifica que todo compile correctamente
9

Code Review Automatizado

Implementar un proceso de code review multi-perspectiva:

1// Sistema de review con múltiples perspectivas usando LlamaIndex
2import { multiAgent } from "@llamaindex/workflow";
3import { z } from "zod";
4
5// Schema para el resultado del review
6const ReviewResultSchema = z.object({
7  seguridad: z.string(),
8  performance: z.string(),
9  estandares: z.string(),
10  recomendaciones: z.array(z.string())
11});
12
13// Agentes especializados para code review
14const securityAuditor = agent({
15  name: "SecurityAuditor",
16  description: "Audita código para vulnerabilidades de seguridad",
17  tools: [],
18  llm: openai({ model: "gpt-4o-mini" })
19});
20
21const performanceAnalyzer = agent({
22  name: "PerformanceAnalyzer",
23  description: "Analiza impacto en performance",
24  tools: [],
25  llm: openai({ model: "gpt-4o-mini" })
26});
27
28const standardsReviewer = agent({
29  name: "StandardsReviewer",
30  description: "Verifica cumplimiento de estándares",
31  tools: [],
32  llm: openai({ model: "gpt-4o-mini" })
33});
34
35// Workflow de code review completo
36const codeReviewWorkflow = multiAgent({
37  agents: [securityAuditor, performanceAnalyzer, standardsReviewer],
38  rootAgent: securityAuditor
39});
40
41const codeReviewCompleto = async (pullRequest: string) => {
42  const resultado = await codeReviewWorkflow.run({
43    prompt: `Realiza un review completo del PR ${pullRequest}`,
44    structuredOutput: ReviewResultSchema,
45    stream: false
46  });
47
48  return resultado;
49};
50

Configuración y Optimización

Configurando el Contexto de SubAgentes

El contexto es crucial para el rendimiento de los subagentes:

1// Configuración óptima de contexto con TypeScript
2interface ContextoOptimizado {
3  proyecto: {
4    tipo: string;
5    stack: string[];
6    convenciones: string;
7  };
8  objetivoEspecifico: string;
9  restricciones: string[];
10  herramientasPermitidas: string[];
11  formatoSalida: 'json' | 'text' | 'markdown';
12}
13
14const contextoOptimizado: ContextoOptimizado = {
15  proyecto: {
16    tipo: "aplicación web",
17    stack: ["React", "Node.js", "PostgreSQL"],
18    convenciones: "path/to/conventions.md"
19  },
20  objetivoEspecifico: "optimizar queries de base de datos",
21  restricciones: [
22    "mantener compatibilidad con API existente",
23    "no modificar schema de base de datos",
24    "mejorar performance en al menos 20%"
25  ],
26  herramientasPermitidas: ["Read", "Edit", "Bash"],
27  formatoSalida: "json"
28};
29
30// Aplicar contexto al agente
31const agenteOptimizador = agent({
32  name: "DBOptimizer",
33  description: contextoOptimizado.objetivoEspecifico,
34  tools: [], // herramientas basadas en permisos
35  llm: openai({
36    model: "gpt-4o-mini",
37    systemMessage: JSON.stringify(contextoOptimizado)
38  })
39});
40

Limitaciones y Consideraciones

Es importante entender las limitaciones actuales de los subagentes:

1// Consideraciones al usar subagentes en TypeScript
2interface Limitaciones {
3  contexto: string;
4  comunicacion: string;
5  persistencia: string;
6  sincronizacion: string;
7}
8
9const limitaciones: Limitaciones = {
10  contexto: "Cada subagente tiene su propio límite de contexto",
11  comunicacion: "No pueden comunicarse directamente entre ellos",
12  persistencia: "No mantienen estado entre invocaciones",
13  sincronizacion: "Requieren coordinación manual para tareas paralelas"
14};
15
16// Estrategias para mitigar limitaciones con LlamaIndex
17import { tool } from "llamaindex";
18import fs from "fs/promises";
19
20const contextoCompartidoTool = tool({
21  name: "shared_context",
22  description: "Lee y escribe contexto compartido entre agentes",
23  parameters: z.object({
24    action: z.enum(["read", "write"]),
25    data: z.any().optional()
26  }),
27  execute: async ({ action, data }) => {
28    const path = "/tmp/shared_context.json";
29
30    if (action === "read") {
31      const content = await fs.readFile(path, "utf-8");
32      return JSON.parse(content);
33    } else {
34      await fs.writeFile(path, JSON.stringify(data));
35      return { success: true };
36    }
37  }
38});
39

Debugging y Troubleshooting

Monitoreando SubAgentes

Es crucial poder monitorear qué están haciendo los subagentes:

1# Técnicas de monitoreo
2claude "ejecuta análisis de código con logging detallado de subagentes"
3
4# El sistema puede mostrar:
5# [SubAgente-1] Iniciando análisis de archivo main.py
6# [SubAgente-1] Encontradas 3 funciones con complejidad > 10
7# [SubAgente-2] Generando propuestas de refactorización
8# [SubAgente-2] Creadas 5 propuestas de mejora
9

Manejando Errores

Los subagentes pueden fallar, y es importante tener estrategias de recuperación:

1// Manejo robusto de errores con TypeScript y LlamaIndex
2interface ResultadoAgente {
3  exitoso: boolean;
4  data?: any;
5  error?: string;
6}
7
8class TimeoutError extends Error {}
9class ContextLimitError extends Error {}
10
11const ejecutarConRecuperacion = async (
12  tarea: string,
13  maxIntentos: number = 3
14): Promise<ResultadoAgente> => {
15
16  for (let intento = 0; intento < maxIntentos; intento++) {
17    try {
18      // Crear agente con timeout configurado
19      const agenteConTimeout = agent({
20        name: "GeneralPurpose",
21        description: "Agente de propósito general",
22        tools: [],
23        llm: openai({
24          model: "gpt-4o-mini",
25          timeout: 30000 // 30 segundos en ms
26        })
27      });
28
29      const resultado = await agenteConTimeout.run({
30        prompt: tarea
31      });
32
33      if (resultado) {
34        return {
35          exitoso: true,
36          data: resultado
37        };
38      }
39
40    } catch (error) {
41      if (error instanceof TimeoutError) {
42        console.log(`Intento ${intento + 1} falló por timeout`);
43        // Simplificar tarea o dividirla
44        tarea = await simplificarTarea(tarea);
45
46      } else if (error instanceof ContextLimitError) {
47        console.log("Límite de contexto alcanzado");
48        // Reducir contexto o dividir en subtareas
49        tarea = await reducirContexto(tarea);
50      }
51    }
52  }
53
54  return {
55    exitoso: false,
56    error: "Máximo de intentos alcanzado"
57  };
58};
59
60// Funciones auxiliares
61const simplificarTarea = async (tarea: string): Promise<string> => {
62  // Lógica para simplificar la tarea
63  return tarea.substring(0, tarea.length / 2);
64};
65
66const reducirContexto = async (tarea: string): Promise<string> => {
67  // Lógica para reducir el contexto
68  return tarea.split("\n")[0];
69};
70

Mejores Prácticas

Diseño de Tareas para SubAgentes

Para obtener los mejores resultados, las tareas deben ser:

  1. Específicas: Objetivos claros y medibles
  2. Autocontenidas: Mínima dependencia de contexto externo
  3. Verificables: Con criterios claros de éxito
  4. Modulares: Fácilmente componibles con otras tareas
1// Ejemplo de tarea bien diseñada con tipos TypeScript
2import { z } from "zod";
3
4// Schema para validar estructura de tarea
5const TareaBienDiseñadaSchema = z.object({
6  objetivo: z.string(),
7  ubicacion: z.string(),
8  metricasExito: z.object({
9    tiempoEjecucion: z.string(),
10    complejidad: z.string(),
11    coberturaTests: z.string()
12  }),
13  restricciones: z.array(z.string())
14});
15
16type TareaBienDiseñada = z.infer<typeof TareaBienDiseñadaSchema>;
17
18const tareaBienDiseñada: TareaBienDiseñada = {
19  objetivo: "Optimizar función calculateTotalPrice()",
20  ubicacion: "src/utils/pricing.ts",
21  metricasExito: {
22    tiempoEjecucion: "< 100ms",
23    complejidad: "< 5",
24    coberturaTests: "> 90%"
25  },
26  restricciones: [
27    "mantener firma de función",
28    "no cambiar comportamiento observable"
29  ]
30};
31
32// Crear agente con la tarea estructurada
33const agenteOptimizacion = agent({
34  name: "FunctionOptimizer",
35  description: tareaBienDiseñada.objetivo,
36  tools: [],
37  llm: openai({
38    model: "gpt-4o-mini",
39    systemMessage: JSON.stringify(tareaBienDiseñada)
40  })
41});
42

Orquestación Eficiente

La clave para usar subagentes efectivamente es la orquestación inteligente:

1// Patrón de orquestación eficiente con LlamaIndex
2import { multiAgent, agent } from "@llamaindex/workflow";
3
4class OrquestadorInteligente {
5  // Análisis inicial para determinar estrategia
6  private evaluarComplejidad(proyecto: string): number {
7    // Lógica para evaluar complejidad del proyecto
8    return proyecto.length / 100; // Ejemplo simplificado
9  }
10
11  async procesar(proyecto: string) {
12    const complejidad = this.evaluarComplejidad(proyecto);
13
14    // Selección dinámica de estrategia
15    if (complejidad < 5) {
16      return await this.estrategiaSimple(proyecto);
17    } else if (complejidad < 10) {
18      return await this.estrategiaParalela(proyecto);
19    } else {
20      return await this.estrategiaJerarquica(proyecto);
21    }
22  }
23
24  private async estrategiaSimple(proyecto: string) {
25    // Un solo agente para tareas simples
26    const agenteSimple = agent({
27      name: "SimpleAgent",
28      description: "Procesamiento simple",
29      tools: [],
30      llm: openai({ model: "gpt-4o-mini" })
31    });
32
33    return await agenteSimple.run({ prompt: proyecto });
34  }
35
36  private async estrategiaParalela(proyecto: string) {
37    // Múltiples agentes trabajando en paralelo
38    const agente1 = agent({
39      name: "ParallelAgent1",
40      description: "Procesa parte A",
41      tools: [],
42      llm: openai({ model: "gpt-4o-mini" })
43    });
44
45    const agente2 = agent({
46      name: "ParallelAgent2",
47      description: "Procesa parte B",
48      tools: [],
49      llm: openai({ model: "gpt-4o-mini" })
50    });
51
52    const workflow = multiAgent({
53      agents: [agente1, agente2],
54      rootAgent: agente1
55    });
56
57    return await workflow.run({ prompt: proyecto });
58  }
59
60  private async estrategiaJerarquica(proyecto: string) {
61    // Estructura compleja con múltiples niveles
62    const coordinador = agent({
63      name: "Coordinator",
64      description: "Coordina agentes especializados",
65      tools: [],
66      llm: openai({ model: "gpt-4o" }) // Modelo más potente para coordinación
67    });
68
69    const especialista1 = agent({
70      name: "Specialist1",
71      description: "Especialista en análisis",
72      tools: [],
73      llm: openai({ model: "gpt-4o-mini" })
74    });
75
76    const especialista2 = agent({
77      name: "Specialist2",
78      description: "Especialista en optimización",
79      tools: [],
80      llm: openai({ model: "gpt-4o-mini" })
81    });
82
83    const workflowJerarquico = multiAgent({
84      agents: [coordinador, especialista1, especialista2],
85      rootAgent: coordinador
86    });
87
88    return await workflowJerarquico.run({
89      prompt: proyecto,
90      stream: true
91    });
92  }
93}
94
95// Uso del orquestador
96const orquestador = new OrquestadorInteligente();
97const resultado = await orquestador.procesar("proyecto complejo");
98

El Poder de la Colaboración Emergente

Lo más fascinante de los subagentes es cómo comportamientos complejos emergen de la interacción de componentes simples. Cuando múltiples agentes colaboran, cada uno con su perspectiva y especialización, las soluciones resultantes a menudo superan lo que cualquier agente individual podría lograr.

Esta colaboración emergente no es solo suma de partes; es multiplicación de capacidades. Un agente puede identificar un patrón que otro agente puede optimizar, mientras un tercero verifica la corrección. El resultado es un sistema que exhibe creatividad y robustez que trasciende sus componentes individuales.

Preparándose para Técnicas Avanzadas

Este capítulo ha cubierto los fundamentos de los subagentes, pero apenas hemos arañado la superficie de lo que es posible. En el próximo capítulo exploraremos técnicas avanzadas como workflows adaptativos, aprendizaje entre agentes, y arquitecturas de agentes auto-organizadas.

El dominio de los subagentes básicos es el foundation sobre el cual construiremos sistemas verdaderamente inteligentes y autónomos. La práctica con estos conceptos fundamentales es esencial antes de aventurarse en las técnicas más sofisticadas que exploraremos a continuación.

Los subagentes representan un cambio fundamental en cómo conceptualizamos la solución de problemas en desarrollo de software, transformando tareas solitarias en esfuerzos colaborativos orquestados inteligentemente.