Merging changes synced from https://github.com/MicrosoftDocs/semantic-kernel-pr (branch live)

Author: Learn Build Service GitHub App

agent-framework/AGENTS.md

@@ -205,6 +205,7 @@ Every docs page maps to sample files in both repos:
 | `agents/tools/local-mcp-tools.md` | `02-agents/tools/local_mcp_tools.py` | `02-agents/tools/LocalMcpTools.cs` |
 | `agents/tools/tool-approval.md` | `02-agents/tools/tool_approval.py` | `02-agents/tools/ToolApproval.cs` |
 | `agents/middleware/*.md` | `02-agents/middleware/<matching>.py` | `02-agents/middleware/<matching>.cs` |
+| `agents/providers/foundry-local.md` | `02-agents/providers/foundry/foundry_local_agent.py` | N/A |
 | `agents/providers/*.md` | `02-agents/providers/<matching>.py` | `02-agents/providers/<matching>.cs` |
 | `agents/conversations/*.md` | `02-agents/conversations/<matching>.py` | `02-agents/conversations/<matching>.cs` |
 | `workflows/<pattern>.md` | `03-workflows/<pattern>/<matching>.py` | `03-workflows/<pattern>/<matching>.cs` |

agent-framework/TOC.yml

@@ -40,6 +40,8 @@ items:
     href: agents/observability.md
   - name: Agent Skills
     href: agents/skills.md
+  - name: Agent Safety
+    href: agents/safety.md
   - name: Tools
     items:
     - name: Overview
@@ -100,6 +102,8 @@ items:
       href: agents/providers/openai.md
     - name: Microsoft Foundry
       href: agents/providers/microsoft-foundry.md
+    - name: Foundry Local
+      href: agents/providers/foundry-local.md
     - name: Anthropic
       href: agents/providers/anthropic.md
     - name: Ollama
@@ -152,6 +156,16 @@ items:
       href: workflows/orchestrations/group-chat.md
     - name: Magentic
       href: workflows/orchestrations/magentic.md
+  - name: Advanced
+    items:
+    - name: Agent Executor
+      href: workflows/advanced/agent-executor.md
+    - name: Execution Modes
+      href: workflows/advanced/execution-modes.md
+    - name: Resettable Executors
+      href: workflows/advanced/resettable-executors.md
+    - name: Sub-Workflows
+      href: workflows/advanced/sub-workflows.md
 - name: Integrations
   items:
   - name: Overview

agent-framework/agents/agent-pipeline.md

@@ -190,12 +190,12 @@ The `Agent` class accepts any client that implements `SupportsChatGetResponse`.
 
 ```python
 from agent_framework import Agent
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.foundry import FoundryChatClient
 
-client = AzureOpenAIResponsesClient(
+client = FoundryChatClient(
     credential=credential,
     project_endpoint=endpoint,
-    deployment_name=model,
+    model=model,
 )
 
 agent = Agent(client=client, instructions="You are helpful.")

agent-framework/agents/background-responses.md

@@ -172,12 +172,12 @@ For non-streaming scenarios, when you initially run an agent with `background=Tr
 ```python
 import asyncio
 from agent_framework import Agent
-from agent_framework.openai import OpenAIResponsesClient
+from agent_framework.openai import OpenAIChatClient
 
 agent = Agent(
     name="researcher",
     instructions="You are a helpful research assistant.",
-    client=OpenAIResponsesClient(model_id="o3"),
+    client=OpenAIChatClient(model="o3"),
 )
 
 session = agent.create_session()

agent-framework/agents/conversations/compaction.md

@@ -59,7 +59,7 @@ Compaction solves these problems by selectively removing, collapsing, or summari
 
 Compaction applies only to agents that manage their own conversation history in memory. Agents that rely on service-managed context or conversation state do not benefit from compaction because the service already handles context management. Examples of service-managed agents include:
 
-- **Foundry Agents** — context is managed server-side by the Azure AI Foundry service.
+- **Foundry Agents** — context is managed server-side by the Microsoft Foundry service.
 - **Responses API with store enabled** (the default) — conversation state is stored and managed by the OpenAI service.
 - **Copilot Studio agents** — conversation context is maintained by the Copilot Studio service.
 
@@ -650,7 +650,4 @@ compacted = await apply_compaction(
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Context Providers](context-providers.md)
-
-> [!div class="nextstepaction"]
-> [Storage](storage.md)
+> [Middleware](../middleware/index.md)

agent-framework/agents/conversations/storage.md

@@ -361,4 +361,4 @@ resumed = AgentSession.from_dict(serialized)
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Running Agents](../running-agents.md)
+> [Compaction](./compaction.md)

agent-framework/agents/index.md

@@ -101,7 +101,7 @@ When using Foundry, Azure OpenAI, OpenAI services, or Anthropic services, you ha
 | [Azure OpenAI](/azure/ai-foundry/openai/overview) <sup>1</sup> | Azure OpenAI SDK <sup>2</sup> | [Azure.AI.OpenAI](https://www.nuget.org/packages/Azure.AI.OpenAI) | https://&lt;resource&gt;.openai.azure.com/ |
 | [Azure OpenAI](/azure/ai-foundry/openai/overview) <sup>1</sup> | OpenAI SDK | [OpenAI](https://www.nuget.org/packages/OpenAI) | https://&lt;resource&gt;.openai.azure.com/openai/v1/ |
 | OpenAI | OpenAI SDK | [OpenAI](https://www.nuget.org/packages/OpenAI) | No url required |
-| [Azure AI Foundry Anthropic](/azure/ai-foundry/foundry-models/how-to/use-foundry-models-claude) | Anthropic Foundry SDK | [Anthropic.Foundry](https://www.nuget.org/packages/Anthropic.Foundry) | Resource name required |
+| [Microsoft Foundry Anthropic](/azure/ai-foundry/foundry-models/how-to/use-foundry-models-claude) | Anthropic Foundry SDK | [Anthropic.Foundry](https://www.nuget.org/packages/Anthropic.Foundry) | Resource name required |
 | Anthropic | Anthropic SDK | [Anthropic](https://www.nuget.org/packages/Anthropic) | No url or resource name required |
 
 1. [Upgrading from Azure OpenAI to Foundry](/azure/ai-foundry/how-to/upgrade-azure-openai)
@@ -169,7 +169,7 @@ AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
     name: "Joker");
 ```
 
