서브에이전트

Codex는 전문화된 에이전트를 병렬로 생성해 동시에 탐색, 처리, 분석하도록 하여 서브에이전트 워크플로를 실행할 수 있습니다.

서브에이전트 워크플로가 도움이 되는 이유

컨텍스트 창이 커도 모델이 한 번에 안정적으로 다룰 수 있는 정보에는 한계가 있습니다. 요구 사항, 제약, 결정을 정리해야 하는 메인 대화에 탐색 메모, 테스트 로그, 스택 트레이스, 명령 출력처럼 잡음이 많은 중간 결과가 쌓이면 시간이 지날수록 세션의 신뢰성이 떨어질 수 있습니다.

이는 흔히 다음과 같이 설명됩니다.

컨텍스트 오염: 유용한 정보가 잡음이 많은 중간 출력 아래에 묻힙니다.
컨텍스트 부패: 대화가 관련성이 낮은 세부 사항으로 채워지면서 성능이 저하됩니다.

배경 설명은 Chroma의 context rot 글을 참고하십시오.

서브에이전트 워크플로는 잡음이 많은 작업을 메인 스레드 밖으로 분리해 다음을 가능하게 합니다.

메인 에이전트가 요구 사항, 결정, 최종 출력에 집중하게 합니다.
탐색, 테스트, 로그 분석을 위해 전문화된 서브에이전트를 병렬로 실행합니다.
원시 중간 출력 대신 서브에이전트의 요약을 반환합니다.

서로 독립적인 작업은 병렬로 실행해 시간을 줄일 수 있습니다. 큰 작업을 제한된 조각으로 나누기도 쉬워집니다. 예를 들어 Codex는 수백만 토큰 규모의 문서 분석을 더 작은 문제로 나누고, 정제된 핵심 내용만 메인 스레드로 반환할 수 있습니다.

처음에는 탐색, 테스트, 초기 진단, 요약처럼 읽기 중심 작업에 병렬 에이전트를 사용하는 것이 좋습니다. 쓰기 중심 병렬 워크플로는 여러 에이전트가 동시에 코드를 편집해 충돌이나 조정 부담을 만들 수 있으므로 더 신중하게 설계해야 합니다.

핵심 용어

서브에이전트 워크플로: Codex가 병렬 에이전트를 실행하고 그 결과를 결합하는 워크플로입니다.
서브에이전트: 특정 작업을 처리하도록 Codex가 시작하는 위임된 에이전트입니다.
에이전트 스레드: 에이전트의 CLI 스레드입니다. /agent로 검사하고 전환할 수 있습니다.

사용 가능 여부와 기본 흐름

현재 Codex 릴리스에서는 서브에이전트 워크플로가 기본으로 활성화되어 있습니다. 서브에이전트 활동은 Codex 앱과 CLI에 표시됩니다. IDE 확장에서도 곧 표시될 예정입니다.

Codex는 서브에이전트를 자동으로 생성하지 않으며, 사용자가 서브에이전트나 병렬 에이전트 작업을 명시적으로 요청할 때만 서브에이전트를 생성합니다.

실제로는 "에이전트 두 개를 생성해 줘", "이 작업을 병렬로 위임해 줘", "항목마다 에이전트 하나를 사용해 줘" 같은 직접 지시가 트리거가 됩니다. 각 서브에이전트가 자체 모델 호출과 도구 작업을 수행하므로, 같은 작업을 단일 에이전트로 실행할 때보다 더 많은 토큰을 사용합니다.

Codex는 새 서브에이전트 생성, 후속 지침 라우팅, 결과 대기, 에이전트 스레드 종료 같은 여러 에이전트 간 오케스트레이션을 처리합니다. 여러 에이전트가 실행 중이면 요청한 결과가 준비될 때까지 기다린 뒤 통합 응답을 반환할 수 있습니다.

좋은 프롬프트는 작업을 어떻게 나눌지, 계속하기 전에 Codex가 모든 에이전트를 기다려야 하는지, 어떤 요약이나 출력을 반환해야 하는지를 명확히 설명합니다.

현재 PR을 main과 비교해 다음 항목을 검토해 줘. 항목마다 에이전트 하나를 생성하고, 모두 끝날 때까지 기다린 뒤 항목별 결과를 파일 참조와 함께 요약해 줘.
1. 보안 문제
2. 코드 품질
3. 버그
4. 경쟁 상태
5. 테스트 불안정성
6. 코드 유지보수성

