chore: import upstream snapshot with attribution

python/packages/openai/AGENTS.md

@@ -0,0 +1,34 @@
+# 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`).
+
+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_*`).
+
+## Dependencies
+
+- `agent-framework-core` — core abstractions
+- `openai` — OpenAI Python SDK

python/packages/openai/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

python/packages/openai/README.md

@@ -0,0 +1,113 @@
+# agent-framework-openai
+
+OpenAI integration for Microsoft Agent Framework.
+
+This package provides:
+
+- `OpenAIChatClient` for the OpenAI Responses API
+- `OpenAIChatCompletionClient` for the Chat Completions API
+- `OpenAIEmbeddingClient` for embeddings
+
+## Installation
+
+```bash
+pip install agent-framework-openai
+```
+
+## Which chat client should I use?
+
+Use `OpenAIChatClient` for new work unless you specifically need the Chat Completions API.
+
+- `OpenAIChatClient` uses the Responses API and is the preferred general-purpose chat client.
+- `OpenAIChatCompletionClient` uses 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_MODEL`
+- `OpenAIChatCompletionClient`: `OPENAI_CHAT_COMPLETION_MODEL` -> `OPENAI_MODEL`
+- `OpenAIEmbeddingClient`: `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_MODEL`
+- `OpenAIChatCompletionClient`: `AZURE_OPENAI_CHAT_COMPLETION_MODEL` -> `AZURE_OPENAI_MODEL`
+- `OpenAIEmbeddingClient`: `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
+
+```python
+from agent_framework.openai import OpenAIChatClient
+
+client = OpenAIChatClient(model="gpt-4.1")
+```
+
+## Azure OpenAI example
+
+```python
+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:
+
+```python
+from agent_framework.openai import OpenAIChatCompletionClient
+
+client = OpenAIChatCompletionClient(model="gpt-4o-mini")
+```

