Cómo crear y usar subagentes en Claude Code: una guía práctica

CometAPI
AnnaOct 22, 2025
Cómo crear y usar subagentes en Claude Code: una guía práctica

Los subagentes son una de las incorporaciones más útiles al ecosistema de Claude Code/Claude Agent: permiten dividir flujos de trabajo complejos en "equipos de IA" más pequeños y especializados, preservar el contexto del hilo principal y limitar de forma segura el acceso a las herramientas. Este artículo explica ¿Qué son los subagentes?, Cómo crearlos e invocarlos (CLI, sistema de archivos y SDK), el principios de diseño que debes seguir al construirlos y código de muestra concreto Puedes copiar y adaptar.

¿Qué son los subagentes?

A subagente Es un asistente de IA preconfigurado y de alcance limitado al que Claude Code (o el SDK de Claude Agent) puede delegar tareas. Cada subagente:

  • Tiene un nombre único y una descripción clara del propósito.
  • Corre en su ventana de contexto propia separado de la conversación principal (para que las largas cadenas de detalles no contaminen el contexto del orquestador).
  • Se puede configurar con un conjunto limitado de (lectura/escritura de archivos, bash, grep, herramientas MCP, etc.) y con una elección de modelo específica.
  • Contiene un mensaje del sistema (la personalidad y las instrucciones del subagente) que guía el comportamiento y las restricciones.

Estas propiedades hacen que los subagentes sean ideales para tareas que requieren muchos tokens (investigación, búsqueda en registros grandes), son sensibles a la seguridad (herramientas de escaneo o potencialmente destructivas) o son repetitivas y bien especificadas (verificación de estilo, ejecución de pruebas).

Anthropic ha estado iterando rápidamente: la CLI de Claude Code y el SDK del agente se han refactorizado y ampliado en el SDK de Claude AgentSe ha introducido soporte de complementos para agrupar agentes y personalizaciones relacionadas (comandos de barra, servidores MCP, ganchos) y Habilidades Proporcionan una forma de empaquetar flujos de trabajo de dominio para su reutilización en Claude.ai, Claude Code y el SDK del agente. Estas actualizaciones facilitan... compartir, instalar y versionar Subagentes en equipos y proyectos. Si planea crear flujos de trabajo de producción, debería evaluar el empaquetado de plugins y habilidades, así como los patrones de implementación basados ​​en SDK.

Por qué son importantes los subagentes

Tres razones por las que son inmediatamente útiles:

  1. Preservación del contexto Las búsquedas, pruebas o escaneos largos o ruidosos se ejecutan dentro de un subagente en lugar de saturar el contexto principal. Esto reduce el desperdicio de tokens y facilita el análisis de los resultados.
  2. Experiencia especializada — puede codificar el conocimiento y el comportamiento del dominio en un mensaje del sistema adaptado a la tarea (por ejemplo, un security-auditor que se centra en secretos, problemas de dependencia y uso inseguro del shell).
  3. Permisos más seguros — limitar las herramientas por subagente reduce el radio de explosión (un revisor de documentos puede tener herramientas de solo lectura; un ejecutor de pruebas tiene Bash pero no Edit).
  4. Paralelización Puede activar varios subagentes para que se ejecuten simultáneamente (por ejemplo: style-checker, security-scanner, test-runner) y luego recopilar sus breves resultados: una gran victoria para las verificaciones independientes y costosas.

Requisitos previos para el uso de subagentes en Claude Code

Antes de comenzar a crear subagentes, asegúrese de tener lo siguiente en su lugar:

1) Claude Code instalado y autenticado

Instale la CLI de Claude Code o utilice las integraciones web/IDE. Documentación de inicio rápido y configuración de CometAPI enumerar los métodos de instalación admitidos (paquete global npm o instaladores nativos) y mostrar cómo verificar su instalación con claude --version / claude doctor. También necesitarás un CometAPI cuenta (usar la clave de CometAPI para acceder al código de Claude es más económico y más conveniente que el modelo oficial), como se indica en la Guía de inicio rápido.

