OpenAI Codex 서브에이전트 패치노트 핵심 변경점 정리
OpenAI가 Codex에 서브에이전트 워크플로우 를 정식 출시(GA)하며 코드 생성 워크플로우의 변화 가능성을 키웠습니다. Codex 서브에이전트는 복잡한 개발 작업을 여러 에이전트에 병렬로 분배해 처리하는 멀티 에이전트 시스템으로, 기존 단일 세션 기반 코딩 지원을 보완합니다.
이번 업데이트는 코드베이스 탐색, PR 리뷰, 멀티스텝 기능 구현처럼 병렬 처리가 유리한 작업에 초점을 맞췄습니다. 기존 코딩 에이전트와는 다른 병렬 팬아웃(fan-out) 방식의 운영 구조를 제시합니다.
Codex 서브에이전트 업데이트 배경 (OpenAI Codex 서브에이전트)
기존 Codex는 단일 세션에서 코드 생성, 분석, 리뷰를 모두 처리했지만, 복잡한 프로젝트에서는 보안 검토, 코드 품질 점검, 문서 확인 등 여러 관점을 동시에 다뤄야 합니다. OpenAI는 이 문제를 해결하기 위해, 사용자가 명시적으로 요청하면 전문화된 서브에이전트를 병렬로 스폰(spawn)하는 구조를 도입했습니다.
서브에이전트 아키텍처는 메인 Codex 세션이 오케스트레이션을 담당하고, 스폰된 각 에이전트가 병렬로 독립 실행된 뒤 결과를 통합 응답으로 반환하는 구조입니다. 사용자가 자연어 프롬프트로 에이전트 스폰을 요청하면, Codex가 라우팅, 대기, 결과 수집까지 처리합니다.
핵심 개념 : 서브에이전트는 사용자의 명시적 요청에 의해서만 생성되며, 각자 독립적으로 모델 호출과 도구 사용을 수행한 뒤 통합 결과를 반환합니다. 자동 분배가 아닌 사용자 주도 방식입니다.
이번 업데이트의 핵심 목적은 병렬 처리가 필요한 대규모 작업에서 AI 지원 범위를 넓히는 데 있습니다. 코드베이스 탐색, 멀티포인트 PR 리뷰, CSV 기반 대량 배치 처리처럼 단일 에이전트로는 비효율적인 작업을 효과적으로 분담할 수 있습니다.
핵심 변경사항 상세 분석
Codex 서브에이전트 시스템은 3개의 내장 에이전트와 사용자 정의 커스텀 에이전트로 구성됩니다. 내장 에이전트인 default는 범용 폴백 역할, worker는 구현과 수정 중심의 실행 에이전트, explorer는 읽기 위주의 코드베이스 탐색 에이전트입니다. 이 외에 필요한 전문 에이전트는 TOML 파일로 직접 정의해 사용합니다.
커스텀 에이전트는
~/.codex/agents/
(개인용) 또는
.codex/agents/
(프로젝트용) 경로에 TOML 파일을 추가해 정의합니다. 각 파일에는
name
,
description
,
developer_instructions
가 필수이며, 모델 종류, 추론 노력 수준, 샌드박스 모드, MCP 서버 연동까지 세밀하게 설정할 수
있습니다.
에이전트 스폰 방식도 주목할 부분입니다. Codex는 자동으로 서브에이전트를 생성하지 않으며, 사용자가 자연어 프롬프트로 명시적으로 요청해야 합니다. 예를 들어 "PR의 보안, 코드 품질, 버그, 테스트 안정성을 각각 에이전트로 검토해줘"처럼 구체적으로 지시하면, Codex가 에이전트별로 작업을 스폰하고 모든 결과가 준비되면 통합 응답을 반환합니다.
실행 제어 옵션도 충실합니다.
agents.max_threads
(기본값 6)로 동시 실행 에이전트 수를 제한하고,
agents.max_depth
(기본값 1)로 에이전트 중첩 깊이를 관리합니다. 서브에이전트는 부모 세션의 샌드박스 정책과 승인
설정을 상속하므로, 보안 경계가 일관되게 유지됩니다.
대량 작업을 위한 CSV 배치 처리 기능(
spawn_agents_on_csv
)도 실험적으로 제공됩니다. CSV 파일의 각 행을 하나의 작업 단위로 삼아 워커 에이전트를 병렬로
스폰하고, 결과를 다시 CSV로 내보내는 방식입니다. 파일별 감사, 인시던트별 분석, 마이그레이션 대상
일괄 점검 같은 반복 작업에 적합합니다.
보안 관점에서는 별도의 내장 Security Agent가 존재하지는 않지만, 커스텀 에이전트로 보안 전담
리뷰어를 구성할 수 있습니다. 예를 들어
sandbox_mode = "read-only"
로 코드 수정 권한을 제거한 리뷰 전용 에이전트를 만들고, PR 리뷰 시 보안·코드품질·버그를 각각 다른
에이전트에 맡기는 워크플로우를 구성하는 방식이 공식 문서에서 권장됩니다.
개발자 워크플로우 영향 및 전망
서브에이전트 시스템이 도입되면서 개발자의 역할은 코드 작성자에서 AI 협업 오케스트레이터로 확장되고 있습니다. 복잡한 PR 리뷰에서는 "보안, 코드 품질, 버그, 레이스 컨디션, 테스트 안정성, 유지보수성을 각각 에이전트로 검토해줘"와 같이 고수준 지시만 내리면 Codex가 병렬 처리를 맡습니다.
개발 현장에서 눈에 띄는 변화는 코드 리뷰 프로세스입니다. 커스텀 에이전트로 구성한 리뷰어가 1차 병렬 리뷰를 수행해 팀 리뷰 부담을 줄이고, 휴먼 리뷰어가 비즈니스 로직과 아키텍처 검토에 더 집중할 수 있도록 돕습니다. 공식 문서에서는 explorer로 코드 경로를 탐색하고, reviewer로 리스크를 찾고, docs_researcher로 API 문서를 검증하는 3에이전트 조합을 예시로 제시합니다.
- 병렬 PR 리뷰로 리뷰 사이클 시간 단축
- CSV 배치 처리로 반복 감사·마이그레이션 작업 자동화
- 커스텀 에이전트를 프로젝트별로 공유해 팀 워크플로우 표준화
- read-only 샌드박스와 에이전트별 모델 지정으로 비용·보안 세분화
엔터프라이즈 도입 관점에서는 프로젝트 단위로
.codex/agents/
디렉터리에 커스텀 에이전트를 배치해 개발 표준을 공유할 수 있습니다. 동일한 에이전트 구성을 통해
리뷰 기준과 코딩 가이드라인을 팀 전체에 일관되게 적용할 수 있어, 코드 스타일 편차를 줄이는 데
유리합니다.
주의사항
: 각 서브에이전트가 독립적으로 모델 호출과 도구 사용을 수행하므로, 단일 에이전트 실행보다 토큰
소비량이 크게 증가합니다.
agents.max_threads
와 에이전트별 모델 선택(예: 빠른 작업에는 gpt-5.3-codex-spark)으로 비용을 관리해야 합니다.
현재 서브에이전트 활동은 Codex App과 CLI에서 확인할 수 있으며, IDE Extension 지원은 아직 준비
중입니다. CLI에서는
/agent
명령으로 활성 에이전트 스레드를 전환하고 상태를 확인할 수 있습니다.
주니어 개발자 교육과 온보딩에서도 활용 여지가 있습니다. explorer 에이전트로 코드베이스를 탐색한 결과를 학습 자료로 활용하거나, 커스텀 에이전트에 코드 리뷰 기준을 상세히 기술해 시니어 리뷰어의 관점을 팀에 전파하는 방식이 가능합니다.
마무리
OpenAI Codex 서브에이전트는 단순 코드 생성 도구를 넘어 병렬 워크플로우를 통해 개발 작업의 범위를 넓히고 있습니다. 3개 내장 에이전트(default, worker, explorer)를 기반으로 TOML 커스텀 에이전트를 자유롭게 조합해, PR 리뷰부터 대량 배치 감사까지 다양한 시나리오에 대응할 수 있는 구조를 제공합니다.
개발자의 역할도 코드 작성 중심에서 AI 협업 관리 중심으로 이동하는 추세입니다. 이 변화는 더 높은 난도의 문제 해결과 의사결정에 집중할 시간을 확보하는 방향으로 이어질 수 있습니다.
이번 업데이트는 AI 기반 개발 도구의 새로운 패러다임을 보여주며, 소프트웨어 개발 방식 전반의 변화를 가속하는 계기가 될 수 있습니다. 상세한 설정 방법과 예시는 공식 서브에이전트 문서 에서 확인할 수 있습니다.