Menggunakan Codex dengan Agents SDK

Menjalankan Codex sebagai server MCP

Anda dapat menjalankan Codex sebagai server MCP dan menghubungkannya dari klien MCP lain (misalnya, agen yang dibuat dengan integrasi MCP OpenAI Agents SDK).

Untuk memulai Codex sebagai server MCP, Anda dapat menggunakan perintah berikut:

codex mcp-server

Anda dapat meluncurkan server MCP Codex dengan Model Context Protocol Inspector:

npx @modelcontextprotocol/inspector codex mcp-server

Kirim permintaan tools/list untuk melihat dua alat:

codex: Jalankan sesi Codex dengan prompt dan penggantian konfigurasi berikut:

codex-reply: Lanjutkan sesi Codex dengan memberikan ID utas dan prompt. Alat codex-reply menerima properti berikut:

Gunakan threadId dari structuredContent.threadId dalam respons tools/call. Prompt persetujuan (exec/patch) juga menyertakan threadId dalam payload params-nya.

Contoh payload respons:

{
  "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."
    }
  ]
}

Perhatikan bahwa klien MCP modern umumnya hanya melaporkan "structuredContent" sebagai hasil pemanggilan alat jika tersedia, meskipun server MCP Codex juga mengembalikan "content" untuk mendukung klien MCP lama.

Membuat alur kerja multiagen

Codex CLI dapat melakukan jauh lebih banyak daripada sekadar menjalankan tugas ad hoc. Dengan mengekspos CLI sebagai server Model Context Protocol (MCP) dan mengorkestrasikannya dengan OpenAI Agents SDK, Anda dapat membuat alur kerja deterministik dan dapat ditinjau yang berkembang dari satu agen hingga menjadi pipeline pengiriman perangkat lunak lengkap.

Panduan ini menguraikan alur kerja yang sama dengan yang ditampilkan dalam OpenAI Cookbook. Anda akan:

• meluncurkan Codex CLI sebagai server MCP yang berjalan terus-menerus,
• membangun alur kerja satu agen yang terfokus dan menghasilkan gim browser yang dapat dimainkan, serta
• mengorkestrasikan tim multiagen dengan serah terima, batasan pengaman, dan rekaman pelacakan lengkap yang dapat Anda tinjau setelahnya.

Sebelum memulai, pastikan Anda memiliki:

• Codex CLI yang terinstal secara lokal agar perintah codex tersedia.
• Python 3.10+ dengan pip.
• Node.js 18+ jika Anda ingin menjalankan contoh MCP Inspector di atas.
• API key OpenAI yang disimpan secara lokal. Anda dapat membuat atau mengelola kunci di dasbor OpenAI.

Buat direktori kerja untuk panduan ini dan tambahkan API key Anda ke file .env:

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

Menginstal dependensi

Agents SDK menangani orkestrasi di antara Codex, serah terima, dan rekaman pelacakan. Instal paket SDK terbaru:

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

Menginisialisasi Codex CLI sebagai server MCP

Mulailah dengan mengubah Codex CLI menjadi server MCP yang dapat dipanggil oleh Agents SDK. Server ini mengekspos dua alat (codex() untuk memulai percakapan dan codex-reply() untuk melanjutkannya) dan mempertahankan Codex tetap aktif selama beberapa giliran agen.

Buat file bernama codex_mcp.py dan tambahkan kode berikut:

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())

Jalankan skrip satu kali untuk memastikan Codex berhasil diluncurkan:

python codex_mcp.py

Skrip berhenti setelah mencetak Codex MCP server started.. Pada bagian berikutnya, Anda akan menggunakan kembali server MCP yang sama di dalam alur kerja yang lebih lengkap.

Membangun alur kerja satu agen

Mari mulai dengan contoh terbatas yang menggunakan Codex MCP untuk menghasilkan sebuah gim browser kecil. Alur kerja ini menggunakan dua agen:

1. Perancang Gim: menulis ringkasan rancangan gim.
2. Pengembang Gim: mengimplementasikan gim dengan memanggil Codex MCP.

Perbarui codex_mcp.py dengan kode berikut. Kode ini mempertahankan penyiapan server MCP di atas dan menambahkan kedua agen.

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())

Jalankan skrip:

python codex_mcp.py

Codex akan membaca ringkasan perancang, membuat file index.html, dan menulis seluruh gim ke disk. Buka file yang dihasilkan di browser untuk memainkannya. Setiap eksekusi menghasilkan desain berbeda dengan variasi gaya bermain dan penyempurnaan yang unik.

Memperluas menjadi alur kerja multiagen

Sekarang ubah penyiapan satu agen menjadi alur kerja yang terorkestrasi dan dapat dilacak. Sistem menambahkan:

• Manajer Proyek: membuat persyaratan bersama, mengoordinasikan serah terima, dan menerapkan batasan pengaman.
• Perancang, Pengembang Frontend, Pengembang Server, dan Penguji: masing-masing memiliki instruksi dan folder output dengan cakupan tertentu.

Buat file baru bernama 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())

Jalankan skrip dan amati file yang dihasilkan:

python multi_agent_workflow.py
ls -R

Agen manajer proyek menulis REQUIREMENTS.md, TEST.md, dan AGENT_TASKS.md, lalu mengoordinasikan serah terima di antara agen perancang, frontend, server, dan penguji. Setiap agen menulis artefak sesuai cakupannya ke foldernya sendiri sebelum menyerahkan kembali kendali kepada manajer proyek.

Melacak alur kerja

Codex secara otomatis merekam jejak yang mencakup setiap prompt, pemanggilan alat, dan serah terima. Setelah eksekusi multiagen selesai, buka dasbor Traces untuk memeriksa linimasa eksekusi.

Jejak tingkat tinggi menyoroti cara manajer proyek memverifikasi serah terima sebelum melanjutkan. Buka setiap langkah untuk melihat prompt, panggilan Codex MCP, file yang ditulis, dan durasi eksekusi. Detail ini memudahkan Anda mengaudit setiap serah terima dan memahami perkembangan alur kerja dari satu giliran ke giliran berikutnya. Jejak ini memudahkan Anda men-debug kendala alur kerja, mengaudit perilaku agen, dan mengukur performa dari waktu ke waktu tanpa memerlukan instrumentasi tambahan.