Sub-agents & Multi-Agent Workflows

Codex can spawn sub-agents — child instances that work on delegated tasks while the parent session continues. This enables multi-agent workflows where independent tasks run in parallel: one sub-agent writes tests while another implements the feature, or one sub-agent refactors Module A while another refactors Module B.

Sub-agents inherit the parent's AGENTS.md context but operate in their own context window. They can be configured via the [agents] block in config.toml, where you define agent names, their model assignments, and their specializations.

# Configure sub-agents
[agents.test-writer]
model = "gpt-4.1"
description = "Writes comprehensive test suites"

[agents.reviewer]
model = "o3"
reasoning_effort = "high"
description = "Reviews code changes for correctness and style"

For more sophisticated orchestration, Codex integrates with the OpenAI Agents SDK. This lets you build programmatic multi-agent pipelines where agents hand off work to each other, share context through structured messages, and produce traces for debugging. The Agents SDK is Python-based and provides primitives for agent definition, tool binding, hand-offs, and observability.

Hand-offs are the key concept: Agent A works on a task until it reaches a decision point, then hands off to Agent B with context about what was done and what is needed next. Each hand-off is a trace event that you can inspect later.