Claude Code Agents y Subagents: Como Crear Agentes IA Autonomos [Tutorial 2026]

Claude Code Agents: Tutorial Completo para Crear Agentes IA Autonomos [2026]

Quieres dominar la programacion agentica? Formacion in-company en Claude Code con modulo avanzado de Agents y subagentes.

TL;DR

• Claude Code puede lanzar subagentes autonomos con la Agent tool, delegando tareas complejas sin bloquear el flujo principal
• 3 tipos de subagentes: general-purpose (todas las herramientas), Explore (solo lectura, rapido) y Plan (arquitectura y diseno)
• Los subagentes trabajan en paralelo y cada uno tiene su propio contexto, herramientas y ventana de ejecucion independiente
• 10 patrones practicos: investigacion paralela, testing distribuido, refactorizacion aislada, code review automatico y mas
• Se pueden ejecutar en background con run_in_background: true o en worktrees aislados para cambios experimentales
• El Claude Agent SDK (@anthropic-ai/claude-agent-sdk) permite construir sistemas multi-agente personalizados fuera de Claude Code

"Los equipos que adoptan patrones multi-agente con Claude Code reportan una reduccion del 40% en tiempo de tareas complejas como refactorizaciones, migraciones y auditorias de seguridad." -- Datos de adopcion temprana, Q1 2026

La programacion agentica ha dejado de ser un concepto teorico. Con Claude Code Agents, cualquier desarrollador puede orquestar multiples agentes IA autonomos desde la terminal, delegando investigacion, planificacion, testing y refactorizacion a subprocesos inteligentes que trabajan en paralelo. Este tutorial cubre los 3 tipos de subagentes, 10 patrones practicos y las mejores practicas para aprovechar al maximo la arquitectura multi-agente de Claude Code en 2026.

Que Son los Agents en Claude Code?

Los Agents en Claude Code son subprocesos autonomos que ejecutan tareas complejas de forma independiente, sin bloquear al agente principal. Cuando Claude Code detecta que una tarea requiere multiples pasos, busquedas extensas o trabajo paralelo, puede lanzar uno o varios subagentes que operan con su propio contexto y herramientas.

A diferencia de una simple llamada a una herramienta (como Read o Bash), un Agent es un bucle completo de razonamiento: recibe un objetivo, decide que herramientas usar, ejecuta multiples pasos, y devuelve un resultado estructurado al agente principal.

Diferencia clave frente a herramientas simples

El agente principal de Claude Code actua como orquestador: analiza la tarea del usuario, identifica sub-tareas que se benefician de ejecucion independiente, lanza subagentes, y luego integra los resultados.

Tipos de Subagentes Disponibles

Claude Code ofrece 3 tipos de subagentes, cada uno optimizado para un tipo de tarea diferente. La eleccion del tipo correcto impacta directamente en la velocidad, el coste y la seguridad de la ejecucion.

general-purpose: El Agente Completo

El subagente general-purpose tiene acceso a todas las herramientas de Claude Code, incluyendo edicion y ejecucion de comandos. Es el tipo mas potente pero tambien el que mas tokens consume. Usalo cuando el subagente necesita modificar archivos, ejecutar comandos o realizar operaciones de escritura.

Ejemplo de uso: "Genera tests unitarios para el modulo de autenticacion y ejecutalos para verificar que pasan."

Explore: Busqueda Rapida y Segura

El subagente Explore esta limitado a herramientas de solo lectura, lo que lo hace mas rapido y seguro. No puede modificar ningun archivo ni ejecutar comandos del sistema. Es ideal para investigacion paralela donde necesitas encontrar informacion sin riesgo de efectos secundarios.

El subagente Explore acepta un parametro de profundidad (thoroughness) que controla cuanto tiempo dedica a la busqueda:

Plan: Arquitectura Antes de Codigo

El subagente Plan analiza el codebase y genera un plan de implementacion detallado antes de que se escriba una sola linea de codigo. Tiene acceso de solo lectura y se enfoca en producir una lista de pasos ordenados, archivos a modificar y dependencias a considerar.

