Cómo ejecutar los subagentes de Claude Code con otro modelo: configuración y mediciones al delegar en Sonnet o Haiku

Quieres que la sesión principal de Claude Code siga en Opus 5 y con el esfuerzo (effort) alto. Pero usar ese mismo modelo para trabajos como traducir o revisar montones de archivos parece un desperdicio. De ahí la pregunta: ¿se pueden ejecutar solo los subagentes con Sonnet o Haiku?

La respuesta corta: sí. El modelo de un subagente se decide por separado del de la sesión principal, y puedes cambiarlo indicándolo al invocar el subagente, con model en el archivo de definición o con una variable de entorno. El esfuerzo también se puede fijar con un valor distinto para cada subagente.

En este artículo repaso lo que dice la documentación oficial a 15 de septiembre de 2026 y después muestro lo que pasó cuando lancé subagentes con otros modelos y lo comprobé en los registros de conversación. Encargué la misma traducción a Opus 5, Sonnet 5 y Haiku 4.5, dos veces a cada uno, y comparé el tiempo, el coste y la calidad de la traducción.

1. Qué se puede hacer: subagentes con otro modelo y otro esfuerzo

Un subagente es un trabajador con su propio contexto que Claude Code lanza para delegarle parte de una tarea. No comparte el historial de la conversación con la sesión principal y, al terminar, solo le devuelve el resultado (la diferencia con los Agent Teams se trata en Subagents vs Agent Teams en Claude Code).

Para los subagentes, la documentación oficial indica que se pueden fijar por separado estas dos cosas.

Es decir, una combinación como «sesión principal con Opus 5 y esfuerzo high, traductor con Sonnet 5 y esfuerzo medium» se puede montar tal cual dentro del comportamiento oficial. Para saber qué significa el propio esfuerzo, consulta Claude Code: el ajuste de esfuerzo (effort) explicado.

Fuente: documentación oficial de Claude Code, «Create custom subagents» (Supported frontmatter fields), «Model configuration» (prioridad del esfuerzo)

2. El orden en que se decide el modelo

Como muestra la figura del principio, el modelo de un subagente es la primera coincidencia en este orden: el modelo indicado al invocarlo → model en el archivo de definición → la variable de entorno CLAUDE_CODE_SUBAGENT_MODEL → el modelo de la sesión principal. Conviene vigilar tres puntos.

Primero, el orden depende de la versión. Antes de la v2.1.251, la variable de entorno estaba arriba del todo y se imponía incluso al modelo indicado al invocar y al model del archivo de definición (incluido inherit). Si escribiste model: sonnet en una definición y no parece surtir efecto, comprueba primero la versión y las variables de entorno.

Segundo, hay un ajuste aparte para forzar un único modelo en todo. Con la variable de entorno sola, los subagentes cuyo archivo de definición indica model no le hacen caso. Para forzarlos a todos, además de CLAUDE_CODE_SUBAGENT_MODEL, pon CLAUDE_CODE_SUBAGENT_MODEL_FORCE a 1 (v2.1.257 y posteriores).

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Al forzarlo, se ignora el model de los archivos de definición, también en los integrados Explore y Plan, y Claude ya no puede indicar un modelo al invocar un subagente. Hay dos excepciones que se quedan con el modelo de la sesión principal: un fork, que hereda la conversación entera, y una skill con model: inherit que se ejecuta en un subagente.

Tercero, a dónde apuntan sonnet y opus depende del proveedor. Aunque escribas el mismo sonnet, el modelo resultante cambia así.

Fuente: documentación oficial de Claude Code, «Model configuration» (tabla a 15 de septiembre de 2026). Para fijar una versión concreta, escribe el ID de modelo completo en lugar de un alias

Si la configuración administrada de tu organización limita los modelos disponibles (availableModels), el model de los subagentes y la variable de entorno también quedan sujetos a esa limitación.

3. Cómo configurarlo (cinco formas)

1. Escribirlo en el archivo de definición (para roles que siempre deben usar el mismo modelo)

Lo más práctico es crear un archivo de definición por rol. Si lo pones en .claude/agents/ del proyecto, puedes compartirlo con git; para usarlo en todos tus proyectos, ponlo en ~/.claude/agents/.

