Python: [BREAKING]: removed display_name, renamed context_providers, middleware and AggregateContextProvider (#3139)

* removed display_name, renamed context_providers, middleware and AggregateContextProvider

* fixes

* fixed test

* testfix

* removed mistakenly put back test

* updated new test

* rename middlewares to middleware

* middleware fixes

python/samples/getting_started/agents/custom/custom_agent.py

@@ -158,7 +158,6 @@ async def main() -> None:
     # Test non-streaming
     print(f"Agent Name: {echo_agent.name}")
     print(f"Agent ID: {echo_agent.id}")
-    print(f"Display Name: {echo_agent.display_name}")
 
     query = "Hello, custom agent!"
     print(f"\nUser: {query}")

python/samples/getting_started/agents/custom/custom_chat_client.py

@@ -123,7 +123,6 @@ async def main() -> None:
     )
 
     print(f"\nAgent Name: {echo_agent.name}")
-    print(f"Agent Display Name: {echo_agent.display_name}")
 
     # Test non-streaming with agent
     query = "This is a test message"

python/samples/getting_started/context_providers/aggregate_context_provider.py

@@ -0,0 +1,276 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+This sample demonstrates how to use an AggregateContextProvider to combine multiple context providers.
+
+The AggregateContextProvider is a convenience class that allows you to aggregate multiple
+ContextProviders into a single provider. It delegates events to all providers and combines
+their context before returning.
+
+You can use this implementation as-is, or implement your own aggregation logic.
+"""
+
+import asyncio
+import sys
+from collections.abc import MutableSequence, Sequence
+from contextlib import AsyncExitStack
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, cast
+
+from agent_framework import ChatAgent, ChatMessage, Context, ContextProvider
+from agent_framework.azure import AzureAIClient
+from azure.identity.aio import AzureCliCredential
+
+if TYPE_CHECKING:
+    from agent_framework import ToolProtocol
+
+if sys.version_info >= (3, 12):
+    from typing import override  # type: ignore # pragma: no cover
+else:
+    from typing_extensions import override  # type: ignore[import] # pragma: no cover
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+
+# region AggregateContextProvider
+
+
+class AggregateContextProvider(ContextProvider):
+    """A ContextProvider that contains multiple context providers.
+
+    It delegates events to multiple context providers and aggregates responses from those
+    events before returning. This allows you to combine multiple context providers into a
+    single provider.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework import ChatAgent
+
+            # Create multiple context providers
+            provider1 = CustomContextProvider1()
+            provider2 = CustomContextProvider2()
+            provider3 = CustomContextProvider3()
+
+            # Combine them using AggregateContextProvider
+            aggregate = AggregateContextProvider([provider1, provider2, provider3])
+
+            # Pass the aggregate to the agent
+            agent = ChatAgent(chat_client=client, name="assistant", context_provider=aggregate)
+
+            # You can also add more providers later
+            provider4 = CustomContextProvider4()
+            aggregate.add(provider4)
+    """
+
+    def __init__(self, context_providers: ContextProvider | Sequence[ContextProvider] | None = None) -> None:
+        """Initialize the AggregateContextProvider with context providers.
+
+        Args:
+            context_providers: The context provider(s) to add.
+        """
+        if isinstance(context_providers, ContextProvider):
+            self.providers = [context_providers]
+        else:
+            self.providers = cast(list[ContextProvider], context_providers) or []
+        self._exit_stack: AsyncExitStack | None = None
+
+    def add(self, context_provider: ContextProvider) -> None:
+        """Add a new context provider.
+
+        Args:
+            context_provider: The context provider to add.
+        """
+        self.providers.append(context_provider)
+
+    @override
+    async def thread_created(self, thread_id: str | None = None) -> None:
+        await asyncio.gather(*[x.thread_created(thread_id) for x in self.providers])
+
+    @override
+    async def invoking(self, messages: ChatMessage | MutableSequence[ChatMessage], **kwargs: Any) -> Context:
+        contexts = await asyncio.gather(*[provider.invoking(messages, **kwargs) for provider in self.providers])
+        instructions: str = ""
+        return_messages: list[ChatMessage] = []
+        tools: list["ToolProtocol"] = []
+        for ctx in contexts:
+            if ctx.instructions:
+                instructions += ctx.instructions
+            if ctx.messages:
+                return_messages.extend(ctx.messages)
+            if ctx.tools:
+                tools.extend(ctx.tools)
+        return Context(instructions=instructions, messages=return_messages, tools=tools)
+
+    @override
+    async def invoked(
+        self,
+        request_messages: ChatMessage | Sequence[ChatMessage],
+        response_messages: ChatMessage | Sequence[ChatMessage] | None = None,
+        invoke_exception: Exception | None = None,
+        **kwargs: Any,
+    ) -> None:
+        await asyncio.gather(*[
+            x.invoked(
+                request_messages=request_messages,
+                response_messages=response_messages,
+                invoke_exception=invoke_exception,
+                **kwargs,
+            )
+            for x in self.providers
+        ])
+
+    @override
+    async def __aenter__(self) -> "Self":
+        """Enter the async context manager and set up all providers.
+
+        Returns:
+            The AggregateContextProvider instance for chaining.
+        """
+        self._exit_stack = AsyncExitStack()
+        await self._exit_stack.__aenter__()
+
+        # Enter all context providers
+        for provider in self.providers:
+            await self._exit_stack.enter_async_context(provider)
+
+        return self
+
+    @override
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Exit the async context manager and clean up all providers.
+
+        Args:
+            exc_type: The exception type if an exception occurred, None otherwise.
+            exc_val: The exception value if an exception occurred, None otherwise.
+            exc_tb: The exception traceback if an exception occurred, None otherwise.
+        """
+        if self._exit_stack is not None:
+            await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
+            self._exit_stack = None
+
+
+# endregion
+
+
+# region Example Context Providers
+
+
+class TimeContextProvider(ContextProvider):
+    """A simple context provider that adds time-related instructions."""
+
+    @override
+    async def invoking(self, messages: ChatMessage | MutableSequence[ChatMessage], **kwargs: Any) -> Context:
+        from datetime import datetime
+
+        current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return Context(instructions=f"The current date and time is: {current_time}. ")
+
+
+class PersonaContextProvider(ContextProvider):
+    """A context provider that adds a persona to the agent."""
+
+    def __init__(self, persona: str):
+        self.persona = persona
+
+    @override
+    async def invoking(self, messages: ChatMessage | MutableSequence[ChatMessage], **kwargs: Any) -> Context:
+        return Context(instructions=f"Your persona: {self.persona}. ")
+
+
+class PreferencesContextProvider(ContextProvider):
+    """A context provider that adds user preferences."""
+
+    def __init__(self):
+        self.preferences: dict[str, str] = {}
+
+    @override
+    async def invoking(self, messages: ChatMessage | MutableSequence[ChatMessage], **kwargs: Any) -> Context:
+        if not self.preferences:
+            return Context()
+        prefs_str = ", ".join(f"{k}: {v}" for k, v in self.preferences.items())
+        return Context(instructions=f"User preferences: {prefs_str}. ")
+
+    @override
+    async def invoked(
+        self,
+        request_messages: ChatMessage | Sequence[ChatMessage],
+        response_messages: ChatMessage | Sequence[ChatMessage] | None = None,
+        invoke_exception: Exception | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Simple example: extract and store preferences from user messages
+        # In a real implementation, you might use structured extraction
+        msgs = [request_messages] if isinstance(request_messages, ChatMessage) else list(request_messages)
+
+        for msg in msgs:
+            content = msg.content if hasattr(msg, "content") else ""
+            # Very simple extraction - in production, use LLM-based extraction
+            if isinstance(content, str) and "prefer" in content.lower() and ":" in content:
+                parts = content.split(":")
+                if len(parts) >= 2:
+                    key = parts[0].strip().lower().replace("i prefer ", "")
+                    value = parts[1].strip()
+                    self.preferences[key] = value
+
+
+# endregion
+
+
+# region Main
+
+
+async def main():
+    """Demonstrate using AggregateContextProvider to combine multiple providers."""
+    async with AzureCliCredential() as credential:
+        chat_client = AzureAIClient(credential=credential)
+
+        # Create individual context providers
+        time_provider = TimeContextProvider()
+        persona_provider = PersonaContextProvider("You are a helpful and friendly AI assistant named Max.")
+        preferences_provider = PreferencesContextProvider()
+
+        # Combine them using AggregateContextProvider
+        aggregate_provider = AggregateContextProvider([
+            time_provider,
+            persona_provider,
+            preferences_provider,
+        ])
+
+        # Create the agent with the aggregate provider
+        async with ChatAgent(
+            chat_client=chat_client,
+            instructions="You are a helpful assistant.",
+            context_provider=aggregate_provider,
+        ) as agent:
+            # Create a new thread for the conversation
+            thread = agent.get_new_thread()
+
+            # First message - the agent should include time and persona context
+            print("User: Hello! Who are you?")
+            result = await agent.run("Hello! Who are you?", thread=thread)
+            print(f"Agent: {result}\n")
+
+            # Set a preference
+            print("User: I prefer language: formal English")
+            result = await agent.run("I prefer language: formal English", thread=thread)
+            print(f"Agent: {result}\n")
+
+            # Ask something - the agent should now include the preference
+            print("User: Can you tell me a fun fact?")
+            result = await agent.run("Can you tell me a fun fact?", thread=thread)
+            print(f"Agent: {result}\n")
+
+            # Show what the aggregate provider is tracking
+            print(f"\nPreferences tracked: {preferences_provider.preferences}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/context_providers/azure_ai_search/README.md

@@ -144,7 +144,7 @@ async with AzureAIAgentClient(credential=DefaultAzureCredential()) as client:
     async with ChatAgent(
         chat_client=client,
         model=model_deployment,
-        context_providers=search_provider,
+        context_provider=search_provider,
     ) as agent:
         response = await agent.run("What information is in the knowledge base?")
 ```
@@ -169,7 +169,7 @@ search_provider = AzureAISearchContextProvider(
 async with ChatAgent(
     chat_client=client,
     model=model_deployment,
-    context_providers=search_provider,
+    context_provider=search_provider,
 ) as agent:
     response = await agent.run("Analyze and compare topics across documents")
 ```

python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_agentic.py

@@ -120,7 +120,7 @@ async def main() -> None:
                 "Use the provided context from the knowledge base to answer complex "
                 "questions that may require synthesizing information from multiple sources."
             ),
-            context_providers=[search_provider],
+            context_provider=search_provider,
         ) as agent,
     ):
         print("=== Azure AI Agent with Search Context (Agentic Mode) ===\n")

