Python: [BREAKING] Python: Provider-leading client design & OpenAI package extraction (#4818)

* Python: Provider-leading client design & OpenAI package extraction

Major refactoring of the Python Agent Framework client architecture:

- Extract OpenAI clients into new `agent-framework-openai` package
- Core package no longer depends on openai, azure-identity, azure-ai-projects
- Rename clients for discoverability: OpenAIResponsesClient → OpenAIChatClient,
  OpenAIChatClient → OpenAIChatCompletionClient
- Unify `model_id`/`deployment_name`/`model_deployment_name` → `model` param
- New FoundryChatClient for Azure AI Foundry Responses API
- New FoundryAgent/FoundryAgentClient for connecting to pre-configured Foundry agents
- Remove OpenAIBase/OpenAIConfigMixin from non-deprecated client MRO
- Deprecate AzureOpenAI* clients, AzureAIClient, OpenAIAssistantsClient
- Reorganize samples: azure_openai+azure_ai+azure_ai_agent → azure/
- ADR-0020: Provider-Leading Client Design

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: missing Agent imports in samples, .model_id → .model in foundry_local sample

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: CI failures — mypy errors, coverage targets, sample imports

- azure-ai mypy: add type ignores for TypedDict total=, model arg, forward ref
- Coverage: replace core.azure/openai targets with openai package target
- project_provider: add type annotation for opts dict

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: populate openai .pyi stub, fix broken README links, coverage targets

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fixes

* updated observabilitty

* reset azure init.pyi

* fix errors

* updated adr number

* fix foundry local

* fixed not renamed docstrings and comments, and added deprecated markers to old classes

* fix tests and pyprojects

* fix test vars

* updated function tests

* update durable

* updated test setup for functions

* Fix Foundry auth in workflow samples

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Stabilize Python integration workflows

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Update hosting samples for Foundry

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Trigger full CI rerun

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Trigger CI rerun again

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* trigger rerun

* trigger rerun

* fix for litellm

* undo durabletask changes

* Move Foundry APIs into foundry namespace

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix Foundry pyproject formatting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Split provider samples by Foundry surface

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Restore hosting sample requirements

Also fix the Foundry Local sample link after the provider sample move.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* updated tests

* udpated foundry integration tests

* removed dist from azurefunctions tests

* Use separate Foundry clients for concurrent agents

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix client setup in azfunc and durable

* disabled two tests

* updated setup for some function and durable tests

* improved azure openai setup with new clients

* ignore deprecated

* fixes

* skip 11

* remove openai assistants int tests

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/samples/02-agents/conversations/custom_history_provider.py

@@ -4,7 +4,7 @@ import asyncio
 from collections.abc import Sequence
 from typing import Any
 
-from agent_framework import AgentSession, BaseHistoryProvider, Message
+from agent_framework import Agent, AgentSession, BaseHistoryProvider, Message
 from agent_framework.openai import OpenAIChatClient
 from dotenv import load_dotenv
 
@@ -54,7 +54,8 @@ async def main() -> None:
 
     # OpenAI Chat Client is used as an example here,
     # other chat clients can be used as well.
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="CustomBot",
         instructions="You are a helpful assistant that remembers our conversation.",
         # Use custom history provider.

python/samples/02-agents/conversations/redis_history_provider.py

@@ -4,7 +4,7 @@ import asyncio
 import os
 from uuid import uuid4
 
-from agent_framework import AgentSession
+from agent_framework import Agent, AgentSession
 from agent_framework.openai import OpenAIChatClient
 from agent_framework.redis import RedisHistoryProvider
 from dotenv import load_dotenv
@@ -36,7 +36,8 @@ async def example_manual_memory_store() -> None:
     )
 
     # Create agent with Redis history provider
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="RedisBot",
         instructions="You are a helpful assistant that remembers our conversation using Redis.",
         context_providers=[redis_provider],
@@ -75,7 +76,8 @@ async def example_user_session_management() -> None:
     )
 
     # Create agent with history provider
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="SessionBot",
         instructions="You are a helpful assistant. Keep track of user preferences.",
         context_providers=[redis_provider],
@@ -114,7 +116,8 @@ async def example_conversation_persistence() -> None:
         redis_url=REDIS_URL,
     )
 
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="PersistentBot",
         instructions="You are a helpful assistant. Remember our conversation history.",
         context_providers=[redis_provider],
@@ -163,7 +166,8 @@ async def example_session_serialization() -> None:
         redis_url=REDIS_URL,
     )
 
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="SerializationBot",
         instructions="You are a helpful assistant.",
         context_providers=[redis_provider],
@@ -206,7 +210,8 @@ async def example_message_limits() -> None:
         max_messages=3,  # Keep only 3 most recent messages
     )
 
-    agent = OpenAIChatClient().as_agent(
+    agent = Agent(
+        client=OpenAIChatClient(),
         name="LimitBot",
         instructions="You are a helpful assistant with limited memory.",
         context_providers=[redis_provider],

python/samples/02-agents/conversations/suspend_resume_session.py

@@ -2,9 +2,8 @@
 
 import asyncio
 
-from agent_framework import AgentSession
-from agent_framework.azure import AzureAIAgentClient
-from agent_framework.openai import OpenAIChatClient
+from agent_framework import Agent, AgentSession
+from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import AzureCliCredential
 from dotenv import load_dotenv
 
@@ -24,11 +23,13 @@ async def suspend_resume_service_managed_session() -> None:
     """Demonstrates how to suspend and resume a service-managed session."""
     print("=== Suspend-Resume Service-Managed Session ===")
 
-    # AzureAIAgentClient supports service-managed sessions.
+    # FoundryChatClient supports service-managed sessions.
     async with (
         AzureCliCredential() as credential,
-        AzureAIAgentClient(credential=credential).as_agent(
-            name="MemoryBot", instructions="You are a helpful assistant that remembers our conversation."
+        Agent(
+            client=FoundryChatClient(credential=credential),
+            name="MemoryBot",
+            instructions="You are a helpful assistant that remembers our conversation.",
         ) as agent,
     ):
         # Start a new session for the agent conversation.
@@ -60,8 +61,10 @@ async def suspend_resume_in_memory_session() -> None:
 
     # OpenAI Chat Client is used as an example here,
     # other chat clients can be used as well.
-    agent = OpenAIChatClient().as_agent(
-        name="MemoryBot", instructions="You are a helpful assistant that remembers our conversation."
+    agent = Agent(
+        client=FoundryChatClient(),
+        name="MemoryBot",
+        instructions="You are a helpful assistant that remembers our conversation.",
     )
 
     # Start a new session for the agent conversation.