python/packages/openai/agent_framework_openai/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""OpenAI integration for Microsoft Agent Framework.
+
+This package provides OpenAI client implementations for the Agent Framework,
+including clients for the Responses API and Chat Completions API.
+"""
+
+import importlib.metadata
+
+from ._chat_client import (
+    OpenAIChatClient,
+    OpenAIChatOptions,
+    OpenAIContinuationToken,
+    RawOpenAIChatClient,
+)
+from ._chat_completion_client import (
+    OpenAIChatCompletionClient,
+    OpenAIChatCompletionOptions,
+    RawOpenAIChatCompletionClient,
+)
+from ._embedding_client import OpenAIEmbeddingClient, OpenAIEmbeddingOptions
+from ._exceptions import ContentFilterResultSeverity, OpenAIContentFilterException
+from ._shared import OpenAISettings
+
+try:
+    __version__ = importlib.metadata.version("agent-framework-openai")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "ContentFilterResultSeverity",
+    "OpenAIChatClient",
+    "OpenAIChatCompletionClient",
+    "OpenAIChatCompletionOptions",
+    "OpenAIChatOptions",
+    "OpenAIContentFilterException",
+    "OpenAIContinuationToken",
+    "OpenAIEmbeddingClient",
+    "OpenAIEmbeddingOptions",
+    "OpenAISettings",
+    "RawOpenAIChatClient",
+    "RawOpenAIChatCompletionClient",
+    "__version__",
+]

python/packages/openai/agent_framework_openai/_embedding_client.py

@@ -0,0 +1,500 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import base64
+import struct
+import sys
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypedDict, overload
+
+from agent_framework._clients import BaseEmbeddingClient
+from agent_framework._settings import SecretString
+from agent_framework._telemetry import USER_AGENT_KEY
+from agent_framework._types import Embedding, EmbeddingGenerationOptions, GeneratedEmbeddings, UsageDetails
+from agent_framework.observability import EmbeddingTelemetryLayer
+from openai import AsyncAzureOpenAI, AsyncOpenAI
+
+from ._shared import AzureTokenProvider, load_openai_service_settings
+
+if sys.version_info >= (3, 13):
+    from typing import TypeVar  # pragma: no cover
+else:
+    from typing_extensions import TypeVar  # pragma: no cover
+
+if TYPE_CHECKING:
+    from azure.core.credentials import TokenCredential
+    from azure.core.credentials_async import AsyncTokenCredential
+
+    AzureCredentialTypes = TokenCredential | AsyncTokenCredential
+
+
+DEFAULT_AZURE_OPENAI_EMBEDDING_API_VERSION = "2024-10-21"
+
+
+class OpenAIEmbeddingOptions(EmbeddingGenerationOptions, total=False):
+    """OpenAI-specific embedding options.
+
+    Extends EmbeddingGenerationOptions with OpenAI-specific fields.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.openai import OpenAIEmbeddingOptions
+
+            options: OpenAIEmbeddingOptions = {
+                "model": "text-embedding-3-small",
+                "dimensions": 1536,
+                "encoding_format": "float",
+            }
+    """
+
+    encoding_format: Literal["float", "base64"]
+    user: str
+
+
+OpenAIEmbeddingOptionsT = TypeVar(
+    "OpenAIEmbeddingOptionsT",
+    bound=TypedDict,  # type: ignore[valid-type]
+    default="OpenAIEmbeddingOptions",
+    covariant=True,
+)
+
+
+class RawOpenAIEmbeddingClient(
+    BaseEmbeddingClient[str, list[float], OpenAIEmbeddingOptionsT],
+    Generic[OpenAIEmbeddingOptionsT],
+):
+    """Raw OpenAI embedding client without telemetry."""
+
+    INJECTABLE: ClassVar[set[str]] = {"client"}
+
+    @overload
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        api_key: str | SecretString | Callable[[], str | Awaitable[str]] | None = None,
+        org_id: str | None = None,
+        base_url: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncOpenAI | None = None,
+        additional_properties: dict[str, Any] | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize a raw OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding model identifier. When not provided, the constructor reads
+                ``OPENAI_EMBEDDING_MODEL`` and then ``OPENAI_MODEL``.
+            api_key: API key. When not provided explicitly, the constructor reads
+                ``OPENAI_API_KEY``. A callable API key is also supported.
+            org_id: OpenAI organization ID. When not provided explicitly, the constructor reads
+                ``OPENAI_ORG_ID``.
+            base_url: Base URL override. When not provided explicitly, the constructor reads
+                ``OPENAI_BASE_URL``.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured OpenAI client.
+            additional_properties: Additional properties stored on the client instance.
+            env_file_path: Optional ``.env`` file that is checked before the process environment
+                for ``OPENAI_*`` values.
+            env_file_encoding: Encoding for the ``.env`` file.
+        """
+        ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        azure_endpoint: str | None = None,
+        credential: AzureCredentialTypes | AzureTokenProvider | None = None,
+        api_version: str | None = None,
+        api_key: str | SecretString | Callable[[], str | Awaitable[str]] | None = None,
+        base_url: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncAzureOpenAI | AsyncOpenAI | None = None,
+        additional_properties: dict[str, Any] | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize a raw OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding deployment name. When not provided, the constructor reads
+                ``AZURE_OPENAI_EMBEDDING_MODEL`` and then
+                ``AZURE_OPENAI_MODEL``.
+            azure_endpoint: Azure resource endpoint. When not provided explicitly, the constructor
+                reads ``AZURE_OPENAI_ENDPOINT``.
+            credential: Azure credential or token provider for Entra auth.
+            api_version: Azure API version. When not provided explicitly, the constructor reads
+                ``AZURE_OPENAI_API_VERSION`` and then uses the embedding default.
+            api_key: API key. For Azure this can be used instead of ``AZURE_OPENAI_API_KEY`` for key
+                auth. A callable token provider is also accepted, but ``credential`` is the preferred
+                Azure auth surface.
+            base_url: Base URL override. When not provided explicitly, the constructor reads
+                ``AZURE_OPENAI_BASE_URL``. Use this instead of ``azure_endpoint`` when you want
+                to pass the full ``.../openai/v1`` base URL directly.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured client. Passing ``AsyncAzureOpenAI`` keeps the client on
+                Azure; passing ``AsyncOpenAI`` keeps the client on OpenAI.
+            additional_properties: Additional properties stored on the client instance.
+            env_file_path: Optional ``.env`` file that is checked before process environment
+                variables for ``AZURE_OPENAI_*`` values.
+            env_file_encoding: Encoding for the ``.env`` file.
+        """
+        ...
+
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        api_key: str | SecretString | Callable[[], str | Awaitable[str]] | None = None,
+        credential: AzureCredentialTypes | AzureTokenProvider | None = None,
+        org_id: str | None = None,
+        base_url: str | None = None,
+        azure_endpoint: str | None = None,
+        api_version: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncAzureOpenAI | AsyncOpenAI | None = None,
+        additional_properties: dict[str, Any] | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize a raw OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding model or Azure OpenAI deployment name. When not provided, the
+                constructor reads ``OPENAI_EMBEDDING_MODEL`` and then ``OPENAI_MODEL``
+                for OpenAI. For Azure it first checks ``AZURE_OPENAI_EMBEDDING_MODEL``
+                and then ``AZURE_OPENAI_MODEL``.
+            api_key: API key override. For OpenAI this maps to ``OPENAI_API_KEY``.
+                For Azure this can be used instead of ``AZURE_OPENAI_API_KEY`` for key auth.
+                A callable token provider is also accepted for backwards compatibility,
+                but ``credential`` is the preferred Azure auth surface.
+            credential: Azure credential or token provider for Azure OpenAI auth. Passing this
+                is an explicit Azure signal, even when ``OPENAI_API_KEY`` is also configured.
+                Credential objects require the optional ``azure-identity`` package.
+            org_id: OpenAI organization ID. Used only for OpenAI and resolved from
+                ``OPENAI_ORG_ID`` when not provided.
+            base_url: Base URL override. For OpenAI this maps to ``OPENAI_BASE_URL``.
+                For Azure this may be used instead of ``azure_endpoint`` when you want
+                to pass the full ``.../openai/v1`` base URL directly.
+            azure_endpoint: Azure resource endpoint. When not provided explicitly, Azure
+                falls back to ``AZURE_OPENAI_ENDPOINT``.
+            api_version: Azure API version to use for Azure requests. When not provided explicitly,
+                Azure falls back to
+                ``AZURE_OPENAI_API_VERSION`` and then the embedding default.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured client. Passing ``AsyncAzureOpenAI`` keeps the client on
+                Azure; passing ``AsyncOpenAI`` keeps the client on OpenAI.
+            additional_properties: Additional properties stored on the client instance.
+            env_file_path: Optional ``.env`` file that is checked before process environment
+                variables. The same file is used for both ``OPENAI_*`` and ``AZURE_OPENAI_*``
+                lookups.
+            env_file_encoding: Encoding for the ``.env`` file.
+
+        Notes:
+            Environment resolution precedence is:
+
+            1. Explicit Azure inputs (``azure_endpoint`` or ``credential``)
+            2. Explicit OpenAI API key or ``OPENAI_API_KEY``
+            3. Azure environment fallback
+
+            OpenAI reads ``OPENAI_API_KEY``, ``OPENAI_EMBEDDING_MODEL``,
+            ``OPENAI_MODEL``, ``OPENAI_ORG_ID``, and ``OPENAI_BASE_URL``. Azure reads
+            ``AZURE_OPENAI_ENDPOINT``, ``AZURE_OPENAI_BASE_URL``,
+            ``AZURE_OPENAI_API_KEY``, ``AZURE_OPENAI_EMBEDDING_MODEL``,
+            ``AZURE_OPENAI_MODEL``, and ``AZURE_OPENAI_API_VERSION``.
+        """
+        settings, client, use_azure_client = load_openai_service_settings(
+            model=model,
+            api_key=api_key,
+            credential=credential,
+            org_id=org_id,
+            base_url=base_url,
+            endpoint=azure_endpoint,
+            api_version=api_version,
+            default_azure_api_version=DEFAULT_AZURE_OPENAI_EMBEDDING_API_VERSION,
+            default_headers=default_headers,
+            client=async_client,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+            openai_model_fields=("embedding_model", "model"),
+            azure_model_fields=("embedding_model", "model"),
+        )
+
+        self.client = client
+        resolved_model = settings.get("model")
+        self.model: str | None = resolved_model.strip() if isinstance(resolved_model, str) and resolved_model else None
+
+        # Store configuration for serialization
+        self.org_id = settings.get("org_id")
+        self.base_url = settings.get("base_url")
+        self.azure_endpoint = settings.get("endpoint")
+        self.api_version = settings.get("api_version")
+        if default_headers:
+            self.default_headers: dict[str, Any] | None = {
+                k: v for k, v in default_headers.items() if k != USER_AGENT_KEY
+            }
+        else:
+            self.default_headers = None
+        if use_azure_client:
+            self.OTEL_PROVIDER_NAME = "azure.ai.openai"  # type: ignore[misc]
+
+        super().__init__(additional_properties=additional_properties)
+
+    def service_url(self) -> str:
+        """Get the URL of the service."""
+        return str(self.client.base_url) if self.client else "Unknown"
+
+    async def get_embeddings(
+        self,
+        values: Sequence[str],
+        *,
+        options: OpenAIEmbeddingOptionsT | None = None,
+    ) -> GeneratedEmbeddings[list[float], OpenAIEmbeddingOptionsT]:
+        """Call the OpenAI embeddings API.
+
+        Args:
+            values: The text values to generate embeddings for.
+            options: Optional embedding generation options.
+
+        Returns:
+            Generated embeddings with usage metadata.
+
+        Raises:
+            ValueError: If model is not provided or values is empty.
+        """
+        if not values:
+            return GeneratedEmbeddings([], options=options)
+
+        opts: dict[str, Any] = options or {}  # type: ignore
+        model = opts.get("model") or self.model
+        if not model:
+            raise ValueError("model is required")
+
+        kwargs: dict[str, Any] = {"input": list(values), "model": model}
+        if dimensions := opts.get("dimensions"):
+            kwargs["dimensions"] = dimensions
+        if encoding_format := opts.get("encoding_format"):
+            kwargs["encoding_format"] = encoding_format
+        if user := opts.get("user"):
+            kwargs["user"] = user
+
+        response = await self.client.embeddings.create(**kwargs)
+
+        encoding = kwargs.get("encoding_format", "float")
+        embeddings: list[Embedding[list[float]]] = []
+        for item in response.data:
+            vector: list[float]
+            if encoding == "base64" and isinstance(item.embedding, str):
+                # Decode base64-encoded floats (little-endian IEEE 754)
+                raw = base64.b64decode(item.embedding)
+                vector = list(struct.unpack(f"<{len(raw) // 4}f", raw))
+            else:
+                vector = item.embedding
+            embeddings.append(
+                Embedding(
+                    vector=vector,
+                    dimensions=len(vector),
+                    model=response.model,
+                )
+            )
+
+        usage_dict: UsageDetails | None = None
+        if response.usage:
+            usage_dict = {
+                "input_token_count": response.usage.prompt_tokens,
+                "total_token_count": response.usage.total_tokens,
+            }
+
+        return GeneratedEmbeddings(embeddings, options=options, usage=usage_dict)
+
+
+class OpenAIEmbeddingClient(
+    EmbeddingTelemetryLayer[str, list[float], OpenAIEmbeddingOptionsT],
+    RawOpenAIEmbeddingClient[OpenAIEmbeddingOptionsT],
+    Generic[OpenAIEmbeddingOptionsT],
+):
+    """OpenAI embedding client with telemetry support."""
+
+    OTEL_PROVIDER_NAME: ClassVar[str] = "openai"
+
+    @overload
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        api_key: str | Callable[[], str | Awaitable[str]] | None = None,
+        org_id: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncOpenAI | None = None,
+        base_url: str | None = None,
+        otel_provider_name: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize an OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding model identifier. When not provided, the constructor reads
+                ``OPENAI_EMBEDDING_MODEL`` and then ``OPENAI_MODEL``.
+            api_key: API key. When not provided explicitly, the constructor reads
+                ``OPENAI_API_KEY``. A callable API key is also supported.
+            org_id: OpenAI organization ID. When not provided explicitly, the constructor reads
+                ``OPENAI_ORG_ID``.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured OpenAI client.
+            base_url: Base URL override. When not provided explicitly, the constructor reads
+                ``OPENAI_BASE_URL``.
+            otel_provider_name: Optional telemetry provider name override.
+            env_file_path: Optional ``.env`` file that is checked before the process environment
+                for ``OPENAI_*`` values.
+            env_file_encoding: Encoding for the ``.env`` file.
+        """
+        ...
+
+    @overload
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        azure_endpoint: str | None = None,
+        credential: AzureCredentialTypes | AzureTokenProvider | None = None,
+        api_version: str | None = None,
+        api_key: str | Callable[[], str | Awaitable[str]] | None = None,
+        base_url: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncAzureOpenAI | AsyncOpenAI | None = None,
+        otel_provider_name: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize an OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding deployment name. When not provided, the constructor reads
+                ``AZURE_OPENAI_EMBEDDING_MODEL`` and then
+                ``AZURE_OPENAI_MODEL``.
+            azure_endpoint: Azure resource endpoint. When not provided explicitly, the constructor
+                reads ``AZURE_OPENAI_ENDPOINT``.
+            credential: Azure credential or token provider for Entra auth.
+            api_version: Azure API version. When not provided explicitly, the constructor reads
+                ``AZURE_OPENAI_API_VERSION`` and then uses the embedding default.
+            api_key: API key. For Azure this can be used instead of ``AZURE_OPENAI_API_KEY`` for key
+                auth. A callable token provider is also accepted, but ``credential`` is the preferred
+                Azure auth surface.
+            base_url: Base URL override. When not provided explicitly, the constructor reads
+                ``AZURE_OPENAI_BASE_URL``. Use this instead of ``azure_endpoint`` when you want
+                to pass the full ``.../openai/v1`` base URL directly.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured client. Passing ``AsyncAzureOpenAI`` keeps the client on
+                Azure; passing ``AsyncOpenAI`` keeps the client on OpenAI.
+            otel_provider_name: Optional telemetry provider name override.
+            env_file_path: Optional ``.env`` file that is checked before process environment
+                variables for ``AZURE_OPENAI_*`` values.
+            env_file_encoding: Encoding for the ``.env`` file.
+        """
+        ...
+
+    def __init__(
+        self,
+        *,
+        model: str | None = None,
+        api_key: str | Callable[[], str | Awaitable[str]] | None = None,
+        credential: AzureCredentialTypes | AzureTokenProvider | None = None,
+        org_id: str | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        async_client: AsyncAzureOpenAI | AsyncOpenAI | None = None,
+        base_url: str | None = None,
+        azure_endpoint: str | None = None,
+        api_version: str | None = None,
+        otel_provider_name: str | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize an OpenAI embedding client.
+
+        Keyword Args:
+            model: Embedding model or Azure OpenAI deployment name. When not provided, the
+                constructor reads ``OPENAI_EMBEDDING_MODEL`` and then ``OPENAI_MODEL``
+                for OpenAI. For Azure it first checks ``AZURE_OPENAI_EMBEDDING_MODEL``
+                and then ``AZURE_OPENAI_MODEL``.
+            api_key: API key override. For OpenAI this maps to ``OPENAI_API_KEY``.
+                For Azure this can be used instead of ``AZURE_OPENAI_API_KEY`` for key auth.
+                A callable token provider is also accepted for backwards compatibility,
+                but ``credential`` is the preferred Azure auth surface.
+            credential: Azure credential or token provider for Azure OpenAI auth. Passing this
+                is an explicit Azure signal, even when ``OPENAI_API_KEY`` is also configured.
+                Credential objects require the optional ``azure-identity`` package.
+            org_id: OpenAI organization ID. Used only for OpenAI and resolved from
+                ``OPENAI_ORG_ID`` when not provided.
+            default_headers: Additional HTTP headers.
+            async_client: Pre-configured client. Passing ``AsyncAzureOpenAI`` keeps the client on
+                Azure; passing ``AsyncOpenAI`` keeps the client on OpenAI.
+            base_url: Base URL override. For OpenAI this maps to ``OPENAI_BASE_URL``.
+                For Azure this may be used instead of ``azure_endpoint`` when you want
+                to pass the full ``.../openai/v1`` base URL directly.
+            azure_endpoint: Azure resource endpoint. When not provided explicitly, Azure
+                falls back to ``AZURE_OPENAI_ENDPOINT``.
+            api_version: Azure API version to use for Azure requests. When not provided explicitly,
+                Azure falls back to
+                ``AZURE_OPENAI_API_VERSION`` and then the embedding default.
+            otel_provider_name: Override the OpenTelemetry provider name.
+            env_file_path: Optional ``.env`` file that is checked before process environment
+                variables. The same file is used for both ``OPENAI_*`` and ``AZURE_OPENAI_*``
+                lookups.
+            env_file_encoding: Encoding for the ``.env`` file.
+
+        Notes:
+            Environment resolution precedence is:
+
+            1. Explicit Azure inputs (``azure_endpoint`` or ``credential``)
+            2. Explicit OpenAI API key or ``OPENAI_API_KEY``
+            3. Azure environment fallback
+
+            OpenAI reads ``OPENAI_API_KEY``, ``OPENAI_EMBEDDING_MODEL``,
+            ``OPENAI_MODEL``, ``OPENAI_ORG_ID``, and ``OPENAI_BASE_URL``. Azure reads
+            ``AZURE_OPENAI_ENDPOINT``, ``AZURE_OPENAI_BASE_URL``,
+            ``AZURE_OPENAI_API_KEY``, ``AZURE_OPENAI_EMBEDDING_MODEL``,
+            ``AZURE_OPENAI_MODEL``, and ``AZURE_OPENAI_API_VERSION``.
+
+        Examples:
+            .. code-block:: python
+
+                from agent_framework.openai import OpenAIEmbeddingClient
+
+                # Using environment variables
+                # Set OPENAI_API_KEY=sk-...
+                # Set OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+                client = OpenAIEmbeddingClient()
+
+                # Or passing OpenAI parameters directly
+                client = OpenAIEmbeddingClient(
+                    model="text-embedding-3-small",
+                    api_key="sk-...",
+                )
+
+                # Or using Azure OpenAI with an Azure credential
+                client = OpenAIEmbeddingClient(
+                    model="text-embedding-3-small",
+                    azure_endpoint="https://example-resource.openai.azure.com/",
+                    credential=my_azure_credential,
+                )
+        """
+        super().__init__(
+            model=model,
+            api_key=api_key,
+            credential=credential,
+            org_id=org_id,
+            base_url=base_url,
+            azure_endpoint=azure_endpoint,
+            api_version=api_version,
+            default_headers=default_headers,
+            async_client=async_client,
+            otel_provider_name=otel_provider_name,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )

python/packages/openai/agent_framework_openai/_exceptions.py

@@ -0,0 +1,90 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from agent_framework.exceptions import ChatClientContentFilterException
+from openai import BadRequestError
+
+
+class ContentFilterResultSeverity(Enum):
+    """The severity of the content filter result."""
+
+    HIGH = "high"
+    MEDIUM = "medium"
+    SAFE = "safe"
+    LOW = "low"
+
+
+@dataclass
+class ContentFilterResult:
+    """The result of a content filter check."""
+
+    filtered: bool = False
+    detected: bool = False
+    severity: ContentFilterResultSeverity = ContentFilterResultSeverity.SAFE
+
+    @classmethod
+    def from_inner_error_result(cls, inner_error_results: dict[str, Any]) -> ContentFilterResult:
+        """Creates a ContentFilterResult from the inner error results.
+
+        Args:
+            inner_error_results: The inner error results.
+
+        Returns:
+            ContentFilterResult: The ContentFilterResult.
+        """
+        return cls(
+            filtered=inner_error_results.get("filtered", False),
+            detected=inner_error_results.get("detected", False),
+            severity=ContentFilterResultSeverity(
+                inner_error_results.get("severity", ContentFilterResultSeverity.SAFE.value)
+            ),
+        )
+
+
+class ContentFilterCodes(Enum):
+    """Content filter codes."""
+
+    RESPONSIBLE_AI_POLICY_VIOLATION = "ResponsibleAIPolicyViolation"
+
+
+@dataclass
+class OpenAIContentFilterException(ChatClientContentFilterException):
+    """AI exception for an error from Azure OpenAI's content filter."""
+
+    # The parameter that caused the error.
+    param: str | None
+
+    # The error code specific to the content filter.
+    content_filter_code: ContentFilterCodes
+
+    # The results of the different content filter checks.
+    content_filter_result: dict[str, ContentFilterResult]
+
+    def __init__(
+        self,
+        message: str,
+        inner_exception: BadRequestError,
+    ) -> None:
+        """Initializes a new instance of the ContentFilterAIException class.
+
+        Args:
+            message: The error message.
+            inner_exception: The inner exception.
+        """
+        super().__init__(message)
+
+        self.param = inner_exception.param
+        if inner_exception.body is not None and isinstance(inner_exception.body, dict):
+            inner_error = inner_exception.body.get("innererror", {})  # type: ignore
+            self.content_filter_code = ContentFilterCodes(
+                inner_error.get("code", ContentFilterCodes.RESPONSIBLE_AI_POLICY_VIOLATION.value)  # type: ignore
+            )
+            self.content_filter_result = {
+                key: ContentFilterResult.from_inner_error_result(values)  # type: ignore
+                for key, values in inner_error.get("content_filter_result", {}).items()  # type: ignore
+            }

python/packages/openai/agent_framework_openai/_shared.py

@@ -0,0 +1,386 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from copy import copy
+from typing import TYPE_CHECKING, Any, Literal, Union
+
+from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import APP_INFO, prepend_agent_framework_to_user_agent
+from agent_framework.exceptions import SettingNotFoundError
+from openai import AsyncAzureOpenAI, AsyncOpenAI, AsyncStream, _legacy_response  # type: ignore
+from openai.types import Completion
+from openai.types.audio import Transcription
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+from openai.types.images_response import ImagesResponse
+from openai.types.responses.response import Response
+from openai.types.responses.response_stream_event import ResponseStreamEvent
+
+if sys.version_info >= (3, 11):
+    from typing import TypedDict  # pragma: no cover
+else:
+    from typing_extensions import TypedDict  # pragma: no cover
+
+if TYPE_CHECKING:
+    from azure.core.credentials import TokenCredential
+    from azure.core.credentials_async import AsyncTokenCredential
+
+    AzureCredentialTypes = TokenCredential | AsyncTokenCredential
+
+
+AZURE_OPENAI_TOKEN_SCOPE = "https://cognitiveservices.azure.com/.default"  # noqa: S105 # nosec B105
+
+
+RESPONSE_TYPE = Union[
+    ChatCompletion,
+    Completion,
+    AsyncStream[ChatCompletionChunk],
+    AsyncStream[Completion],
+    list[Any],
+    ImagesResponse,
+    Response,
+    AsyncStream[ResponseStreamEvent],
+    Transcription,
+    _legacy_response.HttpxBinaryResponseContent,
+]
+
+AzureTokenProvider = Callable[[], str | Awaitable[str]]
+
+
+class OpenAISettings(TypedDict, total=False):
+    """OpenAI environment settings.
+
+    Settings are resolved in this order: explicit keyword arguments, values from an
+    explicitly provided .env file, then environment variables with the prefix
+    'OPENAI_'. If settings are missing after resolution, validation will fail.
+
+    Keyword Args:
+        api_key: OpenAI API key, see https://platform.openai.com/account/api-keys.
+            Can be set via environment variable OPENAI_API_KEY.
+        base_url: The base URL for the OpenAI API.
+            Can be set via environment variable OPENAI_BASE_URL.
+        org_id: This is usually optional unless your account belongs to multiple organizations.
+            Can be set via environment variable OPENAI_ORG_ID.
+        model: The OpenAI model to use, for example, gpt-4o or o1.
+            Can be set via environment variable OPENAI_MODEL.
+        embedding_model: The OpenAI embedding model to use, for example, text-embedding-3-small.
+            Can be set via environment variable OPENAI_EMBEDDING_MODEL.
+        chat_model: The OpenAIChatClient model to prefer before OPENAI_MODEL.
+            Can be set via environment variable OPENAI_CHAT_MODEL.
+        chat_completion_model: The OpenAIChatCompletionClient model to prefer before OPENAI_MODEL.
+            Can be set via environment variable OPENAI_CHAT_COMPLETION_MODEL.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework.openai import OpenAISettings
+
+            # Using environment variables
+            # Set OPENAI_API_KEY=sk-...
+            # Set OPENAI_MODEL=gpt-4o
+            settings = load_settings(OpenAISettings, env_prefix="OPENAI_")
+
+            # Or passing parameters directly
+            settings = load_settings(OpenAISettings, env_prefix="OPENAI_", api_key="sk-...", model="gpt-4o")
+
+            # Or loading from a .env file
+            settings = load_settings(OpenAISettings, env_prefix="OPENAI_", env_file_path="path/to/.env")
+    """
+
+    api_key: SecretString | None
+    base_url: str | None
+    org_id: str | None
+    model: str | None
+    embedding_model: str | None
+    chat_model: str | None
+    chat_completion_model: str | None
+
+
+class AzureOpenAISettings(TypedDict, total=False):
+    """Azure OpenAI environment settings."""
+
+    endpoint: str | None
+    base_url: str | None
+    api_key: SecretString | None
+    model: str | None
+    embedding_model: str | None
+    chat_model: str | None
+    chat_completion_model: str | None
+    api_version: str | None
+
+
+OpenAIModelSettingName = Literal["model", "embedding_model", "chat_model", "chat_completion_model"]
+
+OPENAI_MODEL_ENV_VARS: dict[OpenAIModelSettingName, str] = {
+    "model": "OPENAI_MODEL",
+    "embedding_model": "OPENAI_EMBEDDING_MODEL",
+    "chat_model": "OPENAI_CHAT_MODEL",
+    "chat_completion_model": "OPENAI_CHAT_COMPLETION_MODEL",
+}
+
+AZURE_MODEL_ENV_VARS: dict[OpenAIModelSettingName, str] = {
+    "model": "AZURE_OPENAI_MODEL",
+    "embedding_model": "AZURE_OPENAI_EMBEDDING_MODEL",
+    "chat_model": "AZURE_OPENAI_CHAT_MODEL",
+    "chat_completion_model": "AZURE_OPENAI_CHAT_COMPLETION_MODEL",
+}
+
+
+def _resolve_named_setting(
+    settings: Mapping[str, Any],
+    fields: Sequence[OpenAIModelSettingName],
+) -> str | None:
+    """Return the first populated value from ``fields``."""
+    for field in fields:
+        value = settings.get(field)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _join_env_names(env_names: Sequence[str]) -> str:
+    """Format env var names for user-facing error messages."""
+    return ", ".join(f"'{env_name}'" for env_name in env_names)
+
+
+def load_openai_service_settings(
+    *,
+    model: str | None,
+    api_key: str | SecretString | Callable[[], str | Awaitable[str]] | None,
+    credential: AzureCredentialTypes | AzureTokenProvider | None,
+    org_id: str | None,
+    base_url: str | None,
+    endpoint: str | None,
+    api_version: str | None,
+    default_azure_api_version: str,
+    default_headers: Mapping[str, str] | None = None,
+    client: AsyncOpenAI | None = None,
+    env_file_path: str | None,
+    env_file_encoding: str | None,
+    openai_model_fields: Sequence[OpenAIModelSettingName] = ("model",),
+    azure_model_fields: Sequence[OpenAIModelSettingName] = ("model",),
+    responses_mode: bool = False,
+    timeout: float | None = None,
+) -> tuple[dict[str, Any], AsyncOpenAI, bool]:
+    """Load OpenAI settings, including Azure OpenAI model aliases.
+
+    The generic OpenAI clients primarily read from ``OPENAI_*`` variables. Azure-specific
+    environment variables are used only when an explicit Azure signal is present
+    (``endpoint`` or ``credential``) or when no explicit
+    OpenAI API key is available.
+    """
+    # Merge APP_INFO into the headers
+    merged_headers = dict(copy(default_headers)) if default_headers else {}
+    if APP_INFO:
+        merged_headers.update(APP_INFO)
+        merged_headers = prepend_agent_framework_to_user_agent(merged_headers)
+
+    api_key_callable = api_key if callable(api_key) else None
+    api_key_str = api_key if not callable(api_key) else None
+    azure_client = isinstance(client, AsyncAzureOpenAI)
+    use_azure = azure_client or endpoint is not None or credential is not None
+    checked_openai = False
+    if not use_azure:
+        openai_settings_kwargs: dict[str, Any] = {
+            "api_key": api_key_str,
+            "org_id": org_id,
+            "base_url": base_url,
+            "env_file_path": env_file_path,
+            "env_file_encoding": env_file_encoding,
+        }
+        if model is not None:
+            openai_settings_kwargs[openai_model_fields[0]] = model
+        openai_settings = load_settings(
+            OpenAISettings,
+            env_prefix="OPENAI_",
+            **openai_settings_kwargs,
+        )
+        if resolved_model := _resolve_named_setting(openai_settings, openai_model_fields):
+            openai_settings["model"] = resolved_model
+        if client:
+            return openai_settings, client, False  # type: ignore[return-value]
+        if openai_settings.get("api_key") is not None or api_key_callable is not None:
+            resolved_model = _resolve_named_setting(openai_settings, openai_model_fields)
+            if not resolved_model:
+                raise SettingNotFoundError(
+                    "Model must be specified via the 'model' parameter or the "
+                    f"{_join_env_names([OPENAI_MODEL_ENV_VARS[field] for field in openai_model_fields])} "
+                    "environment variable."
+                )
+
+            client_args: dict[str, Any] = {
+                "api_key": api_key_callable
+                if api_key_callable is not None
+                else openai_settings["api_key"].get_secret_value(),  # type: ignore[reportOptionalMemberAccess, union-attr]
+                "organization": openai_settings.get("org_id"),
+                "default_headers": merged_headers,
+            }
+            if base_url := openai_settings.get("base_url"):
+                client_args["base_url"] = base_url
+            if timeout is not None:
+                client_args["timeout"] = timeout
+            return openai_settings, AsyncOpenAI(**client_args), False  # type: ignore[return-value]
+        checked_openai = True
+    azure_settings = load_settings(
+        AzureOpenAISettings,
+        env_prefix="AZURE_OPENAI_",
+        required_fields=None if client else [("base_url", "endpoint")],
+        api_key=api_key_str,
+        endpoint=endpoint,
+        base_url=base_url,
+        api_version=api_version or default_azure_api_version,
+        env_file_path=env_file_path,
+        env_file_encoding=env_file_encoding,
+    )
+    if model is not None:
+        azure_settings[azure_model_fields[0]] = model
+    client_args = {}
+    resolved_azure_model = _resolve_named_setting(azure_settings, azure_model_fields)
+    if resolved_azure_model is None and client:
+        azure_deployment = getattr(client, "_azure_deployment", None)
+        if isinstance(azure_deployment, str) and azure_deployment:
+            resolved_azure_model = azure_deployment
+    if resolved_azure_model:
+        azure_settings["model"] = resolved_azure_model
+        client_args["azure_deployment"] = resolved_azure_model
+    else:
+        deployment_env_guidance = _join_env_names([AZURE_MODEL_ENV_VARS[field] for field in azure_model_fields])
+        has_azure_configuration = (
+            client is not None
+            or azure_settings.get("endpoint") is not None
+            or azure_settings.get("base_url") is not None
+        )
+        if checked_openai and not has_azure_configuration:
+            raise SettingNotFoundError(
+                "OpenAI credentials are required. Provide the 'api_key' parameter or set 'OPENAI_API_KEY'. "
+                "To use Azure OpenAI instead, pass 'azure_endpoint' or set 'AZURE_OPENAI_ENDPOINT' or "
+                "'AZURE_OPENAI_BASE_URL'."
+            )
+        raise SettingNotFoundError(
+            "Azure OpenAI client requires a model, which can be provided via the 'model' parameter, "
+            f"or the {deployment_env_guidance} environment variable."
+        )
+    if client:
+        return azure_settings, client, True  # type: ignore[return-value]
+    client_args["default_headers"] = merged_headers
+    if endpoint := azure_settings.get("endpoint"):
+        if responses_mode:
+            client_args["base_url"] = f"{endpoint.rstrip('/')}/openai/v1/"
+        else:
+            client_args["azure_endpoint"] = endpoint
+    if base_url := azure_settings.get("base_url"):
+        client_args["base_url"] = base_url
+    if api_key := azure_settings.get("api_key"):
+        client_args["api_key"] = api_key.get_secret_value()
+    if api_key_callable:
+        client_args["api_key"] = api_key_callable
+    if api_version := azure_settings.get("api_version"):
+        client_args["api_version"] = api_version
+    if credential:
+        client_args["azure_ad_token_provider"] = _resolve_azure_credential_to_token_provider(credential)
+    if "api_key" not in client_args and "azure_ad_token_provider" not in client_args:
+        raise SettingNotFoundError(
+            "Azure OpenAI client requires either an API key or an Azure AD token provider."
+            " This can be provided either as a callable api_key or via the credential parameter."
+        )
+
+    # The /openai/v1 endpoint exposes an OpenAI-compatible API surface.
+    # AsyncAzureOpenAI rewrites certain request paths (e.g. /embeddings,
+    # /chat/completions) by inserting /deployments/{model}/, which produces
+    # 404s on this endpoint.  Use AsyncOpenAI instead so request URLs are
+    # sent as-is.  responses_mode is excluded because the Responses API path
+    # (/responses) is not rewritten by the Azure SDK.
+    resolved_base_url = client_args.get("base_url", "")
+    if not responses_mode and resolved_base_url and resolved_base_url.rstrip("/").endswith("/openai/v1"):
+        openai_args: dict[str, Any] = {
+            "base_url": resolved_base_url,
+            "default_headers": client_args.get("default_headers"),
+        }
+        if "azure_ad_token_provider" in client_args:
+            openai_args["api_key"] = _ensure_async_token_provider(client_args["azure_ad_token_provider"])
+        elif "api_key" in client_args:
+            openai_args["api_key"] = client_args["api_key"]
+        if timeout is not None:
+            openai_args["timeout"] = timeout
+        return azure_settings, AsyncOpenAI(**openai_args), True  # type: ignore[return-value]
+
+    if timeout is not None:
+        client_args["timeout"] = timeout
+    return azure_settings, AsyncAzureOpenAI(**client_args), True  # type: ignore[return-value]
+
+
+def _ensure_async_token_provider(
+    provider: AzureTokenProvider,
+) -> Callable[[], Awaitable[str]]:
+    """Wrap a (possibly synchronous) token provider so it always returns an awaitable.
+
+    ``AsyncOpenAI`` requires callable ``api_key`` values to return ``Awaitable[str]``.
+    Azure token providers may return a plain ``str``, so this normalises them.
+    """
+
+    async def _wrapper() -> str:
+        result = provider()
+        if isinstance(result, str):
+            return result
+        return await result
+
+    return _wrapper
+
+
+def _resolve_azure_credential_to_token_provider(
+    credential: AzureCredentialTypes | AzureTokenProvider,
+) -> AzureTokenProvider:
+    """Resolve an Azure credential or token provider for Azure OpenAI auth."""
+    if callable(credential):
+        return credential
+
+    try:
+        from azure.core.credentials import TokenCredential
+        from azure.core.credentials_async import AsyncTokenCredential
+        from azure.identity import get_bearer_token_provider
+        from azure.identity.aio import get_bearer_token_provider as get_async_bearer_token_provider
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            "Azure credential auth requires the 'azure-identity' package. Install it with: pip install azure-identity"
+        ) from exc
+
+    if isinstance(credential, AsyncTokenCredential):
+        return get_async_bearer_token_provider(credential, AZURE_OPENAI_TOKEN_SCOPE)
+    if isinstance(credential, TokenCredential):
+        return get_bearer_token_provider(credential, AZURE_OPENAI_TOKEN_SCOPE)
+    raise ValueError(
+        "The 'credential' parameter must be an Azure TokenCredential, AsyncTokenCredential, or a "
+        "callable token provider."
+    )
+
+
+def maybe_append_azure_endpoint_guidance(message: str, *, azure_endpoint: str | None) -> str:
+    """Append Azure endpoint guidance only when the configured endpoint shape looks suspicious."""
+    if not azure_endpoint or not azure_endpoint.rstrip("/").endswith("/openai/v1"):
+        return message
+
+    return (
+        f"{message} If you are using Azure OpenAI key auth, pass the resource endpoint without "
+        "'/openai/v1' to 'azure_endpoint', or pass the full '/openai/v1' URL via 'base_url' instead."
+    )
+
+
+def get_api_key(
+    api_key: str | SecretString | Callable[[], str | Awaitable[str]] | None,
+) -> str | Callable[[], str | Awaitable[str]] | None:
+    """Get the appropriate API key value for client initialization.
+
+    Args:
+        api_key: The API key parameter which can be a string, SecretString, callable, or None.
+
+    Returns:
+        For callable API keys: returns the callable directly.
+        For SecretString: returns the unwrapped secret value.
+        For string/None API keys: returns as-is.
+    """
+    if isinstance(api_key, SecretString):
+        return api_key.get_secret_value()
+
+    return api_key  # Pass callable, string, or None directly to OpenAI SDK

