Codex, Subagents 지원 시작: OpenAI Codex의 서브에이전트 지원 공식화

OpenAI가 Codex에 서브에이전트(Subagents) 지원을 공식화했다. 단일 에이전트가 처음부터 끝까지 모든 작업을 처리하던 방식에서, 여러 전문화된 서브에이전트가 협력하는 계층적 구조로의 전환이다. 이는 복잡한 소프트웨어 개발 태스크를 자동화하는 방식에 근본적인 변화를 가져올 수 있다. Codex 서브에이전트의 작동 방식, 설계 원리, API 사용 방법, 실제 활용 사례를 살펴본다.

Codex 서브에이전트란 무엇인가

OpenAI Codex는 원래 코드 생성에 특화된 언어 모델로 시작했으나, 현재는 코드 실행, 파일 조작, 터미널 명령 수행이 가능한 에이전트 플랫폼으로 발전했다. 서브에이전트 지원 공식화는 이 발전의 핵심 마일스톤이다.

서브에이전트는 오케스트레이터 에이전트로부터 특정 서브태스크를 위임받아 독립적으로 실행하는 전문화된 에이전트 인스턴스다. 각 서브에이전트는 자체적인 컨텍스트, 도구 세트, 실행 환경을 가질 수 있다.

⤢✕

단일 에이전트와 무엇이 다른가

기존 단일 에이전트 방식에서 Codex는 하나의 LLM 인스턴스가 전체 작업을 순차적으로 처리했다. 이 방식에는 구조적 한계가 있다. 대규모 코드베이스를 한 번에 처리할 수 없는 컨텍스트 길이 제한, 독립적인 서브태스크도 순차적으로 실행되는 병렬 처리 불가, 하나의 에이전트가 모든 역할(분석, 작성, 검토)을 담당하는 전문화 부재, 중간 단계 실패 시 전체 작업이 중단되는 오류 격리 어려움이다.

항목	단일 에이전트	서브에이전트 구조
병렬 처리	불가	독립 태스크 병렬 실행
컨텍스트 관리	단일 컨텍스트	태스크별 분리된 컨텍스트
전문화	범용	역할별 특화 가능
오류 격리	전체 영향	서브태스크 수준 격리
확장성	제한적	수평 확장 가능
비용 최적화	단일 모델	태스크별 적합한 모델 선택

⤢✕

오케스트레이터-서브에이전트 설계

OpenAI Codex의 서브에이전트 시스템은 계층적 구조를 따른다. 오케스트레이터는 전체 목표를 이해하고 태스크를 분해해 서브에이전트에 위임하며, 결과를 통합한다. 오케스트레이터는 사용자 요청 파싱 및 의도 파악, 태스크 분해 및 의존성 분석, 서브에이전트 선택 및 태스크 위임, 실행 순서 및 병렬화 결정, 결과 수집·검증·통합을 책임지고, 서브에이전트는 위임받은 단일 태스크 실행, 필요한 도구 사용, 결과를 오케스트레이터가 이해할 수 있는 형식으로 반환, 실패 시 명확한 오류 정보 반환을 책임진다.

서브에이전트 시스템에서 가장 중요한 설계 요소는 태스크 의존성 관리다. 독립적인 태스크는 병렬로 실행하고, 의존성이 있는 태스크는 순차적으로 실행해야 한다.

⤢✕

Responses API로 구현하기

OpenAI는 Responses API를 통해 서브에이전트 기능을 지원한다. 핵심은 computer_use_preview 도구와 에이전트 간 통신 메커니즘이다.

기본 오케스트레이터 구현은 다음과 같다.

from openai import OpenAI

client = OpenAI()

def create_orchestrator(task: str) -> dict:
    """오케스트레이터 에이전트: 태스크를 서브태스크로 분해"""
    response = client.responses.create(
        model="codex-mini-latest",
        input=f"""
        다음 태스크를 독립적인 서브태스크로 분해하세요.
        각 서브태스크는 JSON 형식으로 반환하세요.

        태스크: {task}

        반환 형식:
        {{
            "subtasks": [
                {{
                    "id": "task_1",
                    "description": "서브태스크 설명",
                    "dependencies": [],
                    "agent_type": "analyzer|coder|tester|reviewer"
                }}
            ]
        }}
        """,
        tools=[{"type": "code_interpreter"}],
    )
    return response

