Giles Odigwe
b2a2fcbd87
* Python: Fix reasoning content parsing in OpenAIChatCompletionClient Fix two issues with reasoning content handling in the Chat Completions client: 1. (#6979) reasoning_details plaintext buried as encrypted data: The client dumped the entire reasoning_details array into Content.protected_data without setting Content.text, causing AG-UI to emit ReasoningEncryptedValueEvent instead of visible ReasoningMessageContentEvent for plaintext reasoning providers (e.g. OpenRouter). Now extracts readable text from reasoning_details entries into Content.text while preserving protected_data for round-trip fidelity. 2. (#6978) Mistral list content causes crash: Mistral reasoning models return content as a list of typed chunks ([{"type": "thinking", ...}, {"type": "text", ...}]) instead of a plain string. _parse_text_from_openai assumed content was always a string, causing a Pydantic ValidationError downstream. Now detects list content and parses thinking chunks as Content.from_text_reasoning and text chunks as Content.from_text. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix pyright strict-mode type errors and handle content-as-string shape - Use cast() for proper type narrowing in _extract_reasoning_text and _parse_chunked_content to satisfy pyright strict mode - Handle {"content": "..."} string shape in _extract_reasoning_text (addresses review comment about missing format coverage) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix mypy errors: cast list content to Any in tests model_construct bypasses Pydantic runtime validation but mypy still checks declared types. Use cast(Any, ...) for the list content args. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review comments: summary field, reasoning field, and round-trip - Add 'summary' field extraction in _extract_reasoning_text for reasoning.summary entries from OpenRouter - Handle message.reasoning and message.reasoning_content top-level fields (plaintext reasoning without reasoning_details) in both streaming and non-streaming paths - reasoning_details takes priority when both fields are present - Preserve original Mistral chunk list in additional_properties ('_source_content_list') so _prepare_message_for_openai can reconstruct the structured list content for multi-turn reasoning - Add 5 new tests covering all new behaviors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix ruff used-dummy-variable: rename _skip_structured_siblings Remove leading underscore from _skip_structured_siblings variable since it is accessed (not a dummy variable). Ruff's used-dummy-variable rule flags variables with leading underscores that are read. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix missing newline at end of test file Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review: type-agnostic chunk round-trip and reasoning field echo-back - Honor the _source_content_list marker regardless of the first emitted content's type by handling it before the type match, so a chunk list beginning with a text chunk still round-trips as one structured message (addresses github-actions review comment on results[0]). - Tag every chunked-content item with a shared _structured_content_group id and skip only exact group siblings during serialization, instead of suppressing all later text/reasoning content. - Record provenance of top-level reasoning/reasoning_content fields in _reasoning_source_field and echo the value back under the same key on the next request, which providers such as vLLM require (addresses Kimahriman review comment). Replaces the prior behavior that replayed surfaced reasoning as visible answer text. - Factor the duplicated reasoning parsing into _parse_reasoning_content. - Add tests for provenance capture, reasoning/reasoning_content round-trip, reasoning-only messages, text-first chunk round-trip, and unrelated sibling preservation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Replace provider-specific reasoning logic with configurable parse/prepare hooks Following review feedback (#7028), keep OpenAIChatCompletionClient free of provider-specific quirks for 'almost OpenAI-compatible' endpoints. Instead of branching in core for OpenRouter/vLLM/Mistral, expose two optional callables so callers adapt the client themselves: - response_parser (OpenAIChatResponseContentsParser): post-processes the Content list parsed from each response choice/streaming delta, to surface non-standard fields (e.g. reasoning/reasoning_content/reasoning_details) for display. - message_preparer (OpenAIChatMessagePreparer): post-processes the outgoing request message dicts built from each framework Message, to echo provider-specific fields back on later turns (e.g. vLLM reasoning) for multi-turn continuity. Both default to None (no-op; byte-identical stock OpenAI behavior). This reverts the provider-specific reasoning/chunked-content parsing and round-trip markers previously added to core; Mistral chunked content is now handled by agent-framework-mistral. - Add the two callables to RawOpenAIChatCompletionClient / OpenAIChatCompletionClient constructors and invoke them at the parse and prepare seams. - Export the type aliases from the package and the core lazy openai namespace (+ .pyi). - Replace the removed-behavior tests with tests for the two hooks. - Document the hooks in packages/openai/AGENTS.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Skip non-string content in default text parsing Structured list content (e.g. Mistral reasoning models returning content as a list of chunks) was wrapped verbatim into a text Content, producing a malformed Content whose text is a list that crashes downstream (issue #6978). Default text parsing now skips non-string content so a configured response_parser receives a clean slate to expand it. Applies to both streaming and non-streaming paths. Add tests for the skip and for a response_parser expanding chunked content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 * Address review: hook signature, per-role preparer, robust round-trip - response_parser now receives the already-selected ChatCompletionMessage / ChoiceDelta instead of Choice | ChunkChoice, so callers no longer duplicate the streaming dispatch (removes the Any/hasattr pattern from tests). The client owns the dispatch; parsers read provider fields directly. - message_preparer now runs once per Message for every role: the build logic moved to _build_openai_messages and the hook is applied at a single exit point in _prepare_message_for_openai, so system/developer messages no longer bypass it. - Round-trip example/test now correlates surfaced reasoning via an additional_properties marker on message.contents with bounded, order-aware, one-to-one dict removal, instead of fragile request-string matching. Adds a test proving an answer whose text equals the reasoning text is no longer dropped. - Update packages/openai/AGENTS.md for the new parser signature and guidance. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5 --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
agent-framework-openai
OpenAI integration for Microsoft Agent Framework.
This package provides:
OpenAIChatClientfor the OpenAI Responses APIOpenAIChatCompletionClientfor the Chat Completions APIOpenAIEmbeddingClientfor embeddings
Installation
pip install agent-framework-openai
Which chat client should I use?
Use OpenAIChatClient for new work unless you specifically need the Chat Completions API.
OpenAIChatClientuses the Responses API and is the preferred general-purpose chat client.OpenAIChatCompletionClientuses the Chat Completions API and is mainly for compatibility with existing Chat Completions-based integrations.
The previous deprecated Responses alias has been removed. Use OpenAIChatClient directly.
Environment variables
OpenAI
These variables are used when the client is configured for OpenAI:
| Variable | Purpose |
|---|---|
OPENAI_API_KEY |
OpenAI API key |
OPENAI_ORG_ID |
OpenAI organization ID |
OPENAI_BASE_URL |
Custom OpenAI-compatible base URL |
OPENAI_MODEL |
Generic fallback model |
OPENAI_CHAT_MODEL |
Preferred model for OpenAIChatClient |
OPENAI_CHAT_COMPLETION_MODEL |
Preferred model for OpenAIChatCompletionClient |
OPENAI_EMBEDDING_MODEL |
Preferred model for OpenAIEmbeddingClient |
Model lookup order:
OpenAIChatClient:OPENAI_CHAT_MODEL->OPENAI_MODELOpenAIChatCompletionClient:OPENAI_CHAT_COMPLETION_MODEL->OPENAI_MODELOpenAIEmbeddingClient:OPENAI_EMBEDDING_MODEL->OPENAI_MODEL
These model variables are only consulted when you do not pass model= directly. In other words,
OpenAIChatClient(model="...") ignores OPENAI_CHAT_MODEL, and
OpenAIChatCompletionClient(model="...") ignores OPENAI_CHAT_COMPLETION_MODEL.
Azure OpenAI
These variables are used when the client is configured for Azure OpenAI:
| Variable | Purpose |
|---|---|
AZURE_OPENAI_ENDPOINT |
Azure OpenAI resource endpoint |
AZURE_OPENAI_BASE_URL |
Full Azure OpenAI base URL (.../openai/v1) |
AZURE_OPENAI_API_KEY |
Azure OpenAI API key |
AZURE_OPENAI_API_VERSION |
Azure OpenAI API version |
AZURE_OPENAI_MODEL |
Generic fallback deployment |
AZURE_OPENAI_CHAT_MODEL |
Preferred deployment for OpenAIChatClient |
AZURE_OPENAI_CHAT_COMPLETION_MODEL |
Preferred deployment for OpenAIChatCompletionClient |
AZURE_OPENAI_EMBEDDING_MODEL |
Preferred deployment for OpenAIEmbeddingClient |
Deployment lookup order:
OpenAIChatClient:AZURE_OPENAI_CHAT_MODEL->AZURE_OPENAI_MODELOpenAIChatCompletionClient:AZURE_OPENAI_CHAT_COMPLETION_MODEL->AZURE_OPENAI_MODELOpenAIEmbeddingClient:AZURE_OPENAI_EMBEDDING_MODEL->AZURE_OPENAI_MODEL
For Azure routing, the same rule applies: the client-specific deployment variable is checked first,
then the generic AZURE_OPENAI_MODEL fallback. Passing model= overrides both environment variables.
When both OpenAI and Azure environment variables are present, the generic clients prefer OpenAI
when OPENAI_API_KEY is configured. To use Azure explicitly, pass azure_endpoint or
credential.
OpenAI example
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(model="gpt-4.1")
Azure OpenAI example
from azure.identity.aio import AzureCliCredential
from agent_framework.openai import OpenAIChatClient
client = OpenAIChatClient(
model="my-responses-deployment",
azure_endpoint="https://my-resource.openai.azure.com",
credential=AzureCliCredential(),
)
ChatClient vs ChatCompletionClient
Use OpenAIChatClient when you want the Responses API as your default chat surface.
Use OpenAIChatCompletionClient when you specifically need the Chat Completions API:
from agent_framework.openai import OpenAIChatCompletionClient
client = OpenAIChatCompletionClient(model="gpt-4o-mini")