Agents · ·25 min ·Beginner

Introducción a lo sistemas agénticos

Un agente no es solo un LLM con ínfulas: percibe, decide, actúa y aprende de los resultados. Vemos cómo se organizan cuando trabajan en equipo y cómo sacarle partido al sistema de subagentes de Claude Code para delegar trabajo, aislar contexto y paralelizar tareas.

1. Qué es un agente

En este post vamos a ver algunas cosas sobre los agentes. La primera parte es una introducción general y luego ya entramos con el sistema de subagentes de Claude.

En el taller “Agentic AI”, Andrew Ng explicaba que había advertido dentro de la comunidad de IA «un debate estéril sobre qué es un agente: algunos publicaban artículos diciendo “construí un agente” y otros respondían “no, eso no es un verdadero agente” […] por eso empecé a usar el término agéntico, porque si lo usamos como adjetivo en lugar de como un binario —o es agente o no lo es—, tenemos que reconocer que los sistemas pueden ser agénticos en distintos grados».

Así, explicaba Ng, los sistemas agénticos forman un espectro: desde agentes con pasos predefinidos y secuencia fija, pasando por agentes semi-autónomos que eligen herramientas, hasta agentes altamente autónomos que planifican sus propios pasos e incluso crean nuevas herramientas. A mayor autonomía, mayor potencia, pero también menor control y predictibilidad.

Hoy en día no existe una definición universalmente aceptada, pero el consenso en la industria apunta a que un agente es un sistema de IA que percibe su entorno, toma decisiones y ejecuta acciones de forma autónoma para alcanzar un objetivo, con capacidad de iterar y adaptarse según los resultados. Lo que lo distingue de un simple LLM es precisamente esa capacidad de actuar en bucles, de usar herramientas y de mantener cierto estado a lo largo del tiempo.

Dicho de otro modo, los componentes que suelen definir a un agente son:

  • Un modelo —un LLM— que razona y genera acciones: el cerebro.
  • Memoria (a corto plazo dentro del contexto, y a largo plazo en bases de datos externas).
  • Herramientas (tools) que puede invocar para interactuar con el mundo, como los MCPs.
  • Un bucle de ejecución que decide cuándo actuar, cuándo esperar y cuándo terminar.

2. Sistemas multiagénticos

Ng también hablaba de sistemas multiagénticos: una arquitectura de IA en la que varios agentes autónomos trabajan conjuntamente para resolver tareas que serían demasiado complejas, largas o especializadas para un único agente. La idea central es la misma que en un equipo humano: en lugar de tener a una sola persona que sepa hacer de todo, tienes especialistas que colaboran. Un agente puede ser experto en buscar información, otro en redactar, otro en revisar código, otro en interactuar con bases de datos… y un coordinador que los orquesta.

Hay varias formas de organizar cómo se comunican los agentes entre sí en estos sistemas:

  • Orquestador + subagentes. El patrón más común y controlable. Un agente central recibe la tarea, la divide y delega. Los subagentes devuelven resultados al orquestador, que los integra. Es predecible y fácil de depurar.
  • Pipeline secuencial. Como una cadena de montaje: el output de un agente es el input del siguiente. Se usa mucho en flujos de procesamiento de documentos o generación de contenido (investigar > redactar > revisar > publicar).
  • Red de pares. Los agentes se comunican directamente entre sí sin un coordinador central. Es más flexible y resistente a fallos, pero mucho más difícil de controlar y depurar.
  • Agentes con roles fijos. Como ChatDev, donde cada agente tiene una identidad definida (CEO, programador, tester, diseñador…) y actúan como una organización simulada con jerarquía y flujos de trabajo internos.

3. Ventajas e inconvenientes

Los sistemas multiagente resuelven problemas que un solo agente no puede abordar bien por varias razones:

  • Especialización. Cada agente está optimizado para su tarea concreta, con el modelo más adecuado, el prompt más ajustado y las herramientas necesarias. Un agente generalista que intenta hacer todo suele hacerlo todo regular.
  • Paralelización. Permite ejecutar subtareas simultáneamente. Si necesitas investigar cinco temas a la vez, cinco agentes pueden hacerlo en paralelo mientras que uno solo tendría que hacerlos en secuencia.
  • Superación del límite de contexto. Las tareas muy largas —analizar centenares de documentos, escribir un informe exhaustivo— no caben en la ventana de contexto de un solo LLM. Con múltiples agentes, cada uno trabaja con su parte y el orquestador integra los resultados.
  • Resiliencia. Si un agente falla, el orquestador puede reintentarlo, asignárselo a otro agente o tomar una ruta alternativa.

