Sync Agent Framework Python 1.0.0 docs (#960)

* Sync Python 1.0.0 docs

Update the Agent Framework docs to reflect the final Python 1.0.0 changes, including the stable package installs, final Message(contents=...) construction change, and the latest breaking-change guidance.

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

* Fix OpenAI provider tab IDs

Resolve the duplicate DocFX tab-id warning in the OpenAI provider page by giving the configuration and creation tab groups distinct IDs.

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

---------

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

Author: eavanvalkenburg

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).
@@ -228,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
@@ -276,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
@@ -287,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/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

@@ -97,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,

agent-framework/agents/index.md

@@ -4,7 +4,7 @@ titleSuffix: Microsoft Foundry
 description: Learn different Agent Framework agent types.
 ms.service: agent-framework
 ms.topic: tutorial
-ms.date: 09/04/2025
+ms.date: 04/01/2026
 ms.reviewer: ssalgado
 zone_pivot_groups: programming-languages
 author: TaoChenOSU
@@ -224,8 +224,8 @@ from azure.identity.aio import DefaultAzureCredential
 agent = Agent(
     client=FoundryChatClient(
         credential=DefaultAzureCredential(),
-        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
-        model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
+        model=os.getenv("FOUNDRY_MODEL"),
     ),
     instructions="You are a helpful assistant",
 )
@@ -240,8 +240,8 @@ from azure.identity.aio import DefaultAzureCredential
 
 agent = FoundryChatClient(
     credential=DefaultAzureCredential(),
-    project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
-    model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+    project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
+    model=os.getenv("FOUNDRY_MODEL"),
 ).as_agent(
     instructions="You are a helpful assistant"
 )
@@ -259,7 +259,6 @@ For detailed examples, see the agent-specific documentation sections below.
 |[Foundry Agent](./providers/microsoft-foundry.md)|An agent that uses the Agent Service as its backend.|Yes|
 |[Azure OpenAI Chat Completion](./providers/azure-openai.md)|An agent that uses the Azure OpenAI Chat Completion service.|No|
 |[Azure OpenAI Responses](./providers/azure-openai.md)|An agent that uses the Azure OpenAI Responses service.|Yes|
-|[Azure OpenAI Assistants](./providers/azure-openai.md)|An agent that uses the Azure OpenAI Assistants service.|Yes|
 |[OpenAI Chat Completion](./providers/openai.md)|An agent that uses the OpenAI Chat Completion service.|No|
 |[OpenAI Responses](./providers/openai.md)|An agent that uses the OpenAI Responses service.|Yes|
 |[Anthropic Claude](./providers/anthropic.md)|An agent that uses Anthropic Claude models.|No|
@@ -287,9 +286,11 @@ async for chunk in agent.run("What's the weather like in Portland?", stream=True
 
 For streaming examples, see:
 
-- [Azure AI streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/azure_ai/azure_ai_basic.py)
-- [Azure OpenAI streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/azure_openai/azure_chat_client_basic.py)
-- [OpenAI streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/openai/openai_chat_client_basic.py)
+- [Foundry streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/foundry/foundry_chat_client_basic.py)
+- [Azure OpenAI Chat Completion streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/azure/openai_chat_completion_client_basic.py)
+- [Azure OpenAI Responses streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/azure/openai_client_basic.py)
+- [OpenAI Chat Completion streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/openai/chat_completion_client_basic.py)
+- [OpenAI Responses streaming examples](https://github.com/microsoft/agent-framework/blob/main/python/samples/02-agents/providers/openai/client_basic.py)
 
 For more invocation patterns, see [Running Agents](./running-agents.md).
 
@@ -310,8 +311,8 @@ def get_weather(location: Annotated[str, "The location to get the weather for."]
 async with DefaultAzureCredential() as credential:
     agent = FoundryChatClient(
         credential=credential,
-        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
-        model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
+        model=os.getenv("FOUNDRY_MODEL"),
     ).as_agent(
         instructions="You are a helpful weather assistant.",
         tools=get_weather,

agent-framework/agents/middleware/agent-vs-run-scope.md

@@ -5,7 +5,7 @@ zone_pivot_groups: programming-languages
 author: eavanvalkenburg
 ms.topic: reference
 ms.author: edvan
-ms.date: 02/09/2026
+ms.date: 04/01/2026
 ms.service: agent-framework
 ---
 
@@ -150,7 +150,8 @@ from agent_framework import (
     FunctionInvocationContext,
     tool,
 )
-from agent_framework.azure import AzureAIAgentClient
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
@@ -325,7 +326,8 @@ async def main() -> None:
     # authentication option.
     async with (
         AzureCliCredential() as credential,
-        AzureAIAgentClient(credential=credential).as_agent(
+        Agent(
+            client=FoundryChatClient(credential=credential),
             name="WeatherAgent",
             instructions="You are a helpful weather assistant.",
             tools=get_weather,
@@ -448,7 +450,8 @@ from agent_framework import (
     FunctionInvocationContext,
     tool,
 )
-from agent_framework.azure import AzureAIAgentClient
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
@@ -623,7 +626,8 @@ async def main() -> None:
     # authentication option.
     async with (
         AzureCliCredential() as credential,
-        AzureAIAgentClient(credential=credential).as_agent(
+        Agent(
+            client=FoundryChatClient(credential=credential),
             name="WeatherAgent",
             instructions="You are a helpful weather assistant.",
             tools=get_weather,