コンテンツにスキップ

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 リクエストを送信すると、2 つのツールが表示されます。

codex: 次のプロンプトと設定の上書きを使用して Codex セッションを実行します。

プロパティ 説明
prompt(必須) string Codex の会話を開始するための初期ユーザープロンプトです。
approval-policy string モデルが生成したシェルコマンドに対する承認ポリシーです。untrustedon-requestnever のいずれかです。
base-instructions string デフォルトの指示の代わりに使用する指示のセットです。
compact-prompt string 会話をコンパクションするときに使用するプロンプトです。
config object $CODEX_HOME/config.toml の設定を上書きする個別の設定です。
cwd string セッションの作業ディレクトリです。相対パスの場合は、サーバープロセスの現在のディレクトリを基準に解決されます。
developer-instructions string 開発者ロールのメッセージとして挿入される開発者向け指示です。
model string モデル名のオプションの上書きです(例: gpt-5.4)。
sandbox string サンドボックスモードです。read-onlyworkspace-writedanger-full-access のいずれかです。

codex-reply: スレッド ID とプロンプトを指定して Codex セッションを続行します。codex-reply ツールは次のプロパティを受け取ります。

プロパティ 説明
prompt(必須) string Codex の会話を続行するための次のユーザープロンプトです。
threadId(必須) string 続行するスレッドの ID です。
conversationId(非推奨) string threadId の非推奨の別名です(互換性のために保持されています)。

tools/callstructuredContent.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 キー。OpenAI ダッシュボード でキーを作成または管理できます。

このガイド用の作業ディレクトリを作成し、.env ファイルに API キーを追加します。

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

仮想環境を有効にすると、SDK の依存関係をシステムの他の部分から分離できます。

Codex CLI を MCP サーバーとして初期化する

まず、Agents SDK から呼び出せるように Codex CLI を MCP サーバーに変換します。このサーバーは 2 つのツール(会話を開始する 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())

スクリプトを 1 回実行して、Codex が正常に起動することを確認します。

python codex_mcp.py

スクリプトは Codex MCP server started. を出力した後に終了します。次のセクションでは、同じ MCP サーバーをより高度なワークフローで再利用します。

単一エージェントワークフローを構築する

まずは、Codex MCP を使用して小さなブラウザーゲームを提供する、範囲を絞った例から始めます。このワークフローでは、2 つのエージェントを使用します。

  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.mdTEST.mdAGENT_TASKS.md を作成し、その後、デザイナー、フロントエンド、サーバー、テスターの各エージェント間のハンドオフを調整します。各エージェントは、プロジェクトマネージャーに制御を戻す前に、自身のフォルダーへ範囲を絞った成果物を書き込みます。

ワークフローをトレースする

Codex は、すべてのプロンプト、ツール呼び出し、ハンドオフを記録するトレースを自動的に保存します。マルチエージェントの実行が完了したら、トレースダッシュボード を開いて実行タイムラインを確認します。

高レベルのトレースでは、プロジェクトマネージャーが次に進む前にハンドオフを検証している様子を確認できます。個々のステップをクリックすると、プロンプト、Codex MCP 呼び出し、書き込まれたファイル、実行時間を確認できます。これらの詳細により、すべてのハンドオフを簡単に監査し、ワークフローがターンごとにどのように進化したかを理解できます。 これらのトレースにより、追加の計装を必要とせずに、ワークフローの問題をデバッグし、エージェントの動作を監査し、時間の経過に伴うパフォーマンスを測定できます。