Agents SDK에서 Codex 사용하기

Codex를 MCP 서버로 실행하기

Codex를 MCP 서버로 실행하고 다른 MCP 클라이언트(예: OpenAI Agents SDK MCP 통합으로 구축한 에이전트)에서 연결할 수 있습니다.

Codex를 MCP 서버로 시작하려면 다음 명령을 사용하세요.

codex mcp-server

Model Context Protocol Inspector를 사용하여 Codex MCP 서버를 실행할 수 있습니다.

npx @modelcontextprotocol/inspector codex mcp-server

두 가지 도구를 확인하려면 tools/list 요청을 보내세요.

codex: 다음 프롬프트와 구성 재정의를 사용하여 Codex 세션을 실행합니다.

codex-reply: 스레드 ID와 프롬프트를 제공하여 Codex 세션을 계속합니다. codex-reply 도구는 다음 속성을 사용합니다.

tools/call 응답에서 structuredContent.threadId의 threadId를 사용하세요. 승인 프롬프트(exec/patch)의 params 페이로드에도 threadId가 포함됩니다.

응답 페이로드 예시:

{
  "structuredContent": {
    "threadId": "019bbb20-bff6-7130-83aa-bf45ab33250e",
    "content": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."
  },
  "content": [
    {
      "type": "text",
      "text": "`ls -lah` (or `ls -alh`) — long listing, includes dotfiles, human-readable sizes."
    }
  ]
}

최신 MCP 클라이언트는 일반적으로 "structuredContent"가 있으면 이것만 도구 호출 결과로 보고합니다. 다만 Codex MCP 서버는 이전 MCP 클라이언트를 위해 "content"도 반환합니다.

멀티 에이전트 워크플로 만들기

Codex CLI는 임시 작업을 실행하는 것보다 훨씬 많은 일을 할 수 있습니다. CLI를 Model Context Protocol(MCP) 서버로 노출하고 OpenAI Agents SDK로 오케스트레이션하면 단일 에이전트부터 완전한 소프트웨어 제공 파이프라인까지 확장할 수 있는 결정론적이고 검토 가능한 워크플로를 만들 수 있습니다.

이 가이드에서는 OpenAI Cookbook에서 소개한 것과 동일한 워크플로를 살펴봅니다. 다음 작업을 수행합니다.

• Codex CLI를 장기 실행 MCP 서버로 시작합니다.
• 플레이 가능한 브라우저 게임을 만드는 목적이 명확한 단일 에이전트 워크플로를 구축합니다.
• 핸드오프, 가드레일, 나중에 검토할 수 있는 전체 트레이스를 갖춘 멀티 에이전트 팀을 오케스트레이션합니다.

시작하기 전에 다음 항목을 준비하세요.

• codex 명령을 사용할 수 있도록 로컬에 Codex CLI를 설치합니다.
• pip가 포함된 Python 3.10 이상이 필요합니다.
• 위의 MCP Inspector 예제를 실행하려면 Node.js 18 이상이 필요합니다.
• 로컬에 저장된 OpenAI API key가 필요합니다. OpenAI 대시보드에서 키를 만들거나 관리할 수 있습니다.

가이드용 작업 디렉터리를 만들고 .env 파일에 API key를 추가하세요.

mkdir codex-workflows
cd codex-workflows
printf "OPENAI_API_KEY=sk-..." > .env

종속 항목 설치하기

Agents SDK는 Codex, 핸드오프, 트레이스 전반의 오케스트레이션을 처리합니다. 최신 SDK 패키지를 설치하세요.

python -m venv .venv
source .venv/bin/activate
pip install --upgrade openai openai-agents python-dotenv

Codex CLI를 MCP 서버로 초기화하기

먼저 Codex CLI를 Agents SDK에서 호출할 수 있는 MCP 서버로 전환합니다. 서버는 대화를 시작하는 codex()와 대화를 계속하는 codex-reply()라는 두 가지 도구를 노출하며, 여러 에이전트 턴에 걸쳐 Codex가 계속 실행되도록 합니다.