---
name: translator
description: Traduce artículos en japonés al inglés. Úsalo cuando te pidan una traducción
model: sonnet
effort: medium
tools: Read, Write, Grep
---
Eres traductor de artículos técnicos. No cambies las etiquetas ni los atributos HTML;
convierte solo el texto visible en un inglés natural.

Cuando hay varias definiciones con el mismo nombre, la prioridad es esta: configuración administrada de la organización, --agents al arrancar, proyecto, usuario y plugins. Desde la v2.1.198, el comando /agents ya no abre una pantalla de creación, así que pídele a Claude que cree el archivo o escríbelo tú directamente.

2. Indicarlo al invocar (para cambiarlo solo esa vez)

Aunque no crees una definición, Claude puede añadir un modelo al lanzar un subagente. Si en la conversación pides algo como «encarga esta revisión a un subagente con Haiku», Claude lanza el subagente con ese modelo añadido a la llamada. Esta indicación tiene prioridad sobre el archivo de definición. Para comprobar que de verdad se añadió, usa el método de la sección 5.

3. Fijar un valor por defecto con una variable de entorno (para cambiar de golpe todo lo que no indica modelo)

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
  }
}

Si lo escribes en env de settings.json, se aplica a los subagentes cuyo modelo no se haya decidido de otra forma. Según la documentación oficial, también cubre a los miembros de los equipos de agentes y a los agentes de los flujos de trabajo. Pero esto solo no cambia el modelo de los integrados Explore y Plan (sección 4).

4. Pasarlo con --agents al arrancar (solo para esa sesión)

claude --agents '{
  "translator": {
    "description": "Translates Japanese articles into English.",
    "prompt": "You are a technical translator. Keep all HTML tags.",
    "model": "sonnet",
    "effort": "medium"
  }
}'

No se guarda en ningún archivo: solo sirve mientras dura esa sesión.

5. Definirlo en el Claude Agent SDK

from claude_agent_sdk import ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "translator": AgentDefinition(
            description="Translates Japanese articles into English.",
            prompt="You are a technical translator. Keep all HTML tags.",
            tools=["Read", "Write"],
            model="sonnet",
            effort="medium",
        ),
    }
)

En el AgentDefinition del SDK, model también admite un alias, inherit o un ID de modelo completo. Si no lo indicas, se decide según el orden de arriba. Además, la documentación oficial señala que Opus 5 reparte trabajo entre subagentes con más facilidad que los modelos anteriores y remite a ajustes para limitar cuántos se ejecutan a la vez (20 por defecto) y cuánto dinero gastan.

Fuente: documentación oficial de Claude Code, «Create custom subagents» (ubicaciones y prioridad, --agents, el cambio en /agents, variables de entorno), «Model configuration» (a qué se aplica CLAUDE_CODE_SUBAGENT_MODEL), «Subagents in the SDK» (AgentDefinition, ajustes de límites)

4. Con qué modelo funcionan los subagentes integrados

Aunque no definas nada, Claude Code trae de serie varios subagentes. Sus modelos son estos.

Fuente: documentación oficial de Claude Code, «Create custom subagents» (Built-in subagents, a 15 de septiembre de 2026)

Desde la v2.1.198, Explore ya no se ejecuta siempre con Haiku. Hereda el modelo de la sesión principal, con Opus como tope en la API de Claude. Si la sesión principal usa un modelo superior como Fable, Explore se ejecuta con Opus; si usa Sonnet o Haiku, se ejecuta con ese modelo. Para volver a Haiku, la documentación oficial propone crear un archivo de definición llamado Explore y escribir model: haiku (tu propia definición tiene prioridad sobre la integrada del mismo nombre).

Para cambiar el modelo de Explore y Plan con la variable de entorno, también hay que configurar CLAUDE_CODE_SUBAGENT_MODEL_FORCE, de la sección 2.

5. Medición 1: ¿de verdad se ejecutó con ese modelo?

Comprobé si se comporta según la documentación en mi propio entorno (sesión principal con Opus 5 y esfuerzo high). Le encargué al subagente integrado general-purpose la misma tarea pequeña, «lee el README y resúmelo en tres líneas», de tres formas: con el modelo indicado como sonnet, como haiku y sin indicarlo.