2) Nodo/entorno (para algunas rutas de instalación) y herramientas básicas de shell

Si realiza la instalación mediante el paquete npm, debería tener Node.js (Node 18+ es común en los ejemplos). Si pretende usar el SDK del Agente (JavaScript/TypeScript o Python), necesitará un proyecto con la dependencia del SDK instalada. Muchos tutoriales asumen el uso de herramientas de desarrollo estándar (Git, Bash, opcional). gh CLI para flujos de trabajo de GitHub).

3) Diseño del proyecto y CLAUDE.md

La mejor práctica es mantener los documentos auxiliares a nivel de repositorio (CLAUDE.md) y poner agentes dentro del ámbito del proyecto .claude/agents/ Para que los compañeros de equipo los hereden. Los archivos CLAUDE.md se extraen automáticamente al contexto de Claude y ayudan a guiar el comportamiento de forma consistente en todas las sesiones. Cada subagente es un archivo Markdown con YAML como frontmatter. Ejemplo mínimo:

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.
  • name es un identificador en minúsculas.
  • description Guía la invocación y coincidencia automática.
  • tools restringe el acceso a las herramientas (omite heredar todo).
  • model puede ser sonnet, opus, haiku o inherit.

4) Permisos y servidores MCP (opcional pero común)

Si sus flujos de trabajo utilizan servidores de Protocolo de Contexto de Modelo (MCP) o herramientas externas (Puppeteer, Sentry, herramientas REST personalizadas), asegúrese de que sus servidores MCP estén configurados y accesibles. Para operaciones sensibles (escritura, bash, confirmación de Git), tenga cuidado con la lista de permitidos y por agente. tools alcance.

Cómo crear subagentes en Claude Code

Puede crear subagentes de tres formas principales: a través de la CLI interactiva (/agents), como archivos Markdown del sistema de archivos o mediante programación a través del SDK del Agente. A continuación, se muestran las opciones paso a paso:

Claude Code admite tres formas prácticas de crear subagentes:

  1. CLI interactivo /agents UI — lo más rápido para la creación iterativa dentro de una sesión.
  2. Basado en el sistema de archivos — crear archivos Markdown con frontmatter YAML en .claude/agents/ (a nivel de proyecto) o ~/.claude/agents/ (nivel de usuario). Los agentes de proyecto tienen mayor prioridad.
  3. Programático (SDK del agente) — definir subagentes en el código a través de agents parámetro cuando llamas query()Recomendado para aplicaciones basadas en SDK. Este enfoque es ideal cuando los subagentes deben crearse dinámicamente o integrarse en una aplicación.

Flujo interactivo rápido (primer paso recomendado)

  1. Inicie Claude Code en su terminal o abra la paleta de comandos en VS Code.
  2. Ejecute la interfaz de subagentes con el comando slash:
/agents
  1. Selecciona Crear nuevo agenteSeleccione el alcance a nivel de proyecto o de usuario, complete el nombre, la descripción, las herramientas y el mensaje del sistema y guarde. Puede generar un borrador con Claude y luego refinarlo. Una vez guardado, el agente estará disponible en /agents y puede invocarse explícita o automáticamente.

Subagentes basados ​​en el sistema de archivos (Markdown + YAML frontmatter)

