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.137.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, 보수적 fallback은 GPT-5.4를 기준으로 나누는 편이 자연스럽습니다
• service-tier/subagent 운영 보강 (0.131.0): spawned agents에도 service-tier overrides가 전달되고, multi-agent v2 tool namespace 설정과 wait-agent timeout 제어가 더 명확해졌습니다
• Multi-agent v2 runtime metadata (0.137.0): 각 spawned thread가 runtime choice를 유지하고, follow-up task와 metadata default가 더 깨끗하게 정리됩니다. 여러 runtime이나 원격 환경을 섞는 팀은 parent thread에서 "어떤 runtime으로 보낸 작업인지"를 기록하세요
• multi-agent delegation modes (0.142.0): delegated task의 parent/child handoff 방식을 명시적으로 다루므로, parent thread에는 "누가 통합하고 누가 조사만 하는지", "어떤 파일은 어떤 agent가 소유하는지", "언제 /usage와 rollout budget을 재확인할지"를 남깁니다
• spawned child listener 안정화 (0.137.0): spawned child listener가 raw events를 더 일관되게 상속하고, self-target close 같은 오류 경로가 줄었습니다. 내부 UI/SDK 클라이언트는 child thread close/follow-up 이벤트를 별도 상태로 표시하는 편이 좋습니다
• 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 (영어)