microsoft--agent-framework/python/packages/openai/AGENTS.md

AGENTS.md — agent-framework-openai

OpenAI integration package for Agent Framework. Contains OpenAI Responses API and Chat Completions API clients.

Package Structure

agent_framework_openai/
├── __init__.py                 # Public API exports
├── _chat_client.py             # OpenAIChatClient (Responses API) + RawOpenAIChatClient
├── _chat_completion_client.py  # OpenAIChatCompletionClient (Chat Completions API) + RawOpenAIChatCompletionClient
├── _embedding_client.py        # OpenAIEmbeddingClient
├── _exceptions.py              # OpenAI-specific exceptions
└── _shared.py                  # OpenAISettings and shared config helpers

Key Classes

Class	API	Status
OpenAIChatClient	Responses API	Primary
OpenAIChatCompletionClient	Chat Completions API	Primary
OpenAIEmbeddingClient	Embeddings API	Primary

All clients follow the Raw + Full-Featured pattern (e.g., RawOpenAIChatClient + OpenAIChatClient).

For Responses API continuation with service-side storage, a prior hosted function_approval_request is server-issued and must not be replayed inline, while the new hosted function_approval_response is serialized as mcp_approval_response so the user's approved or rejected decision reaches the service. Local FunctionTool approval controls are resolved in-process and must not be serialized as MCP items. An approval is hosted when its function call carries a server_label in function_call.additional_properties; approvals without that metadata are local. Applications that manually replay message history must not send that same hosted approval response again on later turns.

The generic OpenAI clients support both OpenAI and Azure OpenAI routing. Precedence is: explicit Azure inputs (credential, azure_endpoint, api_version) → OpenAI API key (OPENAI_API_KEY) → Azure environment fallback (AZURE_OPENAI_*).

Adapting the Chat Completions client to OpenAI-compatible endpoints

OpenAIChatCompletionClient targets the OpenAI Chat Completions wire format and is intentionally kept free of provider-specific quirks. Many "OpenAI-compatible" providers (OpenRouter, vLLM, Mistral, DeepSeek, Ollama, …) diverge on the edges — e.g. returning reasoning under reasoning / reasoning_content / reasoning_details, or content as a list of chunks. Rather than branching in core, the client exposes two optional callables so callers adapt it themselves:

• response_parser: OpenAIChatResponseContentsParser — (message_or_delta, default_contents) -> contents. Post-processes the Content items parsed from each response choice. Receives the already-selected ChatCompletionMessage (non-streaming) or ChoiceDelta (streaming) — the client resolves the dispatch — so a parser reads provider fields directly (e.g. getattr(msg, "reasoning", None)) without branching. Use it to surface non-standard fields for display. Applied per choice in both paths.
• message_preparer: OpenAIChatMessagePreparer — (message, default_dicts) -> dicts. Post-processes the outgoing request message dicts built from each framework Message (called once per Message, for every role including system/developer). Use it to echo provider-specific fields (e.g. vLLM reasoning) back on later turns for multi-turn continuity. To correlate a surfaced-reasoning Content with the dict the default serializer emitted for it, tag the Content via additional_properties in the parser and match against message.contents rather than raw request-string matching.

Both default to None (no-op → byte-identical stock OpenAI behavior) and are constructor args on RawOpenAIChatCompletionClient / OpenAIChatCompletionClient. Provider round-trips generally need both: the parser surfaces the field for display, the preparer sends it back. Prefer a dedicated client (e.g. agent-framework-mistral) when an endpoint diverges substantially.

Dependencies

• agent-framework-core — core abstractions
• openai — OpenAI Python SDK