핵심 요약
Codex의 서브에이전트 워크플로우는 여러 전문 에이전트를 병렬로 돌린 뒤 결과를 한 번에 취합해 복잡한 일을 빠르게 처리하는 방식입니다.
직접 "서브에이전트를 써 달라"고 요청할 때만 생성되며, 각 에이전트가 별도 작업을 하므로 토큰 비용이 늘어납니다.
커스텀 에이전트를 TOML로 정의해 역할·모델·샌드박스·도구(MCP/스킬)를 분리하고, CSV 한 줄당 에이전트 1개로 대량 작업을 팬아웃하는 실험 기능도 제공합니다.
서브에이전트 워크플로우가 해결하는 문제
한 에이전트에게 "코드 탐색 + 위험 분석 + 문서 검증 + 수정"을 모두 시키면, 한 번에 처리하긴 쉽지만 맥락이 지저분해지고(불필요한 정보가 대화에 쌓임) 작업 성격이 섞여 품질이 흔들릴 수 있습니다.
서브에이전트는 이를 "역할 분업"으로 바꿉니다. 예를 들어 탐색 전용, 리뷰 전용, 문서 확인 전용을 동시에 돌리고, 마지막에 부모가 결론만 모아 보고서처럼 정리합니다.
특히 코드베이스 탐색이나 다단계 기능 구현처럼 서로 독립적인 조사가 많은 작업에서 효과가 큽니다.
사용 조건과 비용 감각(언제 자동으로 생기나)
Codex는 서브에이전트를 자동으로 마구 생성하지 않습니다. 사용자가 명시적으로 "포인트별로 에이전트를 나눠 달라"처럼 요청해야만 스폰됩니다.
대신 한 번 스폰되면, 각 에이전트가 모델 추론과 툴 사용을 따로 수행하므로 단일 에이전트로 밀어붙이는 것보다 토큰이 더 듭니다. "더 빠르고 명확한 분업"을 돈과 맞바꾸는 선택지로 이해하면 좋습니다.
가시성은 현재 Codex 앱과 CLI에서 제공되며, IDE 확장에는 추후 들어올 예정입니다.
전형적인 실행 흐름(오케스트레이션)
부모 역할의 Codex가 전체 진행을 지휘합니다. 필요한 만큼 서브에이전트를 만들고, 추가 질문이나 지시를 각 스레드로 라우팅하며, 결과가 모두 모일 때까지 기다립니다.
여러 에이전트가 동시에 달릴 때는 "전원 도착" 후에 한 번에 합쳐진 답을 돌려주는 방식이 기본입니다.
다음 같은 프롬프트가 대표적입니다(포인트별로 1개씩 생성해 최종 요약):
I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code실행 중인 서브에이전트 다루기(CLI/제어)
CLI에서는 /agent로 현재 열려 있는 에이전트 스레드들 사이를 이동하면서 진행 상황을 확인할 수 있습니다.
또한 Codex에게 "지금 돌아가는 서브에이전트를 저 방향으로 더 파라", "중지해라", "끝난 스레드는 닫아라"처럼 직접 조종을 요청할 수 있습니다. 멀티스레드 작업을 '한 번 던지고 기다리는' 것에서 '진행 중 교통정리'로 바꿔주는 지점입니다.
승인(approvals)·샌드박스 정책: 상속과 예외
서브에이전트는 부모 세션의 샌드박스 정책을 그대로 물려받습니다. 그래서 부모가 읽기 전용이면 기본적으로 자식도 읽기 전용, 쓰기 허용이면 자식도 그 정책 아래에서 움직입니다.
인터랙티브 CLI에서는 메인 스레드를 보고 있어도 다른(비활성) 스레드에서 승인 요청이 튀어나올 수 있습니다. 이때 오버레이에 "어느 스레드에서 왔는지" 라벨이 표시되고, o로 해당 스레드를 열어 확인한 뒤 승인/거절/응답할 수 있습니다.
비인터랙티브 환경처럼 새 승인을 띄울 수 없으면, 추가 승인이 필요한 액션은 실패하고 그 오류가 부모 워크플로우로 보고됩니다.
추가로, 부모 턴에서 적용한 런타임 오버라이드(예: /approvals 변경, --yolo)는 자식 스폰 시에도 다시 적용됩니다. 커스텀 에이전트 파일에 다른 기본값이 있더라도, 세션에서 즉석으로 바꾼 "라이브 정책"이 우선 반영될 수 있다고 이해하면 안전합니다.
커스텀 에이전트: 파일로 역할을 제품화하기
Codex에는 기본 에이전트가 있습니다. 일반용 default, 구현/수정 중심 worker, 읽기 중심 탐색 explorer처럼 성격이 나뉩니다.
여기에 팀/프로젝트에 맞춘 "나만의 전문 에이전트"를 TOML 파일로 추가할 수 있습니다. 개인용은 ~/.codex/agents/, 프로젝트 한정은 .codex/agents/ 아래에 파일을 두면 됩니다. 각 파일은 스폰될 세션의 설정 레이어처럼 동작해, 모델·샌드박스·MCP·스킬 등 세션 설정을 덮어쓸 수 있습니다.
필수 필드는 3개뿐입니다: name, description, developer_instructions. 나머지(model, sandbox_mode, mcp_servers, skills.config 등)는 생략하면 부모 세션 값을 상속합니다.
주의할 점은 "파일명은 관례일 뿐"이고, 실제 식별자는 name이라는 점입니다. 또한 explorer처럼 기본 에이전트 이름과 같게 만들면 커스텀이 우선합니다.
전역 제한 설정: 스레드 수·깊이·CSV 작업 타임아웃
서브에이전트 전체 운영 규칙은 설정의 [agents] 아래에서 관리합니다. 핵심은 세 가지입니다.
agents.max_threads는 동시에 열어둘 수 있는 에이전트 스레드 상한이며, 기본값은 6입니다.
agents.max_depth는 "중첩 스폰"을 어디까지 허용할지로, 루트가 0일 때 기본값 1은 "자식까지만 허용, 손자(더 깊은 스폰)는 차단"에 가깝습니다.
agents.job_max_runtime_seconds는 CSV 팬아웃 작업(spawn_agents_on_csv)에서 각 워커의 기본 타임아웃이며, 미설정 시 호출별 기본(워커당 1800초)이 쓰입니다.
표시용 닉네임: 같은 에이전트를 여러 개 돌릴 때 읽기 좋게
여러 인스턴스가 동시에 뜨면 UI에서 전부 같은 이름으로 보여 헷갈릴 수 있습니다. nickname_candidates를 주면 Codex가 보기 좋은 별칭을 랜덤/순차로 배정해 구분을 돕습니다.
중요한 점은 닉네임은 "표시만" 바뀌고, 실제 스폰과 식별은 여전히 name으로 한다는 것입니다. 별칭 목록은 비어 있으면 안 되고, 중복도 허용되지 않으며, 사용 가능한 문자는 영문/숫자/공백/하이픈/언더스코어 정도로 제한됩니다.
예시는 다음처럼 구성합니다:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]패턴 1: PR 리뷰를 3역으로 쪼개는 구성(탐색/리뷰/문서검증)
좋은 커스텀 에이전트는 "좁고 고집 센 역할"을 가집니다. PR 리뷰는 특히 분업 이점이 큽니다. 예를 들어, 코드 경로를 증거 중심으로 훑는 탐색자, 리스크를 집요하게 찾는 리뷰어, 외부 문서를 MCP로 확인하는 문서 담당을 분리합니다.
프로젝트 설정은 보통 다음처럼 스레드/깊이를 잡고:
[agents]
max_threads = 6
max_depth = 1탐색 전용(읽기 전용 샌드박스) 에이전트:
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""리뷰 전용(고추론, 읽기 전용):
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""문서 검증 전용(MCP 연결, 읽기 전용):
name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"이 조합은 "리뷰어가 감으로 말하지 않게 하고, 근거를 분리해 모으는" 데 강합니다.
CSV 팬아웃 배치(spawn_agents_on_csv): 행마다 워커 1명(실험 기능)
비슷한 작업을 수십~수백 개 반복해야 할 때는 "CSV 한 줄 = 작업 한 건"으로 바꿔 자동 분산 처리할 수 있습니다. Codex가 CSV를 읽고 행마다 워커 서브에이전트를 띄운 뒤, 결과를 다시 CSV로 합칩니다.
입력은 csv_path, 워커 프롬프트 템플릿인 instruction(예: {column_name} 치환), 안정적인 식별을 위한 id_column, 결과 JSON 형태를 강제하는 output_schema, 그리고 제어용 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 같은 메타데이터가 붙습니다. 작업 상태 저장은 SQLite 기반이며, 위치는 sqlite_home로 제어합니다.
패턴 2: 프론트엔드 통합 디버깅(재현/경로파악/최소수정)
UI 회귀나 브라우저 플로우 문제는 "재현 증거"와 "코드 소유 경로"와 "수정"이 서로 다른 기술을 요구합니다. 그래서 (1) 재현 담당은 브라우저 도구를 쓰되 코드 수정은 하지 않고, (2) 경로 파악 담당은 읽기 전용으로 소유 파일을 특정하고, (3) 수정 담당이 최소 변경만 수행하는 식으로 나누면 안정적입니다.
브라우저 재현은 MCP로 DevTools를 붙이는 식으로 구성할 수 있습니다:
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20여기서 핵심은 "재현 담당이 코드를 고치기 시작하지 않게 막고", "수정 담당이 원인 파악 없이 추측 수정하지 않게 막는" 역할 경계입니다.
인사이트
서브에이전트는 '사람 팀'을 흉내 내는 기능이라서, 역할을 좁히고 산출물을 명확히 정의할수록 성능이 급상승합니다.
가장 실전적인 시작점은 "읽기 전용 탐색자 + 고추론 리뷰어 + 문서 검증자" 3분업이며, 샌드박스는 기본적으로 읽기 전용을 깔고 정말 필요할 때만 쓰기를 허용하세요.
대량 반복 작업은 CSV 팬아웃으로 바꾸되, 워커가 반드시 report_agent_job_result를 한 번 호출하도록 프롬프트에 결과 계약(스키마/키)을 못 박아두면 실패율이 크게 줄어듭니다.
출처 및 참고 : Subagents
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.