Codex 멀티 에이전트 작업 분할 ㅡ 병렬화, 소유권, 합류까지 실전 설계

멀티 에이전트의 성패는 에이전트 수보다 작업 경계에서 갈린다. 서로 독립적인 조사와 리뷰는 병렬로 보내고, 공유 계약을 정하거나 같은 파일을 고치는 일은 순서대로 처리해야 한다. 각 에이전트에는 역할 이름 대신 소유 파일, 수정 금지 영역, 완료 조건을 줘야 한다.

이 글은 2026년 8월 17일의 공식 문서를 기준으로 한다. 먼저 자주 섞이는 두 기능을 분리한 뒤, 병렬화 판정표와 한 기능을 나누는 DAG, 실제 위임 프롬프트를 차례로 만든다.

 

먼저 알아둘 용어

용어	이 글에서 쓰는 뜻
Codex 서브에이전트	Codex 앱·CLI·IDE의 루트 에이전트가 하위 작업을 맡기는 에이전트
Responses API Multi-agent beta	GPT-5.6 API 요청 안에서 루트와 서브에이전트를 실행하는 beta 기능
루트 에이전트	작업을 나누고 결과를 합쳐 최종 응답을 만드는 상위 에이전트
작업 소유권	한 에이전트만 수정하도록 지정한 파일이나 모듈 범위
공유 계약	API 스키마나 공통 타입처럼 여러 작업이 함께 따라야 하는 규칙
DAG	선행 관계와 병렬 실행 구간을 방향 그래프로 나타낸 작업 계획

 

Codex 서브에이전트와 Responses API Multi-agent beta는 무엇이 다른가?

둘은 비슷한 협업 개념을 쓰지만, 실행 위치와 사용자가 다르다. Codex 서브에이전트는 Codex 앱·CLI·IDE에서 개발 작업을 위임하는 기능이다. Responses API Multi-agent beta는 애플리케이션 개발자가 GPT-5.6 API 요청 안에서 루트 에이전트와 서브에이전트를 실행하는 별도 beta 기능이다.

