Subagents in OpenAI Codex
Subagents enable Codex to spawn specialized agents in parallel to handle complex, multi-step tasks efficiently. This documentation covers how to use subagent workflows, define custom agents with specific configurations, and manage agent orchestration.
Key Features
- Parallel Agent Execution: Spawn multiple specialized agents simultaneously to handle different aspects of a task
- Custom Agent Definition: Create tailored agents with specific models, instructions, and configurations
- Built-in Agents: Includes default, worker, and explorer agents for different task types
- CSV Batch Processing: Experimental feature for processing CSV data with multiple agents
- Sandbox Inheritance: Subagents inherit parent session's sandbox policies and approval controls
- Agent Management: Tools for switching between agents, inspecting threads, and controlling execution
Use Cases
- Code Review: Parallel review of security, code quality, bugs, and maintainability aspects
- Complex Task Decomposition: Breaking down large tasks like codebase exploration or feature implementation
- Batch Processing: Handling multiple similar tasks simultaneously using CSV input
- Specialized Workflows: Creating agents optimized for specific tasks like documentation research or UI debugging
Technical Implementation
Custom agents are defined using TOML configuration files stored in ~/.codex/agents/ (personal) or .codex/agents/ (project-scoped). Each agent requires:
- name: Unique identifier for the agent
- description: Human-readable guidance on when to use the agent
- developer_instructions: Core behavior-defining instructions
Optional configurations include model selection, reasoning effort levels, sandbox modes, MCP server connections, and skill configurations.
Configuration Settings
Global subagent settings in config.toml include:
agents.max_threads: Controls concurrent agent threads (default: 6)agents.max_depth: Limits agent nesting depth (default: 1)agents.job_max_runtime_seconds: Timeout for CSV batch jobs
Subagents consume more tokens than single-agent runs due to parallel model and tool work, but provide significant efficiency gains for complex, parallelizable tasks.