python/packages/openai/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "agent-framework-openai"
+description = "OpenAI integrations for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.10.1"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.11.0,<2",
+    "openai>=2.25.0,<3",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+markers = [
+    "azure: marks tests as Azure-backed OpenAI specific",
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+exclude = ['tests']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_openai"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.mypy]
+help = "Run MyPy for this package."
+cmd = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_openai"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_openai --cov-report=term-missing:skip-covered -n auto --dist worksteal tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/openai/tests/openai/conftest.py

@@ -0,0 +1,201 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import Generator
+from typing import Any, cast
+from unittest.mock import patch
+
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExporter
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from pytest import fixture
+
+
+def _reset_env(monkeypatch, env_names: list[str]) -> None:  # type: ignore
+    for env_name in env_names:
+        monkeypatch.delenv(env_name, raising=False)  # type: ignore
+
+
+# region Connector Settings fixtures
+@fixture
+def exclude_list(request: Any) -> list[str]:
+    """Fixture that returns a list of environment variables to exclude."""
+    return request.param if hasattr(request, "param") else []
+
+
+@fixture
+def override_env_param_dict(request: Any) -> dict[str, str]:
+    """Fixture that returns a dict of environment variables to override."""
+    return request.param if hasattr(request, "param") else {}
+
+
+@fixture()
+def openai_unit_test_env(monkeypatch, exclude_list, override_env_param_dict):  # type: ignore
+    """Fixture to set environment variables for OpenAISettings."""
+    if exclude_list is None:
+        exclude_list = []
+
+    if override_env_param_dict is None:
+        override_env_param_dict = {}
+
+    _reset_env(
+        monkeypatch,
+        [
+            "OPENAI_API_KEY",
+            "OPENAI_ORG_ID",
+            "OPENAI_MODEL",
+            "OPENAI_EMBEDDING_MODEL",
+            "OPENAI_CHAT_COMPLETION_MODEL",
+            "OPENAI_CHAT_MODEL",
+            "OPENAI_API_VERSION",
+            "OPENAI_BASE_URL",
+            "AZURE_OPENAI_ENDPOINT",
+            "AZURE_OPENAI_BASE_URL",
+            "AZURE_OPENAI_API_KEY",
+            "AZURE_OPENAI_CHAT_COMPLETION_MODEL",
+            "AZURE_OPENAI_CHAT_MODEL",
+            "AZURE_OPENAI_EMBEDDING_MODEL",
+            "AZURE_OPENAI_MODEL",
+            "AZURE_OPENAI_API_VERSION",
+        ],
+    )
+
+    env_vars = {
+        "OPENAI_API_KEY": "test-dummy-key",
+        "OPENAI_ORG_ID": "test_org_id",
+        "OPENAI_MODEL": "test_model",
+        "OPENAI_EMBEDDING_MODEL": "test_embedding_model",
+    }
+
+    env_vars.update(override_env_param_dict)  # type: ignore
+
+    for key, value in env_vars.items():
+        if key in exclude_list:
+            monkeypatch.delenv(key, raising=False)  # type: ignore
+            continue
+        monkeypatch.setenv(key, value)  # type: ignore
+
+    return env_vars
+
+
+@fixture()
+def azure_openai_unit_test_env(monkeypatch, exclude_list, override_env_param_dict):  # type: ignore
+    """Fixture to set environment variables for Azure-backed OpenAI tests."""
+    if exclude_list is None:
+        exclude_list = []
+
+    if override_env_param_dict is None:
+        override_env_param_dict = {}
+
+    _reset_env(
+        monkeypatch,
+        [
+            "OPENAI_API_KEY",
+            "OPENAI_ORG_ID",
+            "OPENAI_MODEL",
+            "OPENAI_EMBEDDING_MODEL",
+            "OPENAI_CHAT_COMPLETION_MODEL",
+            "OPENAI_CHAT_MODEL",
+            "OPENAI_API_VERSION",
+            "OPENAI_BASE_URL",
+            "AZURE_OPENAI_ENDPOINT",
+            "AZURE_OPENAI_BASE_URL",
+            "AZURE_OPENAI_API_KEY",
+            "AZURE_OPENAI_CHAT_COMPLETION_MODEL",
+            "AZURE_OPENAI_CHAT_MODEL",
+            "AZURE_OPENAI_EMBEDDING_MODEL",
+            "AZURE_OPENAI_MODEL",
+            "AZURE_OPENAI_API_VERSION",
+        ],
+    )
+
+    env_vars = {
+        "AZURE_OPENAI_ENDPOINT": "https://test-endpoint.openai.azure.com",
+        "AZURE_OPENAI_CHAT_COMPLETION_MODEL": "test_chat_deployment",
+        "AZURE_OPENAI_CHAT_MODEL": "test_responses_deployment",
+        "AZURE_OPENAI_EMBEDDING_MODEL": "test_embedding_deployment",
+        "AZURE_OPENAI_MODEL": "test_deployment",
+        "AZURE_OPENAI_API_KEY": "test_api_key",
+        "AZURE_OPENAI_API_VERSION": "2024-12-01-preview",
+    }
+
+    env_vars.update(override_env_param_dict)  # type: ignore
+
+    for key, value in env_vars.items():
+        if key in exclude_list:
+            monkeypatch.delenv(key, raising=False)  # type: ignore
+            continue
+        monkeypatch.setenv(key, value)  # type: ignore
+
+    return env_vars
+
+
+# region Observability fixtures
+@fixture
+def enable_instrumentation(request: Any) -> bool:
+    """Fixture that returns a boolean indicating if Otel is enabled."""
+    return request.param if hasattr(request, "param") else True
+
+
+@fixture
+def enable_sensitive_data(request: Any) -> bool:
+    """Fixture that returns a boolean indicating if sensitive data is enabled."""
+    return request.param if hasattr(request, "param") else True
+
+
+@fixture
+def span_exporter(monkeypatch, enable_instrumentation: bool, enable_sensitive_data: bool) -> Generator[SpanExporter]:
+    """Fixture to remove environment variables for ObservabilitySettings."""
+    env_vars = [
+        "ENABLE_INSTRUMENTATION",
+        "ENABLE_SENSITIVE_DATA",
+        "ENABLE_CONSOLE_EXPORTERS",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_PROTOCOL",
+        "OTEL_EXPORTER_OTLP_HEADERS",
+        "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
+        "OTEL_EXPORTER_OTLP_METRICS_HEADERS",
+        "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
+        "OTEL_SERVICE_NAME",
+        "OTEL_SERVICE_VERSION",
+        "OTEL_RESOURCE_ATTRIBUTES",
+    ]
+
+    for key in env_vars:
+        monkeypatch.delenv(key, raising=False)  # type: ignore
+    monkeypatch.setenv("ENABLE_INSTRUMENTATION", str(enable_instrumentation))  # type: ignore
+    if not enable_instrumentation:
+        enable_sensitive_data = False
+    monkeypatch.setenv("ENABLE_SENSITIVE_DATA", str(enable_sensitive_data))  # type: ignore
+    import importlib
+
+    import agent_framework.observability as observability
+    from opentelemetry import trace
+
+    importlib.reload(observability)
+
+    observability_settings = observability.ObservabilitySettings()
+
+    if enable_instrumentation or enable_sensitive_data:
+        from opentelemetry.sdk.trace import TracerProvider
+
+        tracer_provider = TracerProvider(resource=cast(Any, observability_settings)._resource)
+        trace.set_tracer_provider(tracer_provider)
+
+    monkeypatch.setattr(observability, "OBSERVABILITY_SETTINGS", observability_settings, raising=False)  # type: ignore
+
+    with (
+        patch("agent_framework.observability.OBSERVABILITY_SETTINGS", observability_settings),
+        patch("agent_framework.observability.configure_otel_providers"),
+    ):
+        exporter = InMemorySpanExporter()
+        if enable_instrumentation or enable_sensitive_data:
+            current_tracer_provider = trace.get_tracer_provider()
+            if not hasattr(current_tracer_provider, "add_span_processor"):
+                raise RuntimeError("Tracer provider does not support adding span processors.")
+
+            current_tracer_provider.add_span_processor(SimpleSpanProcessor(exporter))  # type: ignore
+
+        yield exporter
+        exporter.clear()

python/packages/openai/tests/openai/test_openai_chat_client_azure.py

@@ -0,0 +1,540 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import asyncio
+import os
+from functools import wraps
+from pathlib import Path
+from types import TracebackType
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+
+import pytest
+from agent_framework import Agent, AgentResponse, ChatResponse, Content, Message, SupportsChatGetResponse, tool
+from agent_framework.exceptions import SettingNotFoundError
+from azure.core.credentials_async import AsyncTokenCredential
+from azure.identity.aio import AzureCliCredential
+from openai import AsyncAzureOpenAI
+from pydantic import BaseModel
+from pytest import param
+
+from agent_framework_openai import OpenAIChatClient
+
+pytestmark = pytest.mark.azure
+
+skip_if_azure_openai_integration_tests_disabled = pytest.mark.skip(
+    reason="Azure OpenAI integration tests temporarily disabled: crashes the xdist runner in CI.",
+)
+
+
+def _with_azure_openai_debug() -> Any:
+    def decorator(func: Any) -> Any:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await func(*args, **kwargs)
+            except Exception as exc:
+                model = os.getenv("AZURE_OPENAI_CHAT_MODEL") or os.getenv("AZURE_OPENAI_MODEL", "<unset>")
+                api_version = os.getenv("AZURE_OPENAI_API_VERSION") or "preview"
+                endpoint = os.getenv("AZURE_OPENAI_ENDPOINT", "<unset>")
+                debug_message = f"Azure OpenAI debug: endpoint={endpoint}, model={model}, api_version={api_version}"
+                if hasattr(exc, "add_note"):
+                    cast(Any, exc).add_note(debug_message)
+                elif exc.args:
+                    exc.args = (f"{exc.args[0]}\n{debug_message}", *exc.args[1:])
+                else:
+                    exc.args = (debug_message,)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+class OutputStruct(BaseModel):
+    """A structured output for testing purposes."""
+
+    location: str
+    weather: str | None = None
+
+
+async def create_vector_store(client: OpenAIChatClient) -> tuple[str, Content]:
+    """Create a vector store with sample documents for testing."""
+    file = await client.client.files.create(
+        file=("todays_weather.txt", b"The weather today is sunny with a high of 75F."),
+        purpose="assistants",
+    )
+    vector_store = await client.client.vector_stores.create(
+        name="knowledge_base",
+        expires_after={"anchor": "last_active_at", "days": 1},
+    )
+    result = await client.client.vector_stores.files.create_and_poll(
+        vector_store_id=vector_store.id,
+        file_id=file.id,
+        poll_interval_ms=1000,
+    )
+    if result.last_error is not None:
+        raise RuntimeError(f"Vector store file processing failed with status: {result.last_error.message}")
+
+    # Wait for the vector store index to be fully searchable.
+    # create_and_poll confirms file processing, but the search index is eventually consistent.
+    for _ in range(10):
+        vs = await client.client.vector_stores.retrieve(vector_store.id)
+        if vs.file_counts.completed >= 1 and vs.file_counts.in_progress == 0:
+            break
+        await asyncio.sleep(1)
+    await asyncio.sleep(2)
+
+    return file.id, Content.from_hosted_vector_store(vector_store_id=vector_store.id)
+
+
+async def delete_vector_store(client: OpenAIChatClient, file_id: str, vector_store_id: str) -> None:
+    """Delete the vector store after tests."""
+
+    await client.client.vector_stores.delete(vector_store_id=vector_store_id)
+    await client.client.files.delete(file_id=file_id)
+
+
+@tool(approval_mode="never_require")
+async def get_weather(location: str) -> str:
+    """Get the current weather in a given location."""
+    return f"The current weather in {location} is sunny."
+
+
+def test_init_with_azure_endpoint(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIChatClient(credential=cast(Any, AzureCliCredential()))
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_MODEL"]
+    assert isinstance(client, SupportsChatGetResponse)
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.OTEL_PROVIDER_NAME == "azure.ai.openai"
+    assert client.azure_endpoint is not None
+    assert client.azure_endpoint.startswith(azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"])
+
+
+def test_init_auto_detects_azure_env(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIChatClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_openai_api_key_wins_over_azure_env(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    client = OpenAIChatClient()
+
+    assert client.model == "gpt-5"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_api_version_alone_does_not_override_openai_api_key(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    client = OpenAIChatClient(api_version="2024-10-21")
+
+    assert client.model == "gpt-5"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_explicit_credential_wins_over_openai_api_key(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    client = OpenAIChatClient(credential=lambda: "token")
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_init_falls_back_to_generic_azure_deployment_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_MODEL", raising=False)
+
+    client = OpenAIChatClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+
+
+def test_init_does_not_fall_back_to_openai_responses_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_CHAT_MODEL", "test_responses_model")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIChatClient()
+
+
+def test_init_does_not_fall_back_to_openai_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_CHAT_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIChatClient()
+
+
+def test_init_with_credential_wraps_async_token_credential(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    class TestAsyncTokenCredential(AsyncTokenCredential):
+        async def get_token(self, *scopes: str, **kwargs: object):
+            raise NotImplementedError
+
+        async def close(self) -> None:
+            pass
+
+        async def __aexit__(
+            self,
+            exc_type: type[BaseException] | None = None,
+            exc_value: BaseException | None = None,
+            traceback: TracebackType | None = None,
+        ) -> None:
+            pass
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+    credential = TestAsyncTokenCredential()
+    token_provider = MagicMock()
+
+    with patch("azure.identity.aio.get_bearer_token_provider", return_value=token_provider) as mock_provider:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    mock_provider.assert_called_once_with(credential, "https://cognitiveservices.azure.com/.default")
+
+
+@pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_API_VERSION"]], indirect=True)
+def test_init_uses_default_azure_api_version(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIChatClient(credential=cast(Any, AzureCliCredential()))
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_MODEL"]
+    assert client.api_version is not None
+
+
+def test_openai_base_url_wins_over_azure_aliases(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://custom-openai-endpoint.com/v1")
+
+    client = OpenAIChatClient()
+
+    assert client.model == "gpt-5"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@pytest.mark.parametrize(
+    "option_name,option_value,needs_validation",
+    [
+        param("max_tokens", 500, False, id="max_tokens"),
+        param("seed", 123, False, id="seed"),
+        param("user", "test-user-id", False, id="user"),
+        param("metadata", {"test_key": "test_value"}, False, id="metadata"),
+        param("frequency_penalty", 0.5, False, id="frequency_penalty"),
+        param("presence_penalty", 0.3, False, id="presence_penalty"),
+        param("stop", ["END"], False, id="stop"),
+        param("allow_multiple_tool_calls", True, False, id="allow_multiple_tool_calls"),
+        param("tool_choice", "none", True, id="tool_choice_none"),
+        param("safety_identifier", "user-hash-abc123", False, id="safety_identifier"),
+        param("truncation", "auto", False, id="truncation"),
+        param("prompt_cache_key", "test-cache-key", False, id="prompt_cache_key"),
+        param("max_tool_calls", 3, False, id="max_tool_calls"),
+        param("tools", [get_weather], True, id="tools_function"),
+        param("tool_choice", "auto", True, id="tool_choice_auto"),
+        param(
+            "tool_choice",
+            {"mode": "required", "required_function_name": "get_weather"},
+            True,
+            id="tool_choice_required",
+        ),
+        param("response_format", OutputStruct, True, id="response_format_pydantic"),
+        param(
+            "response_format",
+            {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": "WeatherDigest",
+                    "strict": True,
+                    "schema": {
+                        "title": "WeatherDigest",
+                        "type": "object",
+                        "properties": {
+                            "location": {"type": "string"},
+                            "conditions": {"type": "string"},
+                            "temperature_c": {"type": "number"},
+                            "advisory": {"type": "string"},
+                        },
+                        "required": ["location", "conditions", "temperature_c", "advisory"],
+                        "additionalProperties": False,
+                    },
+                },
+            },
+            True,
+            id="response_format_runtime_json_schema",
+        ),
+    ],
+)
+@_with_azure_openai_debug()
+async def test_integration_options(
+    option_name: str,
+    option_value: Any,
+    needs_validation: bool,
+) -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+        client.function_invocation_configuration["max_iterations"] = 2
+
+        for streaming in [False, True]:
+            if option_name in {"tools", "tool_choice"}:
+                messages = [Message(role="user", contents=["What is the weather in Seattle?"])]
+            elif option_name == "response_format":
+                messages = [
+                    Message(role="user", contents=["The weather in Seattle is sunny"]),
+                    Message(role="user", contents=["What is the weather in Seattle?"]),
+                ]
+            else:
+                messages = [Message(role="user", contents=["Say 'Hello World' briefly."])]
+
+            options: dict[str, Any] = {option_name: option_value}
+            if option_name == "tool_choice":
+                options["tools"] = [get_weather]
+
+            if streaming:
+                response = (
+                    await cast(Any, client)
+                    .get_response(
+                        messages=messages,
+                        stream=True,
+                        options=options,
+                    )
+                    .get_final_response()
+                )
+            else:
+                response = await cast(Any, client).get_response(messages=messages, options=options)
+
+            assert isinstance(response, ChatResponse)
+            assert response.text is not None
+            assert len(response.text) > 0
+
+            if needs_validation:
+                if option_name in {"tools", "tool_choice"}:
+                    text = response.text.lower()
+                    assert "sunny" in text or "seattle" in text
+                elif option_name == "response_format":
+                    if option_value == OutputStruct:
+                        assert response.value is not None
+                        assert isinstance(response.value, OutputStruct)
+                        assert "seattle" in response.value.location.lower()
+                    else:
+                        assert response.value is not None
+                        assert isinstance(response.value, dict)
+                        assert "location" in response.value
+                        assert "seattle" in response.value["location"].lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_web_search() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+
+        response = await client.get_response(
+            messages=[
+                Message(
+                    role="user",
+                    contents=["What is the current weather? Do not ask for my current location."],
+                )
+            ],
+            options={
+                "tools": [OpenAIChatClient.get_web_search_tool(user_location={"country": "US", "city": "Seattle"})],
+            },
+            stream=True,
+        ).get_final_response()
+        assert isinstance(response, ChatResponse)
+        assert response.text is not None
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_client_file_search() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+        file_id, vector_store = await create_vector_store(client)
+        vector_store_id = vector_store.vector_store_id
+        assert vector_store_id is not None
+        try:
+            response = await cast(Any, client).get_response(
+                messages=[
+                    Message(role="user", contents=["What is the weather today? Do a file search to find the answer."])
+                ],
+                options={
+                    "tools": [OpenAIChatClient.get_file_search_tool(vector_store_ids=[vector_store_id])],
+                    "tool_choice": "auto",
+                },
+            )
+
+            assert "sunny" in response.text.lower()
+            assert "75" in response.text
+        finally:
+            await delete_vector_store(client, file_id, vector_store_id)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_client_file_search_streaming() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+        file_id, vector_store = await create_vector_store(client)
+        vector_store_id = vector_store.vector_store_id
+        assert vector_store_id is not None
+        try:
+            response_stream = cast(Any, client).get_response(
+                messages=[
+                    Message(role="user", contents=["What is the weather today? Do a file search to find the answer."])
+                ],
+                stream=True,
+                options={
+                    "tools": [OpenAIChatClient.get_file_search_tool(vector_store_ids=[vector_store_id])],
+                    "tool_choice": "auto",
+                },
+            )
+
+            full_response = await response_stream.get_final_response()
+            assert "sunny" in full_response.text.lower()
+            assert "75" in full_response.text
+        finally:
+            await delete_vector_store(client, file_id, vector_store_id)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_client_agent_hosted_mcp_tool() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+        response = await client.get_response(
+            messages=[Message(role="user", contents=["How to create an Azure storage account using az cli?"])],
+            options={
+                "max_tokens": 5000,
+                "tools": OpenAIChatClient.get_mcp_tool(
+                    name="Microsoft Learn MCP",
+                    url="https://learn.microsoft.com/api/mcp",
+                ),
+            },
+        )
+
+        assert isinstance(response, ChatResponse)
+        if not response.text:
+            pytest.skip("MCP server returned empty response - service-side issue")
+        assert any(term in response.text.lower() for term in ["azure", "storage", "account", "cli"])
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_client_agent_hosted_code_interpreter_tool() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+
+        response = await client.get_response(
+            messages=[Message(role="user", contents=["Calculate the sum of numbers from 1 to 10 using Python code."])],
+            options={"tools": [OpenAIChatClient.get_code_interpreter_tool()]},
+        )
+
+        contains_relevant_content = any(
+            term in response.text.lower() for term in ["55", "sum", "code", "python", "calculate", "10"]
+        )
+        assert contains_relevant_content or len(response.text.strip()) > 10
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_integration_client_agent_existing_session() -> None:
+    async with AzureCliCredential() as credential:
+        preserved_session = None
+
+        async with Agent(
+            client=OpenAIChatClient(credential=cast(Any, credential)),
+            instructions="You are a helpful assistant with good memory.",
+        ) as first_agent:
+            session = first_agent.create_session()
+            first_response = await first_agent.run(
+                "My hobby is photography. Remember this.",
+                session=session,
+                options={"store": True},
+            )
+
+            assert isinstance(first_response, AgentResponse)
+            preserved_session = session
+
+        if preserved_session:
+            async with Agent(
+                client=OpenAIChatClient(credential=cast(Any, credential)),
+                instructions="You are a helpful assistant with good memory.",
+            ) as second_agent:
+                second_response = await second_agent.run(
+                    "What is my hobby?", session=preserved_session, options={"store": True}
+                )
+
+                assert isinstance(second_response, AgentResponse)
+                assert second_response.text is not None
+                assert "photography" in second_response.text.lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+@pytest.mark.skip(reason="Azure OpenAI is flaky when handling image content as function result. Needs investigation.")
+async def test_azure_openai_chat_client_tool_rich_content_image() -> None:
+    image_path = Path(__file__).parent.parent / "assets" / "sample_image.jpg"
+    image_bytes = image_path.read_bytes()
+
+    @tool(approval_mode="never_require")
+    def get_test_image() -> Content:
+        """Return a test image for analysis."""
+        return Content.from_data(data=image_bytes, media_type="image/jpeg")
+
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatClient(credential=cast(Any, credential))
+        client.function_invocation_configuration["max_iterations"] = 2
+
+        response = await client.get_response(
+            messages=[Message(role="user", contents=["Call the get_test_image tool and describe what you see."])],
+            stream=True,
+            options={"tools": [get_test_image], "tool_choice": "auto"},
+        ).get_final_response()
+
+        assert isinstance(response, ChatResponse)
+        assert response.text is not None
+        assert "house" in response.text.lower(), f"Model did not describe the house image. Response: {response.text}"

python/packages/openai/tests/openai/test_openai_chat_completion_client_azure.py

@@ -0,0 +1,418 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import os
+from functools import wraps
+from types import TracebackType
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+
+import pytest
+from agent_framework import (
+    Agent,
+    AgentResponse,
+    AgentResponseUpdate,
+    ChatResponse,
+    ChatResponseUpdate,
+    Message,
+    SupportsChatGetResponse,
+    tool,
+)
+from agent_framework.exceptions import SettingNotFoundError
+from azure.core.credentials_async import AsyncTokenCredential
+from azure.identity.aio import AzureCliCredential
+from openai import AsyncAzureOpenAI
+
+from agent_framework_openai import OpenAIChatCompletionClient
+
+pytestmark = pytest.mark.azure
+
+skip_if_azure_openai_integration_tests_disabled = pytest.mark.skip(
+    reason="Azure OpenAI integration tests temporarily disabled: crashes the xdist runner in CI.",
+)
+
+
+def _with_azure_openai_debug() -> Any:
+    def decorator(func: Any) -> Any:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await func(*args, **kwargs)
+            except Exception as exc:
+                model = os.getenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL") or os.getenv("AZURE_OPENAI_MODEL", "<unset>")
+                api_version = os.getenv("AZURE_OPENAI_API_VERSION", "<unset>")
+                endpoint = os.getenv("AZURE_OPENAI_ENDPOINT", "<unset>")
+                debug_message = f"Azure OpenAI debug: endpoint={endpoint}, model={model}, api_version={api_version}"
+                if hasattr(exc, "add_note"):
+                    cast(Any, exc).add_note(debug_message)
+                elif exc.args:
+                    exc.args = (f"{exc.args[0]}\n{debug_message}", *exc.args[1:])
+                else:
+                    exc.args = (debug_message,)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+@tool(approval_mode="never_require")
+def get_story_text() -> str:
+    """Returns a story about Emily and David."""
+    return (
+        "Emily and David, two passionate scientists, met during a research expedition to Antarctica. "
+        "Bonded by their love for the natural world and shared curiosity, they uncovered a "
+        "groundbreaking phenomenon in glaciology that could potentially reshape our understanding "
+        "of climate change."
+    )
+
+
+@tool(approval_mode="never_require")
+async def get_weather(location: str) -> str:
+    """Get the current weather in a given location."""
+    return f"The current weather in {location} is sunny, 72F."
+
+
+def test_init_with_azure_endpoint(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIChatCompletionClient(azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"))
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_COMPLETION_MODEL"]
+    assert isinstance(client, SupportsChatGetResponse)
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.OTEL_PROVIDER_NAME == "azure.ai.openai"
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+    assert client.api_version == azure_openai_unit_test_env["AZURE_OPENAI_API_VERSION"]
+
+
+def test_init_auto_detects_azure_env(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIChatCompletionClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_COMPLETION_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_openai_api_key_wins_over_azure_env(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    client = OpenAIChatCompletionClient()
+
+    assert client.model == "gpt-5"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_explicit_credential_wins_over_openai_api_key(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    client = OpenAIChatCompletionClient(credential=lambda: "token")
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_CHAT_COMPLETION_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_init_falls_back_to_generic_azure_deployment_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", raising=False)
+
+    client = OpenAIChatCompletionClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+
+
+def test_init_does_not_fall_back_to_openai_chat_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_CHAT_COMPLETION_MODEL", "test_chat_model")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIChatCompletionClient()
+
+
+def test_init_does_not_fall_back_to_openai_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_CHAT_COMPLETION_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_CHAT_COMPLETION_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIChatCompletionClient()
+
+
+def test_init_with_credential_wraps_async_token_credential(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_API_KEY", raising=False)
+
+    class TestAsyncTokenCredential(AsyncTokenCredential):
+        async def get_token(self, *scopes: str, **kwargs: object):
+            raise NotImplementedError
+
+        async def close(self) -> None:
+            pass
+
+        async def __aexit__(
+            self,
+            exc_type: type[BaseException] | None = None,
+            exc_value: BaseException | None = None,
+            traceback: TracebackType | None = None,
+        ) -> None:
+            pass
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+    credential = TestAsyncTokenCredential()
+    token_provider = MagicMock()
+
+    with patch("azure.identity.aio.get_bearer_token_provider", return_value=token_provider) as mock_provider:
+        client = OpenAIChatCompletionClient(credential=cast(Any, credential))
+
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    mock_provider.assert_called_once_with(credential, "https://cognitiveservices.azure.com/.default")
+
+
+def test_openai_base_url_wins_over_azure_aliases(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://custom-openai-endpoint.com/v1")
+
+    client = OpenAIChatCompletionClient()
+
+    assert client.model == "gpt-5"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_response() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatCompletionClient(credential=cast(Any, credential))
+        assert isinstance(client, SupportsChatGetResponse)
+
+        messages = [
+            Message(
+                role="user",
+                contents=[
+                    (
+                        "Emily and David, two passionate scientists, met during a research expedition to Antarctica. "
+                        "Bonded by their love for the natural world and shared curiosity, they uncovered a "
+                        "groundbreaking phenomenon in glaciology that could potentially reshape our understanding "
+                        "of climate change."
+                    )
+                ],
+            ),
+            Message(role="user", contents=["who are Emily and David?"]),
+        ]
+
+        response = await client.get_response(messages=messages)
+
+        assert response is not None
+        assert isinstance(response, ChatResponse)
+        assert any(
+            word in response.text.lower() for word in ["scientists", "research", "antarctica", "glaciology", "climate"]
+        )
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_response_tools() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatCompletionClient(credential=cast(Any, credential))
+
+        response = await client.get_response(
+            messages=[Message(role="user", contents=["who are Emily and David?"])],
+            options={"tools": [get_story_text], "tool_choice": "auto"},
+        )
+
+        assert response is not None
+        assert isinstance(response, ChatResponse)
+        assert "Emily" in response.text or "David" in response.text
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_streaming() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatCompletionClient(credential=cast(Any, credential))
+
+        response = client.get_response(
+            messages=[
+                Message(
+                    role="user",
+                    contents=[
+                        (
+                            "Emily and David, two passionate scientists, met during a research expedition to "
+                            "Antarctica. Bonded by their love for the natural world and shared curiosity, they "
+                            "uncovered a groundbreaking phenomenon in glaciology that could potentially reshape our "
+                            "understanding of climate change."
+                        )
+                    ],
+                ),
+                Message(role="user", contents=["who are Emily and David?"]),
+            ],
+            stream=True,
+        )
+
+        full_message = ""
+        async for chunk in response:
+            assert isinstance(chunk, ChatResponseUpdate)
+            assert chunk.message_id is not None
+            assert chunk.response_id is not None
+            for content in chunk.contents:
+                if content.type == "text" and content.text:
+                    full_message += content.text
+
+        assert "Emily" in full_message or "David" in full_message
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_streaming_tools() -> None:
+    async with AzureCliCredential() as credential:
+        client = OpenAIChatCompletionClient(credential=cast(Any, credential))
+
+        response = client.get_response(
+            messages=[Message(role="user", contents=["who are Emily and David?"])],
+            stream=True,
+            options={"tools": [get_story_text], "tool_choice": "auto"},
+        )
+
+        full_message = ""
+        async for chunk in response:
+            assert isinstance(chunk, ChatResponseUpdate)
+            for content in chunk.contents:
+                if content.type == "text" and content.text:
+                    full_message += content.text
+
+        assert "Emily" in full_message or "David" in full_message
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_agent_basic_run() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        Agent(
+            client=OpenAIChatCompletionClient(credential=cast(Any, credential)),
+        ) as agent,
+    ):
+        response = await agent.run("Please respond with exactly: 'This is a response test.'")
+
+        assert isinstance(response, AgentResponse)
+        assert response.text is not None
+        assert "response test" in response.text.lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_agent_basic_run_streaming() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        Agent(client=OpenAIChatCompletionClient(credential=cast(Any, credential))) as agent,
+    ):
+        full_text = ""
+        async for chunk in agent.run("Please respond with exactly: 'This is a streaming response test.'", stream=True):
+            assert isinstance(chunk, AgentResponseUpdate)
+            if chunk.text:
+                full_text += chunk.text
+
+        assert "streaming response test" in full_text.lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_agent_session_persistence() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        Agent(
+            client=OpenAIChatCompletionClient(credential=cast(Any, credential)),
+            instructions="You are a helpful assistant with good memory.",
+        ) as agent,
+    ):
+        session = agent.create_session()
+        response1 = await agent.run("My name is Alice. Remember this.", session=session)
+        response2 = await agent.run("What is my name?", session=session)
+
+        assert isinstance(response1, AgentResponse)
+        assert isinstance(response2, AgentResponse)
+        assert response2.text is not None
+        assert "alice" in response2.text.lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_chat_completion_client_agent_existing_session() -> None:
+    async with AzureCliCredential() as credential:
+        preserved_session = None
+
+        async with Agent(
+            client=OpenAIChatCompletionClient(credential=cast(Any, credential)),
+            instructions="You are a helpful assistant with good memory.",
+        ) as first_agent:
+            session = first_agent.create_session()
+            first_response = await first_agent.run("My name is Alice. Remember this.", session=session)
+
+            assert isinstance(first_response, AgentResponse)
+            preserved_session = session
+
+        if preserved_session:
+            async with Agent(
+                client=OpenAIChatCompletionClient(credential=cast(Any, credential)),
+                instructions="You are a helpful assistant with good memory.",
+            ) as second_agent:
+                second_response = await second_agent.run("What is my name?", session=preserved_session)
+
+                assert isinstance(second_response, AgentResponse)
+                assert second_response.text is not None
+                assert "alice" in second_response.text.lower()
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_chat_completion_client_agent_level_tool_persistence() -> None:
+    async with (
+        AzureCliCredential() as credential,
+        Agent(
+            client=OpenAIChatCompletionClient(credential=cast(Any, credential)),
+            instructions="You are a helpful assistant that uses available tools.",
+            tools=[get_weather],
+        ) as agent,
+    ):
+        first_response = await agent.run("What's the weather like in Chicago?")
+        second_response = await agent.run("What's the weather in Miami?")
+
+        assert isinstance(first_response, AgentResponse)
+        assert isinstance(second_response, AgentResponse)
+        assert first_response.text is not None
+        assert second_response.text is not None
+        assert any(term in first_response.text.lower() for term in ["chicago", "sunny", "72"])
+        assert any(term in second_response.text.lower() for term in ["miami", "sunny", "72"])

python/packages/openai/tests/openai/test_openai_chat_completion_client_base.py

@@ -0,0 +1,429 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from copy import deepcopy
+from datetime import datetime, timezone
+from typing import Any, cast
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from agent_framework import ChatResponseUpdate, Message
+from agent_framework.exceptions import ChatClientException
+from openai import AsyncStream
+from openai.resources.chat.completions import AsyncCompletions as AsyncChatCompletions
+from openai.types.chat import ChatCompletion, ChatCompletionChunk
+from openai.types.chat.chat_completion import Choice
+from openai.types.chat.chat_completion_chunk import Choice as ChunkChoice
+from openai.types.chat.chat_completion_chunk import ChoiceDelta as ChunkChoiceDelta
+from openai.types.chat.chat_completion_message import ChatCompletionMessage
+from pydantic import BaseModel
+
+from agent_framework_openai import OpenAIChatCompletionClient
+
+
+async def mock_async_process_chat_stream_response(_):
+    mock_content = MagicMock(spec=ChatResponseUpdate)
+    yield mock_content, None
+
+
+@pytest.fixture(scope="function")
+def chat_history() -> list[Message]:
+    return []
+
+
+@pytest.fixture
+def mock_chat_completion_response() -> ChatCompletion:
+    return ChatCompletion(
+        id="test_id",
+        choices=[
+            Choice(index=0, message=ChatCompletionMessage(content="test", role="assistant"), finish_reason="stop")
+        ],
+        created=0,
+        model="test",
+        object="chat.completion",
+    )
+
+
+@pytest.fixture
+def mock_streaming_chat_completion_response() -> AsyncStream[ChatCompletionChunk]:
+    content = ChatCompletionChunk(
+        id="test_id",
+        choices=[ChunkChoice(index=0, delta=ChunkChoiceDelta(content="test", role="assistant"), finish_reason="stop")],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    stream = MagicMock(spec=AsyncStream)
+    stream.__aiter__.return_value = [content]
+    return stream
+
+
+# region Chat Message Content
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_cmc(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    await openai_chat_completion.get_response(messages=chat_history)
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=False,
+        messages=openai_chat_completion._prepare_messages_for_openai(chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_cmc_chat_options(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    await openai_chat_completion.get_response(
+        messages=chat_history,
+    )
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=False,
+        messages=openai_chat_completion._prepare_messages_for_openai(chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_cmc_no_fcc_in_response(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+    orig_chat_history = deepcopy(chat_history)
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    await openai_chat_completion.get_response(
+        messages=chat_history,
+    )
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=False,
+        messages=openai_chat_completion._prepare_messages_for_openai(orig_chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_cmc_structured_output_no_fcc(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    # Define a mock response format
+    class Test(BaseModel):
+        name: str
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    await openai_chat_completion.get_response(
+        messages=chat_history,
+        options={"response_format": Test},
+    )
+    mock_create.assert_awaited_once()
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_scmc_chat_options(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_streaming_chat_completion_response: AsyncStream[ChatCompletionChunk],
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_streaming_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    async for msg in openai_chat_completion.get_response(
+        stream=True,
+        messages=chat_history,
+    ):
+        assert isinstance(msg, ChatResponseUpdate)
+        assert msg.message_id is not None
+        assert msg.response_id is not None
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=True,
+        stream_options={"include_usage": True},
+        messages=openai_chat_completion._prepare_messages_for_openai(chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock, side_effect=Exception)
+async def test_cmc_general_exception(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    with pytest.raises(ChatClientException):
+        await openai_chat_completion.get_response(
+            messages=chat_history,
+        )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_cmc_additional_properties(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    await cast(Any, openai_chat_completion).get_response(
+        messages=chat_history,
+        options={"reasoning_effort": "low"},
+    )
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=False,
+        messages=openai_chat_completion._prepare_messages_for_openai(chat_history),  # type: ignore
+        reasoning_effort="low",
+    )
+
+
+# region Streaming
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_get_streaming(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    openai_unit_test_env: dict[str, str],
+):
+    content1 = ChatCompletionChunk(
+        id="test_id",
+        choices=[],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    content2 = ChatCompletionChunk(
+        id="test_id",
+        choices=[ChunkChoice(index=0, delta=ChunkChoiceDelta(content="test", role="assistant"), finish_reason="stop")],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    stream = MagicMock(spec=AsyncStream)
+    stream.__aiter__.return_value = [content1, content2]
+    mock_create.return_value = stream
+    chat_history.append(Message(role="user", contents=["hello world"]))
+    orig_chat_history = deepcopy(chat_history)
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    async for msg in openai_chat_completion.get_response(
+        stream=True,
+        messages=chat_history,
+    ):
+        assert isinstance(msg, ChatResponseUpdate)
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=True,
+        stream_options={"include_usage": True},
+        messages=openai_chat_completion._prepare_messages_for_openai(orig_chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_get_streaming_singular(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    openai_unit_test_env: dict[str, str],
+):
+    content1 = ChatCompletionChunk(
+        id="test_id",
+        choices=[],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    content2 = ChatCompletionChunk(
+        id="test_id",
+        choices=[ChunkChoice(index=0, delta=ChunkChoiceDelta(content="test", role="assistant"), finish_reason="stop")],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    stream = MagicMock(spec=AsyncStream)
+    stream.__aiter__.return_value = [content1, content2]
+    mock_create.return_value = stream
+    chat_history.append(Message(role="user", contents=["hello world"]))
+    orig_chat_history = deepcopy(chat_history)
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    async for msg in openai_chat_completion.get_response(
+        stream=True,
+        messages=chat_history,
+    ):
+        assert isinstance(msg, ChatResponseUpdate)
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=True,
+        stream_options={"include_usage": True},
+        messages=openai_chat_completion._prepare_messages_for_openai(orig_chat_history),  # type: ignore
+    )
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_get_streaming_structured_output_no_fcc(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    openai_unit_test_env: dict[str, str],
+):
+    content1 = ChatCompletionChunk(
+        id="test_id",
+        choices=[],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    content2 = ChatCompletionChunk(
+        id="test_id",
+        choices=[ChunkChoice(index=0, delta=ChunkChoiceDelta(content="test", role="assistant"), finish_reason="stop")],
+        created=0,
+        model="test",
+        object="chat.completion.chunk",
+    )
+    stream = MagicMock(spec=AsyncStream)
+    stream.__aiter__.return_value = [content1, content2]
+    mock_create.return_value = stream
+    chat_history.append(Message(role="user", contents=["hello world"]))
+
+    # Define a mock response format
+    class Test(BaseModel):
+        name: str
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    async for msg in openai_chat_completion.get_response(
+        stream=True,
+        messages=chat_history,
+        options={"response_format": Test},
+    ):
+        assert isinstance(msg, ChatResponseUpdate)
+    mock_create.assert_awaited_once()
+
+
+@patch.object(AsyncChatCompletions, "create", new_callable=AsyncMock)
+async def test_get_streaming_no_fcc_in_response(
+    mock_create: AsyncMock,
+    chat_history: list[Message],
+    mock_streaming_chat_completion_response: ChatCompletion,
+    openai_unit_test_env: dict[str, str],
+):
+    mock_create.return_value = mock_streaming_chat_completion_response
+    chat_history.append(Message(role="user", contents=["hello world"]))
+    orig_chat_history = deepcopy(chat_history)
+
+    openai_chat_completion = OpenAIChatCompletionClient()
+    [
+        msg
+        async for msg in openai_chat_completion.get_response(
+            stream=True,
+            messages=chat_history,
+        )
+    ]
+    mock_create.assert_awaited_once_with(
+        model=openai_unit_test_env["OPENAI_MODEL"],
+        stream=True,
+        stream_options={"include_usage": True},
+        messages=openai_chat_completion._prepare_messages_for_openai(orig_chat_history),  # type: ignore
+    )
+
+
+# region UTC Timestamp Tests
+
+
+def test_chat_response_created_at_uses_utc(openai_unit_test_env: dict[str, str]):
+    """Test that ChatResponse.created_at uses UTC timestamp, not local time.
+
+    This is a regression test for the issue where created_at was using local time
+    but labeling it as UTC (with 'Z' suffix).
+    """
+    # Use a specific Unix timestamp: 1733011890 = 2024-12-01T00:31:30Z (UTC)
+    # This ensures we test that the timestamp is actually converted to UTC
+    utc_timestamp = 1733011890
+
+    mock_response = ChatCompletion(
+        id="test_id",
+        choices=[
+            Choice(index=0, message=ChatCompletionMessage(content="test", role="assistant"), finish_reason="stop")
+        ],
+        created=utc_timestamp,
+        model="test",
+        object="chat.completion",
+    )
+
+    client = OpenAIChatCompletionClient()
+    response = client._parse_response_from_openai(mock_response, {})
+
+    # Verify that created_at is correctly formatted as UTC
+    assert response.created_at is not None
+    assert response.created_at.endswith("Z"), "Timestamp should end with 'Z' for UTC"
+
+    # Parse the timestamp and verify it matches UTC time
+    expected_utc_time = datetime.fromtimestamp(utc_timestamp, tz=timezone.utc)
+    expected_formatted = expected_utc_time.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+    assert response.created_at == expected_formatted, (
+        f"Expected UTC timestamp {expected_formatted}, got {response.created_at}"
+    )
+
+
+def test_chat_response_update_created_at_uses_utc(openai_unit_test_env: dict[str, str]):
+    """Test that ChatResponseUpdate.created_at uses UTC timestamp, not local time.
+
+    This is a regression test for the issue where created_at was using local time
+    but labeling it as UTC (with 'Z' suffix).
+    """
+    # Use a specific Unix timestamp: 1733011890 = 2024-12-01T00:31:30Z (UTC)
+    utc_timestamp = 1733011890
+
+    mock_chunk = ChatCompletionChunk(
+        id="test_id",
+        choices=[ChunkChoice(index=0, delta=ChunkChoiceDelta(content="test", role="assistant"), finish_reason="stop")],
+        created=utc_timestamp,
+        model="test",
+        object="chat.completion.chunk",
+    )
+
+    client = OpenAIChatCompletionClient()
+    response_update = client._parse_response_update_from_openai(mock_chunk)
+
+    # Verify that created_at is correctly formatted as UTC
+    assert response_update.created_at is not None
+    assert response_update.created_at.endswith("Z"), "Timestamp should end with 'Z' for UTC"
+
+    # Parse the timestamp and verify it matches UTC time
+    expected_utc_time = datetime.fromtimestamp(utc_timestamp, tz=timezone.utc)
+    expected_formatted = expected_utc_time.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+    assert response_update.created_at == expected_formatted, (
+        f"Expected UTC timestamp {expected_formatted}, got {response_update.created_at}"
+    )

python/packages/openai/tests/openai/test_openai_embedding_client.py

@@ -0,0 +1,266 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import inspect
+import os
+from typing import Any, cast
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from agent_framework import SupportsGetEmbeddings
+from agent_framework.exceptions import SettingNotFoundError
+from openai.types import CreateEmbeddingResponse
+from openai.types import Embedding as OpenAIEmbedding
+from openai.types.create_embedding_response import Usage
+
+from agent_framework_openai import (
+    OpenAIEmbeddingClient,
+    OpenAIEmbeddingOptions,
+)
+from agent_framework_openai._embedding_client import RawOpenAIEmbeddingClient
+
+
+def _make_openai_response(
+    embeddings: list[list[float]],
+    model: str = "text-embedding-3-small",
+    prompt_tokens: int = 5,
+    total_tokens: int = 5,
+) -> CreateEmbeddingResponse:
+    """Helper to create a mock OpenAI embeddings response."""
+    data = [OpenAIEmbedding(embedding=emb, index=i, object="embedding") for i, emb in enumerate(embeddings)]
+    return CreateEmbeddingResponse(
+        data=data,
+        model=model,
+        object="list",
+        usage=Usage(prompt_tokens=prompt_tokens, total_tokens=total_tokens),
+    )
+
+
+# --- OpenAI unit tests ---
+
+
+def test_openai_construction_with_explicit_params() -> None:
+    client = OpenAIEmbeddingClient(
+        model="text-embedding-3-small",
+        api_key="test-key",
+    )
+    assert client.model == "text-embedding-3-small"
+    assert isinstance(client, SupportsGetEmbeddings)
+
+
+def test_raw_openai_embedding_client_init_uses_explicit_parameters() -> None:
+    signature = inspect.signature(RawOpenAIEmbeddingClient.__init__)
+
+    assert "additional_properties" in signature.parameters
+    assert all(parameter.kind != inspect.Parameter.VAR_KEYWORD for parameter in signature.parameters.values())
+
+
+def test_openai_construction_from_env(openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIEmbeddingClient()
+    assert client.model == openai_unit_test_env["OPENAI_EMBEDDING_MODEL"]
+
+
+def test_with_callable_api_key() -> None:
+    """Test OpenAIEmbeddingClient initialization with callable API key."""
+
+    async def get_api_key() -> str:
+        return "test-api-key-123"
+
+    client = OpenAIEmbeddingClient(model="text-embedding-3-small", api_key=get_api_key)
+
+    assert client.model == "text-embedding-3-small"
+    assert client.client is not None
+
+
+@pytest.mark.parametrize("exclude_list", [["OPENAI_API_KEY"]], indirect=True)
+def test_openai_construction_without_openai_or_azure_config_raises_clear_error(
+    openai_unit_test_env: dict[str, str],
+) -> None:
+    with pytest.raises(SettingNotFoundError):
+        OpenAIEmbeddingClient(model="text-embedding-3-small")
+
+
+@pytest.mark.parametrize("exclude_list", [["OPENAI_EMBEDDING_MODEL"]], indirect=True)
+def test_openai_construction_falls_back_to_openai_model(openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIEmbeddingClient()
+
+    assert client.model == openai_unit_test_env["OPENAI_MODEL"]
+
+
+async def test_openai_get_embeddings(openai_unit_test_env: dict[str, str]) -> None:
+    mock_response = _make_openai_response(
+        embeddings=[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
+    )
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock(return_value=mock_response)
+
+    result = await client.get_embeddings(["hello", "world"])
+
+    assert len(result) == 2
+    assert result[0].vector == [0.1, 0.2, 0.3]
+    assert result[1].vector == [0.4, 0.5, 0.6]
+    assert result[0].model == "text-embedding-3-small"
+    assert result[0].dimensions == 3
+
+
+async def test_openai_get_embeddings_usage(openai_unit_test_env: dict[str, str]) -> None:
+    mock_response = _make_openai_response(
+        embeddings=[[0.1]],
+        prompt_tokens=10,
+        total_tokens=10,
+    )
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock(return_value=mock_response)
+
+    result = await client.get_embeddings(["test"])
+
+    assert result.usage is not None
+    assert result.usage["input_token_count"] == 10
+    assert result.usage["total_token_count"] == 10
+
+
+async def test_openai_options_passthrough_dimensions(openai_unit_test_env: dict[str, str]) -> None:
+    mock_response = _make_openai_response(embeddings=[[0.1]])
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock(return_value=mock_response)
+
+    options: OpenAIEmbeddingOptions = {"dimensions": 256}
+    result = await client.get_embeddings(["test"], options=options)
+
+    call_kwargs = client.client.embeddings.create.call_args[1]
+    assert call_kwargs["dimensions"] == 256
+    assert result.options is options
+
+
+async def test_openai_options_passthrough_encoding_format(openai_unit_test_env: dict[str, str]) -> None:
+    mock_response = _make_openai_response(embeddings=[[0.1]])
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock(return_value=mock_response)
+
+    options: OpenAIEmbeddingOptions = {"encoding_format": "base64"}
+    await client.get_embeddings(["test"], options=options)
+
+    call_kwargs = client.client.embeddings.create.call_args[1]
+    assert call_kwargs["encoding_format"] == "base64"
+
+
+async def test_openai_base64_decoding(openai_unit_test_env: dict[str, str]) -> None:
+    import base64
+    import struct
+
+    # Encode [0.1, 0.2, 0.3] as base64 little-endian floats
+    raw_floats = [0.1, 0.2, 0.3]
+    b64_str = base64.b64encode(struct.pack(f"<{len(raw_floats)}f", *raw_floats)).decode()
+
+    # Mock the embedding item to return a base64 string (as the API does with encoding_format=base64)
+    mock_item = MagicMock()
+    mock_item.embedding = b64_str
+    mock_item.index = 0
+
+    mock_response = MagicMock()
+    mock_response.data = [mock_item]
+    mock_response.model = "text-embedding-3-small"
+    mock_response.usage = MagicMock(prompt_tokens=3, total_tokens=3)
+
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock(return_value=mock_response)
+
+    options: OpenAIEmbeddingOptions = {"encoding_format": "base64"}
+    result = await client.get_embeddings(["test"], options=options)
+
+    assert len(result) == 1
+    assert len(result[0].vector) == 3
+    assert result[0].dimensions == 3
+    for expected, actual in zip(raw_floats, result[0].vector):
+        assert abs(expected - actual) < 1e-6
+
+
+async def test_openai_error_when_no_model() -> None:
+    client = cast(Any, object.__new__(OpenAIEmbeddingClient))
+    client.model = None
+    client.client = MagicMock()
+    client.additional_properties = {}
+    client.otel_provider_name = "openai"
+
+    with pytest.raises(ValueError, match="model is required"):
+        await client.get_embeddings(["test"])
+
+
+async def test_openai_empty_values_returns_empty(openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIEmbeddingClient()
+    client.client = MagicMock()
+    client.client.embeddings = MagicMock()
+    client.client.embeddings.create = AsyncMock()
+
+    result = await client.get_embeddings([])
+
+    assert len(result) == 0
+    assert result.usage is None
+    client.client.embeddings.create.assert_not_called()
+
+
+# --- Integration tests ---
+
+skip_if_openai_integration_tests_disabled = pytest.mark.skipif(
+    os.getenv("OPENAI_API_KEY", "") in ("", "test-dummy-key"),
+    reason="No real OPENAI_API_KEY provided; skipping integration tests.",
+)
+
+
+@skip_if_openai_integration_tests_disabled
+@pytest.mark.flaky
+@pytest.mark.integration
+async def test_integration_openai_get_embeddings() -> None:
+    """End-to-end test of OpenAI embedding generation."""
+    client = OpenAIEmbeddingClient(model="text-embedding-3-small")
+
+    result = await client.get_embeddings(["hello world"])
+
+    assert len(result) == 1
+    assert isinstance(result[0].vector, list)
+    assert len(result[0].vector) > 0
+    assert all(isinstance(v, float) for v in result[0].vector)
+    assert result[0].model is not None
+    assert result.usage is not None
+    input_token_count = result.usage["input_token_count"]
+    assert input_token_count is not None
+    assert input_token_count > 0
+
+
+@skip_if_openai_integration_tests_disabled
+@pytest.mark.flaky
+@pytest.mark.integration
+async def test_integration_openai_get_embeddings_multiple() -> None:
+    """Test embedding generation for multiple inputs."""
+    client = OpenAIEmbeddingClient(model="text-embedding-3-small")
+
+    result = await client.get_embeddings(["hello", "world", "test"])
+
+    assert len(result) == 3
+    dims = [len(e.vector) for e in result]
+    assert all(d == dims[0] for d in dims)
+
+
+@skip_if_openai_integration_tests_disabled
+@pytest.mark.flaky
+@pytest.mark.integration
+async def test_integration_openai_get_embeddings_with_dimensions() -> None:
+    """Test embedding generation with custom dimensions."""
+    client = OpenAIEmbeddingClient(model="text-embedding-3-small")
+
+    options: OpenAIEmbeddingOptions = {"dimensions": 256}
+    result = await client.get_embeddings(["hello world"], options=options)
+
+    assert len(result) == 1
+    assert len(result[0].vector) == 256

python/packages/openai/tests/openai/test_openai_embedding_client_azure.py

@@ -0,0 +1,329 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import os
+from functools import wraps
+from types import TracebackType
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+
+import pytest
+from agent_framework.exceptions import SettingNotFoundError
+from azure.core.credentials_async import AsyncTokenCredential
+from azure.identity.aio import AzureCliCredential
+from openai import AsyncAzureOpenAI, AsyncOpenAI
+
+from agent_framework_openai import OpenAIEmbeddingClient, OpenAIEmbeddingOptions
+
+pytestmark = pytest.mark.azure
+
+skip_if_azure_openai_integration_tests_disabled = pytest.mark.skip(
+    reason="Azure OpenAI integration tests temporarily disabled: crashes the xdist runner in CI.",
+)
+
+
+def _with_azure_openai_debug() -> Any:
+    def decorator(func: Any) -> Any:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return await func(*args, **kwargs)
+            except Exception as exc:
+                model = os.getenv("AZURE_OPENAI_EMBEDDING_MODEL") or os.getenv("AZURE_OPENAI_MODEL", "<unset>")
+                api_version = os.getenv("AZURE_OPENAI_API_VERSION", "<unset>")
+                endpoint = os.getenv("AZURE_OPENAI_ENDPOINT", "<unset>")
+                debug_message = f"Azure OpenAI debug: endpoint={endpoint}, model={model}, api_version={api_version}"
+                if hasattr(exc, "add_note"):
+                    cast(Any, exc).add_note(debug_message)
+                elif exc.args:
+                    exc.args = (f"{exc.args[0]}\n{debug_message}", *exc.args[1:])
+                else:
+                    exc.args = (debug_message,)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def _get_azure_embedding_deployment_name() -> str:
+    return os.getenv("AZURE_OPENAI_EMBEDDING_MODEL") or os.environ["AZURE_OPENAI_MODEL"]
+
+
+def _create_azure_embedding_client(
+    *,
+    api_key: str | None = None,
+    credential: AsyncTokenCredential | None = None,
+) -> OpenAIEmbeddingClient:
+    resolved_api_key = (
+        api_key if api_key is not None else None if credential is not None else os.environ["AZURE_OPENAI_API_KEY"]
+    )
+    return OpenAIEmbeddingClient(
+        model=_get_azure_embedding_deployment_name(),
+        api_key=resolved_api_key,
+        azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
+        credential=cast(Any, credential),
+    )
+
+
+def test_init_with_azure_endpoint(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = _create_azure_embedding_client()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_EMBEDDING_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.OTEL_PROVIDER_NAME == "azure.ai.openai"
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+    assert client.api_version == azure_openai_unit_test_env["AZURE_OPENAI_API_VERSION"]
+
+
+def test_init_auto_detects_azure_embedding_env(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIEmbeddingClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_EMBEDDING_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_init_falls_back_to_generic_azure_deployment_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_EMBEDDING_MODEL", raising=False)
+
+    client = OpenAIEmbeddingClient()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+
+
+def test_init_does_not_fall_back_to_openai_embedding_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_EMBEDDING_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIEmbeddingClient()
+
+
+def test_init_does_not_fall_back_to_openai_model_for_azure_env(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.delenv("AZURE_OPENAI_EMBEDDING_MODEL", raising=False)
+    monkeypatch.delenv("AZURE_OPENAI_MODEL", raising=False)
+    monkeypatch.delenv("OPENAI_EMBEDDING_MODEL", raising=False)
+    monkeypatch.setenv("OPENAI_MODEL", "gpt-5")
+
+    with pytest.raises(SettingNotFoundError, match="Azure OpenAI client requires a model"):
+        OpenAIEmbeddingClient()
+
+
+def test_openai_api_key_wins_over_azure_env(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+
+    client = OpenAIEmbeddingClient()
+
+    assert client.model == "text-embedding-3-small"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_api_version_alone_does_not_override_openai_api_key(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+
+    client = OpenAIEmbeddingClient(api_version="2024-10-21")
+
+    assert client.model == "text-embedding-3-small"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_explicit_credential_wins_over_openai_api_key(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+
+    client = OpenAIEmbeddingClient(credential=lambda: "token")
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_EMBEDDING_MODEL"]
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint == azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"]
+
+
+def test_init_with_credential_wraps_async_token_credential(
+    monkeypatch, azure_openai_unit_test_env: dict[str, str]
+) -> None:
+    class TestAsyncTokenCredential(AsyncTokenCredential):
+        async def get_token(self, *scopes: str, **kwargs: object):
+            raise NotImplementedError
+
+        async def close(self) -> None:
+            pass
+
+        async def __aexit__(
+            self,
+            exc_type: type[BaseException] | None = None,
+            exc_value: BaseException | None = None,
+            traceback: TracebackType | None = None,
+        ) -> None:
+            pass
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+    credential = TestAsyncTokenCredential()
+    token_provider = MagicMock()
+
+    with patch("azure.identity.aio.get_bearer_token_provider", return_value=token_provider) as mock_provider:
+        client = OpenAIEmbeddingClient(credential=cast(Any, credential))
+
+    assert isinstance(client.client, AsyncAzureOpenAI)
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_EMBEDDING_MODEL"]
+    mock_provider.assert_called_once_with(credential, "https://cognitiveservices.azure.com/.default")
+
+
+@pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_API_VERSION"]], indirect=True)
+def test_init_uses_default_azure_api_version(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = _create_azure_embedding_client()
+
+    assert client.model == azure_openai_unit_test_env["AZURE_OPENAI_EMBEDDING_MODEL"]
+    assert client.api_version == "2024-10-21"
+
+
+def test_openai_base_url_wins_over_azure_aliases(monkeypatch, azure_openai_unit_test_env: dict[str, str]) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "test-dummy-key")
+    monkeypatch.setenv("OPENAI_EMBEDDING_MODEL", "text-embedding-3-small")
+    monkeypatch.setenv("OPENAI_BASE_URL", "https://custom-openai-endpoint.com/v1")
+
+    client = OpenAIEmbeddingClient()
+
+    assert client.model == "text-embedding-3-small"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert client.azure_endpoint is None
+
+
+def test_init_with_openai_v1_base_url_and_credential_uses_openai_client(monkeypatch) -> None:
+    for env in [
+        "OPENAI_API_KEY",
+        "OPENAI_ORG_ID",
+        "OPENAI_MODEL",
+        "OPENAI_EMBEDDING_MODEL",
+        "OPENAI_BASE_URL",
+        "AZURE_OPENAI_ENDPOINT",
+        "AZURE_OPENAI_BASE_URL",
+        "AZURE_OPENAI_API_KEY",
+        "AZURE_OPENAI_EMBEDDING_MODEL",
+        "AZURE_OPENAI_MODEL",
+        "AZURE_OPENAI_API_VERSION",
+        "AZURE_OPENAI_CHAT_MODEL",
+        "AZURE_OPENAI_CHAT_COMPLETION_MODEL",
+    ]:
+        monkeypatch.delenv(env, raising=False)
+
+    client = OpenAIEmbeddingClient(
+        base_url="https://myproject.openai.azure.com/openai/v1/",
+        model="text-embedding-3-large",
+        credential=lambda: "fake-token",
+    )
+
+    assert client.model == "text-embedding-3-large"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert isinstance(client.client, AsyncOpenAI)
+    assert client.OTEL_PROVIDER_NAME == "azure.ai.openai"
+    assert str(client.client.base_url).rstrip("/").endswith("/openai/v1")
+
+
+def test_init_with_openai_v1_base_url_and_api_key_uses_openai_client(monkeypatch) -> None:
+    for env in [
+        "OPENAI_API_KEY",
+        "OPENAI_ORG_ID",
+        "OPENAI_MODEL",
+        "OPENAI_EMBEDDING_MODEL",
+        "OPENAI_BASE_URL",
+        "AZURE_OPENAI_ENDPOINT",
+        "AZURE_OPENAI_BASE_URL",
+        "AZURE_OPENAI_API_KEY",
+        "AZURE_OPENAI_EMBEDDING_MODEL",
+        "AZURE_OPENAI_MODEL",
+        "AZURE_OPENAI_API_VERSION",
+        "AZURE_OPENAI_CHAT_MODEL",
+        "AZURE_OPENAI_CHAT_COMPLETION_MODEL",
+    ]:
+        monkeypatch.delenv(env, raising=False)
+
+    # AZURE_OPENAI_BASE_URL + AZURE_OPENAI_API_KEY enter the Azure settings
+    # path without an explicit endpoint parameter; the /openai/v1 suffix
+    # should still produce AsyncOpenAI (not AsyncAzureOpenAI).
+    monkeypatch.setenv("AZURE_OPENAI_BASE_URL", "https://myproject.openai.azure.com/openai/v1/")
+    monkeypatch.setenv("AZURE_OPENAI_API_KEY", "test-api-key")
+
+    client = OpenAIEmbeddingClient(model="text-embedding-3-large")
+
+    assert client.model == "text-embedding-3-large"
+    assert not isinstance(client.client, AsyncAzureOpenAI)
+    assert isinstance(client.client, AsyncOpenAI)
+    assert str(client.client.base_url).rstrip("/").endswith("/openai/v1")
+
+
+def test_init_with_azure_endpoint_still_uses_azure_client(azure_openai_unit_test_env: dict[str, str]) -> None:
+    client = OpenAIEmbeddingClient(
+        azure_endpoint=azure_openai_unit_test_env["AZURE_OPENAI_ENDPOINT"],
+        api_key=azure_openai_unit_test_env["AZURE_OPENAI_API_KEY"],
+    )
+
+    assert isinstance(client.client, AsyncAzureOpenAI)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_get_embeddings() -> None:
+    async with AzureCliCredential() as credential:
+        client = _create_azure_embedding_client(credential=cast(Any, credential))
+
+        result = await client.get_embeddings(["hello world"])
+
+    assert len(result) == 1
+    assert isinstance(result[0].vector, list)
+    assert len(result[0].vector) > 0
+    assert all(isinstance(v, float) for v in result[0].vector)
+    assert result[0].model is not None
+    assert result.usage is not None
+    input_token_count = result.usage["input_token_count"]
+    assert input_token_count is not None
+    assert input_token_count > 0
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_get_embeddings_multiple() -> None:
+    async with AzureCliCredential() as credential:
+        client = _create_azure_embedding_client(credential=cast(Any, credential))
+
+        result = await client.get_embeddings(["hello", "world", "test"])
+
+    assert len(result) == 3
+    dims = [len(embedding.vector) for embedding in result]
+    assert all(dimension == dims[0] for dimension in dims)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_azure_openai_integration_tests_disabled
+@_with_azure_openai_debug()
+async def test_azure_openai_get_embeddings_with_dimensions() -> None:
+    async with AzureCliCredential() as credential:
+        client = _create_azure_embedding_client(credential=cast(Any, credential))
+
+        options: OpenAIEmbeddingOptions = {"dimensions": 256}
+        result = await client.get_embeddings(["hello world"], options=options)
+
+    assert len(result) == 1
+    assert len(result[0].vector) == 256

python/packages/openai/tests/openai/test_openai_shared.py

@@ -0,0 +1,91 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+
+import pytest
+from azure.core.credentials import TokenCredential
+from azure.core.credentials_async import AsyncTokenCredential
+
+from agent_framework_openai._shared import (
+    AZURE_OPENAI_TOKEN_SCOPE,
+    _ensure_async_token_provider,
+    _resolve_azure_credential_to_token_provider,
+)
+
+
+class _AsyncTokenCredentialStub(AsyncTokenCredential):
+    async def get_token(self, *scopes: str, **kwargs: object):
+        raise NotImplementedError
+
+    async def close(self) -> None:
+        pass
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        pass
+
+
+class _TokenCredentialStub(TokenCredential):
+    def get_token(self, *scopes: str, **kwargs: object):
+        raise NotImplementedError
+
+
+def test_resolve_azure_async_credential_wraps_provider() -> None:
+    credential = _AsyncTokenCredentialStub()
+    token_provider = MagicMock()
+
+    with patch("azure.identity.aio.get_bearer_token_provider", return_value=token_provider) as mock_provider:
+        resolved = _resolve_azure_credential_to_token_provider(credential)
+
+    assert resolved is token_provider
+    mock_provider.assert_called_once_with(credential, AZURE_OPENAI_TOKEN_SCOPE)
+
+
+def test_resolve_azure_sync_credential_wraps_provider() -> None:
+    credential = _TokenCredentialStub()
+    token_provider = MagicMock()
+
+    with patch("azure.identity.get_bearer_token_provider", return_value=token_provider) as mock_provider:
+        resolved = _resolve_azure_credential_to_token_provider(credential)
+
+    assert resolved is token_provider
+    mock_provider.assert_called_once_with(credential, AZURE_OPENAI_TOKEN_SCOPE)
+
+
+def test_resolve_azure_callable_token_provider_passthrough() -> None:
+    token_provider = MagicMock()
+
+    assert _resolve_azure_credential_to_token_provider(token_provider) is token_provider
+
+
+def test_resolve_azure_invalid_credential_raises() -> None:
+    with pytest.raises(ValueError, match="credential"):
+        _resolve_azure_credential_to_token_provider(cast(Any, object()))
+
+
+async def test_ensure_async_token_provider_wraps_sync_provider() -> None:
+    def sync_provider() -> str:
+        return "sync-token"
+
+    wrapper = _ensure_async_token_provider(sync_provider)
+    result = await wrapper()
+
+    assert result == "sync-token"
+
+
+async def test_ensure_async_token_provider_wraps_async_provider() -> None:
+    async def async_provider() -> str:
+        return "async-token"
+
+    wrapper = _ensure_async_token_provider(async_provider)
+    result = await wrapper()
+
+    assert result == "async-token"