Ahora bien, los sistemas multiagente también introducen problemas nuevos que no existen con un solo agente:

  • Propagación de errores. Un error en un agente temprano del pipeline se amplifica en los siguientes. Si el agente de búsqueda recupera información incorrecta, el agente de redacción escribirá un texto incorrecto con mucha confianza.
  • Coordinación y estado compartido. Los agentes necesitan compartir contexto relevante sin pasarse toda la información —lo que sería ineficiente— ni perderse información crítica. Gestionar qué sabe cada agente en cada momento es complejo.
  • Depuración difícil. Cuando algo sale mal en un sistema multiagente, rastrear exactamente qué agente tomó qué decisión y por qué puede ser muy complicado. Por eso la trazabilidad y los logs detallados son esenciales.
  • Bucles y bloqueos. Dos agentes pueden entrar en un bucle esperando información el uno del otro, o un agente puede quedarse esperando una respuesta que nunca llega.

Habría muchísimo más que comentar sobre los agentes, pero de momento lo dejamos aquí para ver cómo funcionan los subagentes de Claude Code.

4. Los subagentes de Claude

Como acabamos de ver, los subagentes son asistentes especializados que gestionan tipos específicos de tareas. Cada subagente corre en su propia ventana de contexto con un system prompt personalizado, acceso específico a herramientas y permisos independientes. Cuando Claude encuentra una tarea que encaja con la descripción de un subagente, delega en él; el subagente trabaja de forma independiente y devuelve los resultados.

Además de permitir paralelizar tareas —algo muy de agradecer en procesos que llevan mucho tiempo—, su principal ventaja está precisamente en ese contexto independiente. En lugar de que un agente intente mantener el estado de un proyecto entero, los subagentes especializados gestionan tareas concretas con ventanas de contexto limpias. El agente principal coordina con un plan de alto nivel mientras los subagentes realizan trabajo técnico en profundidad. Cada subagente puede explorar extensamente —usando decenas de miles de tokens— pero devuelve solo un resumen condensado de su trabajo.

Aunque la documentación oficial es bastante concisa al respecto, Claude Code incluye, entre otros, tres grandes tipos de subagentes integrados:

  • Explore. De solo lectura, optimizado para buscar y analizar código sin modificar nada. Usa modelos menos costosos (Haiku) y se activa cuando Claude necesita entender una base de código antes de actuar.
  • Plan. También de solo lectura, pero orientado a la planificación. Cuando estás en modo plan y Claude necesita entender tu código, delega la investigación en este subagente.
  • General-purpose. El más capaz de los tres. Claude delega en él cuando la tarea requiere tanto exploración como modificación, razonamiento complejo o múltiples pasos dependientes entre sí.

Se entiende mejor con un ejemplo. Pongamos que le pedimos a Claude que refactorice un conjunto de tests. Por debajo podría montar un flujo así:

  1. Claude entra en modo plan.
  2. Lanza Plan, que investiga el módulo, dependencias y uso en el proyecto.
  3. Claude te presenta un plan de acción.
  4. Tú apruebas el plan.
  5. Claude lanza General-purpose, que ejecuta la refactorización: lee los archivos, los edita, ejecuta comandos, verifica que funciona…
  6. Durante esa ejecución, si necesita localizar algo concreto rápidamente, lanza Explore.

En resumen:

  • Plan: solo mira, para entender y proponer.
  • Explore: solo mira, para encontrar algo concreto y rápido.
  • General-purpose: mira y actúa, para hacer el trabajo real.

Llegados aquí, alguien podría preguntarse: ¿para qué existe General-purpose si ya está el agente principal?

La razón es la misma que justifica todos los subagentes: aislar el ruido del contexto principal. Si Claude hiciera la refactorización directamente en la conversación principal, todo lo que va leyendo, ejecutando y modificando se acumularía en tu contexto. Con General-purpose, todo ese trabajo ocurre en un contexto aislado y tú solo recibes el resumen final. Además, permite paralelismo: Claude puede lanzar varios General-purpose simultáneamente para trabajar en distintos módulos a la vez, algo que no podría hacer si todo ocurriera en la conversación principal.

Entendido esto, vamos con lo interesante: preparar nuestros propios subagentes.

5. Anatomía de un subagente personalizado

La estructura básica de un subagente es muy parecida a la de una skill. Es simplemente un archivo Markdown con dos partes: un bloque de configuración YAML al principio (el frontmatter) y el cuerpo del archivo, que se convierte en el system prompt del subagente.

---
name: nombre-del-agente
description: Descripción clara de cuándo debe usarse este agente
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---

Eres un [descripción del rol y área de expertise]...

[Instrucciones específicas, checklists, patrones de comportamiento...]

