하위 에이전트

ChatGPT Work와 Codex는 특화된 에이전트를 병렬로 생성한 다음 그 결과를 하나의 응답으로 취합하여 하위 에이전트 워크플로를 실행할 수 있습니다. 이는 코드베이스 탐색이나 여러 단계로 구성된 기능 계획 구현처럼 병렬화 수준이 높은 복잡한 작업에 특히 유용할 수 있습니다.

로컬 Codex 클라이언트에서는 작업별로 서로 다른 모델 구성과 지침을 사용하는 사용자 지정 에이전트도 정의할 수 있습니다.

사용 가능 여부

웹의 ChatGPT Work

ChatGPT Work는 자격 요건을 충족하는 계정에 하위 에이전트 워크플로와 활동을 제공합니다.

로컬 Codex 클라이언트

현재 Codex 릴리스에서는 하위 에이전트 워크플로가 기본적으로 활성화됩니다. 하위 에이전트 활동은 ChatGPT 데스크톱 앱, Codex CLI, IDE 확장 프로그램에 표시됩니다.

각 하위 에이전트가 자체적으로 모델 및 도구 작업을 수행하므로, 하위 에이전트 워크플로는 비슷한 단일 에이전트 실행보다 더 많은 토큰을 사용합니다.

웹의 ChatGPT Work

ChatGPT Work에서는 독립적인 작업을 하위 에이전트에게 위임하도록 ChatGPT에 요청하세요. 에이전트는 ChatGPT의 호스팅 환경에서 실행되며, 채팅에 에이전트의 활동과 결과가 표시됩니다. 대부분의 지능 수준에서는 위임을 명시적으로 요청하세요. Ultra를 사용하면 병렬 에이전트가 속도나 품질을 실질적으로 개선할 수 있을 때 ChatGPT가 선제적으로 작업을 위임할 수 있습니다.

ChatGPT 데스크톱 앱

앱 채팅에서 작업의 독립적인 부분을 하위 에이전트에게 위임하도록 Codex에 요청하세요. 현재 로컬 Codex 릴리스는 직접 요청하거나 적용 가능한 AGENTS.md 또는 스킬 지침에서 위임을 요청할 때 작업을 위임합니다. 앱에는 각 하위 에이전트 스레드가 표시되므로 해당 작업과 기본 채팅에 반환된 요약을 검토할 수 있습니다.

Codex CLI

대화형 CLI 세션에서 하위 에이전트를 사용하도록 Codex에 요청하세요. Codex는 위임을 요청하는 적용 가능한 AGENTS.md 또는 스킬 지침을 따를 수도 있습니다. 에이전트가 실행되는 동안 /agent을 사용하여 에이전트 스레드를 검토하고 전환하세요. 기본 스레드는 하위 에이전트 결과를 최종 응답으로 취합합니다.

IDE 확장 프로그램

IDE 채팅에서 작업의 독립적인 부분을 하위 에이전트에게 위임하도록 Codex에 요청하세요. Codex는 위임을 요청하는 적용 가능한 AGENTS.md 또는 스킬 지침을 따를 수도 있습니다. 백그라운드 에이전트 UI를 사용할 수 있으면 활성 하위 에이전트가 작성기 위에 표시됩니다. 패널을 펼치면 상태를 확인하거나 활성 상태인 모든 하위 에이전트를 중지하거나 개별 하위 에이전트 스레드를 열 수 있습니다.

하위 에이전트 워크플로가 유용한 이유

컨텍스트 창이 크더라도 모델에는 한계가 있습니다. 요구 사항, 제약 조건, 의사 결정을 정의하는 기본 채팅에 탐색 메모, 테스트 로그, 스택 트레이스, 명령 출력과 같은 잡음이 많은 중간 출력을 쏟아 넣으면 시간이 지날수록 세션의 신뢰성이 낮아질 수 있습니다.

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

• 컨텍스트 오염: 유용한 정보가 잡음이 많은 중간 출력에 묻힙니다.
• 컨텍스트 부패: 관련성이 낮은 세부 정보가 채팅에 쌓이면서 성능이 저하됩니다.

배경 정보는 Chroma의 컨텍스트 부패 관련 글을 참조하세요.

하위 에이전트 워크플로는 잡음이 많은 작업을 기본 스레드 밖으로 옮겨 다음과 같은 도움을 줍니다.

• 기본 에이전트가 요구 사항, 의사 결정, 최종 출력에 집중하도록 합니다.
• 탐색, 테스트 또는 로그 분석을 위해 특화된 하위 에이전트를 병렬로 실행합니다.
• 원시 중간 출력 대신 하위 에이전트의 요약을 반환합니다.

