Ch9. 멀티에이전트

Codex는 멀티에이전트 워크플로우를 통해 복잡한 작업을 병렬로 분할 처리할 수 있습니다. 대규모 코드베이스 탐색, 멀티 모듈 리팩토링, 배치 작업 등에서 단일 에이전트 대비 효율이 크게 좋아집니다.

최근 릴리스에서는 멀티에이전트가 "실험 기능"을 넘어, 승인 추적/스레드 전환/컨텍스트 handoff까지 다듬어져 실전 운영성이 크게 좋아졌습니다.

활성화

최신 Codex 릴리스에서는 subagent workflow가 기본 활성화되어 있습니다. 오래된 CLI나 제한된 조직 정책에서는 feature flag가 꺼져 있을 수 있으므로 /experimental과 /status로 현재 세션 상태를 확인하세요.

# 오래된 CLI에서 세션 내 활성화가 필요할 때
/experimental  # → "Multi-agents" 선택 후 Codex 재시작

# 또는 config.toml에 영구 설정

# ~/.codex/config.toml
[features]
multi_agent = true

동작 방식

Codex가 멀티에이전트 모드에서 하는 일:

1. 서브에이전트 생성: 자동 또는 명시적 요청으로 전문 에이전트를 스폰
2. 작업 분배: 각 에이전트에 역할과 지시를 할당
3. 진행 추적: 모든 에이전트의 결과를 대기하고 통합
4. 스레드 관리: 완료된 에이전트 스레드를 자동 정리

최근 변화(0.105.0~0.130.0)

• child-thread approval 가시화: 어느 자식 스레드가 승인 때문에 멈췄는지 더 잘 보임
• /agent 기반 enablement: 실험 기능을 별도 토글로만 켜는 대신, 세션 내 /agent 플로우가 더 자연스러워짐
• 닉네임/role handoff 강화: ordinal nickname, cleaner picker, role-labeled handoff context로 추적성이 올라감
• /multiagent alias: 팀 문서/교육 자료에서 /agent와 함께 보조 표기로 설명 가능
• handoff 시 실시간 transcript 컨텍스트 전달 (0.114.0): 에이전트 간 handoff 시 기존 대화 transcript가 함께 넘어가, 인수받는 에이전트가 이전 맥락을 더 정확히 이해합니다. 반복 설명이 줄고 연속성이 크게 좋아졌습니다
• 실험적 hooks 엔진 (0.114.0): SessionStart와 Stop hook 이벤트가 도입되어, 멀티에이전트 워크플로우의 시작/종료 시점에 자동화 트리거를 걸 수 있습니다
• GPT-5.5 중심 재정렬 (2026-05): browser use가 섞인 조사형 에이전트와 복잡한 구현 작업은 GPT-5.5, 빠른 보조 에이전트는 GPT-5.4-mini, API-key/미가용 fallback은 GPT-5.4를 기준으로 나누는 편이 자연스럽습니다
• Codex App 자동화 개편 (App 26.312): 자동화에서 로컬/워크트리 실행 선택, 모델·추론 수준 개별 지정이 가능해져 멀티에이전트 운영의 유연성이 높아졌습니다
• Smart Approvals guardian subagent (0.115.0): 스마트 승인이 guardian 서브에이전트를 통해 라우팅됩니다. 다중 인터페이스(TUI, App, app-server)에서 일관된 승인 경험을 제공하며, 승인 판단의 정확도가 향상됐습니다
• wait_agent 도구 이름 변경 (0.115.0): 기존 서브에이전트 대기 도구가 wait_agent로 이름이 변경됐습니다. 기존 wait 도구와의 혼동을 줄이기 위한 변경입니다
• 경로 기반 에이전트 주소 (0.117.0): 서브에이전트가 /root/agent_a 같은 읽기 쉬운 path-based address를 사용해, 로그/리뷰/모니터링에서 식별성이 좋아졌습니다
• structured inter-agent messaging + agent listing (0.117.0): multi-agent v2에서 에이전트 간 메시지와 목록 조회가 더 구조화되어, 부모 스레드가 서브에이전트 네트워크를 추적하기 쉬워졌습니다
• MultiAgentV2 설정 명시화 (0.128.0): thread cap, wait-time control, root/subagent hint, depth handling이 더 분명해졌습니다
• config reference 확장 (2026-05): agents.max_threads, agents.max_depth, agents.job_max_runtime_seconds, agents.<name>.config_file, nickname_candidates를 팀 표준으로 문서화할 수 있습니다