Ejemplo de salida de un Plan agent:

1Plan de implementacion: Migrar autenticacion de JWT a OAuth2
2 
31. Archivos a modificar:
4   - src/auth/jwt.ts → reemplazar por oauth2.ts
5   - src/middleware/auth.middleware.ts → actualizar validacion
6   - src/config/auth.config.ts → nuevas variables de entorno
7 
82. Nuevos archivos:
9   - src/auth/oauth2-provider.ts
10   - src/auth/token-refresh.ts
11 
123. Tests a actualizar:
13   - tests/auth/*.test.ts (6 archivos)
14 
154. Dependencias:
16   - Instalar: passport-oauth2, openid-client
17   - Eliminar: jsonwebtoken
18 
195. Orden de ejecucion recomendado:
20   a) Config → b) Provider → c) Middleware → d) Tests → e) Cleanup

Como Funciona la Agent Tool

La Agent tool es el mecanismo interno que Claude Code usa para crear y gestionar subagentes. Cuando el agente principal decide delegar una tarea, sigue un flujo de 6 pasos.

Flujo de ejecucion paso a paso

1. El agente principal identifica una sub-tarea que se beneficia de ejecucion independiente
2. Crea un subagente especificando: tipo, prompt/objetivo y parametros opcionales (profundidad, aislamiento)
3. El subagente recibe su propio contexto y su conjunto de herramientas segun el tipo
4. El subagente trabaja de forma autonoma: lee archivos, busca codigo, ejecuta comandos y toma decisiones
5. Devuelve los resultados al agente principal en formato estructurado
6. El agente principal integra los resultados y continua con la tarea del usuario

Arquitectura visual

1Agente Principal (Claude Code)
2│
3├── Subagente 1: Explore
4│   ├── Grep("patron de error")
5│   ├── Read("src/utils/logger.ts")
6│   └── Resultado: "El error esta en linea 45 de logger.ts"
7│
8├── Subagente 2: general-purpose
9│   ├── Read("tests/auth.test.ts")
10│   ├── Edit("tests/auth.test.ts")
11│   ├── Bash("pnpm test auth")
12│   └── Resultado: "Tests actualizados, 12/12 pasan"
13│
14└── Subagente 3: Plan
15    ├── Glob("src/**/*.ts")
16    ├── Read("src/config/database.ts")
17    └── Resultado: "Plan de migracion en 5 pasos..."

Ejecucion en paralelo

Los subagentes pueden ejecutarse en paralelo cuando sus tareas son independientes. Claude Code detecta automaticamente cuando dos o mas sub-tareas no tienen dependencias entre si y las lanza simultaneamente. Esto reduce drasticamente el tiempo total de tareas complejas.

Ejemplo: si pides "analiza la seguridad del proyecto y genera tests para el modulo de pagos", Claude Code puede lanzar un Explore agent para la auditoria de seguridad y un general-purpose agent para los tests, ambos al mismo tiempo.

10 Patrones Practicos con Agents

Estos son los 10 patrones mas efectivos para aprovechar subagentes en proyectos reales. Cada patron incluye el tipo de subagente recomendado y el caso de uso optimo.

Patron 1: Investigacion Paralela

Lanza multiples agentes Explore para buscar en diferentes partes del codebase simultaneamente. En lugar de buscar secuencialmente, cada agente investiga un area independiente y devuelve resultados al mismo tiempo.

• Tipo: Explore (x2-4 agentes en paralelo)
• Caso de uso: "Encuentra todos los puntos donde se usa la API de pagos y todos los tests relacionados"
• Ventaja: Reduccion de tiempo del 60-70% frente a busqueda secuencial

Patron 2: Testing Distribuido

Un agente escribe tests mientras otro revisa el codigo que se esta testeando. El agente de tests no necesita esperar a que la revision termine, y viceversa.