codex_mcp.py라는 파일을 만들고 다음 내용을 추가하세요.

import asyncio

from agents import Agent, Runner
from agents.mcp import MCPServerStdio


async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={
            "command": "codex",
            "args": ["mcp-server"],
        },
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        print("Codex MCP server started.")
        # More logic coming in the next sections.
        return


if __name__ == "__main__":
    asyncio.run(main())

스크립트를 한 번 실행하여 Codex가 정상적으로 시작되는지 확인하세요.

python codex_mcp.py

스크립트는 Codex MCP server started.을 출력한 후 종료됩니다. 다음 섹션에서는 더 풍부한 워크플로 안에서 동일한 MCP 서버를 재사용합니다.

단일 에이전트 워크플로 구축하기

Codex MCP를 사용하여 작은 브라우저 게임을 제공하는, 범위가 명확한 예제부터 시작하겠습니다. 이 워크플로는 두 에이전트를 사용합니다.

1. 게임 디자이너: 게임 기획서를 작성합니다.
2. 게임 개발자: Codex MCP를 호출하여 게임을 구현합니다.

다음 코드로 codex_mcp.py을 업데이트하세요. 위에서 구성한 MCP 서버 설정을 유지하면서 두 에이전트를 추가합니다.

import asyncio
import os

from dotenv import load_dotenv

from agents import Agent, Runner, set_default_openai_api
from agents.mcp import MCPServerStdio

load_dotenv(override=True)
set_default_openai_api(os.getenv("OPENAI_API_KEY"))


async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={
            "command": "codex",
            "args": ["mcp-server"],
        },
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        developer_agent = Agent(
            name="Game Developer",
            instructions=(
                "You are an expert in building simple games using basic html + css + javascript with no dependencies. "
                "Save your work in a file called index.html in the current directory. "
                "Always call codex with \"approval-policy\": \"never\" and \"sandbox\": \"workspace-write\"."
            ),
            mcp_servers=[codex_mcp_server],
        )

        designer_agent = Agent(
            name="Game Designer",
            instructions=(
                "You are an indie game connoisseur. Come up with an idea for a single page html + css + javascript game that a developer could build in about 50 lines of code. "
                "Format your request as a 3 sentence design brief for a game developer and call the Game Developer coder with your idea."
            ),
            model="gpt-5",
            handoffs=[developer_agent],
        )

        await Runner.run(designer_agent, "Implement a fun new game!")


if __name__ == "__main__":
    asyncio.run(main())

스크립트를 실행하세요.

python codex_mcp.py

Codex는 디자이너의 기획서를 읽고 index.html 파일을 만든 다음 전체 게임을 디스크에 기록합니다. 생성된 파일을 브라우저에서 열어 결과물을 플레이해 보세요. 실행할 때마다 독특한 플레이 방식의 변형과 완성도를 갖춘 새로운 디자인이 만들어집니다.

멀티 에이전트 워크플로로 확장하기

이제 단일 에이전트 설정을 오케스트레이션되고 추적 가능한 워크플로로 전환합니다. 시스템에는 다음 항목이 추가됩니다.

• 프로젝트 관리자: 공통 요구 사항을 만들고, 핸드오프를 조정하며, 가드레일을 적용합니다.
• 디자이너, 프런트엔드 개발자, 서버 개발자, 테스터: 각각 범위가 지정된 지침과 출력 폴더를 사용합니다.

multi_agent_workflow.py라는 새 파일을 만드세요.

import asyncio
import os

from dotenv import load_dotenv

from agents import (
    Agent,
    ModelSettings,
    Runner,
    WebSearchTool,
    set_default_openai_api,
)
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX
from agents.mcp import MCPServerStdio
from openai.types.shared import Reasoning

load_dotenv(override=True)
set_default_openai_api(os.getenv("OPENAI_API_KEY"))


