Python: Add OpenAI Codex SDK integration (agent-framework-codex)

[LEDazzio01]

Motivation and Context

Closes #4370

The Microsoft Agent Framework currently supports managed agent SDK integrations for Claude (agent-framework-claude) and GitHub Copilot (agent-framework-github-copilot), but not for OpenAI Codex. This PR adds agent-framework-codex to provide parity across the three major agentic coding SDKs.

Description

Adds a new Python package agent-framework-codex that wraps the codex-sdk as a managed agent, following the same conventions as the existing Claude and GitHub Copilot packages.

New Files

File	Description
python/packages/codex/pyproject.toml	Package configuration (flit-core, ruff, pyright, mypy, pytest)
python/packages/codex/README.md	Package README with install instructions
python/packages/codex/LICENSE	MIT License
python/packages/codex/AGENTS.md	Package metadata for agent discovery
python/packages/codex/agent_framework_codex/__init__.py	Public API: CodexAgent, CodexAgentOptions, CodexAgentSettings
python/packages/codex/agent_framework_codex/_agent.py	Core implementation wrapping CodexSDKClient
python/packages/codex/tests/test_codex_agent.py	Comprehensive unit tests (all mocked, no external deps)

Key Classes

• CodexAgentSettings — TypedDict for env-based config (CODEX_AGENT_ prefix)
• CodexAgentOptions — TypedDict for per-request options (model, system_prompt, etc.)
• CodexAgent — BaseAgent subclass with full support for:
  • Streaming and non-streaming responses
  • Session management (service_session_id)
  • Tool conversion (FunctionTool → SDK MCP tools)
  • Async context manager (async with CodexAgent() as agent)
  • Structured output propagation
  • Runtime option changes (model, permission_mode)

Usage

from agent_framework_codex import CodexAgent

async with CodexAgent(
    instructions="You are a helpful coding assistant.",
    default_options={"model": "codex-mini-latest"},
) as agent:
    response = await agent.run("Write a Python function that reverses a linked list.")
    print(response.text)

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR title follows the repo convention
• Tests added to cover the change
• All new and existing tests pass

[Copilot]

Pull request overview

Adds a new Python managed-agent integration package, agent-framework-codex, that wraps the Codex SDK to provide an Agent Framework BaseAgent implementation with streaming, sessions, tool bridging (via MCP), and structured-output propagation.

Changes:

• Introduces CodexAgent, CodexAgentOptions, and CodexAgentSettings plus supporting implementation to run Codex via CodexSDKClient with streaming updates and session resume support.
• Adds a full unit-test suite for initialization, streaming/non-streaming runs, sessions, tool conversion, runtime options, and structured output.
• Adds package scaffolding (pyproject.toml, README, LICENSE, AGENTS.md).

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/packages/codex/agent_framework_codex/_agent.py	Implements the Codex managed agent (client lifecycle, sessions, tool→MCP conversion, streaming).
python/packages/codex/tests/test_codex_agent.py	Adds mocked unit tests covering key agent behaviors.
python/packages/codex/pyproject.toml	Defines the new package metadata, dependencies, and tooling config.
python/packages/codex/agent_framework_codex/init.py	Exposes the package public API + version.
python/packages/codex/README.md	Minimal install/get-started documentation.
python/packages/codex/LICENSE	Adds MIT license text for the package.
python/packages/codex/AGENTS.md	Agent discovery metadata for the new package.

[LEDazzio01]

Thanks for the thorough review! All 3 comments addressed in the latest commits:

1. _ensure_session session isolation (_agent.py) — Fixed. Removed the extra session_id and guard so None is now treated as a distinct session identity. Added a dedicated regression test (test_ensure_session_recreates_when_resumed_then_fresh) that verifies switching from a resumed session back to None correctly creates a new client. (commit 8df3a83, 3b95a7d)

2. pyproject.toml dependency — Aligned agent-framework-core>=1.0.0rc2 → >=1.0.0rc1 to match the other managed-agent integrations. (commit 850cb45)