python/samples/getting_started/context_providers/azure_ai_search/azure_ai_with_search_context_semantic.py

@@ -76,7 +76,7 @@ async def main() -> None:
                 "You are a helpful assistant. Use the provided context from the "
                 "knowledge base to answer questions accurately."
             ),
-            context_providers=[search_provider],
+            context_provider=search_provider,
         ) as agent,
     ):
         print("=== Azure AI Agent with Search Context (Semantic Mode) ===\n")

python/samples/getting_started/context_providers/mem0/mem0_basic.py

@@ -36,7 +36,7 @@ async def main() -> None:
             name="FriendlyAssistant",
             instructions="You are a friendly assistant.",
             tools=retrieve_company_report,
-            context_providers=Mem0Provider(user_id=user_id),
+            context_provider=Mem0Provider(user_id=user_id),
         ) as agent,
     ):
         # First ask the agent to retrieve a company report with no previous context.

python/samples/getting_started/context_providers/mem0/mem0_oss.py

@@ -39,7 +39,7 @@ async def main() -> None:
             name="FriendlyAssistant",
             instructions="You are a friendly assistant.",
             tools=retrieve_company_report,
-            context_providers=Mem0Provider(user_id=user_id, mem0_client=local_mem0_client),
+            context_provider=Mem0Provider(user_id=user_id, mem0_client=local_mem0_client),
         ) as agent,
     ):
         # First ask the agent to retrieve a company report with no previous context.

python/samples/getting_started/context_providers/mem0/mem0_threads.py

@@ -31,7 +31,7 @@ async def example_global_thread_scope() -> None:
             name="GlobalMemoryAssistant",
             instructions="You are an assistant that remembers user preferences across conversations.",
             tools=get_user_preferences,
-            context_providers=Mem0Provider(
+            context_provider=Mem0Provider(
                 user_id=user_id,
                 thread_id=global_thread_id,
                 scope_to_per_operation_thread_id=False,  # Share memories across all threads
@@ -69,7 +69,7 @@ async def example_per_operation_thread_scope() -> None:
             name="ScopedMemoryAssistant",
             instructions="You are an assistant with thread-scoped memory.",
             tools=get_user_preferences,
-            context_providers=Mem0Provider(
+            context_provider=Mem0Provider(
                 user_id=user_id,
                 scope_to_per_operation_thread_id=True,  # Isolate memories per thread
             ),
@@ -116,14 +116,14 @@ async def example_multiple_agents() -> None:
         AzureAIAgentClient(credential=credential).create_agent(
             name="PersonalAssistant",
             instructions="You are a personal assistant that helps with personal tasks.",
-            context_providers=Mem0Provider(
+            context_provider=Mem0Provider(
                 agent_id=agent_id_1,
             ),
         ) as personal_agent,
         AzureAIAgentClient(credential=credential).create_agent(
             name="WorkAssistant",
             instructions="You are a work assistant that helps with professional tasks.",
-            context_providers=Mem0Provider(
+            context_provider=Mem0Provider(
                 agent_id=agent_id_2,
             ),
         ) as work_agent,

python/samples/getting_started/context_providers/redis/redis_basics.py

@@ -185,7 +185,7 @@ async def main() -> None:
             "Before answering, always check for stored context"
         ),
         tools=[],
-        context_providers=provider,
+        context_provider=provider,
     )
 
     # Teach a user preference; the agent writes this to the provider's memory
@@ -227,7 +227,7 @@ async def main() -> None:
             "Before answering, always check for stored context"
         ),
         tools=search_flights,
-        context_providers=provider,
+        context_provider=provider,
     )
     # Invoke the tool; outputs become part of memory/context
     query = "Are there any flights from new york city (jfk) to la? Give me details"

python/samples/getting_started/context_providers/redis/redis_conversation.py

@@ -70,7 +70,7 @@ async def main() -> None:
             "Before answering, always check for stored context"
         ),
         tools=[],
-        context_providers=provider,
+        context_provider=provider,
         chat_message_store_factory=chat_message_store_factory,
     )
 

python/samples/getting_started/context_providers/redis/redis_threads.py

@@ -70,7 +70,7 @@ async def example_global_thread_scope() -> None:
             "Before answering, always check for stored context containing information"
         ),
         tools=[],
-        context_providers=provider,
+        context_provider=provider,
     )
 
     # Store a preference in the global scope
@@ -128,7 +128,7 @@ async def example_per_operation_thread_scope() -> None:
     agent = client.create_agent(
         name="ScopedMemoryAssistant",
         instructions="You are an assistant with thread-scoped memory.",
-        context_providers=provider,
+        context_provider=provider,
     )
 
     # Create a specific thread for this scoped provider
@@ -193,7 +193,7 @@ async def example_multiple_agents() -> None:
     personal_agent = client.create_agent(
         name="PersonalAssistant",
         instructions="You are a personal assistant that helps with personal tasks.",
-        context_providers=personal_provider,
+        context_provider=personal_provider,
     )
 
     work_provider = RedisProvider(
@@ -211,7 +211,7 @@ async def example_multiple_agents() -> None:
     work_agent = client.create_agent(
         name="WorkAssistant",
         instructions="You are a work assistant that helps with professional tasks.",
-        context_providers=work_provider,
+        context_provider=work_provider,
     )
 
     # Store personal information

python/samples/getting_started/context_providers/simple_context_provider.py

@@ -100,7 +100,7 @@ async def main():
         async with ChatAgent(
             chat_client=chat_client,
             instructions="You are a friendly assistant. Always address the user by their name.",
-            context_providers=memory_provider,
+            context_provider=memory_provider,
         ) as agent:
             # Create a new thread for the conversation
             thread = agent.get_new_thread()

python/samples/getting_started/middleware/agent_and_run_level_middleware.py

@@ -202,7 +202,7 @@ async def main() -> None:
         print(f"User: {query}")
         result = await agent.run(
             query,
-            middleware=HighPriorityMiddleware(),  # Run-level middleware
+            middleware=[HighPriorityMiddleware()],  # Run-level middleware
         )
         print(f"Agent: {result.text if result.text else 'No response'}")
         print()

python/samples/getting_started/middleware/chat_middleware.py

@@ -146,7 +146,7 @@ async def class_based_chat_middleware() -> None:
             name="EnhancedChatAgent",
             instructions="You are a helpful AI assistant.",
             # Register class-based middleware at agent level (applies to all runs)
-            middleware=InputObserverMiddleware(),
+            middleware=[InputObserverMiddleware()],
             tools=get_weather,
         ) as agent,
     ):
@@ -168,7 +168,7 @@ async def function_based_chat_middleware() -> None:
             name="FunctionMiddlewareAgent",
             instructions="You are a helpful AI assistant.",
             # Register function-based middleware at agent level
-            middleware=security_and_override_middleware,
+            middleware=[security_and_override_middleware],
         ) as agent,
     ):
         # Scenario with normal query
@@ -226,7 +226,7 @@ async def run_level_middleware() -> None:
         print(f"User: {query}")
         result = await agent.run(
             query,
-            middleware=security_and_override_middleware,
+            middleware=[security_and_override_middleware],
         )
         print(f"Response: {result.text if result.text else 'No response'}")
 

python/samples/getting_started/middleware/exception_handling_with_middleware.py

@@ -62,7 +62,7 @@ async def main() -> None:
             name="DataAgent",
             instructions="You are a helpful data assistant. Use the data service tool to fetch information for users.",
             tools=unstable_data_service,
-            middleware=exception_handling_middleware,
+            middleware=[exception_handling_middleware],
         ) as agent,
     ):
         query = "Get user statistics"

python/samples/getting_started/middleware/middleware_termination.py

@@ -114,7 +114,7 @@ async def pre_termination_middleware() -> None:
             name="WeatherAgent",
             instructions="You are a helpful weather assistant.",
             tools=get_weather,
-            middleware=PreTerminationMiddleware(blocked_words=["bad", "inappropriate"]),
+            middleware=[PreTerminationMiddleware(blocked_words=["bad", "inappropriate"])],
         ) as agent,
     ):
         # Test with normal query
@@ -141,7 +141,7 @@ async def post_termination_middleware() -> None:
             name="WeatherAgent",
             instructions="You are a helpful weather assistant.",
             tools=get_weather,
-            middleware=PostTerminationMiddleware(max_responses=1),
+            middleware=[PostTerminationMiddleware(max_responses=1)],
         ) as agent,
     ):
         # First run (should work)