또한 작업을 독립적으로 병렬 실행할 수 있을 때 시간을 절약할 수 있으며, 규모가 큰 작업을 범위가 명확한 단위로 나누어 더 쉽게 처리할 수 있습니다. 예를 들어 Codex는 수백만 토큰 규모의 문서 분석을 더 작은 문제로 나누고 정제된 핵심 내용을 기본 스레드에 반환할 수 있습니다.

우선 탐색, 테스트, 분류, 요약과 같이 읽기 작업의 비중이 높은 작업에는 병렬 에이전트를 사용하세요. 여러 에이전트가 동시에 코드를 편집하면 충돌이 발생하고 조율 비용이 증가할 수 있으므로 쓰기 작업의 비중이 높은 병렬 워크플로에는 더 신중하게 접근하세요.

핵심 용어

Codex는 하위 에이전트 워크플로에서 서로 관련된 몇 가지 용어를 사용합니다.

• 하위 에이전트 워크플로: Codex가 병렬 에이전트를 실행하고 그 결과를 결합하는 워크플로입니다.
• 하위 에이전트: Codex가 특정 작업을 처리하도록 시작하는 위임된 에이전트입니다.
• 에이전트 스레드: 하위 에이전트가 작업을 수행하는 스레드입니다. 지원되는 클라이언트에서는 이 스레드를 열어 진행 상황이나 결과를 검토할 수 있습니다.

하위 에이전트 워크플로 시작하기

웹의 ChatGPT Work

대부분의 지능 수준에서는 하위 에이전트 또는 병렬 에이전트 작업을 직접 요청하세요. Ultra에서는 선제적 위임이 활성화되므로 ChatGPT가 적합한 독립 작업을 별도의 요청 없이 위임할 수 있습니다.

로컬 Codex 클라이언트

하위 에이전트 또는 병렬 에이전트 작업을 직접 요청하세요. Codex는 적용 가능한 프로젝트 또는 스킬 지침에서 요청할 때도 작업을 위임할 수 있습니다.

실제로 수동 시작은 "에이전트 두 개를 생성해 줘", "이 작업을 병렬로 위임해 줘", 또는 "항목마다 에이전트 하나를 사용해 줘"와 같은 직접적인 지침을 사용하는 것을 의미합니다. 각 하위 에이전트가 자체적으로 모델 및 도구 작업을 수행하므로 하위 에이전트 워크플로는 비슷한 단일 에이전트 실행보다 더 많은 토큰을 사용합니다.

좋은 하위 에이전트 프롬프트는 작업을 나누는 방법, Codex가 계속 진행하기 전에 모든 에이전트를 기다려야 하는지 여부, 반환할 요약 또는 출력의 형태를 설명해야 합니다.

Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.

모델 및 추론 선택하기

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

웹의 ChatGPT Work

ChatGPT Work에서는 작성기에서 모델과 지능 수준을 선택하세요. 선택한 모델에 따라 사용할 수 있는 지능 수준에는 Light, Medium, High, Extra High, Max가 포함될 수 있습니다. Ultra는 자격 요건을 충족하는 계정과 지원되는 모델에서만 사용할 수 있습니다. 최대 수준의 추론을 사용하며 ChatGPT가 적합한 작업을 하위 에이전트에게 선제적으로 위임할 수 있게 합니다.

다른 지능 수준에서는 작업을 병렬로 위임하려면 하위 에이전트를 명시적으로 요청하세요.

로컬 Codex 클라이언트

모델 또는 model_reasoning_effort을 고정하지 않으면 Codex는 작업에 맞게 지능, 속도, 가격의 균형을 맞춘 설정을 선택할 수 있습니다. 빠른 탐색에는 gpt-5.6-terra을 선호하거나 더 까다로운 추론에는 더 높은 수준의 gpt-5.6 구성을 선택할 수 있습니다. 더 세밀하게 제어하려면 프롬프트에서 해당 선택을 지시하거나 에이전트 파일에서 model 및 model_reasoning_effort을 직접 설정하세요.

모델 선택

• gpt-5.6: 까다로운 에이전트에는 여기서 시작하세요. 더 큰 컨텍스트 전반에서 계획, 도구 사용, 검증, 후속 처리가 필요한 모호한 여러 단계의 작업에 가장 강력합니다.
• gpt-5.6-terra: 탐색, 읽기 작업 비중이 높은 조사, 대용량 파일 검토, 보조 문서 처리처럼 깊이보다 속도와 효율성을 우선하는 에이전트에 사용하세요. 정제된 결과를 기본 에이전트에 반환하는 병렬 작업자에 적합합니다.
• gpt-5.6-luna: 명확하고 반복 가능하거나 대량으로 처리해야 하는 작업을 담당하는, 범위가 좁고 빠른 에이전트에 사용하세요.

추론 노력 수준(model_reasoning_effort)