• Tipo: general-purpose (tests) + Explore (revision)
• Caso de uso: "Genera tests unitarios para el modulo de usuarios y revisa la cobertura actual"
• Ventaja: Tests y revision en paralelo, feedback cruzado al finalizar

Patron 3: Refactorizacion Segura con Worktree

Usa la opcion isolation: "worktree" para refactorizar en una copia aislada del repositorio. Si algo sale mal, el worktree se descarta sin afectar al codigo principal.

• Tipo: general-purpose con worktree
• Caso de uso: "Refactoriza el sistema de rutas de Express a Hono sin romper nada"
• Ventaja: Riesgo cero -- los cambios se aplican solo si el resultado es satisfactorio

Patron 4: Exploracion Profunda de Codebase

Usa un Explore agent con nivel very thorough para mapear todo un codebase desconocido. El agente genera un informe completo de arquitectura, dependencias y patrones detectados.

• Tipo: Explore (very thorough)
• Caso de uso: Incorporacion a un proyecto legacy, onboarding en nuevo equipo
• Ventaja: Comprension completa del proyecto en 1-2 minutos en lugar de horas

Patron 5: Planificacion de Arquitectura

Lanza un Plan agent antes de cualquier implementacion compleja. El agente analiza el codebase existente y genera una lista de pasos, archivos a modificar y riesgos potenciales.

• Tipo: Plan
• Caso de uso: "Planifica la migracion de la base de datos de MongoDB a PostgreSQL"
• Ventaja: Evita refactorizaciones a medio camino y reduce errores de diseno

Patron 6: Background Tasks (Tareas en Segundo Plano)

Ejecuta tareas largas en segundo plano con run_in_background: true. El agente principal sigue disponible para interaccion mientras el subagente trabaja.

• Tipo: Cualquiera con run_in_background: true
• Caso de uso: Generacion de documentacion completa, auditorias de seguridad extensas
• Ventaja: No bloquea la sesion interactiva del usuario

Patron 7: Pipeline Multi-Agente

Encadena agentes en secuencia: Explore, luego Plan, luego general-purpose. Cada agente usa el resultado del anterior como entrada.

• Tipo: Explore (fase 1) -> Plan (fase 2) -> general-purpose (fase 3)
• Caso de uso: "Analiza el modulo de notificaciones, planifica mejoras y ejecutalas"
• Ventaja: Cada fase tiene el contexto y herramientas optimas para su funcion

Patron 8: Code Review Automatizado

Un agente revisa el PR actual mientras el desarrollador continua trabajando en otra tarea. El agente analiza cambios, busca patrones problematicos y genera un informe.

• Tipo: Explore (para revision) o general-purpose (si debe sugerir cambios)
• Caso de uso: "Revisa el PR #42 siguiendo las reglas del CLAUDE.md del equipo"
• Ventaja: Review instantaneo sin esperar a un companero

Patron 9: Migracion Coordinada

Un agente genera migraciones de base de datos mientras otro actualiza los endpoints de la API. Ambos trabajan en paralelo sobre areas diferentes del codigo.

• Tipo: general-purpose (x2 agentes en paralelo)
• Caso de uso: "Migra el schema de usuarios a v2 y actualiza todos los endpoints afectados"
• Ventaja: Migracion de schema y API en paralelo, coordinacion automatica

Patron 10: Documentacion Automatica

Un agente genera documentacion tecnica analizando el codigo mientras el agente principal continua con desarrollo. El subagente extrae tipos, funciones publicas, ejemplos de uso y genera docs en formato Markdown.

• Tipo: Explore (analisis) + general-purpose (escritura)
• Caso de uso: "Documenta la API publica del modulo de pagos con ejemplos"
• Ventaja: Documentacion generada sin interrumpir el flujo de trabajo

Agent SDK: Construir Agentes Personalizados

El Claude Agent SDK (@anthropic-ai/claude-agent-sdk) permite construir sistemas multi-agente personalizados fuera de Claude Code. Si los subagentes internos de Claude Code cubren el 80% de los casos, el SDK abre la puerta al 20% restante: agentes custom con logica de negocio especifica, integraciones propietarias y flujos complejos.