서브에이전트 관리

CLI에서 /agent를 사용해 활성 에이전트 스레드를 전환하고 진행 중인 스레드를 확인합니다.
실행 중인 서브에이전트에 새 지침을 보내거나, 중지하거나, 완료된 에이전트 스레드를 닫아 달라고 Codex에 직접 요청할 수 있습니다.

모델과 추론 선택

에이전트마다 필요한 모델과 추론 설정이 다릅니다.

모델이나 model_reasoning_effort를 고정하지 않으면 Codex가 작업에 맞춰 지능, 속도, 가격의 균형을 잡는 구성을 선택할 수 있습니다. 더 세밀하게 제어하려면 프롬프트에서 선택을 유도하거나 에이전트 파일에 model과 model_reasoning_effort를 직접 설정합니다.

대부분의 Codex 작업은 gpt-5.5에서 시작하면 됩니다. 더 가벼운 서브에이전트 작업에 빠르고 저렴한 옵션이 필요하면 gpt-5.4-mini를 사용합니다. ChatGPT Pro를 사용하고 거의 즉각적인 텍스트 전용 반복이 필요하다면 gpt-5.3-codex-spark가 연구 미리보기로 계속 제공됩니다.

모델 선택

gpt-5.5: 까다로운 에이전트는 여기서 시작합니다. 더 큰 컨텍스트에서 계획, 도구 사용, 검증, 마무리까지 필요한 모호한 다단계 작업에 가장 강합니다.
gpt-5.4: 워크플로가 GPT-5.4에 고정된 경우 사용합니다. 강한 코딩, 추론, 도구 사용, 폭넓은 워크플로를 결합합니다.
gpt-5.4-mini: 탐색, 읽기 중심 스캔, 큰 파일 리뷰, 보조 문서 처리처럼 깊이보다 속도와 효율이 중요한 에이전트에 사용합니다. 정제된 결과를 메인 에이전트에 반환하는 병렬 워커에 잘 맞습니다.
gpt-5.3-codex-spark: ChatGPT Pro를 사용하고 지연 시간이 폭넓은 기능보다 중요할 때, 거의 즉각적인 텍스트 전용 반복을 위해 이 연구 미리보기 모델을 사용합니다.

추론 effort(`model_reasoning_effort`)

high: 에이전트가 복잡한 논리를 추적하거나, 가정을 확인하거나, 경계 조건을 다뤄야 할 때 사용합니다. 예: 리뷰어 또는 보안 중심 에이전트.
medium: 대부분의 에이전트에 적합한 균형 잡힌 기본값입니다.
low: 작업이 단순하고 속도가 가장 중요할 때 사용합니다.

더 높은 추론 effort는 응답 시간과 토큰 사용량을 늘리지만, 복잡한 작업의 품질을 개선할 수 있습니다.

승인 및 샌드박스 제어

서브에이전트는 현재 샌드박스 정책을 상속합니다.

대화형 CLI 세션에서는 사용자가 메인 스레드를 보고 있어도 비활성 에이전트 스레드에서 승인 요청이 나타날 수 있습니다. 승인 오버레이에는 요청을 보낸 스레드 라벨이 표시되며, o를 눌러 해당 스레드를 연 뒤 승인, 거절, 응답을 진행할 수 있습니다.

비대화형 흐름이거나 새 승인을 표시할 수 없는 실행에서는 새 승인이 필요한 동작이 실패하고, Codex가 오류를 부모 워크플로에 전달합니다.

Codex는 자식 에이전트를 생성할 때 부모 턴의 실시간 런타임 오버라이드도 다시 적용합니다. 여기에는 세션 중 /approvals 변경이나 --yolo처럼 대화형으로 설정한 샌드박스와 승인 선택이 포함됩니다. 선택한 사용자 지정 에이전트 파일이 다른 기본값을 설정해도 이 규칙이 적용됩니다.

개별 사용자 지정 에이전트에 대해 샌드박스 구성을 따로 지정할 수도 있습니다. 예를 들어 특정 에이전트를 명시적으로 읽기 전용 모드로 동작하게 만들 수 있습니다.

사용자 지정 에이전트

