Merge pull request #943 from MicrosoftDocs/main

Merge main to live

Author: peibekwe

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/observability.md

@@ -31,7 +31,7 @@ var instrumentedChatClient = new AzureOpenAIClient(new Uri(endpoint), new Defaul
     .GetChatClient(deploymentName)
     .AsIChatClient() // Converts a native OpenAI SDK ChatClient into a Microsoft.Extensions.AI.IChatClient
     .AsBuilder()
-    .UseOpenTelemetry(sourceName: "MyApplication", configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
+    .UseOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true)    // Enable OpenTelemetry instrumentation with sensitive data
     .Build();
 ```
 
@@ -46,7 +46,7 @@ var agent = new ChatClientAgent(
     name: "OpenTelemetryDemoAgent",
     instructions: "You are a helpful assistant that provides concise and informative responses.",
     tools: [AIFunctionFactory.Create(GetWeatherAsync)]
-).WithOpenTelemetry(sourceName: "MyApplication", enableSensitiveData: true);    // Enable OpenTelemetry instrumentation with sensitive data
+).WithOpenTelemetry(sourceName: SourceName, configure: (cfg) => cfg.EnableSensitiveData = true); // Enable OpenTelemetry instrumentation with sensitive data
 ```
 
 > [!IMPORTANT]
@@ -70,7 +70,9 @@ using OpenTelemetry.Trace;
 using OpenTelemetry.Resources;
 using System;
 
-var SourceName = "MyApplication";
+// The source name under which all activities, metrics, and logs will be emitted.
+const string SourceName = "MyApplication";
+const string ServiceName = "AgentOpenTelemetry";
 
 var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATION_INSIGHTS_CONNECTION_STRING")
     ?? throw new InvalidOperationException("APPLICATION_INSIGHTS_CONNECTION_STRING is not set.");
@@ -82,12 +84,13 @@ var resourceBuilder = ResourceBuilder
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .SetResourceBuilder(resourceBuilder)
     .AddSource(SourceName)
-    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
-    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
     .AddAzureMonitorTraceExporter(options => options.ConnectionString = applicationInsightsConnectionString)
     .Build();
 ```
 
+> [!TIP]
+> The `AddSource` method is used to specify the source name which the provider will listen to. Make sure it matches the source name you used in your instrumentation code (e.g., `UseOpenTelemetry(sourceName: SourceName)`). If a source name is not specified in the instrumentation code, it will default to `Experimental.Microsoft.Agents.AI`, in which case you should use `AddSource("Experimental.Microsoft.Agents.AI")` in your tracer provider and meter provider configuration.
+
 > [!TIP]
 > Depending on your backend, you can use different exporters. For more information, see the [OpenTelemetry .NET documentation](https://opentelemetry.io/docs/instrumentation/net/exporters/). For local development, consider using the [Aspire Dashboard](#aspire-dashboard).
 
@@ -112,7 +115,6 @@ var resourceBuilder = ResourceBuilder
 using var meterProvider = Sdk.CreateMeterProviderBuilder()
     .SetResourceBuilder(resourceBuilder)
     .AddSource(SourceName)
-    .AddMeter("*Microsoft.Agents.AI") // Agent Framework metrics
     .AddAzureMonitorMetricExporter(options => options.ConnectionString = applicationInsightsConnectionString)
     .Build();
 ```
@@ -154,8 +156,6 @@ Consider using the Aspire Dashboard as a quick way to visualize your traces and
 using var tracerProvider = Sdk.CreateTracerProviderBuilder()
     .SetResourceBuilder(resourceBuilder)
     .AddSource(SourceName)
-    .AddSource("*Microsoft.Extensions.AI") // Listen to the Experimental.Microsoft.Extensions.AI source for chat client telemetry.
-    .AddSource("*Microsoft.Extensions.Agents*") // Listen to the Experimental.Microsoft.Extensions.Agents source for agent telemetry.
     .AddOtlpExporter(options => options.Endpoint = new Uri("http://localhost:4317"))
     .Build();
 ```
@@ -174,23 +174,27 @@ See a full example of an agent with OpenTelemetry enabled in the [Agent Framewor
 ## Dependencies
 
 ### Included packages
+
 To enable observability in your Python application, the following OpenTelemetry packages are installed by default:
+
 - [opentelemetry-api](https://pypi.org/project/opentelemetry-api/)
 - [opentelemetry-sdk](https://pypi.org/project/opentelemetry-sdk/)
 - [opentelemetry-semantic-conventions-ai](https://pypi.org/project/opentelemetry-semantic-conventions-ai/)
 
-
 ### Exporters
+
 We do *not* install exporters by default to prevent unnecessary dependencies and potential issues with auto instrumentation. There is a large variety of exporters available for different backends, so you can choose the ones that best fit your needs.
 
 Some common exporters you may want to install based on your needs:
+
 - For gRPC protocol support: install `opentelemetry-exporter-otlp-proto-grpc`
 - For HTTP protocol support: install `opentelemetry-exporter-otlp-proto-http`
 - For Azure Application Insights: install `azure-monitor-opentelemetry`
 
 Use the [OpenTelemetry Registry](https://opentelemetry.io/ecosystem/registry/?language=python&component=instrumentation) to find more exporters and instrumentation packages.
 
 ## Enable Observability (Python)
+
 ### Five patterns for configuring observability
 
 We've identified multiple ways to configure observability in your application, depending on your needs:
@@ -330,6 +334,7 @@ The following environment variables control Agent Framework observability:
 The `configure_otel_providers()` function automatically reads standard OpenTelemetry environment variables:
 
 **OTLP Configuration** (for Aspire Dashboard, Jaeger, etc.):
+
 - `OTEL_EXPORTER_OTLP_ENDPOINT` - Base endpoint for all signals (e.g., `http://localhost:4317`)
 - `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` - Traces-specific endpoint (overrides base)
 - `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` - Metrics-specific endpoint (overrides base)
@@ -338,6 +343,7 @@ The `configure_otel_providers()` function automatically reads standard OpenTelem
 - `OTEL_EXPORTER_OTLP_HEADERS` - Headers for all signals (e.g., `key1=value1,key2=value2`)
 
 **Service Identification**:
+
 - `OTEL_SERVICE_NAME` - Service name (default: `agent_framework`)
 - `OTEL_SERVICE_VERSION` - Service version (default: package version)
 - `OTEL_RESOURCE_ATTRIBUTES` - Additional resource attributes
@@ -356,7 +362,8 @@ Make sure you have your Foundry configured with a Azure Monitor instance, see [d
 pip install azure-monitor-opentelemetry
 ```
 
-#### Configure observability directly from the `AzureAIClient`:
+#### Configure observability directly from the `AzureAIClient`
+
 For Foundry projects, you can configure observability directly from the `AzureAIClient`:
 
 ```python
@@ -377,8 +384,8 @@ async def main():
 > [!TIP]
 > The arguments for `client.configure_azure_monitor()` are passed through to the underlying `configure_azure_monitor()` function from the `azure-monitor-opentelemetry` package, see [documentation](/python/api/overview/azure/monitor-opentelemetry-readme#usage) for details, we take care of setting the connection string and resource.
 
+#### Configure azure monitor and optionally enable instrumentation
 
-#### Configure azure monitor and optionally enable instrumentation:
 For non-Foundry projects with Application Insights, make sure you setup a custom agent in Foundry, see [details](/azure/ai-foundry/control-plane/register-custom-agent).
 
 Then run your agent with the same _OpenTelemetry agent ID_ as registered in Foundry, and configure azure monitor as follows:

agent-framework/workflows/events.md

@@ -52,6 +52,9 @@ SuperStepCompletedEvent  // Superstep completes
 RequestInfoEvent         // A request is issued
 ```
 
+> [!NOTE]
+> When agents use approval-required tools, `RequestInfoEvent` typically carries a `ToolApprovalRequestContent` payload for tool calls that require human approval. See [Human-in-the-Loop](./human-in-the-loop.md) for details on handling these events.
+
 ::: zone-end
 
 ::: zone pivot="programming-language-python"
@@ -81,6 +84,9 @@ WorkflowEvent.type == "superstep_completed" # Superstep completes
 WorkflowEvent.type == "request_info"        # A request is issued
 ```
 
+> [!NOTE]
+> When agents use approval-required tools, `request_info` events typically carry a `Content` payload with `type == "function_approval_request"` for tool calls that require human approval. See [Human-in-the-Loop](./human-in-the-loop.md) for details on handling these events.
+
 ::: zone-end
 
 ## Consuming Events

agent-framework/workflows/human-in-the-loop.md

@@ -17,6 +17,7 @@ ms.service: agent-framework
   | Overview                             | ✅ |   ✅   |                                                  |
   | Enable Request and Response Handling | ✅ |   ✅   | C# uses RequestPort; Python uses ctx.request_info |
   | Handling Requests and Responses      | ✅ |   ✅   |                                                  |
+  | HITL with Agent Orchestrations       | ✅ |   ✅   | No zone pivots; links to orchestration docs     |
   | Checkpoints and Requests             | ✅ |   ✅   |                                                  |
   | Next Steps                           | ✅ |   ✅   |                                                  |
 -->
@@ -230,6 +231,19 @@ while pending_responses is not None:
 
 ::: zone-end
 
+## Human-in-the-Loop with Agent Orchestrations
+
+The `RequestPort` pattern described above works with custom executors and `WorkflowBuilder`. When using **agent orchestrations** (such as sequential, concurrent, or group chat workflows), **tool approval** is achieved through the human-in-the-loop request/response mechanism.
+
+Agents can use tools that require human approval before execution. When the agent attempts to call an approval-required tool, the workflow pauses and emits a `RequestInfoEvent` just like the `RequestPort` pattern, but the event payload contains a `ToolApprovalRequestContent` (C#) or a `Content` with `type == "function_approval_request"` (Python) instead of a custom request type.
+
+> [!TIP]
+> For complete examples with code, see:
+> - [Sequential orchestration with HITL](./orchestrations/sequential.md#sequential-orchestration-with-human-in-the-loop)
+> - [GroupChatToolApproval sample (C#)](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/03-workflows/Agents/GroupChatToolApproval)
+> - [Sequential tool approval sample (Python)](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/tool-approval/sequential_builder_tool_approval.py)
+> - [Sequential request info sample (Python)](https://github.com/microsoft/agent-framework/blob/main/python/samples/03-workflows/human-in-the-loop/sequential_request_info.py)
+
 ## Checkpoints and Requests
 
 To learn more about checkpoints, see [Checkpoints](./checkpoints.md).
@@ -238,6 +252,7 @@ When a checkpoint is created, pending requests are also saved as part of the che
 
 ## Next Steps
 
+- [Learn about sequential orchestration with HITL](./orchestrations/sequential.md#sequential-orchestration-with-human-in-the-loop).
 - [Learn how to manage state](./state.md) in workflows.
 - [Learn how to create checkpoints and resume from them](./checkpoints.md).
 - [Learn how to monitor workflows](./observability.md).

agent-framework/workflows/orchestrations/index.md

@@ -20,6 +20,9 @@ Agent Framework provides several built-in multi-agent orchestration patterns:
 | [Group Chat](group-chat.md) | Agents collaborate in a shared conversation |
 | [Magentic](magentic.md) | A manager agent dynamically coordinates specialized agents |
 
+> [!TIP]
+> Orchestrations support **human-in-the-loop** interactions through tool approval and request info. Agents can use approval-required tools that pause the workflow for human review before execution. See [Human-in-the-Loop](../human-in-the-loop.md) and the [sequential orchestration HITL tutorial](sequential.md#sequential-orchestration-with-human-in-the-loop) for details.
+
 ## Next steps
 
 > [!div class="nextstepaction"]