• ultra: 선택한 모델이 지원하는 경우 가장 심층적인 추론에 사용하세요.
• max 및 xhigh: 선택한 모델이 이러한 수준을 지원하는 경우 특히 까다로운 추론에 사용하세요.
• high: 에이전트가 복잡한 논리를 추적하거나 가정을 확인하거나 극단적인 사례를 검토해야 할 때 사용하세요(예: 검토 또는 보안 중심 에이전트).
• medium: 대부분 에이전트에 적합한 균형 잡힌 기본값입니다.
• low: 작업이 단순하고 속도가 가장 중요할 때 사용하세요.

추론 노력 수준이 높을수록 응답 시간과 토큰 사용량이 늘어나지만 복잡한 작업의 품질을 개선할 수 있습니다. 자세한 내용은 모델, 구성 기본 사항, 구성 참조를 참조하세요.

오케스트레이션 및 스레드 제어

ChatGPT 또는 Codex는 새 하위 에이전트 생성, 후속 지침 전달, 결과 대기, 에이전트 스레드 종료를 포함하여 에이전트 간 오케스트레이션을 처리합니다.

많은 에이전트가 실행 중이면 Codex는 요청된 모든 결과를 사용할 수 있을 때까지 기다린 다음 통합된 응답을 반환합니다.

웹의 ChatGPT Work

대부분의 지능 수준에서는 직접 요청한 후 ChatGPT가 에이전트를 생성합니다. Ultra를 사용하면 병렬 작업이 유용할 때 ChatGPT가 선제적으로 작업을 위임할 수도 있습니다.

로컬 Codex 클라이언트

현재 로컬 Codex 릴리스는 직접 요청하거나 적용 가능한 프로젝트 또는 스킬 지침이 있을 때 에이전트를 생성합니다.

프로젝트에서 실제 작동 방식을 확인하려면 다음 프롬프트를 사용해 보세요.

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

하위 에이전트 관리하기

웹의 ChatGPT Work

Subagents를 열어 읽기 전용 Active 및 Done 목록을 확인하세요. 완료된 하위 에이전트를 선택하여 세부 정보와 결과를 검토하세요. 웹 사이드바에는 하위 에이전트 활동이 표시되지만, 개별 하위 에이전트를 중지하거나 지시를 변경하는 제어 기능은 제공되지 않습니다.

ChatGPT 데스크톱 앱

• 기본 스레드에 표시된 활동에서 하위 에이전트 스레드를 열어 작업 내용을 검토하세요.
• 실행 중인 하위 에이전트의 지시를 변경하거나 중지하거나 완료된 하위 에이전트 스레드를 닫도록 Codex에 직접 요청하세요.

Codex CLI

• CLI에서 /agent을 사용하여 활성 에이전트 스레드 사이를 전환하고 진행 중인 스레드를 검토하세요.
• 실행 중인 하위 에이전트의 지시를 변경하거나 중지하거나 완료된 에이전트 스레드를 닫도록 Codex에 직접 요청하세요.

IDE 확장 프로그램

• 백그라운드 에이전트 패널을 사용할 수 있으면 펼쳐서 상태를 검토하거나 활성 하위 에이전트를 중지하거나 하위 에이전트 스레드를 여세요.
• 실행 중인 하위 에이전트의 지시를 변경하거나 중지하거나 완료된 에이전트 스레드를 닫도록 Codex에 직접 요청하세요.

승인 및 샌드박스 제어

로컬 Codex 클라이언트

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

웹의 ChatGPT Work

ChatGPT Work는 호스팅 환경에서 하위 에이전트를 실행하며 로컬 Codex 샌드박스 또는 승인 모드 제어 기능을 제공하지 않습니다. 하위 에이전트는 상위 채팅에서 사용할 수 있는 도구를 사용합니다. 웹사이트 및 커넥터 권한은 각 도구에 따라 달라집니다.

ChatGPT 데스크톱 앱

하위 에이전트는 작성기 아래에서 선택한 권한 모드를 상속합니다. Codex에 작업 위임을 요청하기 전에 상위 턴의 권한 모드를 선택하세요.

Codex CLI

대화형 CLI 세션에서는 기본 스레드를 보고 있는 동안에도 비활성 에이전트 스레드에서 승인 요청이 표시될 수 있습니다. 승인 오버레이에는 소스 스레드 레이블이 표시되며, 요청을 승인하거나 거부하거나 응답하기 전에 o을 눌러 해당 스레드를 열 수 있습니다.

비대화형 흐름이나 실행에서 새 승인 요청을 표시할 수 없는 경우에는 새 승인이 필요한 작업이 실패하고 Codex가 오류를 상위 워크플로에 반환합니다.

또한 Codex는 하위 에이전트를 생성할 때 상위 턴의 실시간 런타임 재정의를 다시 적용합니다. 여기에는 선택한 사용자 지정 에이전트 파일에서 다른 기본값을 설정하더라도 세션 중에 대화형으로 설정한 샌드박스 및 승인 선택 사항(예: /permissions 변경 또는 --yolo)이 포함됩니다.