에이전트 역할(Built-in)

에이전트 역할 설정 (config.toml)

[agents]
max_threads = 4          # 최대 동시 스레드
max_depth = 1            # 최대 중첩 깊이

[agents.reviewer]
description = "코드 리뷰 전담. 보안·정확성·성능 관점에서 검토"
config_file = ".codex/reviewer.toml"  # 역할별 독립 설정

[agents.docs_writer]
description = "코드 변경에 따른 문서 업데이트 담당"

역할별 설정 파일에서 model, sandbox_mode, developer_instructions 등을 독립적으로 지정할 수 있습니다.

/agent 커맨드로 관리

세션 중 /agent를 사용해 서브에이전트 스레드를 관리합니다.

• 활성 스레드 간 전환
• 진행 중인 작업 확인
• 특정 에이전트 중지/닫기
• 닉네임으로 빠른 식별
• 0.117.0 이후에는 원격 세션에서도 raw ID보다 agent name/path가 더 잘 보입니다

Fork + Steering 패턴 (0.99.0~0.107.0)

최근 릴리스 기준으로, 고급 사용자/클라이언트 제작자는 멀티에이전트를 더 능동적으로 제어할 수 있습니다.

• 현재 스레드를 서브에이전트로 fork: 다른 접근을 실험하고 싶을 때 새 세션을 다시 열지 않아도 됨
• active turn steering: 장시간 작업 중인 에이전트에 중간 지시를 추가해 방향을 좁히거나 우선순위를 바꿀 수 있음
• resume_agent 흐름: 일시 중단/연결 끊김 뒤에도 agent 재개가 쉬워짐
• resume 시 승인/입력 상태 복원: 사람이 다시 붙었을 때 "왜 멈췄는지"를 잃지 않음

실전 패턴:

1. explorer가 넓게 탐색
2. 중간에 steer해서 범위를 줄임
3. worker를 fork해 수정안을 병렬로 시도
4. 부모 스레드에서 승인/검증 후 하나만 채택

spawn_agents_on_csv (배치 처리)

CSV 파일에서 작업 목록을 읽어 각 행마다 에이전트를 자동 생성합니다. 진행률 표시와 ETA가 내장되어 있습니다.

적합한 사용 사례

• 대규모 마이그레이션 스크립트(각 모듈별 처리)
• 다수 모듈의 테스트 생성
• 반복적인 코드 정리/리팩토링
• 다중 이슈 트리아지

실전 구성 예시

PR 리뷰 팀

[요청]
이 PR을 종합적으로 리뷰해줘.

[에이전트 역할]
- explorer: 코드베이스 전체 구조 파악, 영향 범위 분석
- reviewer: 정확성·보안·성능 관점 코드 리뷰
- docs_researcher: 관련 문서/API 변경 확인

프론트엔드 디버깅

[요청]
로그인 페이지 버그를 해결해줘.

[에이전트 역할]
- explorer: 관련 코드 경로 탐색
- worker: 버그 수정 구현

Hooks 엔진으로 워크플로우 자동화 (0.114.0)

SessionStart와 Stop hook 이벤트를 활용하면 멀티에이전트 운영을 반자동화할 수 있습니다.

활용 예시:

• 세션 시작 시 특정 에이전트 역할을 자동 스폰
• 세션 종료 시 결과 요약을 외부 시스템(Slack, GitHub Issue 등)에 자동 전송
• 에이전트 완료 시점에 후속 검증 스크립트를 트리거

멀티에이전트와 hooks를 조합하면, 수동 개입 없이도 "탐색 → 구현 → 검증 → 보고"를 하나의 파이프라인으로 연결할 수 있습니다.

샌드박스/승인 상속

• 서브에이전트는 부모의 샌드박스 정책을 상속합니다
• 단, 비대화형 승인으로 동작하여 추가 승인이 필요한 작업은 자동 실패
• 실패한 작업은 에러로 부모에게 전달됩니다
• 역할별 설정 파일에서 sandbox_mode를 개별 오버라이드할 수 있습니다

참고 문서

• Multi-agent: https://developers.openai.com/codex/multi-agent (영어)
• Agents SDK 가이드: https://developers.openai.com/codex/guides/agents-sdk (영어)
• config 레퍼런스: https://developers.openai.com/codex/config-reference (영어)
• CLI 기능: https://developers.openai.com/codex/cli/features (영어)