Que ofrece el Agent SDK

Ejemplo basico con el Agent SDK

1import { Agent } from "@anthropic-ai/claude-agent-sdk";
2 
3const agent = new Agent({
4  model: "claude-sonnet-4-5-20250514",
5  tools: [
6    {
7      name: "buscar_en_base_datos",
8      description: "Busca registros en la base de datos del proyecto",
9      input_schema: {
10        type: "object",
11        properties: {
12          query: { type: "string", description: "Consulta SQL" }
13        },
14        required: ["query"]
15      },
16      handler: async (input) => {
17        // Tu logica de base de datos aqui
18        return await db.query(input.query);
19      }
20    }
21  ]
22});
23 
24const resultado = await agent.run(
25  "Encuentra todos los usuarios que no han iniciado sesion en 30 dias"
26);

Dato clave: El Agent SDK comparte la misma arquitectura de herramientas que Claude Code internamente. Si ya usas MCPs en Claude Code, puedes reutilizarlos directamente en agentes custom del SDK.

Para mas informacion sobre MCP y como conectar herramientas externas, consulta la guia completa de MCP.

Background Agents vs Foreground Agents

Los Background Agents ejecutan tareas en segundo plano sin bloquear la sesion interactiva, mientras que los Foreground Agents bloquean hasta completar. La eleccion depende de si necesitas el resultado inmediatamente o puedes continuar trabajando.

Cuando usar Background Agents

• Generacion de tests para un modulo completo (mas de 10 archivos)
• Auditorias de seguridad o rendimiento de todo el proyecto
• Generacion de documentacion tecnica extensiva
• Migraciones que afectan a muchos archivos
• Cualquier tarea que tarde mas de 60 segundos

Worktrees: Ejecucion Aislada de Agentes

Los git worktrees permiten que un subagente trabaje en una copia aislada del repositorio sin afectar al directorio de trabajo principal. Es la opcion mas segura para refactorizaciones agresivas, cambios experimentales o cualquier operacion donde un fallo podria corromper el estado actual del proyecto.

Como funciona

1. Claude Code crea un worktree (copia ligera del repositorio usando git worktree)
2. El subagente trabaja exclusivamente en esa copia
3. Los cambios se realizan en el worktree, no en el directorio principal
4. Si el resultado es satisfactorio, los cambios se integran (merge)
5. Si algo falla, el worktree se descarta sin consecuencias

Cuando usar worktrees

Limitaciones de worktrees

• Crean una copia parcial del repositorio, lo que consume espacio en disco
• No comparten el estado de node_modules u otras dependencias instaladas (puede requerir reinstalacion)
• El subagente en worktree no puede ver cambios no commiteados del directorio principal

Mejores Practicas para Agents

Seguir estas 8 practicas maximiza la eficiencia y minimiza el consumo de tokens al trabajar con subagentes.

1. Usa Explore para operaciones de solo lectura

El subagente Explore es mas rapido y barato que un general-purpose cuando solo necesitas buscar informacion. No le des acceso de escritura a un agente que solo necesita leer.

2. Planifica antes de implementar

Lanza un Plan agent antes de cualquier tarea compleja con mas de 3 archivos involucrados. El coste de planificar es minimo comparado con rehacer una implementacion mal disenada.

3. Paraleliza tareas independientes

Si dos sub-tareas no dependen entre si, lanzalas como agentes en paralelo. Claude Code detecta dependencias automaticamente, pero puedes estructurar tu peticion para facilitar la paralelizacion: "Mientras buscas X, tambien genera Y."

4. Usa background para tareas largas

Cualquier tarea que tarde mas de 30-60 segundos deberia ejecutarse en background. Esto libera la sesion interactiva para que puedas seguir trabajando.

5. Worktrees para cambios arriesgados