서브에이전트 워크플로에서는 작업 성격에 맞춰 모델 구성과 지침이 다른 사용자 지정 에이전트를 정의할 수 있습니다.

Codex에는 다음 내장 에이전트가 포함됩니다.

에이전트	용도
`default`	일반 목적의 기본 에이전트
`worker`	구현과 수정에 초점을 둔 실행 에이전트
`explorer`	코드베이스 탐색처럼 읽기 중심 작업이 많은 에이전트

개인용 에이전트는 ~/.codex/agents/ 아래에, 프로젝트 범위 에이전트는 .codex/agents/ 아래에 독립 TOML 파일로 정의합니다.

각 파일은 하나의 사용자 지정 에이전트를 정의합니다. Codex는 이 파일을 생성된 세션의 구성 계층으로 로드하므로, 일반 Codex 세션 구성과 같은 설정을 사용자 지정 에이전트에서도 오버라이드할 수 있습니다. 전용 에이전트 매니페스트보다 다소 무겁게 느껴질 수 있으며, 작성과 공유 흐름이 성숙함에 따라 형식은 바뀔 수 있습니다.

모든 독립 사용자 지정 에이전트 파일에는 다음 필드가 필요합니다.

name
description
developer_instructions

nickname_candidates, model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 같은 선택 필드는 생략하면 부모 세션에서 상속됩니다.

전역 설정

전역 서브에이전트 설정은 구성의 [agents] 아래에 둡니다.

필드	타입	필수	목적
`agents.max_threads`	number	아니요	동시에 열 수 있는 에이전트 스레드 상한
`agents.max_depth`	number	아니요	생성된 에이전트의 중첩 깊이, 루트 세션은 0에서 시작
`agents.job_max_runtime_seconds`	number	아니요	`spawn_agents_on_csv` 작업에서 워커별 기본 제한 시간

참고:

agents.max_threads를 설정하지 않으면 기본값은 6입니다.
agents.max_depth의 기본값은 1입니다. 직접 자식 에이전트 생성은 허용하지만 더 깊은 중첩은 막습니다. 재귀 위임이 꼭 필요한 경우가 아니라면 기본값을 유지하십시오. 값을 높이면 넓은 위임 지침이 반복적인 fan-out으로 바뀌어 토큰 사용량, 지연 시간, 로컬 리소스 사용량이 늘어날 수 있습니다.
agents.job_max_runtime_seconds는 선택 사항입니다. 생략하면 spawn_agents_on_csv가 호출별 기본 제한 시간인 워커당 1800초를 사용합니다.
사용자 지정 에이전트 이름이 explorer 같은 내장 에이전트와 같으면 사용자 지정 에이전트가 우선합니다.

사용자 지정 에이전트 파일 스키마

필드	타입	필수	목적
`name`	string	예	Codex가 이 에이전트를 생성하거나 참조할 때 쓰는 이름
`description`	string	예	Codex가 언제 이 에이전트를 사용할지 판단하는 사람용 설명
`developer_instructions`	string	예	에이전트 동작을 정의하는 핵심 지침
`nickname_candidates`	string[]	아니요	생성된 에이전트에 표시할 별칭 후보 목록

사용자 지정 에이전트 파일에는 model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 같은 지원되는 config.toml 키도 넣을 수 있습니다.

Codex는 name 필드로 사용자 지정 에이전트를 식별합니다. 파일 이름을 에이전트 이름과 맞추는 것이 가장 단순한 관례이지만, 실제 기준은 name 필드입니다.

표시 별칭

nickname_candidates는 생성된 에이전트에 읽기 쉬운 표시 이름을 부여하고 싶을 때 사용합니다. 같은 사용자 지정 에이전트를 여러 개 실행해도 UI가 같은 에이전트 이름만 반복하지 않고 구분되는 라벨을 표시할 수 있습니다.

별칭은 표시용일 뿐입니다. Codex는 여전히 name으로 에이전트를 식별하고 생성합니다.

별칭 후보는 비어 있지 않은 고유 이름 목록이어야 합니다. 각 별칭에는 ASCII 문자, 숫자, 공백, 하이픈, 밑줄을 사용할 수 있습니다.

예:

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"]

실제로 Codex 앱과 CLI는 에이전트 활동이 표시되는 위치에 별칭을 보여줄 수 있으며, 내부 에이전트 타입은 계속 reviewer로 유지됩니다.