Hay dos formas de comprobarlo. Mientras se ejecuta, la lista de /tasks muestra el modelo del subagente (así lo indica la documentación oficial). Cuando ya ha terminado, mira message.model en cada respuesta de los archivos agent-*.jsonl de la carpeta subagents/ de tus registros de conversación locales. Dónde están los registros y cómo leerlos lo explico en detalle en Uso de Claude Code por sesión: cómo medirlo.

Fuente: mediciones propias (15 de septiembre de 2026, app de escritorio en Windows. Todas las respuestas de cada subagente registraron el mismo modelo)

Cada uno se ejecutó con el modelo indicado, y el que no lo indicaba heredó el de la sesión principal. En el archivo agent-*.meta.json de la misma carpeta, el valor indicado, como "model": "sonnet", solo aparece cuando se indicó un modelo.

6. Medición 2: decenas de miles de tokens solo por arrancar

Los mismos registros revelaron otra cosa. Un subagente lee decenas de miles de tokens solo en su primera respuesta, antes de empezar a trabajar. Se debe a que lo primero que entra es su propio prompt de sistema, las definiciones de herramientas, CLAUDE.md, etc.

Fuente: mediciones propias (15 de septiembre de 2026. Tokens de la primera respuesta de cada subagente. Todas las escrituras fueron en la caché de 5 minutos)

De estas cifras se deducen tres cosas.

Primero, los subagentes del mismo modelo leen de la caché la parte inicial que comparten. En el segundo arranque, con Sonnet 5, unos 45,000 tokens fueron lecturas de caché (0.1 veces el precio de entrada). La documentación oficial también dice que las solicitudes al mismo modelo con el mismo comienzo comparten caché. En cambio, la caché es independiente para cada modelo, y los subagentes tampoco leen la caché de la sesión principal (porque el contenido inicial es distinto).

Segundo, incluso con suscripción, la caché de los subagentes caduca a los 5 minutos. Según la documentación oficial, al usarlo dentro de un plan, la conversación principal tiene 1 hora, pero los subagentes, 5 minutos. Si dejas pasar más de 5 minutos antes de lanzar el siguiente subagente, vuelve a empezar con una escritura. Para que sea 1 hora, pon en 1h el ajuste subagentPromptCacheTtl o la variable de entorno CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL (v2.1.242 y posteriores). Si quieres decidirlo para cada subagente, escribe cacheTtl dentro de experimental en el archivo de definición (v2.1.248 y posteriores; mientras una suscripción esté usando créditos de uso adicionales (usage credits), el 1h que pongas ahí se ignora). En la caché de 1 hora, la escritura cuesta 2 veces el precio de entrada (en la de 5 minutos, 1.25 veces).

Tercero, Haiku 4.5 da menos tokens para el mismo texto. Según la página oficial de precios, los modelos a partir de Claude 4.7 usan un tokenizador nuevo que cuenta alrededor de un 30% más de tokens para el mismo texto. Haiku 4.5 es de una generación anterior a la 4.7 y no figura entre los modelos que usan el tokenizador nuevo. Si comparas las cifras de la tabla tal cual, Haiku parece más ligero de lo que es.

Si repartes tareas pequeñas entre muchos subagentes, este «coste solo por arrancar» se suma por cada uno. Encargar el trabajo a un modelo más barato abarata también esta parte, no solo el trabajo en sí.

Fuente: documentación oficial de Claude Code, «How Claude Code uses prompt caching» (caché por modelo, subagentes y caché, duración de la caché), Claude Platform Docs, «Pricing» (tokenizador, multiplicadores de la caché), documentación oficial de Claude Code, «Create custom subagents» (omitClaudeMd)

7. Medición 3: la misma traducción, dos veces en cada uno de tres modelos

Probé de verdad la idea del principio, «bajar de modelo solo la traducción». Elegí una sección de la versión japonesa de un artículo de este sitio (6,265 caracteres de HTML, con una tabla, tarjetas de cifras y fragmentos de código) y encargué a cada modelo traducirla al inglés sin cambiar la estructura de etiquetas, dos veces con las mismas instrucciones: seis ejecuciones en total. Opus 5 y Sonnet 5 usaron el esfuerzo high heredado de la sesión principal (Haiku 4.5 no admite el esfuerzo).

Fuente: mediciones propias (15 de septiembre de 2026. El coste es a precio de lista: tokens de los registros de conversación multiplicados por los precios oficiales. No incluye la salida; ver la nota de abajo)

