Codex, Subagents 지원 시작

(developers.openai.com)

8P by GN⁺ 20시간전 | ★ favorite | 댓글 4개

OpenAI Codex가 서브에이전트 워크플로를 지원하여, 복잡한 작업을 여러 전문 에이전트에 병렬 분배하고 결과를 하나로 통합하는 기능 제공
사용자가 명시적으로 요청할 때만 서브에이전트를 생성하며, 각 에이전트가 독립적으로 모델과 도구를 사용하므로 토큰 소비량이 단일 에이전트보다 증가
커스텀 에이전트를 TOML 파일로 정의하여 모델, 샌드박스 모드, MCP 서버 등을 에이전트별로 독립 설정 가능
CSV 파일의 각 행을 하나의 작업 단위로 삼아 워커 에이전트를 일괄 생성하는 spawn_agents_on_csv 실험적 기능도 포함
코드 리뷰, 프론트엔드 디버깅 등 실전 시나리오별 커스텀 에이전트 조합 패턴을 공식 문서에서 직접 안내

서브에이전트 개요 및 가용성

Codex는 전문화된 에이전트를 병렬로 생성(spawn) 하고 결과를 하나의 응답으로 수집하는 서브에이전트 워크플로 지원
코드베이스 탐색이나 다단계 기능 구현 계획처럼 높은 병렬성이 필요한 복잡한 작업에 특히 유용
서브에이전트 워크플로에서는 작업에 따라 서로 다른 모델 설정과 지시사항을 가진 커스텀 에이전트도 정의 가능
현재 Codex 릴리스에서는 서브에이전트 워크플로가 기본 활성화 상태
서브에이전트 활동은 현재 Codex 앱과 CLI에서 확인 가능하며, IDE Extension에서의 가시성은 곧 추가 예정
사용자가 명시적으로 요청할 때만 서브에이전트를 생성하며, 각 서브에이전트가 자체 모델·도구 작업을 수행하므로 단일 에이전트 실행보다 토큰 소비가 많음

일반적인 워크플로

Codex가 에이전트 간 오케스트레이션을 처리: 새 서브에이전트 생성, 후속 지시 라우팅, 결과 대기, 에이전트 스레드 종료 포함
여러 에이전트가 실행 중일 때, Codex는 모든 요청 결과가 준비될 때까지 대기 후 통합 응답 반환
예시 프롬프트: 현재 PR에 대해 보안 이슈, 코드 품질, 버그, 레이스 컨디션, 테스트 불안정성, 유지보수성 각각에 에이전트 하나씩 생성하고 전체 결과를 요약하도록 요청

서브에이전트 관리

CLI에서 /agent 명령으로 활성 에이전트 스레드 간 전환 및 진행 중인 스레드 검사 가능
Codex에 직접 요청하여 실행 중인 서브에이전트를 조종, 중지, 또는 완료된 스레드를 종료 가능

승인 및 샌드박스 제어

서브에이전트는 사용자의 현재 샌드박스 정책을 상속
대화형 CLI 세션에서는 비활성 에이전트 스레드의 승인 요청이 메인 스레드 사용 중에도 표시될 수 있으며, 승인 오버레이에 소스 스레드 레이블이 표시됨
- o를 눌러 해당 스레드를 열고, 승인·거부·응답 가능
비대화형 흐름에서는 새로운 승인을 표시할 수 없어, 승인이 필요한 작업이 실패하고 오류가 상위 워크플로에 전달됨
자식 에이전트 생성 시 부모 턴의 라이브 런타임 오버라이드를 재적용: /approvals 변경이나 --yolo 같은 대화형 설정 포함
- 선택된 커스텀 에이전트 파일이 다른 기본값을 설정하더라도 부모의 설정이 우선
개별 커스텀 에이전트에 대해 샌드박스 설정을 별도로 오버라이드 가능 (예: 특정 에이전트를 읽기 전용 모드로 지정)

커스텀 에이전트

Codex에 기본 내장된 에이전트 3종 제공
- default: 범용 폴백 에이전트
- worker: 구현과 수정에 초점을 맞춘 실행 중심 에이전트
- explorer: 코드베이스 탐색을 위한 읽기 중심 에이전트
커스텀 에이전트 정의 시 ~/.codex/agents/(개인용) 또는 .codex/agents/(프로젝트 범위)에 독립 TOML 파일 추가
각 파일이 하나의 커스텀 에이전트를 정의하며, Codex가 이를 생성 세션의 설정 레이어로 로드
모든 커스텀 에이전트 파일에 반드시 포함해야 하는 필수 필드:
- name, description, developer_instructions
선택 필드: nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 등은 생략 시 부모 세션에서 상속

글로벌 설정

서브에이전트 글로벌 설정은 configuration 파일의 [agents] 섹션에 정의
agents.max_threads: 동시 오픈 에이전트 스레드 상한 (기본값 6)
agents.max_depth: 생성된 에이전트의 중첩 깊이 (기본값 1, 직접 자식 에이전트만 생성 허용, 더 깊은 중첩 방지)
agents.job_max_runtime_seconds: spawn_agents_on_csv 작업의 워커별 기본 타임아웃 (미설정 시 호출당 기본 1800초)
커스텀 에이전트 이름이 explorer 같은 내장 에이전트와 동일하면 커스텀 에이전트가 우선

커스텀 에이전트 파일 스키마

name (string, 필수): Codex가 에이전트를 생성하거나 참조할 때 사용하는 에이전트 이름
description (string, 필수): Codex가 이 에이전트를 언제 사용해야 하는지에 대한 사람 대상 가이드
developer_instructions (string, 필수): 에이전트의 동작을 정의하는 핵심 지시사항
nickname_candidates (string[], 선택): 생성된 에이전트의 표시 닉네임 풀
기타 지원되는 config.toml 키도 포함 가능: model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 등
Codex는 name 필드로 에이전트를 식별하며, 파일명과 에이전트 이름을 일치시키는 것이 가장 단순한 관례이나 name 필드가 진본(source of truth)