3. AGENTS.md description — Updated "Pydantic settings" → "TypedDict-based settings populated via the framework's load_settings() helper". (commit ebdcb5e)

[LEDazzio01]

Thanks for the thorough review @eavanvalkenburg! I've addressed all feedback in the latest force-push (rebased onto latest main):

✅ Changes made:

1. Rebased + bumped dependency → agent-framework-core>=1.0.0rc2

2. AGENT_PROVIDER_NAME — kept as "openai.codex", following the {provider}.{product} convention used by ClaudeAgent ("anthropic.claude"). Happy to change to just "openai" if there's a specific OTel GenAI spec value you'd prefer.

3. Telemetry layer split — implemented! Now:

   • RawCodexAgent(BaseAgent) — core implementation without telemetry
   • CodexAgent(AgentTelemetryLayer, RawCodexAgent) — with OTel instrumentation
   • Both exported from __init__.py
   • Follows the A2AAgent(AgentTelemetryLayer, BaseAgent) pattern

4. Removed MutableMapping from run() options parameter → simplified to OptionsT | None

5. background: bool — the Codex SDK's session model (CLI subprocess) doesn't have a direct equivalent to A2A's background task polling. The SDK doesn't expose task IDs or resubscription like the A2A protocol. I'd suggest deferring this to a follow-up once there's clearer support in the Codex SDK for detached/background execution. Let me know if you'd prefer a different approach.

Ready for another look! 🙏

[eavanvalkenburg]

looks pretty good, just missing a sample to showcase the user code, should be still inside this folder, that will be moved once we include this package structurally

[LEDazzio01]

Thanks for the thorough review @eavanvalkenburg! All feedback has been addressed in commit 4b93a97:

1. Rebase + rc2 — Updated pyproject.toml dependency to agent-framework-core>=1.0.0rc2.

2. Telemetry split — Already done in a prior commit: RawCodexAgent holds the implementation, CodexAgent(AgentTelemetryLayer, RawCodexAgent) adds telemetry. Both are exported from __init__.py.

3. Provider name — Changed AGENT_PROVIDER_NAME from "openai.codex" to "openai" to follow the OTel GenAI semantic conventions. The model name (codex-mini-latest / gpt-5.1-codex) already differentiates Codex telemetry from standard OpenAI chat.

4. Simplified typing — Removed the MutableMapping[str, Any] union from default_options and options parameters across __init__ and all run() overloads. Now uses just OptionsT as suggested. Also removed the unused MutableMapping import.

5. Background support — The Codex SDK currently runs synchronously until completion (with streaming). Background mode would require the SDK to support detaching from a running session and polling for results, which isn't available yet. I'd recommend deferring this to a follow-up PR once the SDK adds that capability. Happy to track it as an issue if you'd like.

6. Sample script — Added samples/codex_sample.py showcasing basic usage, streaming, multi-turn sessions, and custom tool integration via the @tool decorator.

[eavanvalkenburg]

@LEDazzio01 thanks for your patience with this, we have a bunch of new guidance for package management in the skill for that, could you ensure we apply that with this as a alpha package?

[LEDazzio01]

@eavanvalkenburg Thanks for the pointer to the package management skill! I've applied the full alpha package checklist from python/.github/skills/python-package-management/SKILL.md:

Changes in commit 9b09963:

Item	Change
Version	1.0.0b260225 → 1.0.0a260410 (alpha pattern)
Classifier	Development Status :: 4 - Beta → Development Status :: 3 - Alpha
Core dependency	>=1.0.0rc2 → >=1.0.1,<2 (stable + upper bound)
codex-sdk dependency	>=0.1.0 → >=0.1.0,<0.2 (tight upper bound)
Pyright	Added include = ["agent_framework_codex"]
Poe tasks	Switched to structured help + cmd format
Root workspace	Added agent-framework-codex to tool.uv.sources
AGENTS.md	Added codex to package documentation index

Note: The PACKAGE_STATUS.md entry will need to be added after merging/rebasing with main, since that file was added after this branch was created. Happy to rebase if needed.

Ready for review! 🚀