La columna de coste no incluye la salida porque los tokens de salida de los registros no eran fiables. Hubo un caso en que una respuesta que escribió en un archivo una traducción de unos 8,800 caracteres quedó registrada con 18 tokens de salida. El precio de salida por millón de tokens es de $25 en Opus 5, $10 en Sonnet 5 y $5 en Haiku 4.5, y todas las traducciones al inglés rondaron entre 8,500 y 8,900 caracteres.

La calidad de la traducción la revisé yo mismo, comparando frase por frase con el original japonés.

• En ninguna de las seis ejecuciones encontré errores de sentido. Las cifras, las tablas y los enlaces internos se conservaron correctamente. Eso sí, es un texto con muchas cifras y listas, de los fáciles de traducir
• Las diferencias estuvieron en la legibilidad y la coherencia de los términos. Haiku 4.5 mezcló en la 1.ª ejecución «my» y «the author's» para la primera persona, y en la 2.ª produjo un orden de palabras rígido como «G from 9th rises to 6th». Sonnet 5 escribió un inglés natural, pero puso «subagent» como «Sub-agent» en la 1.ª y como «Subagent» en la 2.ª, así que la grafía varió de una ejecución a otra. Opus 5 mantuvo los términos coherentes las dos veces
• El que más tardó fue el más barato, Haiku 4.5. Sonnet 5 tardó casi el doble en una ejecución que en la otra. Con tan pocas ejecuciones, toma el orden de velocidad solo como orientación

8. Cómo afecta al coste y a los límites de uso

Cuánto se gana al bajar de modelo los subagentes depende de si pagas por uso con la API o usas una suscripción como Pro o Max.

API de pago por uso: la proporción de precios se aplica tal cual

Fuente: Claude Platform Docs, «Pricing» (por millón de tokens, a 15 de septiembre de 2026. El precio de lanzamiento de Sonnet 5 pasó a ser su precio normal)

Sonnet 5 cuesta dos quintos de lo que cuesta Opus 5, y Haiku 4.5, un quinto. En las mediciones de la sección 7, la parte de entrada y caché de Sonnet 5 fue aproximadamente la mitad que la de Opus 5, y la de Haiku 4.5, alrededor de un quinto. Haiku 4.5 queda cerca de la proporción de precios, mientras que Sonnet 5 sale por encima de los dos quintos, porque el número de respuestas y la cantidad leída en cada una variaron según el modelo (Sonnet 5 hizo 4 y 6 respuestas, y Opus 5, 4 en ambas; Haiku 4.5 además usa otro tokenizador).

Suscripciones: hay límites que no se recuperan al cambiar de modelo

En Pro y Max, el límite de sesión y el límite semanal son comunes a todos los modelos. Si ya los agotaste, cambiar de modelo con /model no te permite seguir. Aparte, hay límites por familia de modelos, como el «límite de Opus» y el «límite de Sonnet», y solo cuando alcanzas uno de esos puedes continuar cambiando a un modelo de fuera de esa familia.

🟡 No se ha publicado cuánto más duran los límites del plan si los subagentes usan Sonnet o Haiku. La proporción de precios de la API sirve de orientación, pero en ningún sitio dice que los límites se consuman en esa misma proporción. Para ver qué subagentes consumen más, revisa el desglose del plan en /usage (porcentajes por Skill, subagente, plugin y servidor MCP).

