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

[L. Elaine Dazzio (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.

[L. Elaine Dazzio (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)

[L. Elaine Dazzio (LEDazzio01)]

Thanks for the thorough review Eduard van Valkenburg (@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! 🙏

[Eduard van Valkenburg (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

[L. Elaine Dazzio (LEDazzio01)]

Thanks for the thorough review Eduard van Valkenburg (@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.

[Eduard van Valkenburg (eavanvalkenburg)]

L. Elaine Dazzio (@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?

[L. Elaine Dazzio (LEDazzio01)]

Eduard van Valkenburg (@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! 🚀

[Eduard van Valkenburg (eavanvalkenburg)]

please make sure to rebase so that you have all the latest

[L. Elaine Dazzio (LEDazzio01)]

Rebased — branch is now up to date with main. Thanks for the approval! 🙏

[Eduard van Valkenburg (eavanvalkenburg)]

small update needed on the constructor

[L. Elaine Dazzio (LEDazzio01)]

Eduard van Valkenburg (@eavanvalkenburg) Thanks for the review! I've addressed the constructor feedback in commit 1afad29:

1. AgentMiddlewareLayer added to MRO — CodexAgent now inherits AgentMiddlewareLayer, AgentTelemetryLayer, RawCodexAgent[OptionsT], matching the FoundryAgent pattern.

2. Explicit __init__ with full parameter surface — CodexAgent now has its own __init__ that explicitly exposes all parameters from all layers (middleware, telemetry, raw agent), with a comprehensive docstring documenting every keyword argument.

3. run() overloads updated — Added middleware, tools, compaction_strategy, tokenizer, function_invocation_kwargs, and client_kwargs parameters to the run() signature on CodexAgent, matching the ClaudeAgent/FoundryAgent pattern.

4. default_options property — Added for AgentTelemetryLayer compatibility, mapping system_prompt → instructions.

[Eduard van Valkenburg (eavanvalkenburg)]

there is also a conflict, please check L. Elaine Dazzio (@LEDazzio01)

[L. Elaine Dazzio (LEDazzio01)]

Eduard van Valkenburg (@eavanvalkenburg) Rebased onto latest main — conflict in python/pyproject.toml resolved (added agent-framework-codex alongside the new agent-framework-claude entry in alphabetical order). Branch is clean with 12 linear commits, no merge commits.

[Eduard van Valkenburg (eavanvalkenburg)]

still some test failures L. Elaine Dazzio (@LEDazzio01)

[L. Elaine Dazzio (LEDazzio01)]

Fix Summary

The CI failures were caused by two root issues:

1. Wrong dependency package

The original codex-sdk package on PyPI is a Cleanlab internal SDK that provides a codex module — not the OpenAI Codex CLI wrapper. The correct package is codex-sdk-python which provides the codex_sdk module.

2. API migration

The code was written against an older, unreleased SDK API (CodexSDKClient, AssistantMessage, StreamEvent, etc.). The published codex-sdk-python (v0.117.0) uses a completely different architecture:

• Codex + Thread instead of CodexSDKClient
• Thread.run_streamed_events() instead of client.query()/receive_response()
• ItemUpdatedEvent/AgentMessageItem instead of StreamEvent/AssistantMessage
• Thread IDs for session management instead of session IDs

Changes in this push

• Migrated dependency from codex-sdk to codex-sdk-python>=0.117.0,<1
• Rewrote _agent.py to use the new SDK API
• Renamed BaseContextProvider → ContextProvider (upstream API rename after rebase)
• Updated CodexAgentSettings to match new SDK (approval_policy instead of permission_mode)
• Rewrote test suite: 36 tests, all passing
• All local checks pass: tests ✅, ruff lint ✅, ruff format ✅, mypy ✅
• Rebased on upstream/main (Apr 20)

[L. Elaine Dazzio (LEDazzio01)]

Hi team 👋

Thank you for your time reviewing this PR and for all the guidance along the way. I've decided to step back from contributing to the Agent Framework to pursue other interests and projects.

As a result, I won't be able to continue working on this PR. Please feel free to close it, or if any of the work here is useful, don't hesitate to pick it up or adapt it as you see fit.

I really appreciate the welcoming community and everything I've learned contributing here. Wishing you all the best with the project!

Best regards