표시 닉네임

nickname_candidates는 동일 커스텀 에이전트를 여러 인스턴스로 실행할 때 UI에서 구별 가능한 레이블을 표시하기 위한 용도
닉네임은 표시 전용이며, Codex는 여전히 name으로 에이전트를 식별·생성
닉네임 후보는 비어 있지 않은 고유 이름 목록이어야 하며, ASCII 문자·숫자·공백·하이픈·밑줄 사용 가능
예시: reviewer 에이전트에 ["Atlas", "Delta", "Echo"] 닉네임을 설정하면, 앱과 CLI에서 닉네임이 표시되지만 기본 에이전트 타입은 reviewer로 유지

예시 1: PR 리뷰 패턴

리뷰를 세 개의 특화된 커스텀 에이전트로 분할하는 패턴
- pr_explorer: 코드베이스를 매핑하고 증거를 수집하는 읽기 전용 에이전트 (모델: gpt-5.3-codex-spark, reasoning effort: medium)
- reviewer: 정확성, 보안, 테스트 리스크를 찾는 PR 리뷰어 (모델: gpt-5.4, reasoning effort: high)
- docs_researcher: 전용 MCP 서버를 통해 프레임워크나 API 문서를 확인하는 문서 전문가 (모델: gpt-5.3-codex-spark, 읽기 전용)
프로젝트 설정: max_threads = 6, max_depth = 1
pr_explorer의 지시사항: 탐색 모드 유지, 실제 실행 경로를 추적, 파일과 심볼을 인용하며 부모 에이전트가 요청하지 않는 한 수정 제안 자제
reviewer의 지시사항: 소유자 관점에서 리뷰, 정확성·보안·동작 회귀·누락된 테스트 커버리지 우선, 가능한 경우 재현 단계 포함, 스타일 전용 코멘트는 실제 버그를 숨기지 않는 한 회피
docs_researcher의 지시사항: docs MCP 서버를 사용해 API, 옵션, 버전별 동작을 확인하고 링크나 정확한 참조와 함께 간결하게 응답, 코드 변경 금지
사용 예시 프롬프트: "이 브랜치를 main과 비교 리뷰. pr_explorer가 영향 받는 코드 경로를 매핑, reviewer가 실질적 리스크를 찾고, docs_researcher가 패치가 의존하는 프레임워크 API를 검증"

CSV 배치 처리: spawn_agents_on_csv (실험적)

실험적 기능으로 향후 변경 가능
유사한 작업이 많을 때, CSV의 한 행을 하나의 작업 단위로 삼아 워커 서브에이전트를 일괄 생성
Codex가 CSV를 읽고, 행당 워커 에이전트를 생성, 전체 배치 완료를 기다린 뒤 결과를 CSV로 내보내기
적합한 사용 사례:
- 행당 파일, 패키지, 서비스 하나를 리뷰
- 인시던트, PR, 마이그레이션 대상 목록을 점검
- 유사한 다수 입력에 대해 구조화된 요약 생성
도구 입력 파라미터: csv_path(소스 CSV), instruction(워커 프롬프트 템플릿, {column_name} 플레이스홀더 사용), id_column(안정적 항목 ID), output_schema(고정 JSON 형태), output_csv_path, max_concurrency, max_runtime_seconds
각 워커는 report_agent_job_result를 정확히 한 번 호출해야 하며, 결과 보고 없이 종료되면 해당 행이 오류로 표시
codex exec으로 실행 시 배치 진행 중 stderr에 한 줄 진행 상황 업데이트 표시
내보내기된 CSV에는 원본 행 데이터와 job_id, item_id, status, last_error, result_json 등 메타데이터 포함
관련 런타임 설정: agents.max_threads(동시 스레드 상한), agents.job_max_runtime_seconds(워커별 타임아웃, 호출별 max_runtime_seconds가 우선), sqlite_home(에이전트 작업과 내보내기 결과에 사용되는 SQLite 상태 저장 경로)

예시 2: 프론트엔드 통합 디버깅 패턴

UI 회귀, 불안정한 브라우저 흐름, 애플리케이션 코드와 실행 중인 제품을 교차하는 통합 버그에 유용한 패턴
세 개의 커스텀 에이전트 조합:
- code_mapper: 관련 프론트엔드·백엔드 코드 경로를 찾는 읽기 전용 탐색 에이전트 (모델: gpt-5.3-codex-spark, reasoning effort: medium)
- browser_debugger: 브라우저 도구를 사용해 이슈를 재현하고 증거를 캡처하는 UI 디버거 (모델: gpt-5.4, reasoning effort: high, sandbox: workspace-write)
  - 스크린샷, 콘솔 출력, 네트워크 증거를 위해 브라우저 도구 활용, 애플리케이션 코드 편집 금지
  - Chrome DevTools MCP 서버 연결 (http://localhost:3000/mcp, startup_timeout_sec: 20)
- ui_fixer: 이슈가 파악된 후 작고 타겟된 수정을 담당하는 구현 중심 에이전트 (모델: gpt-5.3-codex-spark, reasoning effort: medium)
  - 가장 작은 방어 가능한 변경을 수행, 관련 없는 파일은 건드리지 않으며 변경한 동작만 검증
사용 예시 프롬프트: "설정 모달이 저장에 실패하는 이유를 조사. browser_debugger가 재현, code_mapper가 해당 코드 경로를 추적, ui_fixer가 실패 모드 파악 후 최소한의 수정 구현"