En el frontmatter podemos definir, entre otros, los siguientes campos:

  • name: identificador único del agente. Conviene usar nombres orientados al trabajo que realiza: repo-explorer, test-runner, pr-reviewer, security-auditor. Cuanto más claro y específico sea el nombre, más fácil será que Claude sepa cuándo delegarle.
  • description: el campo más crítico. Como sucede con las skills, Claude lo usa para decidir automáticamente cuándo delegar en este subagente. Debe explicar con precisión cuándo invocarlo, no solo qué hace.
  • tools: las herramientas a las que tiene acceso.
  • model: qué modelo usa. Puedes asignar Haiku para tareas simples y baratas, Sonnet para equilibrio calidad/coste, u Opus para tareas complejas donde la calidad es crítica. Esto permite controlar costes enrutando tareas sencillas a modelos más ligeros.
  • permissionMode: nivel de permisos. Puede ser default, acceptEdits (acepta ediciones sin preguntar), auto, dontAsk, plan o bypassPermissions (sin restricciones).
  • background: si se pone a true, el subagente puede ejecutarse en paralelo sin necesitar aclaraciones del usuario.
  • isolation: cuando se define como worktree (por defecto no activo) crea una rama separada del sistema de archivos para evitar conflictos cuando varios subagentes editan en paralelo.
  • maxTurns: límite máximo de turnos antes de devolver el control.
  • memory: si se activa, el subagente tiene un directorio de memoria persistente en ~/.claude/agent-memory/ donde acumula conocimiento entre sesiones.
  • skills: inyecta el contenido completo de una skill en el contexto del subagente al arrancar. Los subagentes no heredan las skills de la conversación principal, así que si necesitas que el subagente conozca las convenciones de tu proyecto, tienes que listarlas explícitamente aquí.
  • mcpServers: conecta servidores MCP específicos a ese subagente. Es muy potente: puedes darle acceso a herramientas externas que la conversación principal no tiene, o al revés, aislar herramientas sensibles para que solo las use ese subagente concreto.
  • effort: controla cuánto piensa el modelo antes de responder; sirve para ajustar velocidad frente a calidad según la tarea.
  • color: parámetro puramente visual que asigna un color al subagente en la UI de Claude Code para identificarlo fácilmente cuando corren varios en paralelo (red, blue, green, yellow, purple, orange, pink, cyan).
  • hooks: si hay alguno específico para este agente.

Veamos algunos de estos parámetros con más detalle.

6. Tools, turns y hooks

6.1. Tools

Las tools son las acciones concretas que el subagente puede ejecutar para interactuar con el mundo fuera del LLM. Sin tools, el subagente solo puede razonar y generar texto. Con tools, puede hacer cosas reales: leer archivos, ejecutar comandos, buscar en la web, etc.

Agrupadas por funcionalidad, las principales son:

Sobre archivos:

  • Read: lee el contenido de un archivo.
  • Write: crea un archivo nuevo.
  • Edit: modifica un archivo existente.
  • Glob: busca archivos por patrón (**/*.ts, src/**).
  • Grep: busca texto dentro de archivos.

De ejecución:

  • Bash: ejecuta comandos de terminal.

Web:

  • WebFetch: descarga el contenido de una URL.
  • WebSearch: busca en la web.

Se pueden definir de dos maneras: indicando cuáles pueden usarse (y solo esas):

tools: Read, Grep, Glob

O al revés, desactivando algunas en concreto:

disallowedTools: Write, Edit

Si no pones ninguna de las dos, el subagente hereda todas las tools de la conversación principal, incluyendo las de MCP.

Por seguridad, la regla de oro es siempre la misma: usa solo las tools mínimas necesarias para la tarea. Según el tipo de subagente, estas serían las tools recomendadas:

  • Revisor / auditor: Read, Grep, Glob.
  • Investigador: Grep, Glob, WebSearch, WebFetch.
  • Desarrollador: Read, Write, Edit, Bash, Glob, Grep.
  • Ejecutor de tests: Read, Bash.
  • Documentador: Read, Write, Edit, Glob, Grep.

6.2. Turns

Un turno es cada ciclo acción > resultado que ejecuta el subagente. Por ejemplo, en un agente que revisara commits:

  • Turno 1: ejecuta git diff --staged > recibe el diff.
  • Turno 2: ejecuta git log --oneline -5 > recibe el historial.
  • Turno 3: lee el archivo donde detectó un posible problema > recibe el contenido.
  • Turno 4: genera el informe final > devuelve resultado al usuario.

Eso serían 4 turnos, así que con maxTurns: 8 tendría margen de sobra.

Sin límite, un subagente que se queda atascado —porque un comando falla, porque no encuentra lo que busca, porque entra en un bucle de razonamiento— puede seguir dando vueltas indefinidamente consumiendo tiempo y tokens. Con maxTurns incorporamos un fusible de seguridad: cuando lo alcanza, el subagente se detiene y devuelve lo que tenga hasta ese momento.

Como marco general orientativo:

  • Tarea simple (revisar diff, validar formato): maxTurns: 5-10.
  • Tarea media (analizar un módulo, generar tests): maxTurns: 15-20.
  • Tarea compleja (refactorización, migración): maxTurns: 30-50.
  • Sin límite: omite el campo y hereda el default de la sesión.

3) Hooks

Los hooks son scripts que se ejecutan automáticamente en momentos concretos del ciclo de vida del agente, sin intervención manual. La idea central es: “cuando pase X, ejecutar Y automáticamente”.

Se entiende mejor con un ejemplo. Imaginemos un agente que trabaja con una base de datos SQLite y queremos que nunca pueda ejecutar DROP TABLE ni DELETE FROM sin aprobación explícita.

En el frontmatter del subagente definimos un hook que salte en el evento PreToolUse cuando detecte un comando de Bash, y que en ese momento ejecute el script scripts/proteger-db.sh:

---
name: db-agent
description: Trabaja con bases de datos SQLite
tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/proteger-db.sh"
---

Y en ./scripts/proteger-db.sh:

#!/bin/bash

# Leer el input JSON que Claude Code envía por stdin
INPUT=$(cat)

# Extraer el comando que va a ejecutar
COMANDO=$(echo "$INPUT" | jq -r '.tool_input.command')

# Si contiene DROP TABLE o DELETE FROM, bloquearlo
if echo "$COMANDO" | grep -iE '\b(DROP TABLE|DELETE FROM)\b' > /dev/null; then
  echo "Bloqueado: operación destructiva detectada: $COMANDO" >&2
  exit 2
fi

# Si no, dejarlo pasar
exit 0

Si Claude intenta ejecutar sqlite3 mi.db "DELETE FROM usuarios WHERE id=5", el hook intercepta la acción, detecta “DELETE FROM” y ejecuta exit 2.

Los códigos de salida le indican a Claude qué hacer con el evento recibido:

  • 0: deja pasar. Todo correcto.
  • 1: error genérico, pero Claude continúa igualmente.
  • 2: bloquea la acción y muestra el mensaje de stderr a Claude.

Hay muchos eventos disponibles; me remito a la documentación para no desviarme demasiado en esta introducción. A modo de referencia, algunos de los más útiles: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, Stop, TaskCompleted, PreCompact, SessionEnd.

Por último, los hooks no son exclusivos de los subagentes. Funcionan en tres niveles:

1. Sesión principal (settings.json): se aplican a toda la sesión de Claude Code.

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "SubagentStart": [...],
    "SubagentStop": [...]
  }
}

2. Subagente (en el frontmatter): solo se aplican mientras ese subagente está activo.

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validar.sh"

3. Agente principal con --agent: cuando arrancas Claude Code con claude --agent mi-agente, los hooks del frontmatter de ese agente también se aplican, exactamente igual que en un subagente.

6.3. Crear un subagente

Hay dos maneras principales de crear un agente.

A. Desde Claude (recomendado)

  1. Abre la consola y escribe:
/agents

  1. Se abre una interfaz con dos pestañas:

    • Running: subagentes que están corriendo ahora mismo.
    • Library: todos los subagentes disponibles; aquí creas nuevos.

    Selecciona Library y luego Create new agent.

  2. Elige la ubicación:

    • Personal: se guarda en ~/.claude/agents/ (disponible en todos tus proyectos).
    • Project: se guarda en .claude/agents/ (solo en este proyecto).

  3. Selecciona Generate with Claude y descríbele lo que quieres. Por ejemplo:

Quiero un agente que revise si he introducido vulnerabilidades en el código cuando haga commit.
  1. Claude genera el frontmatter y el system prompt.
  2. Ajusta herramientas, modelo y permisos desde la interfaz.
  3. Pulsa s o Enter para guardar.

B. Manualmente

Un subagente es simplemente un archivo .md con esta estructura:

---
name: nombre-del-agente
description: Cuándo debe usarse este agente
tools: Read, Bash, Grep
model: sonnet
---

Aquí va el system prompt.
Explica el rol del agente, qué debe hacer
y cómo debe comportarse.

Lo guardas en:

# Para todos tus proyectos
~/.claude/agents/nombre-del-agente.md

# Solo para el proyecto actual
.claude/agents/nombre-del-agente.md

De momento lo dejamos aquí. Para quien quiera profundizar: