[Lancetnik]

Why are these changes needed?

OpenAIConfig currently selects Chat Completions, while Responses is the intended OpenAI default. Rebinding the name immediately would change existing applications' endpoints and accepted parameters without a migration period.

Expose the current implementation as OpenAICompletionsConfig and keep OpenAIConfig as a deprecated compatibility subclass until 1.4.0. It preserves the constructor, copied config type, Chat Completions parameters, Files API support, and media acceptance. The class is marked deprecated for type checkers; create() emits a DeprecationWarning directing users to OpenAICompletionsConfig or OpenAIResponsesConfig. Construction and copying do not warn, consistent with ADR 0025.

In 1.4.0, the deprecated Chat Completions binding will be removed and OpenAIConfig will become an alias for OpenAIResponsesConfig. This PR records that release change in ADR 0026 and the model configuration guide; it does not switch existing callers to Responses yet. The guide recommends explicit configs during the transition and explains that API-specific options need translation when migrating.

Validation on Python 3.14.3:

• just test --ignore=test/providers -k openai: 410 passed, 28 skipped, 6282 deselected. Includes mocked HTTP requests through Agent.ask() for both public import paths, warning timing and caller location, copy behavior, media acceptance, and existing OpenAI provider tests. Live provider tests were excluded.
• All required commit hooks passed, including repository-wide Ruff lint/format checks, the configured mypy suite, typo/spelling checks, license headers, and secret detection.
• Targeted mypy: no issues in ag2/config/openai/{config,files,__init__}.py and ag2/config/input_acceptance.py.
• Ruff lint and format checks passed for the changed Python files; codespell passed for the new ADR and tests.
• Verified the OpenAICompletionsConfig missing-dependency fallback recommends ag2[openai].
• Parsed all 46 Python examples in the updated model configuration guide. Full documentation build was not run.
• git diff --check passed.

Related issue number

No linked issue.

Checks

• I've included any doc changes needed for https://docs.ag2.ai/. See https://docs.ag2.ai/latest/docs/contributor-guide/documentation/ to build and test documentation locally.
• I've added tests (if relevant) corresponding to the changes introduced in this PR.
• I've made sure all auto checks have passed.

AI assistance

Codex assisted with implementation, tests, documentation, and this description. The diff and description were reviewed against the requested behavior, and the validation above was run before submission.

• I understand the changes in this PR and can explain them in my own words.
• I have verified that the PR description accurately reflects the actual diff.
• If AI assistance was used, I reviewed, tested, and validated the generated code/text before submitting.

[codecov]

Codecov Report

❌ Patch coverage is 93.33333% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
ag2/config/__init__.py	0.00%	1 Missing ⚠️

Files with missing lines	Coverage Δ
ag2/config/input_acceptance.py	96.15% <100.00%> (+0.15%)	⬆️
ag2/config/openai/__init__.py	100.00% <100.00%> (ø)
ag2/config/openai/config.py	99.10% <100.00%> (+0.02%)	⬆️
ag2/config/openai/files.py	100.00% <100.00%> (ø)
ag2/live/cascade.py	83.51% <ø> (ø)
ag2/tools/builtin/image_generation.py	93.18% <ø> (ø)
ag2/config/__init__.py	47.05% <0.00%> (-0.95%)	⬇️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.