agents
.
Descripción General
Los subagentes pueden definirse de dos maneras al usar el SDK:- Programáticamente - Usando el parámetro
agents
en las opciones de tuquery()
(recomendado para aplicaciones SDK) - Basado en sistema de archivos - Colocando archivos markdown con frontmatter YAML en directorios designados (
.claude/agents/
)
agents
, que proporciona una experiencia de desarrollo más integrada para aplicaciones SDK.
Beneficios de Usar Subagentes
Gestión de Contexto
Los subagentes mantienen contexto separado del agente principal, previniendo la sobrecarga de información y manteniendo las interacciones enfocadas. Este aislamiento asegura que las tareas especializadas no contaminen el contexto de conversación principal con detalles irrelevantes. Ejemplo: Un subagenteresearch-assistant
puede explorar docenas de archivos y páginas de documentación sin saturar la conversación principal con todos los resultados de búsqueda intermedios - solo devolviendo los hallazgos relevantes.
Paralelización
Múltiples subagentes pueden ejecutarse concurrentemente, acelerando dramáticamente los flujos de trabajo complejos. Ejemplo: Durante una revisión de código, puedes ejecutar subagentesstyle-checker
, security-scanner
, y test-coverage
simultáneamente, reduciendo el tiempo de revisión de minutos a segundos.
Instrucciones y Conocimiento Especializados
Cada subagente puede tener prompts de sistema personalizados con experiencia específica, mejores prácticas y restricciones. Ejemplo: Un subagentedatabase-migration
puede tener conocimiento detallado sobre mejores prácticas de SQL, estrategias de rollback y verificaciones de integridad de datos que serían ruido innecesario en las instrucciones del agente principal.
Restricciones de Herramientas
Los subagentes pueden limitarse a herramientas específicas, reduciendo el riesgo de acciones no intencionadas. Ejemplo: Un subagentedoc-reviewer
podría tener acceso solo a herramientas Read y Grep, asegurando que pueda analizar pero nunca modificar accidentalmente tus archivos de documentación.
Creando Subagentes
Definición Programática (Recomendada)
Define subagentes directamente en tu código usando el parámetroagents
:
Configuración de AgentDefinition
Campo | Tipo | Requerido | Descripción |
---|---|---|---|
description | string | Sí | Descripción en lenguaje natural de cuándo usar este agente |
prompt | string | Sí | El prompt de sistema del agente definiendo su rol y comportamiento |
tools | string[] | No | Array de nombres de herramientas permitidas. Si se omite, hereda todas las herramientas |
model | 'sonnet' | 'opus' | 'haiku' | 'inherit' | No | Anulación de modelo para este agente. Por defecto usa el modelo principal si se omite |
Definición Basada en Sistema de Archivos (Alternativa)
También puedes definir subagentes como archivos markdown en directorios específicos:- Nivel de proyecto:
.claude/agents/*.md
- Disponible solo en el proyecto actual - Nivel de usuario:
~/.claude/agents/*.md
- Disponible en todos los proyectos
agents
) tienen precedencia sobre los agentes basados en sistema de archivos con el mismo nombre.
Cómo el SDK Usa Subagentes
Al usar el SDK de Claude Agent, los subagentes pueden definirse programáticamente o cargarse desde el sistema de archivos. Claude:- Carga agentes programáticos del parámetro
agents
en tus opciones - Auto-detecta agentes del sistema de archivos de directorios
.claude/agents/
(si no se anulan) - Los invoca automáticamente basado en coincidencia de tareas y la
description
del agente - Usa sus prompts especializados y restricciones de herramientas
- Mantiene contexto separado para cada invocación de subagente
agents
) tienen precedencia sobre los agentes basados en sistema de archivos con el mismo nombre.
Subagentes de Ejemplo
Para ejemplos comprensivos de subagentes incluyendo revisores de código, ejecutores de pruebas, depuradores y auditores de seguridad, consulta la guía principal de Subagentes. La guía incluye configuraciones detalladas y mejores prácticas para crear subagentes efectivos.Patrones de Integración del SDK
Invocación Automática
El SDK invocará automáticamente subagentes apropiados basado en el contexto de la tarea. Asegúrate de que el campodescription
de tu agente indique claramente cuándo debe usarse:
Invocación Explícita
Los usuarios pueden solicitar subagentes específicos en sus prompts:Configuración Dinámica de Agentes
Puedes configurar agentes dinámicamente basado en las necesidades de tu aplicación:Restricciones de Herramientas
Los subagentes pueden tener acceso restringido a herramientas vía el campotools
:
- Omitir el campo - El agente hereda todas las herramientas disponibles (por defecto)
- Especificar herramientas - El agente solo puede usar las herramientas listadas
Combinaciones Comunes de Herramientas
Agentes de solo lectura (análisis, revisión):Documentación Relacionada
- Guía Principal de Subagentes - Documentación comprensiva de subagentes
- Guía de Configuración del SDK - Descripción general de enfoques de configuración
- Configuraciones - Referencia de archivo de configuración
- Comandos Slash - Creación de comandos personalizados