Siempre que un cambio pueda dejar el proyecto en estado inconsistente, usa un worktree. Refactorizaciones grandes, migraciones de dependencias y cambios experimentales son candidatos perfectos.

6. Escribe prompts especificos para subagentes

Cuanto mas claro y especifico sea el objetivo del subagente, mejor sera el resultado. En lugar de "revisa el codigo", especifica: "Busca vulnerabilidades de inyeccion SQL en todos los archivos de src/api/ que acepten parametros del usuario."

7. No sobredelegues

No uses un Agent para tareas que se resuelven con una sola herramienta. Si solo necesitas leer un archivo, usa Read directamente. Los Agents son para tareas que requieren multiples pasos y decisiones autonomas.

8. Monitoriza el consumo de tokens

Cada subagente consume tokens independientemente. En un plan con limite de uso (como Claude Pro con ~45 mensajes Opus por cada 5 horas), ten en cuenta que un pipeline de 4 agentes consume significativamente mas que una ejecucion secuencial simple.

Limitaciones y Consideraciones

Los Agents de Claude Code son potentes pero tienen restricciones importantes que debes conocer antes de integrarlos en tu flujo de trabajo.

Consumo de tokens

Cada subagente inicia su propio bucle de razonamiento y consume tokens de forma independiente. Un pipeline Explore + Plan + general-purpose puede consumir 3-5x mas tokens que hacer la misma tarea secuencialmente con el agente principal. La paralelizacion ahorra tiempo, no tokens.

Aislamiento de contexto

Los subagentes no comparten contexto entre si. Si el Subagente A descubre algo relevante para el Subagente B, no hay comunicacion directa. Solo el agente principal puede pasar informacion entre subagentes, y lo hace cuando recibe los resultados.

Rate limits

Lanzar demasiados agentes en paralelo puede provocar errores por rate limiting de la API de Anthropic. En la practica, 3-4 agentes en paralelo es un numero razonable. Mas alla de eso, es probable que algunos se encolen automaticamente.

Sin interaccion directa con el usuario

Los subagentes no pueden hacer preguntas al usuario ni solicitar confirmacion. Trabajan de forma autonoma con el prompt inicial. Si un subagente necesita una decision humana, la marca como pendiente en su resultado y el agente principal la escala al usuario.

Disponibilidad segun plan

Preguntas Frecuentes

Que son los agents en Claude Code?

Los agents son subprocesos autonomos que Claude Code lanza para ejecutar tareas complejas de forma independiente. Funcionan como mini-instancias de Claude que reciben un objetivo, deciden que herramientas usar, ejecutan multiples pasos y devuelven un resultado al agente principal. Hay 3 tipos: general-purpose (todas las herramientas), Explore (solo lectura) y Plan (planificacion).

Como creo un subagente en Claude Code?

No necesitas crear subagentes manualmente -- Claude Code los lanza automaticamente cuando detecta que una tarea se beneficia de ejecucion paralela o delegacion. Si quieres forzar el uso de subagentes, estructura tu peticion describiendo sub-tareas independientes. Por ejemplo: "Busca todos los endpoints sin tests (tarea 1) y genera un plan de migracion para la base de datos (tarea 2)." Claude Code lanzara agentes para cada sub-tarea.

Cuantos agentes puedo lanzar en paralelo?

En la practica, entre 3 y 4 agentes en paralelo es el numero optimo. No hay un limite tecnico estricto impuesto por Claude Code, pero la API de Anthropic tiene rate limits que se aplican al total de solicitudes concurrentes. Con 3-4 agentes paralelos, el tiempo total de tareas complejas se reduce un 40-60% sin riesgo de throttling.

Los agents de Claude Code cuestan mas?

No tienen un coste adicional por uso de la funcionalidad, pero cada subagente consume tokens de tu cuota. En un plan Pro con ~45 mensajes Opus por cada 5 horas, un pipeline de 3 agentes puede consumir el equivalente a 3-5 mensajes. En planes Team y Enterprise con limites mas amplios, el impacto es menor. En la API directa, pagas por tokens consumidos por cada agente.