사용자 지정 에이전트 예시

좋은 사용자 지정 에이전트는 범위가 좁고 관점이 분명합니다. 각 에이전트에 명확한 역할, 그 역할에 맞는 도구 접근 범위, 주변 작업으로 범위가 번지지 않게 하는 지침을 부여하십시오.

예시 1: PR 리뷰

이 패턴은 리뷰를 세 가지 집중 에이전트로 나눕니다.

pr_explorer: 코드베이스를 매핑하고 근거를 수집합니다.
reviewer: 정확성, 보안, 테스트 위험을 찾습니다.
docs_researcher: 전용 MCP 서버로 프레임워크나 API 문서를 확인합니다.

프로젝트 구성 예시:

[agents]
max_threads = 6
max_depth = 1

.codex/agents/pr-explorer.toml:

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.
"""

.codex/agents/reviewer.toml:

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.
"""

.codex/agents/docs-researcher.toml:

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"

이 구성은 다음과 같은 프롬프트에 적합합니다.

이 브랜치를 main과 비교해 검토해 줘. pr_explorer는 영향받는 코드 경로를 매핑하고, reviewer는 실제 위험을 찾고, docs_researcher는 패치가 의존하는 프레임워크 API를 확인하게 해 줘.

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

이 패턴은 UI 회귀, 불안정한 브라우저 흐름, 애플리케이션 코드와 실행 중인 제품을 넘나드는 통합 버그에 유용합니다.

프로젝트 구성 예시:

[agents]
max_threads = 6
max_depth = 1

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""

.codex/agents/browser-debugger.toml:

name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20

.codex/agents/ui-fixer.toml:

name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false

이 구성은 다음과 같은 프롬프트에 적합합니다.

설정 모달이 저장되지 않는 이유를 조사해 줘. browser_debugger가 재현하고, code_mapper가 관련 코드 경로를 추적하고, 실패 원인이 명확해지면 ui_fixer가 가장 작은 수정으로 고치게 해 줘.

서브에이전트로 CSV 배치 처리하기

이 워크플로는 실험적이며 서브에이전트 지원이 발전하면서 바뀔 수 있습니다.

비슷한 작업이 많고 각 행이 하나의 작업 항목에 대응한다면 spawn_agents_on_csv를 사용합니다. Codex는 CSV를 읽고 행마다 워커 서브에이전트를 하나씩 생성하며, 전체 배치가 끝날 때까지 기다린 다음 결합된 결과를 CSV로 내보냅니다.

다음과 같은 반복 감사에 적합합니다.

행마다 파일, 패키지, 서비스를 하나씩 리뷰
인시던트, PR, 마이그레이션 대상 목록 점검
비슷한 입력에 대해 구조화된 요약 생성

도구 입력:

입력	설명
`csv_path`	원본 CSV 경로
`instruction`	`{column_name}` 자리표시자를 사용하는 워커 프롬프트 템플릿
`id_column`	특정 열에서 안정적인 항목 ID를 가져올 때 사용
`output_schema`	각 워커가 고정 형태의 JSON 객체를 반환해야 할 때 사용
`output_csv_path`	결과 CSV 경로
`max_concurrency`	동시 실행 수
`max_runtime_seconds`	작업 제한 시간

각 워커는 report_agent_job_result를 정확히 한 번 호출해야 합니다. 워커가 결과를 보고하지 않고 종료하면 Codex는 내보낸 CSV에서 해당 행을 오류로 표시합니다.

예시 프롬프트:

/tmp/components.csv를 만들고 path,owner 열에 프론트엔드 컴포넌트마다 한 행씩 넣어 줘.

그 다음 spawn_agents_on_csv를 다음 값으로 호출해 줘.
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "{owner}가 담당하는 {path}를 리뷰해. report_agent_job_result로 path, risk, summary, follow_up 키를 가진 JSON을 반환해."
- output_csv_path: /tmp/components-review.csv
- output_schema: path, risk, summary, follow_up 필수 문자열 필드를 가진 객체

codex exec로 실행하면 배치가 실행되는 동안 Codex가 stderr에 한 줄짜리 진행 상황을 표시합니다. 내보낸 CSV에는 원본 행 데이터와 job_id, item_id, status, last_error, result_json 같은 메타데이터가 포함됩니다.