Merge pull request #961 from MicrosoftDocs/main

Merge latest docs to live

Author: westey-m

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/20/2026
+ms.date: 04/02/2026
 ms.service: agent-framework
 ---
 
@@ -40,13 +40,13 @@ The `Agent` class builds a pipeline through class composition with two main comp
 **Agent** (outer component):
 
 1. **Agent Middleware + Telemetry** - the `AgentMiddlewareLayer` and `AgentTelemetryLayer` classes handle middleware invocation and OpenTelemetry instrumentation
-2. **RawAgent** - Core agent logic that invokes context providers
-3. **Context Providers** - Unified `context_providers` list manages history and additional context
+2. **RawAgent** - Core agent logic that invokes context providers and collects provider-added middleware
+3. **Context Providers** - Unified `context_providers` list manages history, additional context, and per-run chat/function middleware
 
 **ChatClient** (separate and interchangeable component):
 
 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
+2. **Chat Middleware + Telemetry** - Optional middleware chain and instrumentation layers, including any chat middleware added by context providers, 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.
@@ -144,6 +144,8 @@ agent = Agent(
 )
 ```
 
+Context providers can also attach chat or function middleware to a single invocation via `SessionContext.extend_middleware()`. The agent flattens those additions in provider order before entering the ChatClient pipeline.
+
 ::: zone-end
 
 For detailed context provider patterns, see [Context Providers](./conversations/context-providers.md).
@@ -157,9 +159,10 @@ The chat client layer handles the actual communication with the LLM service.
 `ChatClientAgent` uses an `IChatClient` instance, which can be decorated with additional middleware:
 
 ```csharp
-var chatClient = new AzureOpenAIClient(endpoint, credential)
-    .GetChatClient(deploymentName)
-    .AsIChatClient()
+var chatClient = new AIProjectClient(endpoint, credential)
+    .GetProjectOpenAIClient()
+    .GetProjectResponsesClient()
+    .AsIChatClient(deploymentName)
     .AsBuilder()
     .Use(CustomChatClientMiddleware)
     .Build();
@@ -170,9 +173,10 @@ var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");
 You can also use `AIContextProvider` as chat client middleware to enrich messages, tools, and instructions at the client level. This must be used within the context of a running `AIAgent`:
 
 ```csharp
-var chatClient = new AzureOpenAIClient(endpoint, credential)
-    .GetChatClient(deploymentName)
-    .AsIChatClient()
+var chatClient = new AIProjectClient(endpoint, credential)
+    .GetProjectOpenAIClient()
+    .GetProjectResponsesClient()
+    .AsIChatClient(deploymentName)
     .AsBuilder()
     .UseAIContextProviders(new MyContextProvider())
     .Build();
@@ -226,14 +230,14 @@ When you invoke an agent, the request flows through the pipeline:
 **Agent pipeline:**
 
 1. **Agent Middleware + Telemetry** executes middleware (if configured) and records spans
-2. **RawAgent** invokes context providers to load history and add context
+2. **RawAgent** invokes context providers to load history, add context, and collect provider-added chat/function middleware
 3. Request is passed to the ChatClient
 
 **ChatClient pipeline:**
 
 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)
+   - For each tool call, **Function Middleware + Telemetry** executes, including any function middleware added by context providers
+5. **Chat Middleware + Telemetry** executes per model call (if configured), including any chat middleware added by context providers
 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
@@ -274,6 +278,16 @@ var copilotAgent = originalCopilotAgent
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
+
+## Other agent types
+
+Not every Python agent uses the full `Agent` + `ChatClient` pipeline. `GitHubCopilotAgent`, for example, sends requests through the GitHub Copilot CLI instead of a local chat client.
+
+Even so, Python `GitHubCopilotAgent` still supports agent middleware and now runs `context_providers` around each invocation. Provider-added messages and instructions are included in the prompt sent to Copilot, and providers receive the matching `after_run` callback once a response is available.
+
+> [!NOTE]
+> Because `GitHubCopilotAgent` does not use a local chat client, chat client middleware still does not apply.
+
 ::: zone-end
 
 ## Next steps
@@ -285,4 +299,4 @@ var copilotAgent = originalCopilotAgent
 
 - [Middleware](./middleware/index.md) - Add cross-cutting behavior to your agents
 - [Context Providers](./conversations/context-providers.md) - Detailed patterns for history and context injection
-- [Running Agents](./running-agents.md) - How to invoke agents
+- [Running Agents](./running-agents.md) - How to invoke agents

agent-framework/agents/background-responses.md

@@ -55,11 +55,10 @@ Some agents may not allow explicit control over background responses. These agen
 For non-streaming scenarios, when you initially run an agent, it may or may not return a continuation token. If no continuation token is returned, it means the operation has completed. If a continuation token is returned, it indicates that the agent has initiated a background response that is still processing and will require polling to retrieve the final result:
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-    .GetResponsesClient("<deployment-name>")
-    .AsAIAgent();
+    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");
 
 AgentRunOptions options = new()
 {
@@ -100,11 +99,10 @@ Console.WriteLine(response.Text);
 In streaming scenarios, background responses work much like regular streaming responses - the agent streams all updates back to consumers in real-time. However, the key difference is that if the original stream gets interrupted, agents support stream resumption through continuation tokens. Each update includes a continuation token that captures the current state, allowing the stream to be resumed from exactly where it left off by passing this token to subsequent streaming API calls:
 
 ```csharp