def run_subagent(subtask: dict, context: dict) -> dict:
    """서브에이전트: 특정 서브태스크 실행"""
    response = client.responses.create(
        model="codex-mini-latest",
        input=f"""
        다음 서브태스크를 실행하세요:
        {subtask['description']}

        컨텍스트:
        {context}
        """,
        tools=[
            {"type": "code_interpreter"},
            {"type": "file_search"},
        ],
    )
    return {"task_id": subtask["id"], "result": response}

독립적인 서브태스크는 병렬로 실행한다.

import asyncio
from concurrent.futures import ThreadPoolExecutor

def execute_parallel_subtasks(subtasks: list, context: dict) -> list:
    """독립적인 서브태스크를 병렬로 실행"""
    independent_tasks = [t for t in subtasks if not t["dependencies"]]

    with ThreadPoolExecutor(max_workers=4) as executor:
        futures = [
            executor.submit(run_subagent, task, context)
            for task in independent_tasks
        ]
        results = [f.result() for f in futures]

    return results

서브에이전트 간 결과를 전달할 때는 구조화된 형식을 쓰는 것이 중요하다. OpenAI는 서브에이전트 결과를 다음 에이전트의 컨텍스트에 주입하는 방식을 권장한다.

def build_agent_context(previous_results: list) -> str:
    """이전 서브에이전트 결과를 컨텍스트로 변환"""
    context_parts = []
    for result in previous_results:
        context_parts.append(f"""
        === {result['task_id']} 결과 ===
        {result['result']}
        """)
    return "\n".join(context_parts)

복잡한 코딩 태스크에 적용해보기

레거시 Python 2 코드베이스를 Python 3으로 마이그레이션하는 태스크는 서브에이전트로 이렇게 분해된다.

⤢✕

"사용자 인증 시스템 구현" 요청을 받은 오케스트레이터는 기존 코드베이스의 인증 관련 코드를 파악하는 분석 에이전트, 데이터베이스 스키마·API 엔드포인트를 설계하는 설계 에이전트, JWT 발급·검증 로직을 구현하는 백엔드 구현 에이전트, 인증 미들웨어·권한 검사를 구현하는 미들웨어 에이전트, 단위·통합 테스트를 작성하는 테스트 에이전트, API 문서·README를 업데이트하는 문서화 에이전트로 태스크를 나눈다. 각 에이전트가 병렬로 실행 가능한 태스크를 동시에 처리함으로써, 단일 에이전트 대비 3-5배의 속도 향상을 기대할 수 있다.

CI/CD 파이프라인에 서브에이전트 시스템을 통합하면 PR마다 자동으로 OWASP 취약점을 스캔하는 보안 에이전트, 알고리즘 복잡도를 분석하는 성능 에이전트, 미테스트 코드를 탐지·생성하는 테스트 커버리지 에이전트, 변경된 API의 문서를 자동 업데이트하는 문서 에이전트가 실행된다.

비용과 오류를 다루는 법

서브에이전트 구조는 API 호출 수가 증가한다. 비용 최적화를 위해 단순 태스크에는 codex-mini 모델을 쓰고, 복잡한 추론이 필요한 태스크에만 고성능 모델을 할당하며, 서브에이전트 최대 수 설정으로 동시 실행을 제한한다.

서브에이전트 실패 시 전체 파이프라인이 중단되지 않도록 각 서브에이전트에 타임아웃을 설정하고, 실패한 서브에이전트의 재시도 로직을 구현하며, 오케스트레이터가 부분 실패를 처리하는 폴백 전략을 정의해야 한다.

OpenAI Codex의 서브에이전트 지원 공식화는 AI 기반 소프트웨어 개발 자동화의 새로운 장을 열었다. 단일 에이전트의 순차적 처리 한계를 넘어, 전문화된 서브에이전트들이 병렬로 협력하는 계층적 시스템은 복잡한 코딩 태스크를 더 빠르고 효율적으로 처리할 수 있게 한다. 비용 관리와 오류 처리를 신중하게 설계한다면, 실제 소프트웨어 개발 파이프라인에서 즉각적인 생산성 향상을 경험할 수 있다.