구분	Codex 서브에이전트	Responses API Multi-agent beta
주 사용자	Codex로 저장소를 다루는 개발자	API 기반 애플리케이션 개발자
실행 위치	Codex 앱·CLI·IDE 세션	Responses API 요청
활성화	[agents] 설정과 위임 프롬프트	multi_agent.enabled: true와 beta opt-in
구성	.codex/config.toml, .codex/agents/*.toml	요청 본문, beta SDK 또는 HTTP 헤더
결과 종합	루트 Codex 에이전트	API 요청의 루트 에이전트
상태	Codex 제품 기능	GPT-5.6 전용 beta

 

OpenAI의 Codex Subagents 문서는 서브에이전트가 복잡한 작업의 병렬 탐색, 테스트, 리뷰에 알맞다고 설명한다. Responses API Multi-agent 문서는 루트 에이전트가 같은 요청의 모델과 도구를 공유하는 서브에이전트 트리를 만들고 최종 응답을 종합한다고 명시한다. 따라서 Responses API beta를 켜야 Codex 서브에이전트를 쓸 수 있는 것은 아니다.

Agents SDK의 manager와 handoff도 에이전트 오케스트레이션 수단이지만, 위 두 기능과 같은 실행 면은 아니다. 애플리케이션이 에이전트를 코드로 조합할 때 검토할 별도 선택지다.

 

어떤 작업을 병렬화해야 하나?

입력과 결과가 독립적이고 공유 상태에 쓰지 않는 작업만 병렬화한다. 서로 다른 코드 경로 탐색, 공식 문서 조사, 여러 실패 원인 가설 검증, 정확성·보안·테스트의 독립 리뷰가 대표적이다.

반대로 요구사항 확정 뒤 구현, DB 스키마 변경 뒤 ORM 생성, 공통 인터페이스 확정 뒤 양쪽 구현, 구현 뒤 최종 리뷰는 순차 작업이다. 작은 단일 파일을 여러 에이전트가 동시에 고치거나, 하나의 느린 외부 작업이 전체 시간을 지배하는 경우에도 병렬화 이득이 작다.

 

60초 병렬화 판정표

작업을 보내기 전에 아래 여섯 칸을 채운다. 해결되지 않은 선행 의존성이나 같은 공유 상태에 대한 동시 쓰기가 있으면 순차 실행한다. 조사만 읽기 전용으로 병렬화하는 절충안도 있다.

하위 작업	선행 작업	소유 영역	읽기/쓰기	공유 계약	병렬 가능	합류 조건
API 진입점 조사	없음	src/api/** 탐색	읽기	없음	예	경로·현재 동작·위험 반환
데이터 모델 확정	조사 완료	API 스키마	쓰기	프런트와 공유	아니요	루트가 계약 승인
백엔드 구현	계약 승인	src/api/**	쓰기	API 스키마 고정	예	단위 테스트 통과
프런트 구현	계약 승인	src/ui/**	쓰기	API 스키마 고정	예	typecheck 통과
통합 검증	모든 구현 완료	전체 변경	읽기·실행	전체 계약	아니요	test·lint·typecheck 결과

 

OpenAI도 GPT-5.6 모델 가이드에서 Multi-agent가 독립적인 작업 흐름으로 깔끔하게 나뉘는 복잡한 작업에 적합하다고 설명한다. 병렬 호출 자체가 목적은 아니다. 같은 품질 기준을 통과하면서 벽시계 시간이 줄어야 이득이다.

 

작업 계약은 역할보다 책임 경계를 먼저 쓴다

“백엔드를 맡아 줘”는 범위가 없다. 좋은 위임에는 목표, 읽을 파일, 소유 파일, 수정 금지 영역, 입력 계약, 완료 기준, 검증 명령, 반환 형식이 들어간다.

아래 경로와 명령은 설명을 위한 가상 프로젝트 예시이며 이 저장소에서 실행하지 않았다.

에이전트	목표	입력	소유 파일	수정 금지	선행 조건	완료 기준과 반환물
repo_explorer	인증·API·DB 경로 조사	기능 요구사항	없음(읽기 전용)	모든 파일	없음	경로, 현재 동작, 위험, 추천 경계
backend_worker	알림 설정 API 구현	승인된 OpenAPI 계약	src/api/notifications/**	UI, 공통 타입	설계 게이트 통과	API 테스트와 변경 파일 목록
frontend_worker	알림 설정 화면 구현	승인된 OpenAPI 계약	src/ui/settings/notifications/**	서버, API 계약	설계 게이트 통과	typecheck와 변경 파일 목록
test_worker	통합 테스트 작성	승인된 사용자 흐름	tests/notifications/**	구현 파일	설계 게이트 통과	재현 가능한 테스트와 누락 목록
reviewer	독립 최종 검수	diff, 요구사항, 테스트 결과	없음(읽기 전용)	모든 파일	통합 검증 완료	차단 이슈를 파일·재현법과 함께 반환

파일 소유권과 공유 계약은 다르다. src/api/**를 백엔드 작업자가 소유해도 OpenAPI 스키마는 프런트와 함께 쓰는 계약이다. 계약은 설계 게이트에서 먼저 고정하고, 이후 변경은 루트 에이전트가 승인한다. 락파일, 생성 코드, 마이그레이션 순번, 공통 설정은 한 명에게만 맡기는 편이 안전하다. 이는 공식 문서의 동시 쓰기와 충돌 경고에서 도출한 운영 규칙이다.

 

Codex 서브에이전트를 어떻게 설정하나?

Codex의 전역 서브에이전트 설정은 .codex/config.toml의 [agents]에 둔다. 공식 문서에 따르면 agents.enabled의 기본값은 true이며, 동시 스레드 수를 생략하면 Codex가 기본값을 선택한다. 처음부터 높은 동시성 값을 넣기보다 실제 작업과 사용 한도에 맞춰 조정한다. 설정 필드와 기본 동작은 OpenAI의 Codex Subagents 문서에서 확인할 수 있다.

다음 코드는 공식 문서 기반 설정 예시이며 이 글 작성 환경에서는 적용·실행하지 않았다.

# .codex/config.toml
[agents]
enabled = true
max_concurrent_threads_per_session = 3
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"

 

사용자 정의 에이전트는 좁고 분명하게 만든다. 공식 문서에 따르면 사용자 정의 에이전트의 name이 explorer 같은 내장 에이전트와 같으면 사용자 정의 설정이 우선한다. 프로젝트의 기존 .codex/agents/ 파일과 이름이 겹치는지도 함께 확인한다. 자세한 스키마와 우선순위는 Codex Subagents 문서를 참고한다.

# .codex/agents/repo-explorer.toml
# 공식 문서 기반 예시, 로컬 미검증
name = "repo_explorer"
description = "변경 전에 코드 경로와 근거를 수집하는 읽기 전용 탐색자"
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
실행 경로와 관련 파일·심볼을 찾고 근거를 반환하세요.
파일을 수정하거나 구현안을 확정하지 마세요.
"""

# .codex/agents/reviewer.toml
# 공식 문서 기반 예시, 로컬 미검증
name = "reviewer"
description = "정확성, 보안, 회귀, 누락 테스트를 검토하는 읽기 전용 리뷰어"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
스타일 의견보다 재현 가능한 결함을 우선하세요.
각 이슈에 파일·심볼, 재현법, 기대 동작, 수정 방향을 포함하세요.
"""

 

모델 선택은 보장이 아니라 평가 대상이다. 반복적인 읽기 작업에는 Luna나 Terra를 검토하고, 모호한 설계와 고위험 리뷰에는 더 높은 역량과 추론 강도를 후보로 둔다. 실제 저장소의 대표 작업으로 품질, 지연, 사용량을 비교해야 한다.

 

한 기능을 나누는 실제 DAG

기존 서비스에 “사용자 알림 설정 API와 화면”을 추가한다고 가정하자. Tistory에서 Mermaid 렌더링을 보장하기 어려워 텍스트 DAG로 표시한다.

읽기 전용 조사 A ─┐
읽기 전용 조사 B ─┼─> 루트 설계 게이트 ─┬─> Backend 구현 ─┐
공식 문서 조사 C ─┘                     ├─> Frontend 구현 ─┼─> 통합 테스트 ─> 독립 Reviewer
                                          └─> Test 작성 ─────┘

 

1단계: 조사는 병렬로 실행한다

Agent A는 인증·API 진입점과 DB 모델을 찾는다. Agent B는 프런트 상태 흐름과 기존 설정 화면 패턴을 찾는다. Agent C는 프레임워크의 공식 API와 마이그레이션 제약을 확인한다. 모두 파일 경로, 현재 동작, 위험, 추천 경계만 반환하며 수정하지 않는다.

 

2단계: 루트가 설계 게이트를 연다

루트 에이전트는 세 결과를 모두 기다린 뒤 API 스키마, 데이터 모델, 책임 파일, 검증 명령을 확정한다. 결과가 모순되면 코드, 테스트, 공식 문서로 다시 확인한다. 이 단계가 끝나기 전에 구현 작업자를 보내지 않는다.

 

3단계: 소유권이 겹치지 않는 구현만 병렬화한다

백엔드, 프런트, 테스트 작업자는 각자 표에 적힌 파일만 수정한다. 공개 계약을 바꿔야 하면 임의로 고치지 않고 루트에 보고한 뒤 멈춘다. 다른 에이전트의 예상 밖 변경을 발견해도 되돌리지 않는다.

 

4단계: 한 명이 통합하고 검증한다

루트 또는 단일 integration owner가 전체 변경을 확인하고 test, lint, typecheck를 실행한다. 실패가 나면 원인 파일의 소유자를 판정한 뒤 한 명에게 후속 작업을 준다. 모든 작업자에게 같은 실패를 동시에 보내면 중복 수정이 생긴다.

 

5단계: 구현자가 아닌 리뷰어가 승인한다

리뷰어는 요구사항, diff, 실행한 검증 결과를 함께 받아 정확성, 보안, 회귀, 누락 테스트를 판정한다. 차단 이슈에는 파일이나 심볼, 재현법, 기대 동작, 수정 방향이 들어가야 한다. 구현 완료와 검수 통과는 다른 상태다.

 

결과 합류와 충돌을 어떻게 처리하나?

루트 에이전트를 유일한 최종 종합자로 둔다. “모든 에이전트가 끝났다”와 “결과가 서로 맞는다”를 분리해 확인해야 한다.

• 중복 결과는 코드, 테스트, 공식 문서처럼 근거가 강한 쪽으로 합친다.
• 상충 결과는 추측으로 절충하지 않고 같은 근거를 다시 확인한다.
• 예상 밖 변경은 되돌리지 말고 소유자와 범위를 확인한다.
• 같은 파일 충돌, 공유 계약 변경, 새 승인 필요, 테스트 환경 장애는 중단 조건으로 둔다.
• 최종 응답에는 변경 파일, 실행한 검증, 미해결 위험을 남긴다.

Codex 앱과 CLI에서는 서브에이전트 스레드를 관찰하고 전환하거나 중단할 수 있다. 승인이 필요한 작업이라면 어느 스레드에서 요청했는지 확인해야 한다. 사용자 정의 파일에서 생략한 sandbox_mode 같은 세션 설정은 부모에서 상속될 수 있으므로, 읽기 전용 조사자는 에이전트 파일에 sandbox_mode = "read-only"를 명시하는 편이 분명하다. 실행 관리와 설정 상속 범위는 Codex Subagents 문서에 정리돼 있다.

 

비용과 한계는 어떻게 통제하나?

서브에이전트는 각각 별도의 컨텍스트와 도구 호출을 사용하므로 총 토큰과 비용이 늘 수 있다. 공유 파일을 동시에 수정하면 충돌과 재작업도 생긴다. 작은 수정이나 선행 관계가 강한 작업에서는 단일 에이전트가 낫다. 처음에는 2~3개의 독립 조사나 리뷰로 시작하는 것을 운영 권고로 삼을 수 있지만, 이는 Codex 제품의 기본값을 뜻하지 않는다.

Responses API Multi-agent beta는 공식 문서상 max_concurrent_subagents 기본값과 권장값이 3이다. beta 항목 스키마는 바뀔 수 있다. 이 값과 변경 가능성은 Responses API Multi-agent 공식 문서에서 게시 시점에 다시 확인해야 한다. Codex 구독 사용 한도와 API 토큰 과금은 별개다. 이 글은 변동 가능성이 큰 가격 숫자를 싣지 않는다.

단일 실행과 다중 실행은 같은 테스트·리뷰 게이트로 비교한다. 직접 측정하지 않은 값을 채우지 말고 아래 표를 실행 기록으로 사용한다.

방식	성공/실패	벽시계 시간	입력 토큰	출력 토큰	도구 호출	충돌·재작업	검수 차단
단일 에이전트
멀티 에이전트

시간이나 호출 수만 줄었다고 성공으로 판정하지 않는다. 최종 결과가 요구사항과 같은 검증 기준을 통과해야 한다.

 

Responses API Multi-agent beta 호출 예제

다음 코드는 Codex 서브에이전트를 켜는 설정이 아니다. GPT-5.6을 사용하는 Responses API beta 요청 예제다. 공식 문서에서 형식을 대조했지만 beta SDK와 API 키가 준비된 환경에서 실행하지 않은 미검증 예제다.

from openai import OpenAI

client = OpenAI()

response = client.beta.responses.create(
    model="gpt-5.6-sol",
    input=(
        "이 PR diff를 정확성, 보안, 누락 테스트 관점으로 나눠 검토하세요. "
        "중복과 충돌을 조정하고 파일·줄 참조가 있는 최종 리뷰를 반환하세요."
    ),
    multi_agent={
        "enabled": True,
        "max_concurrent_subagents": 3,
    },
    betas=["responses_multi_agent=v1"],
)

# beta 응답 항목을 가공하지 않고 원형 그대로 확인한다.
# 최종 텍스트 추출은 사용 중인 SDK 버전의 공식 예제를 따른다.
for item in response.output:
    print(item)

 

공식 문서에 따르면 Python과 JavaScript의 HTTP 예제는 client.beta.responses와 betas=["responses_multi_agent=v1"]를 사용한다. 원시 HTTP와 WebSocket 연결은 OpenAI-Beta: responses_multi_agent=v1 헤더를 보낸다. 위 예제는 응답 항목의 필드를 가정하지 않고 SDK 객체를 출력한다. 최종 텍스트를 추출하려면 사용 중인 beta SDK 버전의 Multi-agent 공식 문서에 나온 필드와 예제를 적용해야 한다.

 

프로젝트에 맞게 바꿔 쓸 위임 프롬프트

모호한 프롬프트는 소유권과 합류 조건을 루트가 추측하게 만든다.

여러 에이전트로 알림 설정 기능을 구현해 줘.

아래처럼 선행 작업, 소유권, 금지 영역, 반환 형식을 적는다. 경로와 test, lint, typecheck 명령은 실제 저장소에 맞게 교체한다.

기존 서비스에 사용자 알림 설정 API와 화면을 추가하세요.

1. 먼저 다음 읽기 전용 조사를 병렬 실행하세요.
- repo_explorer_api: 인증, API 진입점, DB 모델 경로를 찾고
  [파일 경로, 현재 동작, 위험, 추천 경계]만 반환. 수정 금지.
- repo_explorer_ui: 설정 화면과 상태 관리 패턴을 찾고
  [파일 경로, 현재 동작, 위험, 추천 경계]만 반환. 수정 금지.
- docs_researcher: 사용 중인 프레임워크의 공식 문서에서
  API 및 마이그레이션 제약을 링크와 함께 반환. 수정 금지.

2. 모든 조사 결과를 기다린 뒤 루트가 API 스키마, 데이터 모델,
책임 파일, 검증 명령을 확정하세요. 이 게이트 전에는 구현하지 마세요.

3. 계약 확정 후에만 다음 작업을 병렬 실행하세요.
- backend_worker 소유: src/api/notifications/**
  수정 금지: src/ui/**, 공통 타입, 락파일
- frontend_worker 소유: src/ui/settings/notifications/**
  수정 금지: src/api/**, 승인된 API 계약, 락파일
- test_worker 소유: tests/notifications/**
  수정 금지: 구현 파일

공유 계약 변경이 필요하거나 소유 범위가 겹치면 수정하지 말고
루트에 충돌을 보고하세요. 예상 밖의 다른 변경을 되돌리지 마세요.

4. 구현 결과를 모두 기다린 뒤 루트 또는 단일 integration owner가
test, lint, typecheck를 순차 실행하세요. 실패 소유자를 정한 다음
한 명에게만 후속 수정을 맡기세요.

5. 마지막에 읽기 전용 reviewer가 요구사항, diff, 검증 결과를 검토하세요.
차단 이슈에는 파일·심볼, 재현법, 기대 동작, 수정 방향을 포함하세요.

최종 응답에는 변경 파일, 실제 실행한 검증과 결과, 실행하지 않은 검증,
미해결 위험을 구분해 적으세요.

PR 읽기 전용 리뷰라면 구현 단계를 빼고 정확성, 보안, 테스트 리뷰어를 병렬로 보낸 뒤 루트가 중복과 충돌을 정리하면 된다. 기능 구현 전 탐색이라면 조사 결과를 기다리는 설계 게이트를 생략하지 않는다.

 

자주 묻는 질문

 

Codex 서브에이전트는 자동으로 실행되는가?

Codex는 작업과 설정에 따라 서브에이전트를 위임할 수 있지만, 항상 자동으로 병렬화한다고 가정하면 안 된다. 프롬프트에 병렬 조사 범위, 대기 조건, 합류 책임을 명시하고 실행 중인 스레드를 관찰하는 편이 안전하다.

 

같은 파일을 두 에이전트가 수정해도 되는가?

피하는 것이 좋다. 같은 파일과 공유 가변 상태의 동시 수정은 충돌과 재작업을 만든다. 파일 소유권을 나누기 어렵다면 조사만 병렬로 실행하고 구현은 한 명이 순차로 맡는다.

 

explorer와 worker는 무엇이 다른가?

explorer는 코드 경로와 근거를 찾는 읽기 전용 역할이고, worker는 정해진 소유 영역을 수정하는 역할이다. 이름 자체보다 sandbox_mode, 소유 파일, 수정 금지 영역, 완료 기준이 실제 차이를 만든다.

 

서브에이전트는 토큰을 더 사용하는가?

그럴 수 있다. 각 에이전트가 컨텍스트를 읽고 도구를 호출하므로 총 토큰과 비용이 늘 수 있다. 벽시계 시간, 성공률, 총 토큰, 충돌, 재작업을 단일 실행과 함께 측정해야 한다.

 

Responses API Multi-agent beta가 있어야 Codex 멀티 에이전트를 쓸 수 있는가?

아니다. Codex 서브에이전트는 Codex 클라이언트의 기능이고, Responses API Multi-agent beta는 개발자가 GPT-5.6 API 요청에 넣는 기능이다. 설정과 실행 위치가 다르다.

 

에이전트 수보다 경계를 먼저 정하자

독립성부터 판정하고, 한 에이전트에는 한 소유 영역을 준다. 루트가 결과를 합친 뒤 구현자가 아닌 리뷰어가 검수한다.

첫 실행에서는 현재 할 일 목록에 선행 작업, 소유 영역, 완료 조건 세 열을 추가해 보자. 읽기 중심의 독립 작업 두 개만 병렬화하면 충돌 위험을 낮춘 채 운영 방식을 검증할 수 있다.

 

참고 자료

• OpenAI / ChatGPT Learn, Subagents, 발행·수정일 표시 없음, 2026-08-17 열람.
• OpenAI API Documentation, Multi-agent, 발행·수정일 표시 없음, 2026-08-17 열람.
• OpenAI API Documentation, Model guidance: Using GPT-5.6, 발행·수정일 표시 없음, 2026-08-17 열람.
• OpenAI Agents SDK, Agent orchestration, 발행·수정일 표시 없음, 2026-08-17 열람.