Rename Bare*Client to Raw*Client and BaseChatClient

- Renamed BareChatClient to BaseChatClient (abstract base class)
- Renamed BareOpenAIChatClient to RawOpenAIChatClient
- Renamed BareOpenAIResponsesClient to RawOpenAIResponsesClient
- Renamed BareAzureAIClient to RawAzureAIClient
- Added warning docstrings to Raw* classes about layer ordering
- Updated README in samples/getting_started/agents/custom with layer docs
- Added test for span ordering with function calling

Author: eavanvalkenburg

docs/decisions/0012-python-typeddict-options.md

@@ -126,4 +126,4 @@ response = await client.get_response(
 
 Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods.
 
-See [typed_options.py](../../python/samples/getting_started/chat_client/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.
+See [typed_options.py](../../python/samples/concepts/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.

python/packages/ag-ui/agent_framework_ag_ui/_client.py

@@ -12,7 +12,7 @@
 
 import httpx
 from agent_framework import (
-    BareChatClient,
+    BaseChatClient,
     ChatMessage,
     ChatResponse,
     ChatResponseUpdate,
@@ -57,7 +57,7 @@ def _unwrap_server_function_call_contents(contents: MutableSequence[Content | di
             contents[idx] = content.function_call  # type: ignore[assignment, union-attr]
 
 
-TBareChatClient = TypeVar("TBareChatClient", bound=type[BareChatClient[Any]])
+TBaseChatClient = TypeVar("TBaseChatClient", bound=type[BaseChatClient[Any]])
 
 TAGUIChatOptions = TypeVar(
     "TAGUIChatOptions",
@@ -67,7 +67,7 @@ def _unwrap_server_function_call_contents(contents: MutableSequence[Content | di
 )
 
 
-def _apply_server_function_call_unwrap(chat_client: TBareChatClient) -> TBareChatClient:
+def _apply_server_function_call_unwrap(chat_client: TBaseChatClient) -> TBaseChatClient:
     """Class decorator that unwraps server-side function calls after tool handling."""
 
     original_get_response = chat_client.get_response
@@ -112,12 +112,12 @@ class AGUIChatClient(
     ChatMiddlewareLayer[TAGUIChatOptions],
     ChatTelemetryLayer[TAGUIChatOptions],
     FunctionInvocationLayer[TAGUIChatOptions],
-    BareChatClient[TAGUIChatOptions],
+    BaseChatClient[TAGUIChatOptions],
     Generic[TAGUIChatOptions],
 ):
     """Chat client for communicating with AG-UI compliant servers.
 
-    This client implements the BareChatClient interface and automatically handles:
+    This client implements the BaseChatClient interface and automatically handles:
     - Thread ID management for conversation continuity
     - State synchronization between client and server
     - Server-Sent Events (SSE) streaming
@@ -229,7 +229,7 @@ def __init__(
             additional_properties: Additional properties to store
             middleware: Optional middleware to apply to the client.
             function_invocation_configuration: Optional function invocation configuration override.
-            **kwargs: Additional arguments passed to BareChatClient
+            **kwargs: Additional arguments passed to BaseChatClient
         """
         super().__init__(
             additional_properties=additional_properties,

python/packages/ag-ui/agent_framework_ag_ui/_orchestration/_tooling.py

@@ -5,7 +5,7 @@
 import logging
 from typing import TYPE_CHECKING, Any
 
-from agent_framework import BareChatClient
+from agent_framework import BaseChatClient
 
 if TYPE_CHECKING:
     from agent_framework import AgentProtocol
@@ -79,7 +79,7 @@ def register_additional_client_tools(agent: "AgentProtocol", client_tools: list[
     if chat_client is None:
         return
 
-    if isinstance(chat_client, BareChatClient) and chat_client.function_invocation_configuration is not None:  # type: ignore[attr-defined]
+    if isinstance(chat_client, BaseChatClient) and chat_client.function_invocation_configuration is not None:  # type: ignore[attr-defined]
         chat_client.function_invocation_configuration["additional_tools"] = client_tools  # type: ignore[attr-defined]
         logger.debug(f"[TOOLS] Registered {len(client_tools)} client tools as additional_tools (declaration-only)")
 

python/packages/ag-ui/getting_started/README.md

@@ -350,7 +350,7 @@ if __name__ == "__main__":
 
 ### Key Concepts
 
-- **`AGUIChatClient`**: Built-in client that implements the Agent Framework's `BareChatClient` interface
+- **`AGUIChatClient`**: Built-in client that implements the Agent Framework's `BaseChatClient` interface
 - **Automatic Event Handling**: The client automatically converts AG-UI events to Agent Framework types
 - **Thread Management**: Pass `thread_id` in metadata to maintain conversation context across requests
 - **Streaming Responses**: Use `get_streaming_response()` for real-time streaming or `get_response()` for non-streaming

python/packages/ag-ui/tests/conftest.py

@@ -12,7 +12,7 @@
     AgentResponse,
     AgentResponseUpdate,
     AgentThread,
-    BareChatClient,
+    BaseChatClient,
     ChatMessage,
     ChatResponse,
     ChatResponseUpdate,
@@ -37,7 +37,7 @@ class StreamingChatClientStub(
     ChatMiddlewareLayer[TOptions_co],
     ChatTelemetryLayer[TOptions_co],
     FunctionInvocationLayer[TOptions_co],
-    BareChatClient[TOptions_co],
+    BaseChatClient[TOptions_co],
     Generic[TOptions_co],
 ):
     """Typed streaming stub that satisfies ChatClientProtocol."""

python/packages/ag-ui/tests/test_tooling.py

@@ -54,9 +54,9 @@ def test_merge_tools_filters_duplicates() -> None:
 
 def test_register_additional_client_tools_assigns_when_configured() -> None:
     """register_additional_client_tools should set additional_tools on the chat client."""
-    from agent_framework import BareChatClient, normalize_function_invocation_configuration
+    from agent_framework import BaseChatClient, normalize_function_invocation_configuration
 
-    mock_chat_client = MagicMock(spec=BareChatClient)
+    mock_chat_client = MagicMock(spec=BaseChatClient)
     mock_chat_client.function_invocation_configuration = normalize_function_invocation_configuration(None)
 
     agent = ChatAgent(chat_client=mock_chat_client)

python/packages/anthropic/agent_framework_anthropic/_chat_client.py

@@ -7,7 +7,7 @@
 from agent_framework import (
     AGENT_FRAMEWORK_USER_AGENT,
     Annotation,
-    BareChatClient,
+    BaseChatClient,
     ChatLevelMiddleware,
     ChatMessage,
     ChatMiddlewareLayer,
@@ -233,7 +233,7 @@ class AnthropicClient(
     ChatMiddlewareLayer[TAnthropicOptions],
     ChatTelemetryLayer[TAnthropicOptions],
     FunctionInvocationLayer[TAnthropicOptions],
-    BareChatClient[TAnthropicOptions],
+    BaseChatClient[TAnthropicOptions],
     Generic[TAnthropicOptions],
 ):
     """Anthropic Chat client with middleware, telemetry, and function invocation support."""

python/packages/azure-ai/agent_framework_azure_ai/__init__.py

@@ -4,7 +4,7 @@
 
 from ._agent_provider import AzureAIAgentsProvider
 from ._chat_client import AzureAIAgentClient, AzureAIAgentOptions
-from ._client import AzureAIClient, AzureAIProjectAgentOptions, BareAzureAIClient
+from ._client import AzureAIClient, AzureAIProjectAgentOptions, RawAzureAIClient
 from ._project_provider import AzureAIProjectAgentProvider
 from ._shared import AzureAISettings
 
@@ -21,6 +21,6 @@
     "AzureAIProjectAgentOptions",
     "AzureAIProjectAgentProvider",
     "AzureAISettings",
-    "BareAzureAIClient",
+    "RawAzureAIClient",
     "__version__",
 ]

python/packages/azure-ai/agent_framework_azure_ai/_chat_client.py

@@ -11,7 +11,7 @@
 from agent_framework import (
     AGENT_FRAMEWORK_USER_AGENT,
     Annotation,
-    BareChatClient,
+    BaseChatClient,
     ChatAgent,
     ChatLevelMiddleware,
     ChatMessage,
@@ -206,7 +206,7 @@ class AzureAIAgentClient(
     ChatMiddlewareLayer[TAzureAIAgentOptions],
     ChatTelemetryLayer[TAzureAIAgentOptions],
     FunctionInvocationLayer[TAzureAIAgentOptions],
-    BareChatClient[TAzureAIAgentOptions],
+    BaseChatClient[TAzureAIAgentOptions],
     Generic[TAzureAIAgentOptions],
 ):
     """Azure AI Agent Chat client with middleware, telemetry, and function invocation support."""

python/packages/azure-ai/agent_framework_azure_ai/_client.py

@@ -22,7 +22,7 @@
 from agent_framework.exceptions import ServiceInitializationError
 from agent_framework.observability import ChatTelemetryLayer
 from agent_framework.openai import OpenAIResponsesOptions
-from agent_framework.openai._responses_client import BareOpenAIResponsesClient
+from agent_framework.openai._responses_client import RawOpenAIResponsesClient
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import MCPTool, PromptAgentDefinition, PromptAgentDefinitionText, RaiConfig, Reasoning
 from azure.core.credentials_async import AsyncTokenCredential
@@ -66,11 +66,20 @@ class AzureAIProjectAgentOptions(OpenAIResponsesOptions, total=False):
 )
 
 
-class BareAzureAIClient(BareOpenAIResponsesClient[TAzureAIClientOptions], Generic[TAzureAIClientOptions]):
-    """Bare Azure AI client without middleware, telemetry, or function invocation layers.
+class RawAzureAIClient(RawOpenAIResponsesClient[TAzureAIClientOptions], Generic[TAzureAIClientOptions]):
+    """Raw Azure AI client without middleware, telemetry, or function invocation layers.
 
-    This class provides the core Azure AI functionality. For most use cases,
-    prefer :class:`AzureAIClient` which includes all standard layers.
+    Warning:
+        **This class should not normally be used directly.** It does not include middleware,
+        telemetry, or function invocation support that you most likely need. If you do use it,
+        you should consider which additional layers to apply. There is a defined ordering that
+        you should follow:
+
+        1. **ChatMiddlewareLayer** - Should be applied first as it also prepares function middleware
+        2. **ChatTelemetryLayer** - Telemetry will not be correct if applied outside the function calling loop
+        3. **FunctionInvocationLayer** - Handles tool/function calling
+
+        Use ``AzureAIClient`` instead for a fully-featured client with all layers applied.
     """
 
     OTEL_PROVIDER_NAME: ClassVar[str] = "azure.ai"  # type: ignore[reportIncompatibleVariableOverride, misc]
@@ -603,7 +612,7 @@ class AzureAIClient(
     ChatMiddlewareLayer[TAzureAIClientOptions],
     ChatTelemetryLayer[TAzureAIClientOptions],
     FunctionInvocationLayer[TAzureAIClientOptions],
-    BareAzureAIClient[TAzureAIClientOptions],
+    RawAzureAIClient[TAzureAIClientOptions],
     Generic[TAzureAIClientOptions],
 ):
     """Azure AI client with middleware, telemetry, and function invocation support.
@@ -613,7 +622,7 @@ class AzureAIClient(
     - OpenTelemetry-based telemetry for observability
     - Automatic function/tool invocation handling
 
-    For a minimal implementation without these features, use :class:`BareAzureAIClient`.
+    For a minimal implementation without these features, use :class:`RawAzureAIClient`.
     """
 
     def __init__(