YouTip

Subagents are an advanced feature of Codex that allow you to break down large tasks into smaller parts, processing them in parallel or sequentially. This section details how to configure and use subagents. * * * ## What are Subagents? Subagents are auxiliary agents that Codex can call in parallel to handle different parts of complex tasks. By configuring subagents, you can: * Break down large tasks into manageable parts * Process multiple independent tasks in parallel * Configure specialized agents for different types of tasks * Improve efficiency when handling large projects > Subagents are particularly suitable for scenarios that require processing multiple files or multiple independent tasks simultaneously. !(#) * * * ## Configuring Subagents ### Basic Configuration ## Configuring Subagents # Enable multi-agent feature multi_agent = true # Configure agent parameters # Maximum parallel threads max_threads = 6 # Maximum nesting depth max_depth = 1 # Maximum job runtime (seconds) job_max_runtime_seconds = 1800 ### Custom Agent Roles You can define custom agent roles in your configuration: ## Defining Agent Roles # Define a code review agent [agents.reviewer] description = "Focused on code review and quality issues" nickname_candidates = ["Reviewer", "CodeChecker", "QualityBot"] # Can point to a configuration file # config_file = "agents/reviewer.toml" * * * ## Using Subagents ### Manually Calling Subagents In Codex, you can call subagents using the following methods: ## Calling Subagents # Use @ to mention a subagent @reviewer Review the src/auth.py file # Use the /agents command /agents run reviewer --task"Review all test files" ### Automatic Subagent Usage Codex can automatically choose to use subagents based on the task. For example, for large refactoring tasks, Codex may automatically launch multiple subagents to handle different modules. * * * ## How Subagents Work ### Parallel Processing When tasks can be broken down into independent parts, subagents can work in parallel: Task: Review entire codebase ├─ Subagent 1: Review src/auth/ directory ├─ Subagent 2: Review src/api/ directory ├─ Subagent 3: Review src/utils/ directory └─ Main agent: Aggregate results ### Sequential Processing When tasks have dependencies, subagents work in sequence: Task: Implement new feature └─ Subagent 1: Create data model └─ Subagent 2: Create API endpoints └─ Subagent 3: Write tests ### Nesting Depth The max_depth in configuration controls how many layers agents can be nested: * Depth 0: Root session * Depth 1: Direct subagents * Depth 2: Subagents of subagents > It is recommended to keep max_depth at 1 or 2, as deeper nesting increases complexity and cost. * * * ### Tool Calling Subagents can use all of Codex's standard tools: * Reading and editing files * Executing commands * Using skills * Calling MCP servers ### Result Aggregation The main agent is responsible for aggregating results from all subagents, providing unified output. * * * ## Agent Role Configuration ### Creating Custom Agent Roles ## Creating Agent Role Configuration Files # agents/tester.toml description = "Focused on writing unit tests and integration tests" nickname_candidates = ["Tester", "TestBot", "QABot"] # Agent behavior configuration test_framework = "pytest" # Preferred testing framework include_coverage = true # Require coverage report ### Referencing in Main Configuration ## Referencing Agent Configuration [agents.tester] config_file = "agents/tester.toml" * * * ## Monitoring Subagents ### Viewing Active Agents ## Viewing Active Agents # View in Codex /agents status # View detailed information /agents list ### Agent Output Codex displays the output of each subagent and aggregates results in the main interface. > Progress indicators are displayed while subagents are running, letting you know the overall task status. * * * ## Best Practices ### Task Decomposition * Break down large tasks into independent subtasks * Ensure subtasks don't have strong dependencies (when they can run in parallel) * Define clear inputs and outputs for each subtask ### Configuration Optimization * Adjust max_threads based on task complexity * Configure specialized agent roles for different types of tasks * Set reasonable job_max_runtime_seconds to avoid long-running jobs ### Monitoring and Debugging * Regularly check subagent output * Use /agents status to understand overall progress * Cancel specific subagents when necessary > Subagents are an advanced feature. It is recommended to familiarize yourself with Codex's basic operations before using them. * * * ## Frequently Asked Questions ### Q: What is the difference between subagents and skills? Subagents are independent AI agents that can execute complex multi-step tasks. Skills are predefined workflows focused on specific types of tasks. ### Q: How many subagents can run simultaneously? Configured through max_threads, the default is 6. The actual available quantity depends on your subscription plan. ### Q: Can subagents access my files? Yes, subagents can read and modify files, but are subject to sandbox and security policy restrictions. ### Q: How do I debug subagent issues? Use /agents status to view agent status, and check their output logs to locate problems.