async def main() -> None:
    async with MCPServerStdio(
        name="Codex CLI",
        params={"command": "codex", "args": ["mcp-server"]},
        client_session_timeout_seconds=360000,
    ) as codex_mcp_server:
        designer_agent = Agent(
            name="Designer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "You are the Designer.\n"
                "Your only source of truth is AGENT_TASKS.md and REQUIREMENTS.md from the Project Manager.\n"
                "Do not assume anything that is not written there.\n\n"
                "You may use the internet for additional guidance or research."
                "Deliverables (write to /design):\n"
                "- design_spec.md – a single page describing the UI/UX layout, main screens, and key visual notes as requested in AGENT_TASKS.md.\n"
                "- wireframe.md – a simple text or ASCII wireframe if specified.\n\n"
                "Keep the output short and implementation-friendly.\n"
                "When complete, handoff to the Project Manager with transfer_to_project_manager."
                "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."
            ),
            model="gpt-5",
            tools=[WebSearchTool()],
            mcp_servers=[codex_mcp_server],
        )

        frontend_developer_agent = Agent(
            name="Frontend Developer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "You are the Frontend Developer.\n"
                "Read AGENT_TASKS.md and design_spec.md. Implement exactly what is described there.\n\n"
                "Deliverables (write to /frontend):\n"
                "- index.html – main page structure\n"
                "- styles.css or inline styles if specified\n"
                "- main.js or game.js if specified\n\n"
                "Follow the Designer’s DOM structure and any integration points given by the Project Manager.\n"
                "Do not add features or branding beyond the provided documents.\n\n"
                "When complete, handoff to the Project Manager with transfer_to_project_manager_agent."
                "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        backend_developer_agent = Agent(
            name="Backend Developer",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "You are the Backend Developer.\n"
                "Read AGENT_TASKS.md and REQUIREMENTS.md. Implement the backend endpoints described there.\n\n"
                "Deliverables (write to /backend):\n"
                "- package.json – include a start script if requested\n"
                "- server.js – implement the API endpoints and logic exactly as specified\n\n"
                "Keep the code as simple and readable as possible. No external database.\n\n"
                "When complete, handoff to the Project Manager with transfer_to_project_manager_agent."
                "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        tester_agent = Agent(
            name="Tester",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                "You are the Tester.\n"
                "Read AGENT_TASKS.md and TEST.md. Verify that the outputs of the other roles meet the acceptance criteria.\n\n"
                "Deliverables (write to /tests):\n"
                "- TEST_PLAN.md – bullet list of manual checks or automated steps as requested\n"
                "- test.sh or a simple automated script if specified\n\n"
                "Keep it minimal and easy to run.\n\n"
                "When complete, handoff to the Project Manager with transfer_to_project_manager."
                "When creating files, call Codex MCP with {\"approval-policy\":\"never\",\"sandbox\":\"workspace-write\"}."
            ),
            model="gpt-5",
            mcp_servers=[codex_mcp_server],
        )

        project_manager_agent = Agent(
            name="Project Manager",
            instructions=(
                f"""{RECOMMENDED_PROMPT_PREFIX}"""
                """
                You are the Project Manager.

                Objective:
                Convert the input task list into three project-root files the team will execute against.

                Deliverables (write in project root):
                - REQUIREMENTS.md: concise summary of product goals, target users, key features, and constraints.
                - TEST.md: tasks with [Owner] tags (Designer, Frontend, Backend, Tester) and clear acceptance criteria.
                - AGENT_TASKS.md: one section per role containing:
                  - Project name
                  - Required deliverables (exact file names and purpose)
                  - Key technical notes and constraints

                Process:
                - Resolve ambiguities with minimal, reasonable assumptions. Be specific so each role can act without guessing.
                - Create files using Codex MCP with {"approval-policy":"never","sandbox":"workspace-write"}.
                - Do not create folders. Only create REQUIREMENTS.md, TEST.md, AGENT_TASKS.md.

                Handoffs (gated by required files):
                1) After the three files above are created, hand off to the Designer with transfer_to_designer_agent and include REQUIREMENTS.md and AGENT_TASKS.md.
                2) Wait for the Designer to produce /design/design_spec.md. Verify that file exists before proceeding.
                3) When design_spec.md exists, hand off in parallel to both:
                   - Frontend Developer with transfer_to_frontend_developer_agent (provide design_spec.md, REQUIREMENTS.md, AGENT_TASKS.md).
                   - Backend Developer with transfer_to_backend_developer_agent (provide REQUIREMENTS.md, AGENT_TASKS.md).
                4) Wait for Frontend to produce /frontend/index.html and Backend to produce /backend/server.js. Verify both files exist.
                5) When both exist, hand off to the Tester with transfer_to_tester_agent and provide all prior artifacts and outputs.
                6) Do not advance to the next handoff until the required files for that step are present. If something is missing, request the owning agent to supply it and re-check.

                PM Responsibilities:
                - Coordinate all roles, track file completion, and enforce the above gating checks.
                - Do NOT respond with status updates. Just handoff to the next agent until the project is complete.
                """
            ),
            model="gpt-5",
            model_settings=ModelSettings(
                reasoning=Reasoning(effort="medium"),
            ),
            handoffs=[designer_agent, frontend_developer_agent, backend_developer_agent, tester_agent],
            mcp_servers=[codex_mcp_server],
        )

        designer_agent.handoffs = [project_manager_agent]
        frontend_developer_agent.handoffs = [project_manager_agent]
        backend_developer_agent.handoffs = [project_manager_agent]
        tester_agent.handoffs = [project_manager_agent]

        task_list = """
Goal: Build a tiny browser game to showcase a multi-agent workflow.

High-level requirements:
- Single-screen game called "Bug Busters".
- Player clicks a moving bug to earn points.
- Game ends after 20 seconds and shows final score.
- Optional: submit score to a simple backend and display a top-10 leaderboard.

Roles:
- Designer: create a one-page UI/UX spec and basic wireframe.
- Frontend Developer: implement the page and game logic.
- Backend Developer: implement a minimal API (GET /health, GET/POST /scores).
- Tester: write a quick test plan and a simple script to verify core routes.

Constraints:
- No external database—memory storage is fine.
- Keep everything readable for beginners; no frameworks required.
- All outputs should be small files saved in clearly named folders.
"""

        result = await Runner.run(project_manager_agent, task_list, max_turns=30)
        print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