-### Using the Azure AI Foundry Anthropic SDK
+### Using the Foundry Anthropic SDK
 
 The resource is the subdomain name / first name coming before '.services.ai.azure.com' in the endpoint Uri.
 
@@ -217,29 +217,37 @@ To create one of these agents, simply construct an `Agent` using the chat client
 ```python
 import os
 from agent_framework import Agent
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import DefaultAzureCredential
 
-Agent(
-    client=AzureOpenAIResponsesClient(credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")),
-    instructions="You are a helpful assistant"
-) as agent
+agent = Agent(
+    client=FoundryChatClient(
+        credential=DefaultAzureCredential(),
+        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
+        model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+    ),
+    instructions="You are a helpful assistant",
+)
 response = await agent.run("Hello!")
 ```
 
 Alternatively, you can use the convenience method on the chat client:
 
 ```python
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.foundry import FoundryChatClient
 from azure.identity.aio import DefaultAzureCredential
 
-agent = AzureOpenAIResponsesClient(credential=DefaultAzureCredential(), project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"), deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME")).as_agent(
+agent = FoundryChatClient(
+    credential=DefaultAzureCredential(),
+    project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
+    model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
+).as_agent(
     instructions="You are a helpful assistant"
 )
 ```
 
 > [!NOTE]
-> This example shows using the AzureOpenAIResponsesClient, but the same pattern applies to any chat client that implements `SupportsChatGetResponse`, see [providers overview](./providers/index.md) for more details on other clients.
+> This example shows using the FoundryChatClient, but the same pattern applies to any chat client that implements `SupportsChatGetResponse`, see [providers overview](./providers/index.md) for more details on other clients.
 
 For detailed examples, see the agent-specific documentation sections below.
 
@@ -293,17 +301,17 @@ You can provide function tools to agents for enhanced capabilities:
 import os
 from typing import Annotated
 from azure.identity.aio import DefaultAzureCredential
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework.foundry import FoundryChatClient
 
 def get_weather(location: Annotated[str, "The location to get the weather for."]) -> str:
     """Get the weather for a given location."""
     return f"The weather in {location} is sunny with a high of 25°C."
 
 async with DefaultAzureCredential() as credential:
-    agent = AzureOpenAIResponsesClient(
+    agent = FoundryChatClient(
         credential=credential,
         project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
-        deployment_name=os.getenv("AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"),
+        model=os.getenv("AZURE_AI_MODEL_DEPLOYMENT_NAME"),
     ).as_agent(
         instructions="You are a helpful weather assistant.",
         tools=get_weather,

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

@@ -20,7 +20,7 @@ When both are registered, agent-level middleware runs first (outermost), followe
 
 :::zone pivot="programming-language-csharp"
 
-In C#, middleware is registered on an agent using the builder pattern. Agent-level middleware is applied during agent construction, while run-level middleware can be provided via `AgentRunOptions`.
+In C#, middleware is registered on an agent using the builder pattern with `.AsBuilder().Use(...).Build()`. Agent-level middleware is applied during agent construction and persists across all runs. Run-level middleware uses the same pattern but builds a decorated agent inline before calling `RunAsync` or `RunStreamingAsync`.
 
 ### Agent-level middleware
 
@@ -30,6 +30,7 @@ Agent-level middleware is registered at construction time and applies to every r
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Tasks;
 using Azure.AI.OpenAI;
@@ -50,6 +51,20 @@ async Task<AgentResponse> SecurityMiddleware(
     return response;
 }
 
+async IAsyncEnumerable<AgentResponseUpdate> SecurityStreamingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    AgentSession? session,
+    AgentRunOptions? options,
+    AIAgent innerAgent,
+    [EnumeratorCancellation] CancellationToken cancellationToken)
+{
+    Console.WriteLine("[Security] Validating streaming request...");
+    await foreach (var update in innerAgent.RunStreamingAsync(messages, session, options, cancellationToken))
+    {
+        yield return update;
+    }
+}
+
 AIAgent baseAgent = new AzureOpenAIClient(
     new Uri("https://<myresource>.openai.azure.com"),
     new AzureCliCredential())
@@ -59,15 +74,15 @@ AIAgent baseAgent = new AzureOpenAIClient(
 // Register middleware at the agent level
 var agentWithMiddleware = baseAgent
     .AsBuilder()
-        .Use(runFunc: SecurityMiddleware, runStreamingFunc: null)
+        .Use(runFunc: SecurityMiddleware, runStreamingFunc: SecurityStreamingMiddleware)
     .Build();
 
 Console.WriteLine(await agentWithMiddleware.RunAsync("What's the weather in Paris?"));
 ```
 
 ### Run-level middleware
 
-Run-level middleware is provided per request via `AgentRunOptions`:
+Run-level middleware uses the same builder pattern, applied inline for a specific invocation:
 
 ```csharp
 // Run-level middleware: applied to a specific run only
@@ -84,11 +99,31 @@ async Task<AgentResponse> DebugMiddleware(
     return response;
 }
 
-// Pass run-level middleware via AgentRunOptions for this specific call
-var runOptions = new AgentRunOptions { RunMiddleware = DebugMiddleware };
-Console.WriteLine(await baseAgent.RunAsync("What's the weather in Tokyo?", options: runOptions));
+async IAsyncEnumerable<AgentResponseUpdate> DebugStreamingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    AgentSession? session,
+    AgentRunOptions? options,
+    AIAgent innerAgent,
+    [EnumeratorCancellation] CancellationToken cancellationToken)
+{
+    Console.WriteLine($"[Debug] Input messages: {messages.Count()}");
+    await foreach (var update in innerAgent.RunStreamingAsync(messages, session, options, cancellationToken))
+    {
+        yield return update;
+    }
+}
+
+// Apply run-level middleware by building a decorated agent inline for this specific call
+Console.WriteLine(await baseAgent
+    .AsBuilder()
+        .Use(runFunc: DebugMiddleware, runStreamingFunc: DebugStreamingMiddleware)
+    .Build()
+    .RunAsync("What's the weather in Tokyo?"));
 ```
 
+> [!TIP]
+> The `.AsBuilder().Use(...).Build()` pattern creates a lightweight wrapper around the original agent. You can chain multiple `.Use()` calls to compose several middleware for a single invocation.
+
 :::zone-end
 
 :::zone pivot="programming-language-python"

agent-framework/agents/middleware/index.md

@@ -881,4 +881,4 @@ if __name__ == "__main__":
 ## Next steps
 
 > [!div class="nextstepaction"]
-> [Agent Background Responses](../background-responses.md)
+> [Defining Middleware](./defining-middleware.md)

agent-framework/agents/middleware/result-overrides.md

@@ -94,7 +94,7 @@ from agent_framework import (
     ResponseStream,
     tool,
 )
-from agent_framework.openai import OpenAIResponsesClient
+from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
 """
@@ -260,7 +260,7 @@ async def main() -> None:
 
     # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
     # authentication option.
-    agent = OpenAIResponsesClient(
+    agent = OpenAIChatClient(
         middleware=[validate_weather_middleware, weather_override_middleware],
     ).as_agent(
         name="WeatherAgent",
@@ -316,7 +316,7 @@ from agent_framework import (
     ResponseStream,
     tool,
 )
-from agent_framework.openai import OpenAIResponsesClient
+from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
 """
@@ -482,7 +482,7 @@ async def main() -> None:
 
     # For authentication, run `az login` command in terminal or replace AzureCliCredential with preferred
     # authentication option.
-    agent = OpenAIResponsesClient(
+    agent = OpenAIChatClient(
         middleware=[validate_weather_middleware, weather_override_middleware],
     ).as_agent(
         name="WeatherAgent",