python/samples/getting_started/middleware/override_result_with_middleware.py

@@ -87,7 +87,7 @@ async def main() -> None:
             name="WeatherAgent",
             instructions="You are a helpful weather assistant. Use the weather tool to get current conditions.",
             tools=get_weather,
-            middleware=weather_override_middleware,
+            middleware=[weather_override_middleware],
         ) as agent,
     ):
         # Non-streaming example

python/samples/getting_started/middleware/thread_behavior_middleware.py

@@ -74,7 +74,7 @@ async def main() -> None:
         name="WeatherAgent",
         instructions="You are a helpful weather assistant.",
         tools=get_weather,
-        middleware=thread_tracking_middleware,
+        middleware=[thread_tracking_middleware],
         # Configure agent with message store factory to persist conversation history
         chat_message_store_factory=ChatMessageStore,
     )

python/samples/getting_started/observability/agent_observability.py

@@ -47,7 +47,7 @@ async def main():
         thread = agent.get_new_thread()
         for question in questions:
             print(f"\nUser: {question}")
-            print(f"{agent.display_name}: ", end="")
+            print(f"{agent.name}: ", end="")
             async for update in agent.run_stream(
                 question,
                 thread=thread,

python/samples/getting_started/observability/agent_with_foundry_tracing.py

@@ -84,7 +84,7 @@ async def main():
             thread = agent.get_new_thread()
             for question in questions:
                 print(f"\nUser: {question}")
-                print(f"{agent.display_name}: ", end="")
+                print(f"{agent.name}: ", end="")
                 async for update in agent.run_stream(
                     question,
                     thread=thread,

python/samples/getting_started/observability/azure_ai_agent_observability.py

@@ -64,7 +64,7 @@ async def main():
             thread = agent.get_new_thread()
             for question in questions:
                 print(f"\nUser: {question}")
-                print(f"{agent.display_name}: ", end="")
+                print(f"{agent.name}: ", end="")
                 async for update in agent.run_stream(
                     question,
                     thread=thread,

python/samples/getting_started/purview_agent/README.md

@@ -116,18 +116,18 @@ This is only needed if you want to integrate with external caching systems.
 ```python
 class SimpleDictCacheProvider:
     """Custom cache provider that implements the CacheProvider protocol."""
-    
+
     def __init__(self) -> None:
         self._cache: dict[str, Any] = {}
-    
+
     async def get(self, key: str) -> Any | None:
         """Get a value from the cache."""
         return self._cache.get(key)
-    
+
     async def set(self, key: str, value: Any, ttl_seconds: int | None = None) -> None:
         """Set a value in the cache."""
         self._cache[key] = value
-    
+
     async def remove(self, key: str) -> None:
         """Remove a value from the cache."""
         self._cache.pop(key, None)

python/samples/getting_started/purview_agent/sample_purview_agent.py

@@ -154,7 +154,7 @@ async def run_with_agent_middleware() -> None:
         chat_client=chat_client,
         instructions=JOKER_INSTRUCTIONS,
         name=JOKER_NAME,
-        middleware=purview_agent_middleware,
+        middleware=[purview_agent_middleware],
     )
 
     print("-- Agent Middleware Path --")
@@ -239,7 +239,7 @@ async def run_with_custom_cache_provider() -> None:
         chat_client=chat_client,
         instructions=JOKER_INSTRUCTIONS,
         name=JOKER_NAME,
-        middleware=purview_agent_middleware,
+        middleware=[purview_agent_middleware],
     )
 
     print("-- Custom Cache Provider Path --")
@@ -279,7 +279,7 @@ async def run_with_custom_cache_provider() -> None:
         chat_client=chat_client,
         instructions=JOKER_INSTRUCTIONS,
         name=JOKER_NAME,
-        middleware=purview_agent_middleware,
+        middleware=[purview_agent_middleware],
     )
 
     print("-- Default Cache Path --")