IDE 확장 프로그램

하위 에이전트는 작성기 아래에서 선택한 권한 모드를 상속합니다. Codex에 작업 위임을 요청하기 전에 상위 턴의 권한 모드를 선택하세요.

읽기 전용 모드에서 작업하도록 명시적으로 지정하는 등 개별 사용자 지정 에이전트의 샌드박스 구성을 재정의할 수도 있습니다.

사용자 지정 에이전트

Codex에는 다음과 같은 기본 제공 에이전트가 포함되어 있습니다.

• default: 범용 대체 에이전트입니다.
• worker: 구현 및 수정에 중점을 둔 실행형 에이전트입니다.
• explorer: 읽기 작업의 비중이 높은 코드베이스 탐색 에이전트입니다.

직접 사용자 지정 에이전트를 정의하려면 개인 에이전트의 경우 ~/.codex/agents/ 아래에, 프로젝트 범위 에이전트의 경우 .codex/agents/ 아래에 독립형 TOML 파일을 추가하세요.

각 파일은 하나의 사용자 지정 에이전트를 정의합니다. Codex는 이러한 파일을 생성된 세션의 구성 계층으로 로드하므로, 사용자 지정 에이전트는 일반 Codex 세션 구성과 동일한 설정을 재정의할 수 있습니다. 이 방식은 전용 에이전트 매니페스트보다 다소 무겁게 느껴질 수 있으며, 작성 및 공유 방식이 성숙해짐에 따라 형식이 변경될 수 있습니다.

모든 독립형 사용자 지정 에이전트 파일은 다음을 정의해야 합니다.

• name
• description
• developer_instructions

사용자 지정 에이전트 파일에 model 또는 model_reasoning_effort이 설정되어 있으면 파일의 값이 우선합니다. 그렇지 않으면 Codex는 각 설정을 독립적으로 결정합니다. 먼저 명시적 생성 값, 그다음 해당 [agents] 기본값, 마지막으로 상위 에이전트의 값을 사용합니다. 생성 시 다른 모델을 선택했지만 명시적 또는 구성된 추론 강도가 없으면 Codex는 해당 모델의 기본 추론 강도를 사용합니다. 사용자 지정 에이전트 파일에서 생략된 sandbox_mode, mcp_servers, skills.config 등의 기타 세션 설정은 상위 에이전트에서 상속됩니다.

전역 설정

전역 하위 에이전트 설정은 여전히 구성의 [agents] 아래에 있습니다.

참고:

• agents.enabled의 기본값은 true입니다. 멀티 에이전트 도구를 비활성화하려면 false로 설정하세요.
• agents.max_concurrent_threads_per_session을 설정하지 않으면 Codex가 기본값을 선택합니다. 기존 구성에서는 agents.max_threads을 레거시 별칭으로 계속 사용할 수 있습니다.
• 명시적 생성 값은 agents.default_subagent_model 및 agents.default_subagent_reasoning_effort보다 우선합니다.
• agents.interrupt_message의 기본값은 true입니다. 에이전트 컨텍스트에서 모델에 표시되는 중단 메시지를 생략하려면 false으로 설정하세요.
• 사용자 지정 에이전트 이름이 explorer 같은 기본 제공 에이전트와 일치하면 사용자 지정 에이전트가 우선합니다.

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

사용자 지정 에이전트 파일에는 model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 등 지원되는 다른 config.toml 키도 포함할 수 있습니다.

Codex는 name 필드로 사용자 지정 에이전트를 식별합니다. 파일 이름을 에이전트 이름과 일치시키는 것이 가장 간단한 규칙이지만, name 필드가 최종 기준입니다.

사용자 지정 에이전트 예시

가장 효과적인 사용자 지정 에이전트는 범위가 좁고 명확한 관점을 가집니다. 각 에이전트에 분명한 역할과 그 역할에 맞는 도구 범위, 그리고 인접한 작업으로 벗어나지 않도록 하는 지침을 제공하세요.

예시 1: PR 검토

이 패턴은 검토 작업을 세 개의 전문 사용자 지정 에이전트로 나눕니다.

• pr_explorer은 코드베이스를 파악하고 근거를 수집합니다.
• reviewer은 정확성, 보안 및 테스트 위험을 찾습니다.
• docs_researcher은 전용 MCP 서버를 통해 프레임워크 또는 API 문서를 확인합니다.

프로젝트 구성(.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 8

.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.6-terra"
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.6-luna"
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"

이 설정은 다음과 같은 프롬프트에 적합합니다.

Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

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

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

프로젝트 구성(.codex/config.toml):

[agents]
max_concurrent_threads_per_session = 6

.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.6-luna"
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.6-terra"
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

이 설정은 다음과 같은 프롬프트에 적합합니다.

Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.