스크립트를 실행하고 생성되는 파일을 확인하세요.

python multi_agent_workflow.py
ls -R

프로젝트 관리자 에이전트는 REQUIREMENTS.md, TEST.md, AGENT_TASKS.md을 작성한 다음 디자이너, 프런트엔드, 서버, 테스터 에이전트 간의 핸드오프를 조정합니다. 각 에이전트는 제어권을 프로젝트 관리자에게 돌려주기 전에 자체 폴더에 범위가 지정된 산출물을 작성합니다.

워크플로 추적하기

Codex는 모든 프롬프트, 도구 호출, 핸드오프를 포착하는 트레이스를 자동으로 기록합니다. 멀티 에이전트 실행이 완료되면 트레이스 대시보드를 열어 실행 타임라인을 살펴보세요.

상위 수준 트레이스에는 프로젝트 관리자가 다음 단계로 진행하기 전에 핸드오프를 확인하는 방식이 강조되어 표시됩니다. 개별 단계를 클릭하면 프롬프트, Codex MCP 호출, 작성된 파일, 실행 시간을 확인할 수 있습니다. 이러한 세부 정보 덕분에 모든 핸드오프를 손쉽게 감사하고 워크플로가 각 턴을 거치며 어떻게 발전했는지 이해할 수 있습니다. 이러한 트레이스를 활용하면 추가 계측 없이도 워크플로 문제를 손쉽게 디버그하고, 에이전트 동작을 감사하며, 시간 경과에 따른 성능을 측정할 수 있습니다.