Использование Codex с Agents SDK

Запуск Codex в качестве MCP-сервера

Вы можете запустить Codex как MCP-сервер и подключаться к нему из других MCP-клиентов (например, из агента, созданного с помощью интеграции MCP в OpenAI Agents SDK).

Чтобы запустить Codex как MCP-сервер, используйте следующую команду:

codex mcp-server

Вы можете запустить MCP-сервер Codex с помощью Model Context Protocol Inspector:

npx @modelcontextprotocol/inspector codex mcp-server

Отправьте запрос tools/list, чтобы увидеть два инструмента:

codex: запускает сеанс Codex со следующим запросом и переопределениями конфигурации:

codex-reply: продолжает сеанс Codex с указанными идентификатором потока и запросом. Инструмент codex-reply принимает следующие свойства:

Используйте threadId из structuredContent.threadId в ответе tools/call. Запросы на подтверждение (exec/patch) также содержат threadId в своей полезной нагрузке params.

Пример полезной нагрузки ответа:

{
  "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", если это значение присутствует, хотя MCP-сервер Codex также возвращает "content" для поддержки старых MCP-клиентов.

Создание многоагентных процессов

Codex CLI способен не только выполнять разовые задачи. Предоставив доступ к CLI в виде сервера Model Context Protocol (MCP) и организовав его работу с помощью OpenAI Agents SDK, вы можете создавать детерминированные, доступные для проверки процессы — от одного агента до полного конвейера поставки программного обеспечения.

В этом руководстве рассматривается тот же процесс, который представлен в OpenAI Cookbook. Вы:

• запустите Codex CLI как долгоживущий MCP-сервер;
• создадите специализированный процесс с одним агентом, результатом которого станет готовая браузерная игра;
• организуете многоагентную команду с передачей задач, ограничениями и полными трассировками, которые можно изучить после выполнения.

Перед началом убедитесь, что у вас есть:

• локально установленный Codex CLI, чтобы команда codex была доступна;
• Python 3.10+ с pip;
• Node.js 18+, если вы хотите запустить приведённый выше пример с MCP Inspector;
• локально сохранённый OpenAI API key. Создать ключи и управлять ими можно на панели управления OpenAI.

Создайте рабочий каталог для руководства и добавьте свой API key в файл .env:

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 в MCP-сервер, который сможет вызывать Agents SDK. Сервер предоставляет два инструмента (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 и запишет полную реализацию игры на диск. Откройте созданный файл в браузере, чтобы сыграть. При каждом запуске создаётся новый дизайн с уникальными особенностями игрового процесса и проработанными деталями.

Переход к многоагентному процессу

Теперь преобразуйте конфигурацию с одним агентом в управляемый процесс с возможностью трассировки. В систему добавляются:

• Руководитель проекта: формирует общие требования, координирует передачу задач и обеспечивает соблюдение ограничений.
• Дизайнер, Frontend-разработчик, Server-разработчик и Тестировщик: каждый со специализированными инструкциями и каталогами для результатов.

Создайте новый файл 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, а затем координирует передачу задач между агентами дизайнера, frontend-разработчика, server-разработчика и тестировщика. Каждый агент записывает относящиеся к его области артефакты в собственную папку, после чего передаёт управление обратно руководителю проекта.

Трассировка процесса

Codex автоматически записывает трассировки, охватывающие каждый запрос, вызов инструмента и передачу задачи. После завершения многоагентного процесса откройте панель трассировок, чтобы изучить временную шкалу выполнения.

Высокоуровневая трассировка показывает, как руководитель проекта проверяет передачу задач перед переходом к следующему этапу. Откройте отдельные шаги, чтобы увидеть запросы, вызовы Codex MCP, записанные файлы и длительность выполнения. Эти сведения позволяют легко проверять каждую передачу задачи и понимать, как процесс развивался от хода к ходу. Эти трассировки позволяют легко диагностировать сбои в процессе, проверять поведение агентов и оценивать производительность с течением времени без дополнительных средств инструментирования.