Update agent framework docs for GA: middleware, providers, orchestrations, and Python parity (#928)

* Update agent framework docs for GA: middleware, providers, orchestrations, and Python parity

Source issue: microsoft/agent-framework#4806

* Address review feedback for #928: review comment fixes

* Address review feedback for #928: review comment fixes

---------

Co-authored-by: MAF Dashboard Bot <maf-dashboard-bot@users.noreply.github.com>

Author: moonbox3

agent-framework/agents/agent-pipeline.md

@@ -5,7 +5,7 @@ zone_pivot_groups: programming-languages
 author: eavanvalkenburg
 ms.topic: conceptual
 ms.author: edvan
-ms.date: 03/11/2026
+ms.date: 03/20/2026
 ms.service: agent-framework
 ---
 
@@ -45,8 +45,8 @@ The `Agent` class builds a pipeline through class composition with two main comp
 
 **ChatClient** (separate and interchangeable component):
 
-1. **Chat Middleware + Telemetry** - Optional middleware chain and instrumentation layers
-2. **FunctionInvocation** - Handles tool calling loop, invoking Function Middleware + Telemetry per tool call
+1. **FunctionInvocation** - Handles tool calling loop, invoking Function Middleware + Telemetry per tool call
+2. **Chat Middleware + Telemetry** - Optional middleware chain and instrumentation layers, running per model call
 3. **RawChatClient** - Provider-specific implementation (Azure OpenAI, OpenAI, Anthropic, etc.) that communicates with the LLM
 
 When you call `run()`, your request flows through the Agent layers, then into the ChatClient pipeline for LLM communication.
@@ -231,9 +231,9 @@ When you invoke an agent, the request flows through the pipeline:
 
 **ChatClient pipeline:**
 
-4. **Chat Middleware + Telemetry** executes (if configured)
-5. **FunctionInvocation** sends request to the LLM and handles tool calling loop
+4. **FunctionInvocation** manages the tool calling loop
    - For each tool call, **Function Middleware + Telemetry** executes
+5. **Chat Middleware + Telemetry** executes per model call (if configured)
 6. **RawChatClient** handles provider-specific LLM communication
 7. Response flows back through the same layers
 8. **Context providers** are notified of new messages for storage

agent-framework/agents/middleware/index.md

@@ -5,7 +5,7 @@ zone_pivot_groups: programming-languages
 author: dmytrostruk
 ms.topic: reference
 ms.author: dmytrostruk
-ms.date: 03/16/2026
+ms.date: 03/20/2026
 ms.service: agent-framework
 ---
 
@@ -300,6 +300,9 @@ Chat middleware intercepts chat requests sent to AI models. It uses the `ChatCon
 
 The `call_next` callback continues to the next middleware or sends the request to the AI service.
 
+> [!NOTE]
+> Chat middleware runs inside the function invocation loop. This means it executes for **each model call**, including calls that send tool results back to the model during a multi-turn tool calling sequence.
+
 ### Function-based
 
 ```python

agent-framework/media/agent-pipeline-python.svg

@@ -4,7 +4,7 @@ description: Guide to significant changes in Python releases for Microsoft Agent
 author: eavanvalkenburg
 ms.topic: upgrade-and-migration-article
 ms.author: edvan
-ms.date: 03/13/2026
+ms.date: 03/20/2026
 ms.service: agent-framework
 ---
 # Python 2026 Significant Changes Guide
@@ -18,9 +18,27 @@ This document will be removed once we reach the 1.0.0 stable release, so please
 
 ---
 
-## python-1.0.0rc5 / python-1.0.0b260318 (March 18, 2026)
+## python-1.0.0rc5 / python-1.0.0b260319 (March 19, 2026)
 
-**Release:** Scheduled for March 18, 2026. `agent-framework-core` and `agent-framework-azure-ai` move to `1.0.0rc5`; the remaining Python packages align on the March 2026 build line (`1.0.0b260318`).
+### 🔴 Chat client pipeline reordered: FunctionInvocation now wraps ChatMiddleware
+
+**PR:** [#4746](https://github.com/microsoft/agent-framework/pull/4746)
+
+The ChatClient pipeline ordering has changed. `FunctionInvocation` is now the outermost layer and wraps `ChatMiddleware`, which means chat middleware runs **per model call** (including each iteration of the tool calling loop) instead of once around the entire function invocation sequence.
+
+**Old pipeline order:**
+```
+ChatMiddleware → FunctionInvocation → RawChatClient
+```
+
+**New pipeline order:**
+```
+FunctionInvocation → ChatMiddleware → ChatTelemetry → RawChatClient
+```
+
+If you have custom chat middleware that assumed it ran only once per agent invocation (wrapping the entire tool calling loop), update it to be safe for repeated execution. Chat middleware is now invoked for each individual LLM request, including requests that send tool results back to the model.
+
+Additionally, `ChatTelemetry` is now a separate layer from `ChatMiddleware` in the pipeline, running closest to `RawChatClient`.
 
 ### 🔴 Public runtime kwargs split into explicit buckets