Codex Subagentes (Subagents)

Los subagentes (Subagents) son una función avanzada de Codex que te permite descomponer tareas grandes en partes más pequeñas, procesándolas en paralelo o secuencialmente. Esta sección detalla cómo configurar y usar subagentes.


¿Qué son los subagentes?

Los subagentes son agentes auxiliares que Codex puede invocar en paralelo para manejar diferentes partes de tareas complejas. Al configurar subagentes, puedes:

  • Descomponer tareas grandes en partes manejables
  • Procesar múltiples tareas independientes en paralelo
  • Configurar agentes especializados para diferentes tipos de tareas
  • Mejorar la eficiencia en el manejo de proyectos grandes

Los subagentes son especialmente adecuados para escenarios que requieren manejar múltiples archivos o múltiples tareas independientes al mismo tiempo.


Configurar subagentes

Configuración básica

Configurar subagentes

# Habilitar la funcionalidad de múltiples agentes
[features]
multi_agent = true

# Configurar parámetros del agente
[agents]
# Número máximo de hilos paralelos
max_threads = 6

# Profundidad máxima de anidamiento
max_depth = 1

# Tiempo máximo de ejecución del trabajo (segundos)
job_max_runtime_seconds = 1800

Roles de agente personalizados

Puedes definir roles de agente personalizados en la configuración:

Definir rol de agente

# Definir un agente de revisión de código
[agents.reviewer]
description = "Enfocado en revisión de código y problemas de calidad"
nickname_candidates = ["Reviewer", "CodeChecker", "QualityBot"]

# Puede apuntar a un archivo de configuración
# config_file = "agents/reviewer.toml"

Usar subagentes

Llamar manualmente a los subagentes

En Codex, puedes llamar a los subagentes de las siguientes maneras:

Llamar a los subagentes

# Usar @ para mencionar al subagente
@reviewer revisar src/archivo auth.py

# Usar el comando /agents
/agents run reviewer --task "Revisar todos los archivos de prueba"

Uso automático de subagentes

Codex puede elegir automáticamente usar subagentes según la tarea. Por ejemplo, para tareas grandes de refactorización, Codex puede iniciar automáticamente varios subagentes para manejar diferentes módulos.


Cómo funcionan los subagentes

Procesamiento paralelo

Cuando las tareas se pueden dividir en partes independientes, los subagentes pueden trabajar en paralelo:

任务:审查整个代码库
  ├─ 子代理 1:审查 src/auth/ 目录
  ├─ 子代理 2:审查 src/api/ 目录
  ├─ 子代理 3:审查 src/utils/ 目录
  └─ 主代理:汇总结果

Procesamiento secuencial

Cuando las tareas tienen dependencias, los subagentes trabajan secuencialmente:

任务:实现新功能
  └─ 子代理 1:创建数据模型
       └─ 子代理 2:创建 API 端点
            └─ 子代理 3:编写测试

Profundidad de anidamiento

El parámetro max_depth en la configuración controla el número de niveles que los agentes pueden anidar:

  • Nivel 0: sesión raíz
  • Nivel 1: subagentes directos
  • Nivel 2: subagentes de los subagentes
Se recomienda mantener max_depth en 1 o 2, ya que un anidamiento demasiado profundo aumenta la complejidad y los costos.

Llamadas a herramientas

Los subagentes pueden usar todas las herramientas estándar de Codex:

  • Leer y editar archivos
  • Ejecutar comandos
  • Usar habilidades
  • Llamar a servidores MCP

Resumen de resultados

El agente principal es responsable de resumir los resultados de todos los subagentes y proporcionar una salida unificada.


Configuración de roles de agente

Crear roles de agente personalizados

Crear archivo de configuración de rol de agente

# agents/tester.toml

description = "Enfocado en escribir pruebas unitarias y de integración"
nickname_candidates = ["Tester", "TestBot", "QABot"]

[behavior]
# Configuración del comportamiento del agente
test_framework = "pytest" # Framework de pruebas preferido
include_coverage = true # Requiere incluir informe de cobertura

Referenciar en la configuración principal

Referenciar la configuración del agente

[agents.tester]
config_file = "agents/tester.toml"

Monitorear subagentes

Ver agentes activos

Ver agentes activos

# Ver en Codex
/agents status

# Ver detalles
/agents list

Salida del agente

Codex mostrará la salida de cada subagente y resumirá los resultados en la interfaz principal.

Cuando los subagentes están en ejecución, se muestra un indicador de progreso para que conozcas el estado general de la tarea.

Mejores prácticas

Descomposición de tareas

  • Dividir tareas grandes en subtareas independientes
  • Asegurarse de que no haya dependencias fuertes entre subtareas (cuando puedan ser paralelas)
  • Definir entradas y salidas claras para cada subtarea

Optimización de configuración

  • Ajustar max_threads según la complejidad de la tarea
  • Configurar roles de agente especializados para diferentes tipos de tareas
  • Establecer un job_max_runtime_seconds razonable para evitar ejecuciones prolongadas

Monitoreo y depuración

  • Revisar periódicamente la salida de los subagentes
  • Usar /agents status para conocer el progreso general
  • Si es necesario, se puede cancelar subagentes específicos
Los subagentes son una función avanzada; se recomienda familiarizarse primero con las operaciones básicas de Codex antes de usarlos.

Preguntas frecuentes

P: ¿Cuál es la diferencia entre subagentes y habilidades?

Los subagentes son agentes de IA independientes que pueden ejecutar tareas complejas de varios pasos. Las habilidades son flujos de trabajo predefinidos que se centran en tipos específicos de tareas.

P: ¿Cuántos subagentes pueden ejecutarse simultáneamente como máximo?

Se configura mediante max_threads, el valor predeterminado es 6. La cantidad real disponible depende de tu plan de suscripción.

P: ¿Pueden los subagentes acceder a mis archivos?

Sí, los subagentes pueden leer y modificar archivos, pero están limitados por el sandbox y las políticas de seguridad.

P: ¿Cómo depurar problemas con los subagentes?

Usa /agents status para ver el estado de los agentes y revisa sus registros de salida para localizar el problema.

Otras extensiones