-AIAgent agent = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+AIAgent agent = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-    .GetResponsesClient("<deployment-name>")
-    .AsAIAgent();
+    .AsAIAgent(model: "<deployment-name>", instructions: "You are a helpful assistant.");
 
 AgentRunOptions options = new()
 {

agent-framework/agents/conversations/context-providers.md

@@ -282,10 +282,10 @@ internal sealed class AdvancedServiceMemoryProvider : AIContextProvider
 ```python
 from typing import Any
 
-from agent_framework import AgentSession, BaseContextProvider, SessionContext
+from agent_framework import AgentSession, ContextProvider, SessionContext
 
 
-class UserPreferenceProvider(BaseContextProvider):
+class UserPreferenceProvider(ContextProvider):
     def __init__(self) -> None:
         super().__init__("user-preferences")
 
@@ -314,6 +314,11 @@ class UserPreferenceProvider(BaseContextProvider):
                 state["favorite_food"] = text.split("favorite food is", 1)[1].strip().rstrip(".")
 ```
 
+> [!NOTE]
+> `ContextProvider` and `HistoryProvider` are the canonical Python base classes. `BaseContextProvider` and `BaseHistoryProvider` still exist as deprecated aliases for compatibility, but new providers should inherit from the new names.
+>
+> Context providers can also add chat or function middleware for the current invocation by calling `context.extend_middleware(self.source_id, middleware)`. The agent flattens those additions with `context.get_middleware()` and applies them in provider order before invoking the chat client.
+
 :::zone-end
 
 :::zone pivot="programming-language-python"
@@ -326,10 +331,10 @@ History providers are context providers specialized for loading/storing messages
 from collections.abc import Sequence
 from typing import Any
 
-from agent_framework import BaseHistoryProvider, Message
+from agent_framework import HistoryProvider, Message
 
 
-class DatabaseHistoryProvider(BaseHistoryProvider):
+class DatabaseHistoryProvider(HistoryProvider):
     def __init__(self, db: Any) -> None:
         super().__init__("db-history", load_messages=True)
         self._db = db
@@ -365,6 +370,7 @@ class DatabaseHistoryProvider(BaseHistoryProvider):
 > [!IMPORTANT]
 > In Python, you can configure multiple history providers, but **only one** should use `load_messages=True`.
 > Use additional providers for diagnostics/evals with `load_messages=False` and `store_context_messages=True` so they capture context from other providers alongside input/output.
+> If you need local history to persist around each model call in a tool loop, see [Storage](./storage.md#per-service-call-local-history-persistence).
 >
 > Example pattern:
 >

agent-framework/agents/conversations/storage.md

@@ -120,6 +120,32 @@ response = await agent.run("Continue this conversation.", session=session)
 
 :::zone-end
 
+## Per-service-call local history persistence
+
+Tool-calling runs can make multiple model calls before a single `agent.run()` completes. By default, local history providers persist once after the full run. If you want local history to mirror service-managed conversations more closely, set `require_per_service_call_history_persistence=True` so history providers run around each model call instead.
+
+:::zone pivot="programming-language-python"
+
+```python
+from agent_framework import Agent, InMemoryHistoryProvider
+from agent_framework.openai import OpenAIChatClient
+
+agent = Agent(
+    client=OpenAIChatClient(),
+    name="StorageAgent",
+    instructions="You are a helpful assistant.",
+    context_providers=[InMemoryHistoryProvider("memory", load_messages=True)],
+    require_per_service_call_history_persistence=True,
+)
+```
+
+> [!IMPORTANT]
+> Use this mode only for framework-managed local history. If the run is already bound to a service-managed conversation (for example via `session.service_session_id` or `options={"conversation_id": ...}`), Agent Framework raises an error instead of mixing the two persistence models.
+>
+> This mode is especially useful when middleware can terminate immediately after a tool call: persisting per model call keeps local history aligned with what a service-managed conversation would keep.
+
+:::zone-end
+
 ## Third-party/Custom storage pattern
 
 For database/Redis/blob-backed history, implement a custom history provider.

agent-framework/agents/declarative.md

@@ -18,17 +18,17 @@ Declarative agents allow you to define agent configuration using YAML or JSON fi
 The following example shows how to create a declarative agent from a YAML configuration:
 
 ```csharp
-using Azure.AI.OpenAI;
+using Azure.AI.Projects;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 
 // Create the chat client
-IChatClient chatClient = new AzureOpenAIClient(
-    new Uri("https://<myresource>.openai.azure.com"),
+IChatClient chatClient = new AIProjectClient(
+    new Uri("<your-foundry-project-endpoint>"),
     new DefaultAzureCredential())
-     .GetChatClient("gpt-4o-mini")
-     .AsIChatClient();
+        .GetProjectOpenAIClient()
+        .GetProjectResponsesClient()
+        .AsIChatClient("gpt-4o-mini");
 
 // Define the agent using a YAML definition.
 var yamlDefinition =
@@ -67,6 +67,9 @@ await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pi
 }
 ```
 
+> [!WARNING]
+> `DefaultAzureCredential` is convenient for development but requires careful consideration in production. In production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+
 :::zone-end
 
 :::zone pivot="programming-language-python"
@@ -94,7 +97,7 @@ model:
   id: =Env.AZURE_OPENAI_MODEL
   connection:
     kind: remote
-    endpoint: =Env.AZURE_AI_PROJECT_ENDPOINT
+    endpoint: =Env.FOUNDRY_PROJECT_ENDPOINT
 """
     async with (
         AzureCliCredential() as credential,