Que es el Agent SDK de Anthropic?

El Agent SDK (@anthropic-ai/claude-agent-sdk) es una libreria de TypeScript y Python que permite construir sistemas multi-agente personalizados fuera de Claude Code. Mientras que los agents internos de Claude Code son automaticos, el SDK te permite definir herramientas custom, logica de negocio especifica, y flujos de agentes adaptados a tu caso de uso. Es ideal para automatizaciones en produccion, pipelines CI/CD inteligentes y asistentes especializados.

Puedo usar agents en Claude Code gratis?

No -- los agents requieren un plan de pago de Claude (Pro, Team o Enterprise). No estan disponibles en el plan gratuito. El plan mas accesible es Pro a 20 USD/mes, que incluye acceso completo a agents, background agents y worktrees. Para equipos, el plan Team a 25 USD/usuario/mes anade controles administrativos y limites de uso mas amplios.

Que diferencia hay entre Agent y Explore en Claude Code?

El Agent general-purpose tiene acceso a todas las herramientas (leer, escribir, editar, ejecutar comandos), mientras que Explore esta limitado a herramientas de solo lectura (Read, Grep, Glob). Explore es mas rapido y seguro porque no puede modificar archivos ni ejecutar comandos del sistema. Usa Explore cuando solo necesitas encontrar informacion; usa general-purpose cuando necesitas que el subagente haga cambios en el codigo.

Posts Relacionados

• Guia Completa de Claude Code: Tutorial para Empezar -- Fundamentos, instalacion y primeros pasos con Claude Code
• Claude Code para Empresas: Implementacion, Formacion y ROI -- MCPs, Skills, Hooks y planes enterprise
• MCP: Model Context Protocol - Guia Completa -- Como conectar Claude Code a herramientas externas
• Como Implementar Claude Code en tu Equipo -- Tutorial paso a paso para equipos de desarrollo
• Formacion in-company en Claude Code -- Programa de formacion para empresas con modulo de Agents

Enlaces Oficiales

• Documentacion oficial de Claude Code - Anthropic
• Claude Agent SDK en npm - Paquete oficial
• Especificacion MCP (Model Context Protocol) - Protocolo abierto
• Claude Code en GitHub - Repositorio oficial

Fuentes

• Anthropic Claude Code Documentation - Documentacion oficial de Agents y subagentes
• Model Context Protocol Specification - Spec del protocolo MCP
• Claude Agent SDK Documentation - SDK para agentes custom
• Stack Overflow Developer Survey 2025 - Datos de adopcion de herramientas IA

En Resumen

• Claude Code Agents son subprocesos autonomos que ejecutan tareas complejas de forma independiente, con su propio contexto y herramientas, sin bloquear al agente principal
• 3 tipos de subagentes disponibles: general-purpose (todas las herramientas, para tareas con edicion), Explore (solo lectura, rapido y seguro) y Plan (planificacion de arquitectura antes de implementar)
• La paralelizacion reduce un 40-60% el tiempo de tareas complejas como refactorizaciones, migraciones y auditorias, lanzando 3-4 agentes simultaneos sobre areas independientes del codebase
• Worktrees aislan cambios arriesgados en copias separadas del repositorio, permitiendo descartar experimentos fallidos sin afectar al directorio de trabajo principal
• Cada subagente consume tokens independientemente de su cuota: un pipeline de 3 agentes equivale a 3-5 mensajes, asi que equilibra paralelismo y coste segun tu plan (Pro, Team o Enterprise)
• El Agent SDK (@anthropic-ai/claude-agent-sdk) extiende la capacidad fuera de Claude Code, permitiendo construir agentes custom con herramientas propias, logica de negocio y MCPs para automatizaciones en produccion
• Para la mayoria de equipos de desarrollo: dominar los patrones Explore + Plan + general-purpose y usar background agents para tareas largas es la combinacion con mayor impacto en productividad en 2026 -- formacion disponible