Cómo los subagentes obtienen su propio contexto y herramientas
Un subagente no es una versión más pequeña de la sesión principal de Claude Code.
//
Busca en todas las páginas de la documentación
Un subagente no es una versión más pequeña de la sesión principal de Claude Code.
Es una instancia separada, con una ventana de contexto que comienza casi vacía y una lista de herramientas que puede ser más reducida que la del agente principal.
Comprender por qué existe ese aislamiento, en lugar de tratarlo como un detalle de implementación, es lo que permite usar bien los subagentes en lugar de simplemente invocarlos por reflejo.
Cada sesión de Claude Code tiene una ventana de contexto, el registro en ejecución de todo lo dicho y hecho en esa conversación hasta el momento.
Un subagente obtiene su propia ventana de contexto, no una parte compartida de la del agente principal.
Cuando el agente principal invoca un subagente, escribe un prompt de tarea que describe exactamente lo que el subagente debe hacer, y ese prompt de tarea es efectivamente el punto de partida completo del contexto del subagente.
El subagente no hereda los turnos anteriores del agente principal, sus lecturas de archivos anteriores, ni su hilo de pensamiento en curso, a menos que el agente principal reitere explícitamente esa información en el prompt de tarea.
Una analogía simple: entregar trabajo a un subagente es como entregar una carpeta sellada de instrucciones a un contratista, no como incluir a un compañero de trabajo que ya estaba sentado en la sala durante toda la reunión.
El contratista realiza el trabajo descrito en la carpeta y luego entrega un informe escrito. No regresa a la sala y comienza a narrar todo lo que vio en el camino.
El aislamiento resuelve dos problemas separados, y ayuda nombrarlos por separado.
El primero es el presupuesto de contexto. Una ventana de contexto es finita. Si una tarea de investigación requiere cuarenta llamadas a herramientas para explorar una base de código, ejecutar esa investigación directamente en la sesión principal significa que cuarenta llamadas a herramientas (con sus contenidos de archivos, resultados de búsqueda y callejones sin salida) residen en el historial de la conversación principal, independientemente de si algo de eso resulta importante. Delegar esa investigación a un subagente significa que solo el resumen final del subagente, no sus cuarenta pasos intermedios, llega al contexto del agente principal.
El segundo es el ámbito de las herramientas. Un subagente puede configurarse con una lista de herramientas más reducida que los permisos del propio agente principal.
---
name: codebase-researcher
description: Investigación de solo lectura sobre cómo se implementa una característica específica
tools: Read, Grep, Glob
---
Investigas cómo se implementa una característica nombrada en la base de código y
informas las rutas de archivo y una breve descripción de cada una, en menos de 300 palabras.Esa línea tools es una restricción real, no una sugerencia. Un subagente definido de esta manera no puede llamar a Edit o Write, sin importar cómo esté redactado su prompt de tarea, porque esas herramientas simplemente no están en su conjunto disponible para esa invocación. Esto es lo que convierte el "aislamiento" de una conveniencia en un límite de seguridad real.
Cuando el agente principal invoca varios subagentes a la vez, cada uno obtiene su propio contexto independiente, que es exactamente lo que hace que ejecutarlos en paralelo sea seguro. Dos subagentes que investigan subsistemas diferentes no pueden leer o basarse accidentalmente en los hallazgos intermedios del otro, porque ninguno tiene acceso al contexto del otro en primer lugar.
El modelo de aislamiento tiene compensaciones reales, y tratarlo como gratuito llevaría a un uso excesivo de subagentes.
Invocar un subagente tiene un costo de latencia: iniciar un nuevo contexto, ejecutar la tarea y reportar es más lento que continuar directamente en la sesión principal para una tarea pequeña y bien definida. Una búsqueda de una línea no necesita un subagente; una exploración de cuarenta pasos generalmente sí.
El aislamiento también significa que un subagente puede perder el acceso a los matices que la sesión principal ha desarrollado a lo largo de una conversación larga. Si el agente principal ha estado depurando un problema sutil durante veinte turnos e invoca un subagente para verificar una hipótesis, el subagente solo sabe lo que el prompt de tarea del agente principal le dice, no los veinte turnos de contexto acumulado. Escribir un prompt de tarea que incluya lo suficiente de ese contexto, sin pegar la conversación completa, es una habilidad real, y subespecificarlo es una de las formas más comunes en que el informe de un subagente resulta menos útil de lo esperado.
También hay un ángulo de gobernanza que vale la pena nombrar explícitamente. Dado que el ámbito de las herramientas se aplica por subagente, un proyecto puede definir roles de subagente especializados: un investigador estrictamente de solo lectura, un ejecutor de pruebas con acceso a comandos de prueba pero no a ediciones de código fuente, un redactor de documentación limitado a archivos markdown solamente, cada uno con permisos ajustados a su trabajo real. Esa es una postura de seguridad significativamente diferente a la de una sola sesión con acceso amplio y uniforme que realiza todo tipo de tareas.
| Enfoque | Fortaleza | Debilidad | Mejor Ajuste |
|---|---|---|---|
| Trabajar directamente en la sesión principal | Sin sobrecarga de latencia, contexto completo en ejecución disponible | Cada paso exploratorio consume el presupuesto de contexto compartido | Tareas pequeñas y rápidas estrechamente vinculadas a la conversación en curso |
| Invocar un subagente | Mantiene la exploración fuera del contexto principal, puede reducir el ámbito de las herramientas | Añade latencia, el subagente comienza con contexto mínimo | Una investigación acotada o una tarea aislada con un entregable claro |
| Invocar varios subagentes en paralelo | El trabajo independiente ocurre concurrentemente, sin contaminación cruzada | Sobrecarga de coordinación, el agente principal debe sintetizar múltiples informes | Múltiples subtareas genuinamente independientes (por ejemplo, auditar subsistemas separados) |
Edit en su lista de herramientas genuinamente no puede editar archivos, independientemente de cómo esté redactado su prompt o de cómo se le pida.No necesariamente. La lista de herramientas de un subagente puede configurarse de forma más reducida que la del agente principal, y cualquier herramienta que no esté en esa lista simplemente no está disponible para él, independientemente de lo que pida la tarea.
No. El agente principal solo recibe el resumen que el subagente reporta al final; las lecturas de archivos individuales, búsquedas y pasos de razonamiento intermedios del subagente no se muestran al agente principal.
Debido a que el contexto de cada subagente es independiente, su investigación no puede contaminarse mutuamente. Dos subagentes que investigan subsistemas separados no influirán accidentalmente en los hallazgos del otro, ya que ninguno tiene visibilidad del trabajo del otro.
Ambos, pero el aspecto de seguridad es real, no cosmético. Un subagente limitado a herramientas de solo lectura no puede hacer una edición incluso si su prompt está redactado para intentar convencerlo de hacerlo, porque la herramienta no está disponible para ser llamada.
Sí, principalmente latencia. Iniciar un nuevo contexto y esperar a que el subagente complete su tarea y reporte lleva más tiempo que continuar directamente en la sesión principal, lo que es importante para tareas pequeñas.
El subagente no tiene nada más en lo que basarse, por lo que un prompt de tarea vago o insuficientemente especificado tiende a producir un informe vago o incompleto, ya que el subagente no puede inferir el contexto faltante de una conversación que nunca vio.
El mecanismo existe en la arquitectura subyacente, pero en la práctica la mayoría de los flujos de trabajo mantienen la invocación de subagentes a un solo nivel, delegada desde la sesión principal, para evitar acumular latencia y complejidad de coordinación.
El mecanismo es el mismo tipo de ventana de contexto, pero como comienza casi vacía, un subagente típicamente tiene mucho más margen disponible para su tarea específica que la sesión principal a mitad de una conversación larga.
No. Un subagente con Edit o Write en su lista de herramientas aún puede modificar archivos; el aislamiento se refiere al contexto y al ámbito de permisos, no a si puede actuar sobre la misma base de código en la que está trabajando el agente principal.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.
Revisado por Chris St. John·Última actualización: 16 jul 2026