Fuente: documentación oficial de Claude Code, «Error reference» (You've hit your session limit: límites comunes a todos los modelos y límites por familia de modelos), «Manage costs effectively» (el desglose del plan en /usage)

9. Qué trabajo bajar a un modelo más barato

Como orientación, la documentación oficial indica que Sonnet resuelve bien la mayoría de las tareas de programación y cuesta menos que Opus, que conviene reservar Opus para decisiones de arquitectura complejas o razonamientos de varios pasos, y que para tareas sencillas de subagentes se indique model: haiku en el archivo de definición. También recomienda Sonnet para los miembros de los equipos de agentes.

Sobre esa base, estos son tres criterios que saco de las mediciones de la sección 7 y de cómo gestiono este sitio.

Si dudas, lo más seguro es encargar solo una de tus tareas habituales al modelo más barato y comparar el resultado con el de tu modelo actual. Basta con cambiar una línea, el model del archivo de definición, y si no encaja puedes volver atrás enseguida. Si lo que quieres repartir es el modelo de la sesión principal y no el de un subagente, con Opus solo para planificar y Sonnet para implementar, eso lo hace opusplan; consulta ¿Qué es opusplan en Claude Code?

Preguntas frecuentes

Q1. Si cambio el /model de la sesión principal a mitad de conversación, ¿cambian también los subagentes?
Los subagentes cuyo modelo se decide al invocarlos, con el model del archivo de definición (salvo inherit) o con la variable de entorno no cambian. Los que no tienen ninguna de esas indicaciones y los que tienen inherit en el archivo de definición siguen el modelo de la sesión principal. Ten en cuenta que, al cambiar el modelo de la sesión principal, su caché se tiene que volver a crear.

Q2. ¿Puedo bajar solo el esfuerzo sin cambiar de modelo?
Sí. Si escribes algo como effort: medium en el archivo de definición, ese esfuerzo se aplica solo mientras se ejecuta ese subagente. Pero si la variable de entorno CLAUDE_CODE_EFFORT_LEVEL está definida, tiene prioridad.

Q3. En Amazon Bedrock, ¿qué modelo da model: sonnet?
Según la documentación oficial a 15 de septiembre de 2026, Sonnet 4.5. En la API de Anthropic es Sonnet 5, así que el mismo archivo de definición da resultados distintos según el proveedor. Si quieres fijar la versión, escribe el ID de modelo completo.

Q4. ¿Compensa poner la caché de los subagentes en 1 hora?
Depende de cómo trabajes. Si lanzas muchas veces el mismo tipo de subagente dejando pasar más de 5 minutos entre uno y otro, reduces las escrituras repetidas. En cambio, en la caché de 1 hora la escritura cuesta 2 veces el precio de entrada (1.25 veces en la de 5 minutos), así que si solo los ejecutas en ráfagas cortas, la de 5 minutos sale más barata. Los ajustes para la caché de 1 hora y sus condiciones están en la sección 6.

Q5. Indiqué un modelo, pero parece que no surte efecto.
Comprueba esto en orden: (1) que no esté activado CLAUDE_CODE_SUBAGENT_MODEL_FORCE (hace que se ignore lo indicado en el archivo de definición), (2) que no uses una versión anterior a la v2.1.251 con la variable de entorno definida y (3) que la configuración administrada de tu organización permita ese modelo. Para ver con qué modelo se ejecutó realmente, usa /tasks mientras se ejecuta o message.model en los registros de conversación cuando haya terminado.

Fuentes

• Claude Code Docs — Create custom subagents (campos del archivo de definición, el orden en que se decide el modelo y sus diferencias entre versiones, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagentes integrados, ubicaciones y prioridad, --agents, omitClaudeMd, comprobación con /tasks)
• Claude Code Docs — Model configuration (a dónde apuntan los alias, a qué se aplica CLAUDE_CODE_SUBAGENT_MODEL, prioridad del esfuerzo, availableModels)
• Claude Code Docs — How Claude Code uses prompt caching (caché por modelo, duración de la caché de los subagentes, subagentPromptCacheTtl y cómo indicarlo con la variable de entorno y el archivo de definición)
• Claude Code Docs — Manage costs effectively (orientación para elegir modelo, la recomendación de Sonnet para los miembros de los equipos de agentes, el desglose de /usage)
• Claude Code Docs — Error reference (límites comunes a todos los modelos y límites por familia de modelos)
• Claude Code Docs — Subagents in the SDK (model y effort de AgentDefinition, Opus 5 y los ajustes de límites)
• Claude Code Docs — Orchestrate teams of Claude Code sessions (cómo se decide el modelo de los miembros de los equipos de agentes)
• Claude Platform Docs — Pricing (precios por modelo, multiplicadores de la caché, tokenizador)

Artículos relacionados

• Subagents vs Agent Teams en Claude Code: qué es un subagente
• Claude Code: el ajuste de esfuerzo (effort) explicado: qué significa el esfuerzo
• Uso de Claude Code por sesión: cómo medirlo: cómo leer los registros de conversación
• ¿Qué se está comiendo el contexto de Claude Code?: por qué CLAUDE.md se lee cada vez
• ¿Qué es opusplan en Claude Code?: poner la sesión principal en Opus solo durante el modo de planificación
• Ahorra tokens en Claude Code: 10 consejos y costes extra: otros sitios donde recortar