Los subagentes se almacenan como archivos Markdown con frontmatter YAML. Colóquelos en:

  • Alcance del proyecto: .claude/agents/*.md (máxima prioridad)
  • Ámbito de usuario: ~/.claude/agents/*.md

Estructura básica de archivos:

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

Algunas notas de implementación:

  • name Debe estar en minúsculas con guiones.
  • Omitiendo tools permitirá que el subagente herede todas las herramientas del hilo principal; enumerar las herramientas explícitamente aplica un modelo de mínimo privilegio.
  • Use model: 'inherit' para un comportamiento consistente con el hilo principal, o especifique un alias de modelo (por ejemplo, sonnet, opus, haiku).

Definición JSON de CLI (uso ad hoc/de sesión)

Puede definir subagentes temporales en línea al iniciar una sesión:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

Los agentes definidos por CLI son útiles para ejecuciones o experimentos programados; tienen menor prioridad que los agentes de proyecto, pero mayor que los agentes de usuario.

Definición programática (SDK del agente: recomendado para aplicaciones)

Si está creando una aplicación o automatización, defina subagentes programáticamente a través del SDK del agente. agents Parámetro (esta es la opción más integrada). Ejemplo (TypeScript):

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

El SDK también acepta agentes basados ​​en el sistema de archivos (se cargará .claude/agents/ archivos) si prefiere ese patrón. Los agentes programáticos son eficaces para flujos de trabajo dinámicos e integración de CI.

Para Python, el claude-agent-sdk El paquete admite patrones similares: puedes usar query() or ClaudeSDKClient y configurar opciones, herramientas y servidores MCP mediante programación. Consulte el repositorio del SDK de Python para obtener ejemplos de inicio rápido.

Cómo invocar subagentes

Delegación automática

Claude Code puede automáticamente Elija un subagente cuando una solicitud del usuario coincida con su propósito. Esto es útil para la orquestación en segundo plano, donde el agente principal dirige las tareas automáticamente al especialista adecuado. Utilice descripciones claras de los subagentes y solicitudes del sistema específicas para mejorar la precisión de la selección automática.

Invocación explícita (recomendada para mayor claridad)

Puedes invocar explícitamente un agente en una conversación:

> Use the code-reviewer subagent to check my recent changes

La invocación explícita es determinista y se recomienda para flujos de producción donde desea evitar una delegación inesperada.

Patrones de orquestación del SDK

Patrones comunes en aplicaciones SDK:

  • Tenedor + recoger: Inicie varios subagentes en paralelo, recopile la respuesta concisa de cada agente y luego resuma/fusione los resultados en el agente principal.
  • Bucle de supervisor:El orquestador asigna tareas a los subagentes, inspecciona los resultados y los acepta o solicita un nuevo cálculo o aclaración.
  • Ejecución en entorno aislado:Otorgar capacidades potencialmente peligrosas (implementar, ejecutar scripts) a un agente estrictamente restringido y requerir aprobación humana explícita antes de ejecutar.

Estos patrones se asignan a implementaciones prácticas que utilizan la administración de sesiones, los ganchos y las herramientas MCP del SDK del agente.

Cómo crear subagentes que sean útiles, seguros y componibles

1) Responsabilidad única e indicaciones claras

Cada subagente debe tener un propósito claro y un mensaje del sistema que especifique los límites, los criterios de éxito y el formato de salida. Si la salida deseada es estructurada (JSON, lista con viñetas, parche de código), instruya al subagente con precisión para reducir los errores de análisis.

2) Mínimo privilegio para las herramientas

Otorgar solo las herramientas que un subagente necesita. Por ejemplo, un revisor de documentos no necesita Write or BashEstablezca el modo de solo lectura siempre que sea posible y escale los permisos de las herramientas explícitamente cuando sea necesario. Esto reduce el riesgo y simplifica la auditoría.

3) Devolver resultados compactos y estructurados

Los subagentes deben regresar respuestas concisas y finales En lugar de rastros de pensamiento de larga duración. Un patrón común es: realizar un trabajo intensivo dentro del contexto del subagente y luego devolver un breve resumen con archivos adjuntos (parches, referencias de archivos, JSON). Esto maximiza la eficiencia del contexto para el orquestador.

4) Capacidad de prueba y control de versiones

Almacene archivos de subagente en el control de versiones, cree pruebas de integración continua (CI) que ejecuten ejecuciones reales con entradas pequeñas y fije modelos/conjuntos de herramientas. Si utiliza habilidades y complementos, adopte los patrones de versiones/mercado de complementos para gestionar actualizaciones y reversiones.

5) Ganchos de auditoría y puntos de control con intervención humana

Utilice los ganchos del SDK para interceptar las invocaciones de herramientas (ganchos PreToolUse) y requerir la aprobación humana para acciones destructivas. Registre todas las invocaciones de herramientas para auditorías reproducibles. El SDK proporciona mecanismos de ganchos y permisos para soportar este patrón.

Ejemplo de aplicación: una pequeña tubería similar a una de producción

A continuación se muestra un ejemplo compacto que muestra las piezas típicas: un agente de sistema de archivos, una invocación de SDK que utiliza dos agentes (uno para revisión, otro para pruebas) y una orquestación simple.

1) Agente del sistema de archivos: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2) Orquestación programática (Node.js)

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

Notas: la code-reviewer se almacena en el repositorio para su reutilización en equipo; la llamada al SDK demuestra que los agentes programáticos tienen prioridad y tools El alcance evita escrituras accidentales.

Temas y patrones avanzados

Configuración dinámica del agente

Cree fábricas de agentes parametrizadas que elijan modelos y conjuntos de herramientas según el entorno (desarrollo vs. producción) o los niveles de gravedad (por ejemplo, strict vs balanced modos de seguridad). Los ejemplos del SDK muestran cómo generar definiciones de agente en tiempo de ejecución.

Paralelización

Genere múltiples agentes de análisis de solo lectura en paralelo (estilo, seguridad, cobertura de pruebas) y agregue sus salidas JSON en el hilo principal. Esto reduce considerablemente el tiempo de ejecución de los repositorios grandes.

Agentes proporcionados por complementos

Los complementos pueden proporcionar subagentes empaquetados con el manifiesto del complemento; aparecen en /agents Junto con agentes personalizados, se puede invocar explícitamente. Úselo para distribuir agentes estandarizados entre equipos.

Dónde utilizar el código Claude CLI es más recomendable

Fue un placer anunciar que CometAPI ahora es totalmente compatible con la potente CLI de Claude Code. Solo necesita instalar Claude Code y autenticarse con la clave API de Comet y la dirección base obtenidas para utilizar el modelo API de Comet en Claude Code.

¿Por qué utilizar Claude Code a través de CometAPI?

Principales características de inteligencia artificial: genere, depure y optimice código fácilmente utilizando modelos creados específicamente para desarrolladores.

  • Selección de modelos flexible: Nuestra amplia gama de modelos le permite desarrollar de forma más fluida.
  • Integración perfecta: Las API siempre están disponibles. Integre Claude Code directamente en su flujo de trabajo en minutos.
  • Usar Claude Code a través de CometAPI ahorrará más costosLa API de Claude proporcionada por CometAPI tiene un 20% de descuento sobre el precio oficial y se actualiza con el último modelo oficial.

¿Listo para usar Claude Code CLI? Consulta el Guía de API  para obtener instrucciones detalladas.

Si quieres conocer más consejos, guías y novedades sobre IA síguenos en VK, X  y  Discord!

Vea también ¿Cómo instalar y ejecutar Claude Code a través de CometAPI?

Reflexiones finales

Tratar a los subagentes como micropersonas reutilizables y versionadasEmpieza poco a poco: haz una doc-reviewer y test-runner Para un repositorio, consúltelos .claude/agents/, y automatizarlos en CI usando headless claude -pItere sus indicaciones, agregue resultados estructurados y ajuste los permisos de las herramientas.

El modelo mental más útil: imagina a Claude como gerente de proyecto y a los subagentes como especialistas del equipo. El gerente delega tareas claramente definidas, agrega los entregables de los especialistas y redacta el informe final. Con el tiempo, verás mejoras en la confiabilidad, la capacidad de prueba y la posibilidad de automatizar grandes partes de los flujos de trabajo de los desarrolladores.

Leer Más

500+ Modelos en Una API

Hasta 20% de Descuento