Esta semana circula un fragmento de configuración: establece agents.max_concurrent_threads_per_session = 64 en tu config.toml de Codex y observa cómo una sola sesión se despliega en decenas de subagentes. La publicación que lo originó afirma que el valor predeterminado es 3 y que OpenAI probó 64. La opción de configuración existe. Los dos números no aparecen en la documentación, y lo interesante no es el límite en absoluto: es lo que le ocurre al trabajo cuando lo subes.
Este artículo explica qué hace realmente esta opción según la referencia de Codex, y las tres cosas que fallan en orden cuando una sola sesión ejecuta más agentes de los que una persona puede leer.
TL;DR
agents.max_concurrent_threads_per_session limita cuántos hilos de agentes generados mantiene abiertos Codex a la vez, sin contar el hilo principal. La referencia no publica un valor predeterminado; dice que Codex elige uno cuando la clave no está definida. Los subagentes devuelven resúmenes al hilo principal, que espera a todos ellos y responde una sola vez; además, la documentación los recomienda para trabajo intensivo en lectura y advierte de que los flujos de trabajo paralelos intensivos en escritura generan conflictos y sobrecarga de coordinación. Subir el límite a 64 pone a prueba precisamente esos dos puntos: archivos compartidos y una única respuesta consolidada que nadie puede auditar. Sharkly ejecuta Codex como Runtime y sube el paralelismo un nivel, donde cada ejecución es una Tarea con su propio worktree, su propio registro y su propio revisor.
Qué hace esta opción de configuración
Tres claves de la sección [agents] de config.toml son relevantes aquí. El texto que sigue proviene de la referencia de configuración.
| Clave | Lo que dice la referencia |
|---|---|
agents.max_concurrent_threads_per_session |
«Número máximo de hilos de agentes generados que pueden estar abiertos de forma concurrente, excluyendo el hilo principal. Si no se define, Codex elige el valor predeterminado». |
agents.max_threads |
«Alias heredado de agents.max_concurrent_threads_per_session». |
agents.enabled |
«Activa o desactiva las herramientas multiagente (predeterminado: true)». |
Otras dos claves relacionadas, agents.default_subagent_model y agents.default_subagent_reasoning_effort, determinan en qué se ejecutan los agentes generados, a menos que la llamada de creación indique otra cosa.
Así que el fragmento funciona tal cual está escrito:
[agents]
max_concurrent_threads_per_session = 64
Lo que la referencia no dice es cuál es el valor predeterminado ni que se haya probado ningún valor concreto. Hasta que la documentación diga lo contrario, considera «predeterminado 3» y «OpenAI probó 64» como afirmaciones de una publicación, no del proveedor.
La guía de subagentes añade las dos frases que determinan si merece la pena subir el límite. Sobre los resultados: «Cuando hay muchos agentes en ejecución, Codex espera hasta que todos los resultados solicitados estén disponibles y, a continuación, devuelve una respuesta consolidada». Sobre cuándo usarlos: los subagentes son adecuados para «tareas intensivas en lectura, como exploración, pruebas, triaje y resumen», y la guía recomienda precaución con «flujos de trabajo paralelos intensivos en escritura, porque varios agentes editando código a la vez pueden crear conflictos y aumentar la sobrecarga de coordinación».
Lee ambas cosas juntas y el orden de los fallos se escribe solo.
Lo que falla primero: el checkout compartido
Los subagentes de una misma sesión comparten el directorio de trabajo de la sesión, a menos que organices lo contrario. Eso no supone ningún problema con sesenta y cuatro agentes que solo leen. Pero es un problema de fusión con cuatro agentes que escriben.
El fallo no es nada espectacular. Dos subagentes editan el mismo archivo, la segunda escritura se impone y el resumen consolidado informa de que ambas tareas se han completado. Te enteras en la revisión, si es que la haces, o en producción si no la haces. La advertencia de la documentación sobre conflictos y sobrecarga de coordinación se refiere exactamente a esto.
La solución es la misma a la que converge cualquier configuración de agentes en paralelo: una copia de trabajo por unidad de trabajo. En Sharkly, cada ejecución de Tarea recibe un directorio aislado, y el trabajo respaldado por un repositorio usa un worktree de git independiente por ejecución, el mecanismo que se explica en agentes en paralelo en worktrees aislados. Diez Tareas sobre un mismo repositorio, cero estado compartido. El Runtime que hace la edición puede seguir siendo Codex; el aislamiento se añade a su alrededor.
Lo que falla en segundo lugar: la respuesta consolidada
Codex espera a todos los subagentes y devuelve una única respuesta. Con cuatro subagentes, eso es una comodidad. Con sesenta y cuatro, es un solo mensaje que resume sesenta y cuatro unidades de trabajo, escrito por el agente que las despachó, con la salida intermedia oculta.
Esa forma no sirve para revisar. Quien revisa necesita saber qué tocó cada unidad de trabajo, qué ejecutó y dónde se detuvo, y necesita poder aceptar o rechazar cada una por separado. Un resumen de resúmenes no se puede aceptar parcialmente.
Sharkly guarda la respuesta final del Agente en la Tarea y mantiene un registro de ejecución por cada ejecución con el disparador, la hora de inicio y de finalización, las llamadas a herramientas, los eventos del Runtime y los detalles de los fallos. Las ejecuciones están en su propia pestaña, separadas de la cronología de comentarios. Sesenta y cuatro unidades de trabajo son sesenta y cuatro Tareas con sesenta y cuatro registros, cada una revisable, y cada una devuelve su resultado al lugar donde una persona va a mirar.
Lo que falla en tercer lugar: la persona en el bucle
El límite no dice nada sobre qué ocurre cuando un subagente necesita a una persona. Dentro de una sesión, un subagente bloqueado es un hilo que se ha quedado en silencio dentro de una espera consolidada. El hilo principal no puede responder por ti, y no puedes ver cuál de los sesenta y cuatro hilos es el que se ha detenido.
Sharkly mantiene separados el estado de la Tarea y el estado de trabajo del Agente: una Tarea iniciada puede mostrar Trabajando, Esperando respuesta humana, Esperando revisión humana o Error. Las señales de espera y de fallo llegan a la sección Primary de la Bandeja de entrada de la persona responsable, y una respuesta en la Tarea inicia la ejecución de seguimiento con el hilo como contexto. Así, el que se ha atascado te lo dice, en lugar de quedarse colgado en una espera que no puedes inspeccionar.
¿Subagentes o Tareas? Cómo decidir entre ambos
Usa los subagentes de Codex dentro de una misma sesión cuando el trabajo sea intensivo en lectura y converja en una sola respuesta: explorar un código base, hacer triaje de un lote de fallos, resumir un conjunto de documentos, ejecutar una batería de pruebas. Para eso los recomienda la guía, y subir el límite sale barato cuando nada escribe.
Usa Tareas independientes, cada una asignada a un Agente en un Computer, cuando las unidades de trabajo escriban código, cuando distintas personas vayan a revisar partes distintas o cuando una persona pueda necesitar responder a mitad de la ejecución. Sharkly no sustituye a Codex; Codex es el Runtime que ejecuta cada Tarea. La diferencia está en dónde vive el paralelismo: dentro de la espera consolidada de una sesión, o en un tablero donde el contexto, el progreso, los bloqueos, los resultados y la revisión humana permanecen visibles desde la solicitud hasta la entrega.
Subir el límite de forma segura
Si vas a subir max_concurrent_threads_per_session, hazlo como describen los propios documentos de concurrencia de Sharkly para los Computers: auméntalo solo cuando la configuración actual gestione la carga de trabajo existente de forma fiable, porque una mayor concurrencia consume más CPU, memoria, disco, capacidad del proveedor y ancho de banda del repositorio. Un Computer de Sharkly tiene su propio límite de concurrencia de tareas, y los Agentes que usan directorios temporales toman la mitad de ese límite de forma predeterminada. La capacidad está limitada por el Computer, la concurrencia del Agente y la disponibilidad de directorios; además, un Agente en línea puede seguir teniendo trabajo en cola cuando esa capacidad está llena.
La capacidad del proveedor es la que todo el mundo olvida. Sesenta y cuatro hilos contra una sola clave de API son sesenta y cuatro formas de alcanzar un límite de peticiones a la vez, y un 429 que significa «cuota agotada» no se arregla reintentando. El registro de ejecuciones fallidas de Sharkly conserva la respuesta original del proveedor junto a un título claro, de modo que la diferencia se ve antes de que nadie reintente.
Preguntas frecuentes
¿Cuál es el valor predeterminado de agents.max_concurrent_threads_per_session? La referencia de configuración no indica ninguno. Dice que Codex elige el valor predeterminado cuando la clave no está definida. Los números que circulan en redes sociales no proceden de la referencia.
¿Subir el límite hace que Codex sea más rápido? En un despliegue intensivo en lectura, más hilos terminan antes. En el trabajo intensivo en escritura, la documentación advierte de que las ediciones concurrentes crean conflictos y sobrecarga de coordinación, lo que cuesta más tiempo del que ahorra el paralelismo.
¿Los subagentes de Codex se ejecutan en worktrees de git separados? La guía de subagentes no dice que lo hagan. Planifica como si compartieran el directorio de trabajo, a menos que hayas configurado el aislamiento por tu cuenta.
¿Cómo usa Sharkly Codex? Como Runtime. Un Computer que ejecuta Codex lo reporta como disponible, y las Tareas asignadas a un Agente de ese Computer se ejecutan a través de él, cada ejecución en su propio directorio aislado o worktree.
¿Puedo seguir usando subagentes dentro de una Tarea de Sharkly? Sí. Todo lo que el Runtime puede hacer por su cuenta sigue funcionando dentro de la ejecución. Sharkly añade alrededor la Tarea, el aislamiento, el registro y la revisión.
La versión corta
La opción de configuración existe y el fragmento funciona. Lo que no hace es que sesenta y cuatro ediciones concurrentes sean seguras, que una única respuesta consolidada sea revisable ni decirte qué hilo te está esperando. Esas son las tres cosas que fallan, en ese orden. Reserva los subagentes para el despliegue intensivo en lectura y lleva el trabajo paralelo intensivo en escritura a un tablero donde cada ejecución tenga su propio worktree y su propio revisor. Conecta un Computer con Codex instalado, crea un Agente y asígnale algo aburrido. La documentación explica cada concepto con más detalle: docs.sharkly.ai.
